AbstractThis is something I started in 2006 and at that time it seemed to make sense. Now (2011), you should try Zach Beane's Quicklisp instead. I'm not planning to maintain the starter pack anymore.
This is an attempt to help Common Lisp newcomers getting started. The aim is to quickly set up a comfortable working environment which includes a couple of useful and/or popular open source libraries. It is targeted at the Microsoft Windows platform (but see below) and obviously heavily influenced by the author's personal preferences.
If you're using this document and the accompanying application, I'd like to hear from you. Whether you like it or not, feedback is always appreciated. See my homepage for my email address.
I usually tried to help by setting up a little "starter pack" which (I think) was easy to use and included the libraries the person wanted to deploy in a state ready for immediate usage. My experience with this "starter pack" has been quite good, and so I decided to polish it a bit, make it customizable, and publish it, so I can point people to this website the next time I'm asked.
Feel free to use this document and the accompanying little application
as you see fit, but be aware that all of this will only really work if
you're willing to follow my lead, specifically if you're using the
same Lisp implementation I do - see FAQ for more
about this topic.
I also take for granted that you've found good introductory material which explains the syntax and semantics of Common Lisp. If you haven't done so already, you should definitely take a look at Peter Seibel's great tutorial Practical Common Lisp. I'd recommend buying the dead-tree version, but note that it's also available as a free download from Peter's website and (as a PDF) from the Apress website.
Finally, if for religious or political reasons you only want to use "free" software and Windows and/or LispWorks don't fit with your definition of free, then this text isn't for you.
As for technical requirements, you should use
Windows 2000, XP, or Vista with
all updates and service
packs installed. What I describe here most likely won't work with
older Windows versions - you have been warned...
msvcr80.dll. (The installer for 5.0.1 or higher will have installed it already anyway.) If you don't have it or if you aren't sure, you can get it here. If you're using Windows Vista, you have it already. (Note: This library is needed because the download application you are going to use was built with LispWorks 5.1.2. See here for a technical explanation.)
LispStarterPackfrom http://weitz.de/files/LispStarterPack.zip and unpack the ZIP archive.
LispStarterPack.exeand select the open source libraries you want to have. The application will keep track of dependencies and will automatically check other libraries you will also need. Note that the LW-ADD-ONS library and its supporting libraries are always checked because I will refer to them below. (Yes, all this is nothing but a secret conspiracy to lure people into using LW-ADD-ONS ...:)
LispStarterPack.exeagain, it will completely remove and replace the directory it has written, i.e. the application is not intended to be used more than once to add libraries to the ones you already have. If you're not sure which libraries you want to have, it doesn't hurt to press the Check all button if you have a fast Internet connection.
start.lispthat got installed in a directory called "Lisp Libraries" within your "My Documents" folder. (Of course, depending on your language settings, "My Documents" might have another name, for example "Eigene Dateien" in German.) LispWorks will now start to work frantically to compile some libraries. Just wait until it's finished. (Don't worry - this lengthy compilation only happens the first time after you've installed the libraries.)
It is assumed that you don't use LispWorks' Windows editor emulation, by the way. If you do, many of the key bindings described below won't work.
Unfortunately, you will have to load
time you start LispWorks. LispWorks knows the concept of an
initialization file which is read on startup and you could
start.lisp as your initialization file - but one of
the deliberate limitations of the Personal Edition is that it doesn't read
initialization files. If this annoys you very much, you should
consider to use the Windows Scripting Host to automate this
task - see Bill Clementson's blog for hints.
It is generally a good idea to familiarize yourself with new tools you plan to use extensively. In this case, this means that you will have to learn how to use LispWorks. Spend a couple of days (yes, I said days!) playing with the editor and the various other tools the IDE has to offer. I'd suggest to read at least the following parts of the LispWorks documentation:
Try to navigate
this file not only with the cursor keys you know from other Windows
apps but with the special commands to navigate Lisp expressions -
for example Forward Form
Alt+Ctrl+F), Backward Form
Alt+Ctrl+B), Backward Up List
Alt+Ctrl+U), Transpose Forms
Alt+Ctrl+T), Forward Kill Form
Alt+Ctrl+K), Indent Form
Alt+Ctrl+Q) and so on. (These are all explained in
User Guide, of course).
Use these and similar commands until they become second nature.
(m-v-band then press the Tab key. What you've typed should have been expanded to
F5 - your browser will open up the
corresponding entry of
the Common Lisp
HyperSpec. This will work with all symbols from the ANSI
standard as well as with all LispWorks-specific functionality and
also with a couple of libraries like for
example CL-PPCRE. (See
documentation for more details.)
In the listener, if you're at the very beginning of
a new line (i.e. behind the
> prompt), type a comma.
In the echo area, you will now be prompted for
L (the abbreviation for
"Load ASDF System") and the Return
key. The echo area now prompts for the name of the system to load.
hun then press the Tab key. The name of
the system will automatically be completed
hunchentoot. Press Return to compile and
load the library.
Now do the same to load
hunchentoot-test library. (Note that you can
hun and hit Tab and you will
hunchentoot as a partial completion. Now
- (a hyphen) and Tab and you'll
(Note: We loaded the two libraries individually for educational
purposes. It would have been enough to just
hunchentoot-test because ASDF would've taken care of
hunchentoot as well.)
Evaluate the form
(hunchentoot:start (make-instance 'hunchentoot:acceptor :port 9999))in the listener (don't forget to use completion with the Tab key to save some typing) and then enter the address http://localhost:9999/hunchentoot/test into your favorite web browser. Your Lisp now acts as a web server.
(Note: If you have a firewall or other security software installed, it will probably ask you whether it is OK that LispWorks uses port 9999. You should obviously answer with "yes" to reproduce what is described here.)
See the documentation for Hunchentoot for more info.
Load the library
clsql-sqlite!) as described above. You
can now interact with an SQLite3 database of your choice. Here's an
CL-USER 1 > (use-package :clsql) T ;; Make sure you have a c:\tmp directory or put the file somewhere else. CL-USER 2 > (connect '("c:/tmp/example.db") :database-type :sqlite3) #<CLSQL-SQLITE3:SQLITE3-DATABASE c:/tmp/example.db OPEN 200DD163> CL-USER 3 > (create-table "world_cup" '(("rank" integer) ("country" string))) CL-USER 4 > (loop for rank from 1 for country in '("Italy" "France" "Germany" "Portugal") do (execute-command (format nil "insert into world_cup values (~A, '~A')" rank country))) NIL CL-USER 5 > (query "select country from world_cup where rank < 3") (("Italy") ("France")) ("country")You can of course replace
"c:/tmp/example.db"with some other filename. For this example you should choose a file which doesn't exist yet.
See the CLSQL documentation for more details.
Load the libraries
described above. Here's an example that grabs an image from the
Internet and displays it in LispWorks:
CL-USER 6 > (defun show-jpg-from-web (url) (let ((tmp-file (merge-pathnames "tmp/foo.jpg" (probe-file (sys:get-folder-path :my-documents))))) (with-open-file (file-stream (ensure-directories-exist tmp-file) :direction :output :if-exists :overwrite :if-does-not-exist :create :element-type '(unsigned-byte 8)) (cl-fad:copy-stream (drakma:http-request url :want-stream t :force-binary t) file-stream)) (capi:contain (make-instance 'capi:image-pinboard-object :image (namestring tmp-file))))) SHOW-JPG-FROM-WEB CL-USER 2 > (show-jpg-from-web "http://www.science.uva.nl/~robbert/zappa/files/jpg/maestro2.jpg") ;; LispWorks should now display an image in a new window. #<CAPI:IMAGE-PINBOARD-OBJECT 200FC7BB>Remember: If there are any commands in the code above that you don't understand, click on them and press
ASDF is a system definition facility. It can be used, amongst other
things, to define which source files belong to a library and in which
order they have to be compiled and loaded. In this respect it is
There are other, similar systems
Common Defsystem, but the dominant system for open source
libraries nowadays is ASDF.
An ASDF system is described by a file with the
suffix. If you instruct ASDF to load a system called "foo", it will
try to find the
foo.asd file and proceed from there. If you
plan to only use ASDF to load libraries others have written, you only
need to know how to tell ASDF where to look for these "system
definitions." This is done via
ASDF:*CENTRAL-REGISTRY* which is a list
designators denoting directories. (I'm simplifying a bit. See
the ASDF manual for all
the gory details.)
On a Unix-y platform, most ASDF users really have one central
registry which is a directory to which they symlink all the system
definitions they have on their hard disk. Since Windows doesn't have
symbolic links (yeah, yeah, I know about "reparse points" aka
"junction points"), you have to use another approach. The approach
the "starter pack" uses is to put all libraries into one directory,
parse this directory for sub-directories which contain system
definitions, and add these sub-directories
ASDF:*CENTRAL-REGISTRY*. This happens
start.lisp is executed.
So, in order to add new Lisp libraries you've downloaded manually,
just unpack them into the "Lisp Libraries" folder mentioned above.
ASDF will know about this library after you've restarted LispWorks and
start.lisp again. As an alternative, you can evaluate
(cl-user::update-asdf-central-registry)in the current session.
This works fine unless you have different versions of the same library in the "Lisp Libraries" folder. So, don't do that...
For a slightly different approach to using ASDF on Windows see the
foo.asdwith the following contents:
(in-package :cl-user) (defpackage :foo-asd (:use :cl :asdf)) (in-package :foo-asd) (defsystem :foo :serial t :components ((:file "packages") (:file "file1") (:file "file2") (:file "file3")) :depends-on (:cl-ppcre :clsql))The
:FILEcomponents are the source files (with a
.lispsuffix) that comprise your application. They must also be located in the "foo" directory.
packages.lisp should always be there and it
should always be the first one (see next
supposed to be the files containing your source code and of course
there can be more (or less) than three and they can have different
:SERIAL option means that your files will be compiled and
loaded in the order they are specified. The list
:DEPENDS-ON lists the libraries the presence of
which your code will require in order to work.
:CLSQL with what your
code really needs.
packages.lispwill only contain a DEFPACKAGE form. The minimal version of this file should look like this:
(in-package :cl-user) (defpackage :foo (:use :cl))Of course, you can use other packages here, and you probably want to export some symbols.
Note that we used the same name "foo" for the ASDF system as well as for the Lisp package, but these are different things! It is just a usual habit to do it like this. See Peter's chapter about packages for more information.
file1.lispand so on) should have
(in-package :foo)as their first line.
If you edit code, don't (re)define functions in the listener. Instead, edit directly within the source files and use the editor's compilation commands.
For a more detailed explanation of ASDF
LispStarterPack.exedoes: It downloads the libraries you've specified and unpacks them into the "Lisp Libraries" folder. It also puts ASDF itself there as well as the file
start.lispwhich is pulled from my my website.
start.lisp, which is supposed to be loaded after you've started LispWorks, tells ASDF where to look for system definitions and sets up some stuff for LW-ADD-ONS.
If you've selected CLSQL amongst
the libraries you want to download, the DLL
for SQLite will also be
start.lisp will modify
PATH environment variable so Windows will find this
DLL while LispWorks is running. (If you want to play with CLSQL, you
can also connect to
an ODBC source or
to a PostgreSQL database
back-end. For other types of SQL databases,
or MySQL, you will have to install
the corresponding DLLs yourself.)
The source code for
LispStarterPack.exe including this
website is available
and the program can download and install its own source code in case
you want to inspect it. (Load the
and call the function
Note: Currently (as of August 16, 2006) the program has to use an
of ZIP which I
keep at http://weitz.de/files/zip-cvs-2006-08-16.tar.gz
on my website. The latest release version doesn't work with Windows
and/or LispWorks. This will be changed as soon as a new release is out. See also next section.
For a better, albeit not perfect approach to deal with this problem, see ASDF-INSTALL.
LispStarterPack.exeprobably can't download anything. It will query the Windows registry for the static proxy settings and adhere to them, but it won't be able to cope with per-connection proxy settings or with proxies which require authentication.
.lw-init.lisp(note the initial dot) in your home directory, this will be automatically loaded after
start-lisp, so you can put arbitrary initialization code her.
You can also add libraries to the ones that are hard-coded into
the application if you want. Likewise, you can
overwrite the default download URLs. This is done by creating a file
config.lisp in the same directory where the
application resides. The application will read this file when it
starts up and it will add library definitions found therein to the
ones it already knows. A library definition in this case is
with three or more elements where the second and third elements
and all other elements
The first element is the name of the library which will be shown in
the graphical user interface next to the checkbox and which is used to
uniquely identify the library. The second element is a textual
description which will be used for the tooltip. The third element is
the download URL. And the following elements (if any) denote other
libraries this one depends on. These libraries must also be known to
the application or it will refuse to start.
An example config file could look like this:
(:cl-wbxml "WBXML parser." "http://weitz.de/files/wbxml.tar.gz" :flexi-streams) (:uffi "Portable access to C libraries." "http://files.b9.com/uffi/uffi-1.5.15.tar.gz")The first expression adds the CL-WBXML library to the ones which should be downloaded, and the second one replaces the default download URL for the UFFI library with one that always loads version 1.5.15. The second expression replaces the original UFFI definition because the keyword
:UFFIuniquely identifies this library.
Download URLs must always be HTTP or HTTPS
(see this remark about
SSL) URLs, and the types of the archives that are downloaded must
.tar. Libraries added this way must obviously have
an ASDF system definition in order to be useful.
Most code you will find at (for example)
the Common Lisp
and Common-Lisp.net will have
For another example for a config file
If you don't know what I'm talking about below, just skip this section.
emergeor OS X's
Finkto help with Lisp installations.
For Linux, you should also check out clbuild. For OS X, read Bill Clementson's blog entry.
LispStarterPack.exe? Why is that?
Well, I selected libraries according to the following criteria: They have a reasonable license, I know them and have worked with them, they work with Windows, they use ASDF, they don't use the foreign function interface (FFI), they don't duplicate functionality provided by other libraries in the list. (CLSQL was allowed to violate the point about not using the FFI because it's pretty popular, but otherwise I didn't fancy dealing with DLLs.)
If you think a specific library should definitely be added, contact
me. Or use the customization option.
Redistributions must reproduce the above copyright notice, this condition, and the following disclaimer in the document itself and/or other materials provided with the distribution.IMPORTANT: This document is provided by the author "as is" and any expressed or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the author be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this documentation, even if advised of the possibility of such damage.
$Header: /usr/local/cvsrep/starter-pack/doc/index.html,v 1.88 2011-02-11 19:56:07 edi Exp $
BACK TO MY HOMEPAGE