README

   1 -*- mode: text -*-
   2
   3 (comment to save: (gensym) can make an NA entry).
   4
   5 For a fast start:
   6
   7 You probably did:
   8
   9     git clone git://repo.or.cz/CLS.git
  10
  11 or
  12
  13     git clone git://github.com/blindglobe/common-lisp-stat.git
  14
  15 (or perhaps:
  16     git clone http://repo.or.cz/w/CLS.git
  17 )
  18
  19 and now you should:
  20
  21     git submodules init
  22     git submodules update
  23
  24 to get the whole package.
  25
  26 Make the shared library liblispstat with an ANSI C compiler (only gcc
  27 tested at this point):
  28
  29        cd lib
  30        make
  31
  32 run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in the
  33 current directory.  Recent versions of CFFI and LIFT can be found in
  34 the external/ subdirectory, and should be autoload-able, assuming that
  35 you are using a Lisp implementation supporting ASDF.  (AJR-FIXME: need
  36 to upload my GIT mirrors to repo.or.cz or similar, and have them
  37 potentially available as submodules if needed)
  38
  39 (on Debian or similar systems: can use CLC (Common Lisp Controller) or
  40 SBCL approaches, i.e.  ~/.clc/systems or ~/.sbcl/systems should
  41 contain softlinks to the lispstat, cffi, and lift ASDF files
  42 (i.e. lispstat.asd, cffi.asd, and lift.asd).  AJR-FIXME: There is
  43 probably a similar incantation for other CL's, need to record that
  44 here!).
  45
  46 Step through ls-demo.lisp for a range of examples of activities.
  47
  48
  49 So basically ..
  50
  51 1. change directory into the CommonLispStat working directory.
  52 2. start your lisp
  53 3. follow the commands in the ls-demo.lisp file, i.e.
  54
  55    a. (asdf:oos 'asdf:load-op 'lispstat) ;; use ASDF to load lispstat
  56    b. (in-package :ls-user)
  57    c. (normal-rand 20)
  58    d. (setf mytest (normal-rand 20))
  59    e. ... (and so on) ...
  60
  61    and see if they work (basic CFFI functionality for external C
  62    library, LIFT package for unit-testing framework to ensure run time
  63    stability).
  64
  65 4. Tell me ( mailto:blindglobe@gmail.com ) if there is any thing wrong
  66    (or if anything happens to work.
  67
  68 CMUCL and SBCL seem to work just fine at this stage.
  69
  70 CLISP is finicky regarding the problems that we have with CFFI
  71 conversation.  In particular that we can not really do typing that we
  72 need to take care of.   I think this is my problem, not someone
  73 elses.
  74
  75 Need to test ECL.  Clozure-CL seems to work.
  76
  77 ===========
  78
  79 See Doc/README* for history and design considerations
  80 See Doc/INSTALL for getting this to work and run
  81
  82 ===========
  83
  84 Working on this with git:
  85
  86     git clone git://repo.or.cz/CommonLispStat.git
  87     cd CommonLispStat.git
  88     git submodules init
  89     git submodules update
  90
  91 will pull the whole repository, and create a "master" branch to work
  92 on.  If you are making edits, Probably, you don't want to use the
  93 master branch, but more to use a topic-centric branch, so you might:
  94
  95     git checkout -b myTopicBranch
  96
  97 and then work on myTopicBranch, pulling back to the master branch when
  98 needed by
  99
 100     git checkout master
 101     git pull . myTopicBranch
 102
 103 (or
 104     git rebase myTopicBranch
 105 )
 106
 107 of course, perhaps you want to contribute to the mob branch.   For
 108 that, after cloning the repository as above, you would:
 109
 110     git checkout -b mob remotes/origin/mob
 111
 112 (work, work, work... through a cycle of
 113
 114          <edit>
 115          git add <files just edited>
 116          git commit -m "what I just did"
 117
 118  ad-nauseum.  When ready to commit, then just:
 119
 120      git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 121
 122 )
 123
 124 and it'll be put on the mob branch, as a proposal for merging.
 125
 126 Another approach would be to pull from the topic branch into the mob
 127 branch before uploading.   Will work on a formal example soon.
 128
 129 (the basic principle is that instead of the edit cycle on mob, do
 130 something like:
 131
 132   git checkout mob
 133   git pull . myTopicBranch
 134   git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 135
 136 )
 137
 138 Alternatively, one can work on the github repositories as well.  They
 139 are a bit differently organized, and require one to get a github
 140 account and work from there.  In that case, you'd need to D/L the
 141 libraries.
 142
 143 That gets a bit tricky, but see ./bin/GetRepos.sh for an example.
 144
 145 ===========
 146
 147 I've started putting examples of use in function documentation.   If
 148 you are a lisp'er, you'll find this pendantic and insulting.  Many of
 149 the uses are trivial.  However, this has been tested out on a number
 150 of research statisticians (the primary user audience) and found
 151 useful.
 152
 153 Still need to write the (run-doc-ex 'function-name)  function, which
 154 would print out the example and run it live.  Hopefully with the same
 155 results.  I've used XML markup for this, but for no particular reason,
 156 we could have used SEXPs as well.   This is currently done by using an
 157 <example> tag set, as in
 158     <example>
 159     (progn
 160        (example-code-for-function))
 161     </example>
 162
 163 ===========