Quicklisp library bundles
Quicklisp library bundles are self-contained sets of systems that are exported from Quicklisp and loadable without involving Quicklisp. A library bundle has a directory structure that includes software archives, an index file, and a Lisp file that can be loaded to configure ASDF to understand how to load systems from the bundle. It also includes a directory, initially empty, that works like the local-projects mechanism, whereby any system in the bundle's local-projects directory takes precedence over other systems in the bundle.
Bundling works only for systems available through Quicklisp. It cannot find and bundle external ASDF systems and their sources.
Creating a bundle
Bundles are created with
* (ql:bundle-systems '("vecto" "zpb-exif") :to "my-bundle/") => #P"/Users/xach/my-bundle/bundle.lisp", #<QL-BUNDLE:BUNDLE 6 releases, 10 systems>
When creating a bundle for systems foo, bar, and baz, the directory structure looks like so:
- source code for foo
- source code for bar
- source code for baz
- initially empty
- local projects code
- more local projects code
The "bundled-local-projects/" subdirectory appears only if the include-local-projects argument to bundle-systems is true
Loading a bundle
In the following descriptions, loading a bundle refers to loading the bundle.lisp file created for a bundle.
When a bundle is loaded, the systems in the bundle are visible to
ASDF and can be found
(asdf:find-system system-name) and
(asdf:load-system system-name). Loading
a bundle does not load all the bundle's systems —
it just makes them available for later loading via ASDF.
By default, loading bundle.lisp will make the bundle's systems
load before any other systems known to ASDF. This is done
mechanism, which controls how ASDF finds systems.
Neither Quicklisp nor ASDF are required to load a bundle. ASDF
will be loaded on demand
and Quicklisp is not needed for loading the bundled system.
A newly-created bundle provides the systems indexed by its system-index.txt file.
It also includes a directory, local-projects, into which files and directories may be placed. Any file in the local-projects directory tree matching "*.asd" is added as a loadable system. These systems take precedence over systems in the system index file; if a system named "foo" is available both in the index and the local-projects directory, the local-projects version is loaded.
If two system files in the local-projects directory tree have the
same system name, the one with the shortest pathname
namestring takes precedence. When the two pathnames have the same
length, the one with the lesser (as determined
CL:STRING<) pathname takes precedence.
Loading more than one bundle
When more than one bundle is loaded, the systems of the most recently loaded bundle take precedence.
Reloading a bundle
A bundle can be loaded any number of times; each time it is loaded, its systems move to the front of the precedence list.
Overwriting a bundle
When given a to argument that points to an existing
will delete and recreate the software directory, and overwrite
bundle.lisp and system-index.txt. The local-projects directory and
any other files in to are left unchanged.
BUNDLE-SYSTEMS will signal a continuable
When looking up a system, the bundle system search code checks the timestamp of system-index.txt file and the local-projects directory. If either has an updated filesystem timestamp, the index is reloaded or the directory is re-scanned before continuing with the system lookup.
This allows the automatic detection of simple changes to a bundle's contents. If this automatic detection fails to pick up an expected change, the bundle itself can simply be reloaded to force an update.
Bundles are implemented by adding a symbol named
list. To disable all bundles, that symbol can be removed from the
list. Loading another bundle will re-initialize the bundle system
Creates a system bundle for system-names in the directory to.
For each system named by system-names, and each system required by those systems, recursively, unpacks the release archive in the
software/subdirectory of to.
If any system is not available via Quicklisp, signals an error of type
If overwrite is true (the default) and to already exists, deletes its
software/subdirectory before unpacking.
If overwrite is false and to already exists, signals a continuable error of type
If include-local-projects is true, each directory in ql:*local-project-directories is copied into "bundled-local-projects/" subdirectory of the bundle. Each local project directory is assigned a number in sequence from 0, and copied into a subdirectory named after that number. The number is used to avoid clashing references to local projects, which may have arbitrary names on the filesystem.
Returns the pathname to the bundle loader file as its primary value, and the bundle object itself as the secondary value.
The bundle object can be used with
QL-DIST:PROVIDED-RELEASESto get an exact list of its contents.
This condition is signaled when
:overwrite niland the to argument refers to a directory that already exists.
The directory in question can be accessed with the
This condition is signaled when
QL:BUNDLE-SYSTEMSis given a system name that is not available via Quicklisp.
The system name in question can be accessed with the