Abstract
This 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.)
LispStarterPack
from http://weitz.de/files/LispStarterPack.zip
and unpack the ZIP archive.
LispStarterPack.exe
and 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.exe
again, 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.lisp
that 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 start.lisp
every
time you start LispWorks. LispWorks knows the concept of an
initialization file which is read on startup and you could
use 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
the Editor
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
multiple-value-bind
now.
If you then press the Space key, you'll see at the bottom of the listener (in the so-called "echo area") the argument list of the MULTIPLE-VALUE-BIND macro.
Now press 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
the LW-ADD-ONS
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
a shortcut.
Type an L
(the abbreviation for
"Load ASDF System") and the Return
key. The echo area now prompts for the name of the system to load.
Type hun
then press the Tab key. The name of
the system will automatically be completed
to hunchentoot
. Press Return to compile and
load the library.
Now do the same to load
the hunchentoot-test
library. (Note that you can
type hun
and hit Tab and you will
get hunchentoot
as a partial completion. Now
type -
(a hyphen) and Tab and you'll
get hunchentoot-test
.)
(Note: We loaded the two libraries individually for educational
purposes. It would have been enough to just
load hunchentoot-test
because ASDF would've taken care of
loading 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-sqlite3
(not clsql-sqlite
!) as described above. You
can now interact with an SQLite3 database of your choice. Here's an
example session:
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 drakma
and cl-fad
as
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
F5
.
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
pretty similar
to make
.
There are other, similar systems
like MK:DEFSYSTEM
or LispWorks'
Common Defsystem, but the dominant system for open source
libraries nowadays is ASDF.
An ASDF system is described by a file with the .asd
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
the special
variable ASDF:*CENTRAL-REGISTRY*
which is a list
of pathname
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
to ASDF:*CENTRAL-REGISTRY*
. This happens
when 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
executed 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
Windows
note here.
foo.asd
with
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
:FILE
components are the source files (with
a .lisp
suffix) that comprise your application. They
must also be located in the "foo" directory.
The file packages.lisp
should always be there and it
should always be the first one (see next
point). file1.lisp
through file3.lisp
are
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
names.
The :SERIAL
option means that your files will be compiled and
loaded in the order they are specified. The list
after :DEPENDS-ON
lists the libraries the presence of
which your code will require in order to work.
Replace :CL-PPCRE
and :CLSQL
with what your
code really needs.
packages.lisp
will 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.lisp
and 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
see Mario
Mommer's howto.
LispStarterPack.exe
does: 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.lisp
which 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
downloaded and start.lisp
will modify
the 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
using
the socket
back-end. For other types of SQL databases,
like Oracle
or MySQL, you will have to install
the corresponding DLLs yourself.)
The source code for LispStarterPack.exe
including this
website is available
from http://weitz.de/files/starter-pack.tar.gz
and the program can download and install its own source code in case
you want to inspect it. (Load the starter-pack
system
and call the function STARTER-PACK:MAIN
.)
Note: Currently (as of August 16, 2006) the program has to use an
unreleased version
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.
LispStarterPack.exe
.
For a better, albeit not perfect approach to deal with this problem, see ASDF-INSTALL.
LispStarterPack.exe
probably
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
called 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
a
Lisp list
with three or more elements where the second and third elements
are strings
and all other elements
are keywords.
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
:UFFI
uniquely 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
be .zip
, .tar
, .tar.gz
,
or .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
Directory, CLiki,
and Common-Lisp.net will have
one.
For another example for a config file
see the
lispbuilder project.
If you don't know what I'm talking about below, just skip this section.
apt
, Gentoo's emerge
or OS X's Fink
to 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 $