moved example into TODO where it belonged.

[CommonLispStat.git] / README.org

Time-stamp: <2012-10-04 02:30:43 tony>

* Fast Start

  You probably did  (preferred)

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

  or (coming soon!) from within a Lisp instance, 

#+name: QuickLispLoad
#+begin_src lisp
  (ql:quickload :cls)
#+end_src

  At one point, I planned on git-delivery via submodules, but this
  proved to be a bit more complex than needed, thanks to the creation
  of quicklisp.  

  There will need to be a version for delivering a development QL
  environment (for development) and this will consist of git
  repositories, possibly through submodules, but this is for
  discussion. 

  There are quite a few libraries that are needed, and right now we
  are working on simplifying the whole thing.   Once you get past
  this step, then you should:

  1. 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)

  2. (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.

** Example Usage steps
  
*** change directory into the CommonLispStat working directory.
*** start your lisp
*** follow the commands in the *ls-demo.lisp* (need to add link) file, i.e.
 
**** (ql:quickload :cls)

     use QUICKLISP to load lispstat


**** (in-package :ls-user)

     work in the scratch user package.  Normally, one would create a
     special package to work in.

**** (normal-rand 20)

**** (setf mytest (normal-rand 20))

**** ... (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).
  
*** Inform  moi of problems or successes

    mailto:blindglobe@gmail.com if there is anything wrong, or
    even if something happens to work.

    Current beliefs:
    - 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.

* History

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

* Working on your own modifications

#+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, which I'd like, 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. 

* Documentation and examples

  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

#+srcname: 
#+begin_src xml
  <example>
  (progn
    (example-code-for-function))
  </example>
#+end_src

* 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.