Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the deploy Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:26:20 2022 GMT+0.
Next: Systems, Previous: The deploy Reference Manual, Up: The deploy Reference Manual [Contents][Index]
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: The deploy Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Tools to aid in the deployment of a fully standalone application.
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(GIT https://github.com/Shinmera/deploy.git)
zlib
1.0.0
Next: Packages, Previous: Systems, Up: The deploy Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: deploy/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
deploy (system).
Next: deploy/toolkit.lisp, Previous: deploy/deploy.asd, Up: Lisp [Contents][Index]
deploy (system).
Next: deploy/library.lisp, Previous: deploy/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
deploy (system).
Next: deploy/hooks.lisp, Previous: deploy/toolkit.lisp, Up: Lisp [Contents][Index]
toolkit.lisp (file).
deploy (system).
Next: deploy/deploy.lisp, Previous: deploy/library.lisp, Up: Lisp [Contents][Index]
library.lisp (file).
deploy (system).
*hooks* (special variable).
Next: deploy/osx.lisp, Previous: deploy/hooks.lisp, Up: Lisp [Contents][Index]
hooks.lisp (file).
deploy (system).
Next: deploy/documentation.lisp, Previous: deploy/deploy.lisp, Up: Lisp [Contents][Index]
deploy.lisp (file).
deploy (system).
*info-plist-readtable* (special variable).
Next: Definitions, Previous: Files, Up: The deploy Reference Manual [Contents][Index]
Packages are listed by definition order.
org.shirakumo.deploy
common-lisp.
Next: Indexes, Previous: Packages, Up: The deploy Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [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
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
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.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [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:
- :load These functions should perform the loading of
systems or other kinds of things that will
potentially change the set of libraries.
- :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
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
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
Next: Generic functions, Previous: Macros, Up: Public Interface [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.
Return an absolute path to the resource directory.
See DATA-DIRECTORY
Returns T if the current Lisp environment has been booted from a deployed executable.
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
Returns the value of the given environment variable if it is set to a non-empty value.
Accessor to the hook instance of the given type and name.
See *HOOKS*
See HOOK
See REMOVE-HOOK
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
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
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.
Remove the hook of the given type and name.
See *HOOKS*
See HOOK
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
Returns a pathname to the directory where the executable is being run in.
See UIOP:ARGV0
Print a status message to *status-output*.
The level determines the granularity of the message.
Higher levels mean "more detailed".
See *STATUS-OUTPUT*
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Close/unload the library.
See CFFI:CLOSE-FOREIGN-LIBRARY
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
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
Accessor to the function of the hook.
This function is what is executed when RUN-HOOKS
is called.
See HOOK
See RUN-HOOKS
Accessor to the name of the hook.
The name should be a symbol.
See HOOK
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
Accessor to the type of the hook.
The type can be one of :LOAD :BUILD :DEPLOY :BOOT :QUIT.
See HOOK
Accessor to whether to deploy (copy) the library to the resources directory on build.
See LIBRARY
Accessor to whether the library should not be opened on boot.
See LIBRARY
Return the library’s name.
See CFFI:FOREIGN-LIBRARY-NAME
Returns whether the library is currently open.
See CFFI:FOREIGN-LIBRARY-LOADED-P
Accessor to the definite path to the library’s source file.
If this is NIL, the library could not be found.
See LIBRARY
Accessor to the list of additional paths to search for source files.
See LIBRARY
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
Open/load the library.
See CFFI:LOAD-FOREIGN-LIBRARY
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
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
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
asdf/action.
Previous: Standalone methods, Up: Public Interface [Contents][Index]
An ASDF operation to perform a deployment.
When this operation is performed, the following steps
are taken:
1. The :LOAD hooks are run with the appropriate
arguments.
2. 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.
3. 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.
4. The deployment directories are created.
5. The *DATA-LOCATION* path is adapted to be relative
to the binary file.
6. The :DEPLOY hooks are run with the appropriate
arguments.
7. The :BUILD hooks are run with the appropriate
arguments.
8. 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
program-op.
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
| Initarg | Value |
|---|---|
| :name | (error name required.) |
| :type | (error type required.) |
| :function | (constantly nil) |
| :priority | 0 |
:name
common-lisp.
:type
common-lisp.
:function
:priority
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
foreign-library.
:system
:sources
:path
:dont-open
:dont-deploy
This deployment op generates an OS X app bundle.
See DEPLOY-OP
See PARSE-INFO-PLIST
See *INFO-PLIST-TEMPLATE*
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [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.
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
Custom readtable used to parse parts of the info plist.
Previous: Special variables, Up: Internals [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
Returns all files and subdirectories within the given pathname’s directory.
Return a list of all directories contained in the path.
This includes the path itself.
Returns the paths contained in the given environment variable.
For Windows systems, the split character is ;
otherwise it is :
See SPLIT
See UIOP:GETENV
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.
Create a pathname with the proper type for a library.
The type is OS-dependent.
Linux: "so"
Darwin: "dylib"
Windows: "dll"
Return the full file name of the pathname as a string.
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
Split the string on each split character.
Empty subsequences are not included.
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*.
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
Escape the string for XML.
The following replacements are made:
"<" => "<"
">" => ">"
"&" => "&
Previous: Definitions, Up: The deploy Reference Manual [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 types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
D F N P S T |
|---|
| Jump to: | *
D F N P S T |
|---|
| Jump to: | C D F H L O P S T |
|---|
| Jump to: | C D F H L O P S T |
|---|