example work and move README to org-mode with new CL support coming

[CommonLispStat.git] / README.org

This file will work better with org-mode and David Ito´s
org-babel-lisp as well as his hypo approach to literate programming
for gaming, as an org-babel extension. [fn:1]

* Fast Start

  You probably did  (preferred)

#+begin_src shell
  git clone git://github.com/blindglobe/common-lisp-stat.git
#+end_src

  or

#+begin_src shell
  git clone git://repo.or.cz/CLS.git
  git clone http://repo.or.cz/w/CLS.git
#+end_src

  which might be a few revisions behind, and now you should:

#+begin_src shell
  git submodules init
  git submodules update
#+end_src

  to get the whole package.  However, not all submodules are attached
  yet (need to do this soon).

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

#+begin_src shell
  cd lib && make && cd
#+end_src

  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:

#+begin_src shell
   git clone git://repo.or.cz/CommonLispStat.git 
   cd CommonLispStat
   git submodules init
   git submodules update
#+end_src

   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:

#+begin_src shell
    git checkout -b myTopicBranch
#+end_src

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

#+begin_src shell
    git checkout master
    git pull . myTopicBranch
#+end_src

(or
#+begin_src shell
    git rebase myTopicBranch
#+end_src
)

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

#+begin_src shell
    git checkout -b mob remotes/origin/mob
#+end_src

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

#+begin_src shell
         <edit>
         git add <files just edited>
         git commit -m "what I just did"
#+end_src

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

#+begin_src shell
     git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
#+end_src

)

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:

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

)

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>

===========


* Footnotes

[fn:1] I´m not including instructions for Emacs or git, as the former
is dealt with other places and the latter was required for you to get
this.  Since disk space is cheap, I´m intentionally forcing git to be
part of this system.  Sorry if you hate it.  Org-mode, org-babel, and
org-babel-lisp, and hypo are useful for making this file a literate
and interactively executable piece of work.