2 Time-stamp: <2012-10-08 15:22:18 tony>
4 * Current Status: COMPLETELY BROKEN
6 but we are rebuilding it.
12 (This held for the version before we removed liblispstat and plplot
13 and some other "crutches" which had a bit too much bitrot).
15 We assume that you have a lisp installed and that you have a
16 passing acquaintence with the unix shell.
18 1. The first point that you should note that is that these
19 instructions are written with the assumption of the availibility
22 If you do not have quicklisp , please go to www.quicklisp.org and
25 2. The second point to note is that you will need the "git" utility
26 installed on your machine.
28 for mac osx sudo port install git
29 for linux (eg debian) sudo apt-get install git
31 3. Once that is done execute the following shell commands
34 cd ~/quicklisp/local-projects
35 git clone git://github.com/blindglobe/common-lisp-stat.git
40 These commands copy the the source from the repository and all
41 the associated libraries. It will live as a quicklisp project in
42 the local-projects directory. I find it convenient to
43 symbolically link the quicklisp direct to ~/lisp for easy access
46 ln ~/quicklisp/local-projects ~/lisp
49 4. Configure the locations of the BLAS and LINPACK libraries
51 Currently this is a manual operation, which will change in a
54 Edit the file external/cl-blapack/load-blapack-libs.lisp
56 Search for the following 3 parameters *gfortran-lib* *blas-lib*
59 For OS X: change the parameters as suggested in the file. Both
60 BLAS and LAPACK are pre installed on Mac OSX.
62 For linux, make sure you have the neccessary libraries installed,
63 through apt, yum or otherwise viz
65 viz sudo apt-get install libblas, sudo apt-get install liblapack
67 5. For visualization we are currently using plplot and the
68 cl-plplot interface. this requires the installation of the
71 for MAC OSX you can use macports or homebrew
73 5.1 sudo port install xquartz (or download from the xquartz home site)
75 5.2 sudo port install plplot
77 and on linux your favourite package manager of course.
79 For windows, we recommend you use cygwin to get straightforward
80 access. I'll document the steps if there is a demand.
82 6. You need to check that your dynamic library path has been
83 properly set up in the shell. In your .bashrc (or equivalent
89 DYLD_FALLBACK-LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/opt/local/lib
95 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:????
98 If you get this wrong the load process will not be able to find
99 the libraries and will prompt you.
101 5. Once the pre prequisites have been done, start your favourite lisp
105 (ql:register-local-projects)
109 Retire for a well earned coffee and upon your return you should
110 find the package completely installed.Obviously, potential
111 errors can creep in with spelling the filenames correctly, so be
116 You probably did (preferred)
118 #+name: LoadWithGitClone
120 git clone git://github.com/blindglobe/common-lisp-stat.git
123 (or maybe using the repo.or.cz git repository archive), or (coming
124 soon!) from within a Lisp instance:
126 #+name: LoadWithQuickLisp
131 At one point, I planned a pure git-delivery via cloning and
132 submodules, but this proved to be a bit more complex than needed,
133 thanks to the creation of quicklisp. It's also a stupid idea if
134 one plans to have users who are not hackers or developers, and
135 eventually we want users.
137 Despite quicklisp, there will need to be a version for delivering a
138 system development-oriented CLS environment and this will consist of
139 git repositories, possibly through submodules, but this (submodules)
142 There are quite a few libraries that are needed, and right now we
143 are working on simplifying the whole thing. Once you get past
144 this step, then you should:
146 1. run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in
147 the current directory. You will need ASDF at a minimum,
148 QUICKLISP preferred. And you should have QUICKLISP.
150 2. (on Debian or similar systems: can use CLC (Common Lisp
151 Controller) or SBCL approaches, i.e. ~/.clc/systems or
152 ~/.sbcl/systems should contain softlinks to the cls and other
153 required ASDF files (i.e. cls.asd, cffi.asd, and lift.asd).
155 There are example sessions and scripts for data analysis, some real,
156 some proposed, in the file:examples/ directory. Also see
157 file:TODO.org for snippets of code that work or fail to work.
159 ** Example Usage steps [2/7]
161 *** DONE Start and Load
170 *** DONE Setup a place to work
172 In Common Lisp, you need to select and setup namespace to store data
173 and functions. There is a scratch user-package, or sandbox, for
174 CLS, *cls-user* , which you can select via:
176 #+BEGIN_SRC lisp -n :tangle "readme-example.lisp"
177 (in-package :cls-user)
180 and this has some basic modules from CLS instantiated (dataframes,
181 probability calculus, numerical linear algebra, basic summaries
182 (numerical and visual displays).
184 However, it can be better is to create a package to work in, which
185 pulls in only desired functionality:
188 #+BEGIN_SRC lisp +n :tangle "readme-example.lisp"
190 (defpackage :my-package-user
191 (:documentation "demo of how to put serious work should be placed in
192 a similar package elsewhere for reproducibility. This hints as to
193 what needs to be done for a user- or analysis-package.")
194 (:nicknames :my-clswork-user)
195 (:use :common-lisp ; always needed for user playgrounds!
196 :lisp-matrix ; we only need the packages that we need...
197 :common-lisp-statistics
199 :lisp-stat-data-examples) ;; this ensures access to a data package
200 (:shadowing-import-from :lisp-stat
201 ;; This is needed temporarily until we resolve the dependency and call structure.
202 call-method call-next-method
204 expt + - * / ** mod rem abs 1+ 1- log exp sqrt sin cos tan
205 asin acos atan sinh cosh tanh asinh acosh atanh float random
206 truncate floor ceiling round minusp zerop plusp evenp oddp
207 < <= = /= >= > > ;; complex
208 conjugate realpart imagpart phase
209 min max logand logior logxor lognot ffloor fceiling
210 ftruncate fround signum cis
214 (:export summarize-data summarize-results this-data this-report))
216 (in-package :my-clswork-user) ;; or :my-package-user
223 We need to pull in the packages with data or functions that we need;
224 just because the data/function is pulled in by another package, in
225 that package's namespace, does NOT mean it is available in this name
226 space. However, the *common-lisp-statistics* package will ensure
227 that fundamental objects and functions are always available.
230 *** TODO Get to work [0/3]
232 **** TODO Pull in or create data
234 **** TODO Summarize results
236 **** TODO Save work and results for knowledge building and reuse
238 One can build a package, or save an image (CL implementation
241 *** TODO Inform moi of problems or successes
243 NEED TO SETUP A MAILING LIST!!
245 mailto:blindglobe@gmail.com if there is anything wrong, or
246 even if something happens to work.
249 - SBCL is target platform. CCL and CMUCL should be similar.
250 - CLISP is finicky regarding the problems that we have with CFFI
251 conversation. In particular that we can not really do typing
252 that we need to take care of. I think this is my (Tony's)
253 problem, not someone elses, and specifically, not CLISP's
258 See files in file:Doc/ for history, design considerations, and
259 random, sometimes false and misleading, musings.
261 * Local modifications, Development, Contributions
263 Since this project is
266 # git clone git://repo.or.cz/CommonLispStat.git
267 git clone git://github.com/blindglobe/common-lisp-stat.git
269 # git submodules init
270 # git submodules update
273 will pull the whole repository, and create a "master" branch to
274 work on. If you are making edits, which I'd like, you don't want
275 to use the master branch, but more to use a topic-centric branch,
279 git checkout -b myTopicBranch
282 and then work on myTopicBranch, pulling back to the master branch when
287 git pull . myTopicBranch
292 git rebase myTopicBranch
296 BETTER DOCUMENTATION EXAMPLES EXIST ON-LINE!! PLEASE READ THEM, THE
297 ABOVE IS SPARSE AND MIGHT BE OUTDATED!
300 ** Contributing through GitHub
302 Alternatively, one can work on the github repositories as well.
303 They are a bit differently organized, and require one to get a
304 github account and work from there.
306 basically, clone the repository on github on the WWW interface,
307 then make a branch (as below), push back the branch to github, and
308 notify the main repository that there is something to be pulled.
309 And we'll pull it back in.
311 ** Commiting with the MOB on repo.or.cz
313 of course, perhaps you want to contribute to the mob branch. For
314 that, after cloning the repository as above, you would:
317 git checkout -b mob remotes/origin/mob
320 (work, work, work... through a cycle of
324 git add <files just edited>
325 git commit -m "what I just did"
328 ad-nauseum. When ready to commit, then just:
331 git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
336 and it'll be put on the mob branch, as a proposal for merging.
338 Another approach would be to pull from the topic branch into the mob
339 branch before uploading. Will work on a formal example soon.
341 (the basic principle is that instead of the edit cycle on mob, do
346 git pull . myTopicBranch
347 git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
354 Licensing will be important. Next decade. But do think through
355 what you intend with your contributions. Should we become famous
356 (Ha!) make sure that you've communicated your expectations...
360 [fn:1] I´m not including instructions for Emacs or git, as the former
361 is dealt with other places and the latter was required for you to get
362 this. Since disk space is cheap, I´m intentionally forcing git to be
363 part of this system. Sorry if you hate it. Org-mode, org-babel, and
364 org-babel-lisp, and hypo are useful for making this file a literate
365 and interactively executable piece of work.