README

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