README

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