README

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