Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the deploy Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:57:45 2020 GMT+0.
| • Introduction | What deploy is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
This is a system to help you easily and quickly deploy standalone common lisp applications as binaries. Specifically it is geared towards applications with foreign library dependencies that run some kind of GUI.
In order to make use of Deploy, you'll have to change the ASDF system definition of your project to contain the following properties:
:defsystem-depends-on (:deploy)
:build-operation "deploy-op"
:build-pathname "my-application-name"
:entry-point "my-package:my-start-function"
Once you have updated your system appropriately, all you need to do is start a fresh instance of your implementation from a terminal and run the following function:
(asdf:make :my-system)
This will build your system, gather the necessary information, and deploy a standalone bin folder within your project's root directory. You can then ship this folder to your users.
Sometimes you might want to designate a specific library for deployment, rather than the one used during development. If this is the case, you have to help Deploy out a little by defining extra information about the library with define-library. If the foreign library is in the source tree of a lisp library, you can simply associate the CFFI library with the system that provides it, and Deploy will find it automatically:
(deploy:define-library cffi-library-symbol
:system :system-name-that-defines-the-library)
For example, the cl-mpg123 system provides a single library, which we would annotate like this:
(deploy:define-library cl-mpg123-cffi:libmpg123
:system :cl-mpg123)
If the file is not contained in the directory of the system that provides it, you can also designate specific source directories to scan:
(deploy:define-library cffi-library-symbol
:sources '("/some/path/where/the/library/is/stored/"))
Finally, you can also specify the path directly if you want Deploy to choose a particular file, rather than trying to find one on its own:
(deploy:define-library cffi-library-symbol
:path "/some/path/to/the/file.so")
Generally though these extra associations should not be necessary as Deploy will simply take the path that CFFI has already figured out to find the library.
Sometimes it might not be desired to deploy all the libraries, or reload them all upon boot. You can change this behaviour with define-library's :dont-deploy and :dont-open properties respectively.
Deploy also offers a hooks system with which you can easily extend the steps performed during deployment and during the boot process of the generated executable. With the define-hook macro you can add functions that are executed during various points of the process. Specifically, the following types are available:
:deploy These functions are responsible for copying files into the deployment target directory.:build These functions should prepare the system for the dump to binary. Specifically you might want to shut down existing threads, close file handles, remove unneeded baggage, and remove potentially sensitive information about your system.:boot These functions are run right before the primary entry point is executed. Thus they are responsible for preparing the runtime to continue by restarting threads, re-opening files, and so forth.:quit These functions are run right before the executable exits completely. They offer a last-minute opportunity to dump some information about the system, or to clean up vital resources.If you would simply like to include a data directory to bundle with the rest, use define-resource-directory. After boot, all of the resource files will be in the directory returned by data-directory.
If you would like a nicely bundled .app for OS X, you can simply change the build-operation in your ASDF system file to osx-app-deploy-op. If you would like to customise the Info.plist file that is generated for the app, you can change *info-plist-template* to point to a file that contains what you want.
If you're having trouble with an application that's already deployed, there's a few things you can do to debug it by setting environment variables. The following are recognised by Deploy:
DEPLOY_DEBUG_BOOT if set to a non-empty value, on error the debugger is invoked rather than just exiting the application.DEPLOY_REDIRECT_OUTPUT if set to a file path, the output of all streams is redirected to this file.Particularly on Windows and OS X debugging can be an issue, as a GUI application will not get a standard output to write to. In that case, the above redirect might help. Alternatively, on Windows, you can build your binary with the feature flag :deploy-console present, which will force it to deploy as a console application.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The deploy system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shinmera/deploy.git")
Artistic
Tools to aid in the deployment of a fully standalone application.
1.0.0
deploy.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The deploy/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
deploy.asd
deploy (system)
Next: The deploy/toolkit․lisp file, Previous: The deploy․asd file, Up: Lisp files [Contents][Index]
Next: The deploy/library․lisp file, Previous: The deploy/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
deploy (system)
toolkit.lisp
Next: The deploy/hooks․lisp file, Previous: The deploy/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
deploy (system)
library.lisp
Next: The deploy/deploy․lisp file, Previous: The deploy/library․lisp file, Up: Lisp files [Contents][Index]
library.lisp (file)
deploy (system)
hooks.lisp
*hooks* (special variable)
Next: The deploy/osx․lisp file, Previous: The deploy/hooks․lisp file, Up: Lisp files [Contents][Index]
hooks.lisp (file)
deploy (system)
deploy.lisp
Next: The deploy/documentation․lisp file, Previous: The deploy/deploy․lisp file, Up: Lisp files [Contents][Index]
deploy.lisp (file)
deploy (system)
osx.lisp
*info-plist-readtable* (special variable)
Previous: The deploy/osx․lisp file, Up: Lisp files [Contents][Index]
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The deploy package |
package.lisp (file)
org.shirakumo.deploy
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Relative path designating the location of the resource directory.
This path should be relative to the location of
the executable.
You may set this variable before deployment to
influence where resource files are stored.
See DATA-DIRECTORY
toolkit.lisp (file)
This variable holds a pathname pointing to the Info.plist template to use for OS X app bundles.
See PARSE-INFO-PLIST
The output stream of status messages.
You can set this to NIL if you want to suppress status
messages on the console, or set them to some other
stream that won’t bother the user.
See STATUS
toolkit.lisp (file)
This variable holds a list of paths to system library directories.
Deploy will search through these paths to attempt to
find the source of libraries if the more explicitly
provided paths should fail.
library.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Define a new hook function.
The args list’s arguments are automatically turned into keyword arguments for the hook function. This allows you to only specify the arguments that you are interested in.
The following arguments are available for all hook types:
- SYSTEM The ASDF system object the application is built
with.
- OP The ASDF operation object used to build the
application.
The following hook types are recognised:
- :deploy These functions are responsible for copying
files into the deployment target directory.
It supplies the following extra arguments:
- DIRECTORY The target directory into which resource
files should be placed.
- :build These functions should prepare the system for
the dump to binary. Specifically you might
want to shut down existing threads, close file
handles, remove unneeded baggage, and remove
potentially sensitive information about your
system.
- :boot These functions are run right before the
primary entry point is executed. Thus they are
responsible for preparing the runtime to
continue by restarting threads, re-opening
files, and so forth.
It supplies the following extra arguments:
- DIRECTORY The directory in which the resource files
now reside after boot.
- :quit These functions are run right before the
executable exits completely. They offer a
last-minute opportunity to dump some
information about the system, or to clean up
vital resources.
See HOOK
See REMOVE-HOOK
hooks.lisp (file)
Define additional properties for a foreign library.
The NAME should be one of a valid CFFI foreign library as defined by CFFI:DEFINE-FOREIGN-LIBRARY.
Valid properties are:
- :SYSTEM
- :SOURCES
- :PATH
- :DONT-OPEN
- :DONT-DEPLOY
See LIBRARY
See LIBRARY-SYSTEM
See LIBRARY-SOURCES
See LIBRARY-PATH
See LIBRARY-DONT-OPEN-P
See LIBRARY-DONT-DEPLOY-P
library.lisp (file)
Shorthand to define a hook that simply deploys the given directory.
The directory has to be a form that evaluates to a
pathname to a directory that should be copied. The
path is merged with the system source directory of
the system being deployed. This means that relative
paths are relative to the source root of your system.
See DEFINE-HOOK
See COPY-DIRECTORY-TREE
hooks.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Copy the source directory to the target directory.
If COPY-ROOT is true, the source folder itself is copied, otherwise only its contents are copied.
toolkit.lisp (file)
Return an absolute path to the resource directory.
See DATA-DIRECTORY
toolkit.lisp (file)
Returns T if the current Lisp environment has been booted from a deployed executable.
deploy.lisp (file)
Return the corresponding LIBRARY instance, if possible.
The following happens for the following type of
the argument:
- LIBRARY The argument is returned.
- CFFI:FOREIGN-LIBRARY The object is CHANGE-CLASSd
into a LIBRARY instance.
- SYMBOL The library instance is
retrieved by name and then
passed back in.
See CFFI::GET-FOREIGN-LIBRARY
See LIBRARY
library.lisp (file)
Returns the value of the given environment variable if it is set to a non-empty value.
toolkit.lisp (file)
Accessor to the hook instance of the given type and name.
See *HOOKS*
See HOOK
See REMOVE-HOOK
hooks.lisp (file)
(setf hook) (function)
hooks.lisp (file)
hook (function)
Return a fresh list of known foreign libraries.
All the returned libraries will be of type LIBRARY.
See LIBRARY
See CFFI:LIST-FOREIGN-LIBRARIES
See ENSURE-LIBRARY
library.lisp (file)
Parses the Info.plist file and replaces values as appropriate.
Specifically, anything enclosed in [] is taken as a
list of symbols designating functions to call with
the system object. The resulting values are then
turned into a string by PRINC-TO-STRING, and escaped
for usage by XML-ESCAPED before writing them to
the returned string in place of the []. Note that you
can enclose multiple symbols. The value of the first
function call that returns non-NIL is used as the
value to splice into the file.
This allows to conveniently fill an Info.plist
template with values from the ASDF system.
Have a look at the standard Info.plist file shipped
with Deploy for what’s possible.
See *INFO-PLIST-TEMPLATE*
Runs the quit hooks and terminates the application.
If an error occurs during the execution of a quit hook, it
is ignored.
See RUN-HOOKS
deploy.lisp (file)
Redirect all output to the given file.
This changes *STANDARD-OUTPUT*, *ERROR-OUTPUT*,
*TRACE-OUTPUT*, and *DEBUG-IO*. For the latter,
only its output stream is changed.
The stream to the given target file is returned.
toolkit.lisp (file)
Remove the hook of the given type and name.
See *HOOKS*
See HOOK
hooks.lisp (file)
Run the hooks of the given type, supplying the given arguments.
Refer to DEFINE-HOOKS for the recognised arguments for
each hook type.
This function simply iterates through *HOOKS*, checks the
HOOK-TYPE for compliance, establishes a REPORT-ERROR
restart, and then applies the HOOK-FUNCTION to the given
arguments.
The REPORT-ERROR restart simply prints out the error it
receives and is thus useful for ignoring errors that
might occur during the execution of a hook.
See *HOOKS*
See HOOK-FUNCTION
See DEFINE-HOOK
hooks.lisp (file)
Returns a pathname to the directory where the executable is being run in.
See UIOP:ARGV0
toolkit.lisp (file)
Print a status message to *status-output*.
The level determines the granularity of the message.
Higher levels mean "more detailed".
See *STATUS-OUTPUT*
toolkit.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Close/unload the library.
See CFFI:CLOSE-FOREIGN-LIBRARY
library.lisp (file)
library.lisp (file)
Attempt to resolve the given ASDF system’s entry point to a function.
The entry point may be either a function or a class
designator. If a class, returned is a function that
simply instantiates the class.
See ASDF/SYSTEM:COMPONENT-ENTRY-POINT
deploy.lisp (file)
Attempt to find the source file of the library on the system.
Uses the directories listed in POSSIBLE-DIRECTORIES
to look for the library source.
The directories are searched for pathnames that
match one of the POSSIBLE-PATHNAMES for the library.
See POSSIBLE-DIRECTORIES
See POSSIBLE-PATHNAMES
library.lisp (file)
library.lisp (file)
Accessor to the function of the hook.
This function is what is executed when RUN-HOOKS
is called.
See HOOK
See RUN-HOOKS
(setf hook-function) (generic function)
automatically generated reader method
hooks.lisp (file)
hook-function (generic function)
automatically generated writer method
hooks.lisp (file)
Accessor to the name of the hook.
The name should be a symbol.
See HOOK
(setf hook-name) (generic function)
automatically generated reader method
hooks.lisp (file)
hook-name (generic function)
automatically generated writer method
hooks.lisp (file)
Accessor to the priority of the hook.
The priority should be an integer.
The higher the priority, the earlier the hook is
executed.
See HOOK
(setf hook-priority) (generic function)
automatically generated reader method
hooks.lisp (file)
hook-priority (generic function)
automatically generated writer method
hooks.lisp (file)
Accessor to the type of the hook.
The type can be one of :BUILD :DEPLOY :BOOT :QUIT.
See HOOK
(setf hook-type) (generic function)
automatically generated reader method
hooks.lisp (file)
hook-type (generic function)
automatically generated writer method
hooks.lisp (file)
Accessor to whether to deploy (copy) the library to the resources directory on build.
See LIBRARY
(setf library-dont-deploy-p) (generic function)
automatically generated reader method
library.lisp (file)
library-dont-deploy-p (generic function)
automatically generated writer method
library.lisp (file)
Accessor to whether the library should not be opened on boot.
See LIBRARY
(setf library-dont-open-p) (generic function)
automatically generated reader method
library.lisp (file)
library-dont-open-p (generic function)
automatically generated writer method
library.lisp (file)
Return the library’s name.
See CFFI:FOREIGN-LIBRARY-NAME
library.lisp (file)
library.lisp (file)
Returns whether the library is currently open.
See CFFI:FOREIGN-LIBRARY-LOADED-P
library.lisp (file)
library.lisp (file)
Accessor to the definite path to the library’s source file.
If this is NIL, the library could not be found.
See LIBRARY
(setf library-path) (generic function)
automatically generated reader method
library.lisp (file)
library-path (generic function)
automatically generated writer method
library.lisp (file)
Accessor to the list of additional paths to search for source files.
See LIBRARY
(setf library-sources) (generic function)
automatically generated reader method
library.lisp (file)
library-sources (generic function)
automatically generated writer method
library.lisp (file)
Accessor to the ASDF system associated with the library.
If there is a system associated with this library,
the system’s source tree is used to search for the
library’s source file.
See LIBRARY
(setf library-system) (generic function)
automatically generated reader method
library.lisp (file)
library-system (generic function)
automatically generated writer method
library.lisp (file)
Open/load the library.
See CFFI:LOAD-FOREIGN-LIBRARY
library.lisp (file)
library.lisp (file)
Return a list of possible directories to search for the library.
By default this list includes:
- The LIBRARY-SOURCES of the library.
- The directory tree of the LIBRARY-SYSTEM’s source.
- The CFFI:*FOREIGN-LIBRARY-DIRECTORIES*
- The *SYSTEM-SOURCE-DIRECTORIES*
- The paths from the following environment variables:
- PATH on Windows
- LD_LIBRARY_PATH on Linux
- DYLD_LIBRARY_PATH on Darwin
See LIBRARY-SOURCES
See LIBRARY-SYSTEM
See DISCOVER-SUBDIRECTORIES
See CFFI:*FOREIGN-LIBRARY-DIRECTORIES*
See *SYSTEM-SOURCE-DIRECTORIES*
See ENV-PATHS
library.lisp (file)
library.lisp (file)
Return a list of possible file pathnames that match the library.
By default this list includes:
- The CFFI:FOREIGN-LIBRARY-PATHNAME if present.
- Paths computed through the CFFI library’s spec.
- A generic path after the LIBRARY-NAME.
See CFFI:FOREIGN-LIBRARY-PATHNAME
See CFFI:DEFINE-FOREIGN-LIBRARY
See LIBRARY-NAME
See LIBRARY
See RESOLVE-CFFI-SPEC
library.lisp (file)
library.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
An ASDF operation to perform a deployment.
When this operation is performed, the following steps
are taken:
1. The output files are determined, which should be
a list of two paths, the first being the executable
to dump to, and the second being a directory where
all the resources should be stored.
2. The list of libraries to reload on boot is computed
by removing all libraries that are either marked as
dont-open, or aren’t yet opened from LIST-LIBRARIES.
3. The deployment directories are created.
4. The *DATA-LOCATION* path is adapted to be relative
to the binary file.
5. The :DEPLOY hooks are run with the appropriate
arguments.
6. The :BUILD hooks are run with the appropriate
arguments.
7. The image is dumped to an executable format, using
core compression if available, and using the
appropriate application type depending on the
presence of the operating system and the
:DEPLOY-CONSOLE feature flag.
See LIST-LIBRARIES
See *FOREIGN-LIBRARIES-TO-RELOAD*
See *DATA-LOCATION*
See FIND-RELATIVE-PATH-TO
See RUN-HOOKS
deploy.lisp (file)
program-op (class)
osx-app-deploy-op (class)
This class encapsulates a hook.
Hooks are functions that are run during various
points of deployment and execution of the resulting
executable.
See HOOK-NAME
See HOOK-TYPE
See HOOK-FUNCTION
See HOOK-PRIORITY
See HOOK
See REMOVE-HOOK
See DEFINE-HOOK
See RUN-HOOKS
hooks.lisp (file)
standard-object (class)
:name
hook-name (generic function)
(setf hook-name) (generic function)
:type
hook-type (generic function)
(setf hook-type) (generic function)
:function
hook-function (generic function)
(setf hook-function) (generic function)
:priority
hook-priority (generic function)
(setf hook-priority) (generic function)
| Initarg | Value |
|---|---|
| :name | (error "name required.") |
| :type | (error "type required.") |
| :function | (constantly nil) |
| :priority | 0 |
Class to represent a foreign library.
This is a subclass of CFFI:FOREIGN-LIBRARY with some
additional slots for information necessary for the
Deploy system.
Upon shared-initialize, if the LIBRARY-PATH is not
explicitly set, it is resolved through FIND-SOURCE-
FILE.
See LIBRARY-SYSTEM
See LIBRARY-SOURCES
See LIBRARY-PATH
See LIBRARY-DONT-OPEN-P
See LIBRARY-DONT-DEPLOY-P
See FIND-SOURCE-FILE
library.lisp (file)
foreign-library (class)
:system
library-system (generic function)
(setf library-system) (generic function)
:sources
library-sources (generic function)
(setf library-sources) (generic function)
:path
library-path (generic function)
(setf library-path) (generic function)
:dont-open
library-dont-open-p (generic function)
(setf library-dont-open-p) (generic function)
:dont-deploy
library-dont-deploy-p (generic function)
(setf library-dont-deploy-p) (generic function)
This deployment op generates an OS X app bundle.
See DEPLOY-OP
See PARSE-INFO-PLIST
See *INFO-PLIST-TEMPLATE*
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
This variable keeps a list of library instances to open on boot.
The variable is set during deployment and should not be modified unless you know what you’re doing.
deploy.lisp (file)
This variable holds a list of all hook instances.
The list should be sorted by priority of the hooks
in descending order.
See HOOK
See RUN-HOOKS
hooks.lisp (file)
Custom readtable used to parse parts of the info plist.
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Sets up a basic environment to run the entry point in.
In particular, it sets up an EXIT restart to allow you to quit the application, adds an error handler to handle the top-level errors, potentially redirects all output streams, executes the warm boot, and finally calls the entry point.
If an error should occur during boot or during the
execution of the entry point, a debugger is only invoked
if the environment variable DEPLOY_DEBUG_BOOT is set to a
non-empty value. Otherwise an error will lead to an exit
restart invocation.
If the environment variable DEPLOY_REDIRECT_OUTPUT is set
to a non-empty value, REDIRECT-OUTPUT is called with its
value.
See WARMLY-BOOT
See REDIRECT-OUTPUT
deploy.lisp (file)
Returns all files and subdirectories within the given pathname’s directory.
toolkit.lisp (file)
Return a list of all directories contained in the path.
This includes the path itself.
toolkit.lisp (file)
Returns the paths contained in the given environment variable.
For Windows systems, the split character is ;
otherwise it is :
See SPLIT
See UIOP:GETENV
toolkit.lisp (file)
Attempt to find a way to "get to" the target directory.
This tries to construct a relative path from the source to the target pathname, using :UP transforms in the pathname. If no relative path can be found, an error is signalled.
toolkit.lisp (file)
Create a pathname with the proper type for a library.
The type is OS-dependent.
Linux: "so"
Darwin: "dylib"
Windows: "dll"
toolkit.lisp (file)
Return the full file name of the pathname as a string.
toolkit.lisp (file)
deploy.lisp (file)
Resolve the CFFI foreign library spec to a list of usable pathnames.
This is the spec as used in CFFI:DEFINE-FOREIGN-
LIBRARY.
See CFFI:DEFINE-FOREIGN-LIBRARY
toolkit.lisp (file)
Split the string on each split character.
Empty subsequences are not included.
toolkit.lisp (file)
Returns T if the system-spec is applicable for the current system.
If system-spec is T, this returns T. Otherwise T is
returned if the system-spec is in *FEATURES*.
toolkit.lisp (file)
Perform a warm boot.
This updates the CFFI:*FOREIGN-LIBRARY-DIRECTORIES* variable
to a sensible value which should hopefully ensure that your
designated libraries are reloaded on boot.
This will also run all :BOOT hooks with the appropriate
arguments supplied.
See CFFI:*FOREIGN-LIBRARY-DIRECTORIES*
See RUN-HOOKS
deploy.lisp (file)
Escape the string for XML.
The following replacements are made:
"<" => "<"
">" => ">"
"&" => "&
toolkit.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | D F L |
|---|
| Jump to: | D F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
C D E F G H L M O P Q R S W X |
|---|
| Jump to: | (
C D E F G H L M O P Q R S W X |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
D F N P S T |
|---|
| Jump to: | *
D F N P S T |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C D H L O P S |
|---|
| Jump to: | C D H L O P S |
|---|