-*- mode: text -*-

MOSTLY WRONG, NEEDS UPDATE.


(comment to save: (gensym) can make an NA entry).

For a fast start: 

You probably did:

    git clone git://repo.or.cz/CLS.git

or 

    git clone git://github.com/blindglobe/common-lisp-stat.git

(or perhaps:
    git clone http://repo.or.cz/w/CLS.git
)

and now you should:

    git submodules init
    git submodules update

to get the whole package.  However, not all submodules are attached
yet!  Will need to load 

Make the shared library liblispstat with an ANSI C compiler (only gcc
tested at this point):

       cd lib
       make

run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in the
current directory.  Recent versions of CFFI and LIFT can be found in
the external/ subdirectory, and should be autoload-able, assuming that
you are using a Lisp implementation supporting ASDF.  (AJR-FIXME: need
to upload my GIT mirrors to repo.or.cz or similar, and have them
potentially available as submodules if needed)

(on Debian or similar systems: can use CLC (Common Lisp Controller) or
SBCL approaches, i.e.  ~/.clc/systems or ~/.sbcl/systems should
contain softlinks to the cls, cffi, and lift ASDF files
(i.e. cls.asd, cffi.asd, and lift.asd).  AJR-FIXME: There is
probably a similar incantation for other CL's, need to record that
here!).

Step through ls-demo.lisp for a range of examples of activities.
    

So basically ..   
  
1. change directory into the CommonLispStat working directory.
2. start your lisp
3. follow the commands in the ls-demo.lisp file, i.e.
 
   a. (asdf:oos 'asdf:load-op 'cls) ;; use ASDF to load lispstat
   b. (in-package :ls-user)
   c. (normal-rand 20)
   d. (setf mytest (normal-rand 20))
   e. ... (and so on) ...

   and see if they work (basic CFFI functionality for external C
   library, LIFT package for unit-testing framework to ensure run time
   stability).
  
4. Tell me ( mailto:blindglobe@gmail.com ) if there is any thing wrong
   (or if anything happens to work.

CMUCL and SBCL seem to work just fine at this stage.

CLISP is finicky regarding the problems that we have with CFFI
conversation.  In particular that we can not really do typing that we
need to take care of.   I think this is my problem, not someone
elses. 

Need to test ECL.  Clozure-CL seems to work.

===========

See Doc/README* for history and design considerations
See Doc/INSTALL for getting this to work and run

===========

Working on this with git:

    git clone git://repo.or.cz/CommonLispStat.git 
    cd CommonLispStat
    git submodules init
    git submodules update

will pull the whole repository, and create a "master" branch to work
on.  If you are making edits, Probably, you don't want to use the
master branch, but more to use a topic-centric branch, so you might:

    git checkout -b myTopicBranch

and then work on myTopicBranch, pulling back to the master branch when
needed by

    git checkout master
    git pull . myTopicBranch

(or
    git rebase myTopicBranch
)

of course, perhaps you want to contribute to the mob branch.   For
that, after cloning the repository as above, you would:

    git checkout -b mob remotes/origin/mob

(work, work, work... through a cycle of

         <edit>
   git add <files just edited>
   git commit -m "what I just did"

 ad-nauseum.  When ready to commit, then just:

     git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob

)

and it'll be put on the mob branch, as a proposal for merging.

Another approach would be to pull from the topic branch into the mob
branch before uploading.   Will work on a formal example soon.

(the basic principle is that instead of the edit cycle on mob, do
something like:

  git checkout mob
  git pull . myTopicBranch   
  git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob

)

Alternatively, one can work on the github repositories as well.  They
are a bit differently organized, and require one to get a github
account and work from there.  In that case, you'd need to D/L the
libraries. 

That gets a bit tricky, but see ./bin/GetRepos.sh for an example. 

===========

I've started putting examples of use in function documentation.   If
you are a lisp'er, you'll find this pendantic and insulting.  Many of
the uses are trivial.  However, this has been tested out on a number
of research statisticians (the primary user audience) and found
useful.

Still need to write the (run-doc-ex 'function-name)  function, which
would print out the example and run it live.  Hopefully with the same
results.  I've used XML markup for this, but for no particular reason,
we could have used SEXPs as well.   This is currently done by using an
<example> tag set, as in
    <example>
    (progn
       (example-code-for-function))
    </example>

===========