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