README.org

   1
   2 This file will work better with org-mode and David Ito´s
   3 org-babel-lisp.  Along those lines, please note his hypo approach to
   4 literate programming for gaming, as an org-babel extension. [fn:1] .
   5 That approach describes a literate approach for describing games, but
   6 clearly is no different than the literate approaches described for
   7 data analysis, which is just another game.
   8
   9 * Fast Start
  10
  11   You probably did  (preferred)
  12
  13 #+begin_src shell
  14   git clone git://github.com/blindglobe/common-lisp-stat.git
  15 #+end_src
  16
  17   or
  18
  19 #+begin_src shell
  20   git clone git://repo.or.cz/CLS.git
  21   git clone http://repo.or.cz/w/CLS.git
  22 #+end_src
  23
  24 ** TODO set up git submodules to do the right thing.
  25    - State "TODO"       from ""           [2010-10-10 Sun 23:30]
  26
  27 #+begin_src shell
  28   git submodules init
  29   git submodules update
  30 #+end_src
  31
  32   to get the whole package.
  33
  34   *_Obsolete_*: Make the shared library liblispstat with an ANSI C
  35   compiler (only gcc tested at this point).  This is used for
  36   numerical support which might be more robust to obtain from GSLL or
  37   similar other systems.  It would be done via.
  38
  39 #+begin_src shell
  40   cd lib && make && cd
  41 #+end_src
  42
  43   run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in the
  44   current directory.  Recent versions of CFFI and LIFT can be found in
  45   the external/ subdirectory, and should be autoload-able, assuming
  46   that you are using a Lisp implementation supporting ASDF.
  47   (AJR-FIXME: need to upload my GIT mirrors to repo.or.cz or similar,
  48   and have them potentially available as submodules if needed)
  49
  50   (on Debian or similar systems: can use CLC (Common Lisp Controller)
  51   or SBCL approaches, i.e.  ~/.clc/systems or ~/.sbcl/systems should
  52   contain softlinks to the cls, cffi, and lift ASDF files
  53   (i.e. cls.asd, cffi.asd, and lift.asd).  AJR-FIXME: There is
  54   probably a similar incantation for other CL's, need to record that
  55   here!).
  56
  57   Step through ls-demo.lisp for a range of examples of activities.
  58
  59 ** Example Usage steps
  60
  61 *** change directory into the CommonLispStat working directory.
  62 *** start your lisp
  63 *** follow the commands in the *ls-demo.lisp* (need to add link) file, i.e.
  64
  65 **** (asdf:oos 'asdf:load-op :cls)
  66
  67      use ASDF to load lispstat
  68
  69
  70 **** (in-package :ls-user)
  71
  72      work in the scratch user package.  Normally, one would create a
  73      special package to work in.
  74
  75 **** (normal-rand 20)
  76
  77 **** (setf mytest (normal-rand 20))
  78
  79 **** ... (and so on) ...
  80
  81    and see if they work (basic CFFI functionality for external C
  82    library, LIFT package for unit-testing framework to ensure run time
  83    stability).
  84
  85 *** Inform  moi of problems or successes
  86
  87     mailto:blindglobe@gmail.com if there is anything wrong, or
  88     even if something happens to work.
  89
  90     Current beliefs:
  91     - CMUCL and SBCL seem to work just fine at this stage.
  92     - CLISP is finicky regarding the problems that we have with CFFI
  93       conversation.  In particular that we can not really do typing
  94       that we need to take care of.  I think this is my problem, not
  95       someone elses.
  96     - Need to test ECL.  Clozure-CL seems to work.
  97
  98 * History
  99
 100    See Doc/README* for history and design considerations
 101    See Doc/INSTALL for getting this to work and run
 102
 103 * Working on your own modifications
 104
 105 #+begin_src shell
 106    git clone git://repo.or.cz/CommonLispStat.git
 107    cd CommonLispStat
 108    git submodules init
 109    git submodules update
 110 #+end_src
 111
 112    will pull the whole repository, and create a "master" branch to
 113    work on.  If you are making edits, which I'd like, you don't want
 114    to use the master branch, but more to use a topic-centric branch,
 115    so you might:
 116
 117 #+begin_src shell
 118     git checkout -b myTopicBranch
 119 #+end_src
 120
 121 and then work on myTopicBranch, pulling back to the master branch when
 122 needed by
 123
 124 #+begin_src shell
 125     git checkout master
 126     git pull . myTopicBranch
 127 #+end_src
 128
 129 (or
 130 #+begin_src shell
 131     git rebase myTopicBranch
 132 #+end_src
 133 )
 134
 135 of course, perhaps you want to contribute to the mob branch.   For
 136 that, after cloning the repository as above, you would:
 137
 138 #+begin_src shell
 139     git checkout -b mob remotes/origin/mob
 140 #+end_src
 141
 142 (work, work, work... through a cycle of
 143
 144 #+begin_src shell
 145          <edit>
 146          git add <files just edited>
 147          git commit -m "what I just did"
 148 #+end_src
 149
 150  ad-nauseum.  When ready to commit, then just:
 151
 152 #+begin_src shell
 153      git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 154 #+end_src
 155
 156 )
 157
 158 and it'll be put on the mob branch, as a proposal for merging.
 159
 160 Another approach would be to pull from the topic branch into the mob
 161 branch before uploading.   Will work on a formal example soon.
 162
 163 (the basic principle is that instead of the edit cycle on mob, do
 164 something like:
 165
 166 #+begin_src shell
 167   git checkout mob
 168   git pull . myTopicBranch
 169   git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 170 #+end_src
 171
 172 )
 173
 174 Alternatively, one can work on the github repositories as well.  They
 175 are a bit differently organized, and require one to get a github
 176 account and work from there.  In that case, you'd need to D/L the
 177 libraries.
 178
 179 That gets a bit tricky, but see ./bin/GetRepos.sh for an example.
 180
 181 * Documentation and examples
 182
 183   I've started putting examples of use in function documentation.  If
 184   you are a lisp'er, you'll find this pendantic and insulting.  Many
 185   of the uses are trivial.  However, this has been tested out on a
 186   number of research statisticians (the primary user audience) and
 187   found useful.
 188
 189   Still need to write the (run-doc-ex 'function-name) function, which
 190   would print out the example and run it live.  Hopefully with the
 191   same results.  I've used XML markup for this, but for no particular
 192   reason, we could have used SEXPs as well.  This is currently done by
 193   using an <example> tag set, as in
 194
 195 #+srcname:
 196 #+begin_src xml
 197   <example>
 198   (progn
 199     (example-code-for-function))
 200   </example>
 201 #+end_src
 202
 203 * Footnotes
 204
 205 [fn:1] I´m not including instructions for Emacs or git, as the former
 206 is dealt with other places and the latter was required for you to get
 207 this.  Since disk space is cheap, I´m intentionally forcing git to be
 208 part of this system.  Sorry if you hate it.  Org-mode, org-babel, and
 209 org-babel-lisp, and hypo are useful for making this file a literate
 210 and interactively executable piece of work.