README.org

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