lispx-proxy (Lisp Execution Proxy) is a yet another Lisp application launcher, written in C++ and designed for use primarily on Windows, but *nix port with limited functionality is also available. Although it's intended to be used mainly with Lisp Cabinet (if you have the recent version of Lisp Cabinet installed, you already have lispx-proxy), standalone use is also possible. Moreover, lispx-proxy allows to create relatively complex cross platform executable source code distributions, which require zero configuration to run.
Because of restricted Windows default command processor abilities it's hard to create such scripting tools as cl-launch with Windows command processor language. The most obvious solution of this problem is to create a tool which relies mostly on metadata and predefined filesystem structure rather than scripting.
lispx-proxy incorporates this approach and also is aimed to be more than a script launching tool. It mimics cross platform Java/JAR packaged application distribution paradigm for Lisp and integrates itself into the Windows GUI shell, so it's possible to launch lispx-proxy executable source distributions as regular Windows applications. But lispx-proxy distributions should not be considered as a replacement for native compiled Lisp programs. lispx-proxy is intended to be used merely as a convenience tool, only when it's appropriate.
Usage: lispx [script/application file] [options] [script args1] The following options are available: -l [ --language ] arg specify the application language: lisp - Common Lisp [default] clojure - Clojure scheme - Scheme -i [ --implementation ] arg specify the application language implementation2 -c [ --command ] arg path to an interpreter executable -p [ --classpath ] arg classpath of a JVM based interpreter -b [ --init ] arg load the init file before executing the script -z [ --package ] arg create a packaged distribution3 -C [ --change-dir ] arg change the working directory --clear-cache clear lispx-proxy application cache4 --silent do not print anything to the standard output5 --dump create a fast-loadable image of the application6 --executable produce an executable binary --repl launch the REPL --help print this help message --version display lispx-proxy version
To use lispx-proxy issue the `lispx' command in your command prompt followed by a script or packaged distribution file name and required lispx-proxy command line switches listed at the previous section (it's not necessary to specify a file extension for the supported file types). All options unrecognized by lispx-proxy will be passed to the launched script and will be available as a list (which should be considered constant) through the argument access variables specified in Table 1. If script or package file name is relative and the file is absent in the current directory, lispx-proxy will search for it in the `~/.lispx/scripts' folder (where `~' is a path to the user's home dir.), so you can place often used utilities there.
When launching a packaged distribution, lispx-proxy extracts its content into a folder inside the lispx-proxy application cache located at the `~/.lispx/cache' directory and executes the application from there. After the package was installed into the application cache, its compressed file will be used as a `shortcut' for the application launch until its modification time or the application metadata are changed.
Note, that lispx-proxy never clears its cache, and you have to do this manually with the `--clear-cache' command line switch.
|Language Name||Variable to access
|Variable get the
|Common Lisp||lispx:*argv*||lispx:*app-root*||Clozure CL|
|Clojure||lispx/*argv*||lispx/*app-root*||Clojure for JVM|
|.lisp, .lsp, .cl||Common Lisp||-|
|.lispx||Any of above||Language should be defined in metadata,
Common Lisp is the default
|.lispxz, .zip||Any of above||Packaged executable source distributions|
|Language||Supported Implementations||Name for the --i lispx Option||Default Command||Default Command Line Options|
|Common Lisp||Clozure CL||ccl||wx86cl
(lx86cl on Linux)
(dx86cl on MacOSX)
|Clojure||Clojure for JVM||clojure||java||clojure.main|
lispx-proxy uses a file named `.lispxrc' found in the user's home directory as a configuration file (on Windows user's home directory may be defined with the `USERPROFILE' environment variable, if `HOME' env. variable is absent). There are two kind of options: per-language options and per-implementation options. For an instance see the example configuration file in the lispx-proxy installation directory.
default_implementation - overrides the default language implementation (see Table 3 for details).
command - overrides the default implementation executable name (full path may be specified).
classpath - sets the classpath of a JVM-based language implementation.
load - sets the default initialization file path for a given implementation.
Configuration file options may be overriden by environment variables with the same name.
It's possible to create relatively complex Common Lisp, Clojure or Scheme source code distributions which could be executed with lispx-proxy. To make the launch process simple for a user, lispx-proxy relies on a metadata and predefined filesystem structure of a distribution.
|All languages||Clojure specific1||Description|
|shared/||lib/, lib/dev/, resources/||[shared libraries, Java jar-packages2 and native applications, optional]|
|source/||src/||[application source, optional]|
|systems/||-||[third-party ASDF systems, optional]|
|application.ico||application.ico||[application tray icon, optional, Windows only]|
|application.lispx||application.lispx||[application root file, mandatory]|
|application.meta||application.meta||[application metadata, mandatory]|
Informally, lispx-proxy metadata is a s-expression with the following structure (all parts except the application name and version are optional):
(lispx-meta (application :name "The Application Name" :version "Version String" :author "Application Author" :subsystem gui|console :entry-point "entry-point-function" :url "entry-url") (language :name language-name :implementation implementation-name :command "path/to/an/interpreter" :classpath "jvm/classpath" :init "path/to/an/init/file" :args "override for the default cmd. line") (depends-on (systems :system-name-1 "system-name-2")) (actions ("Action 1" "http://localhost:8080/actions/act1") ("Action 2" "http://localhost:8080/actions/act2") "--"))
The `application' subexpression provides application versioning information and is used to generate lispx-proxy application cache hash values. The `subsystem' option has meaning only on Windows and `defines' the subsystem in which the application should run (the underlying Lisp process console window will not be shown if `gui' value is specified, which is the default). The `entry-point' option defines an application entry point function that will be invoked after the `application.lispx' file has been loaded. The application entry point should be a function with one optional argument, and it is mandatory only in the case of a fast loadable or executable application image creation. The `url' option may be used by external tools to get the entry URL of a web application.
The `language' subexpression options are correspond to the same parameterized lispx-proxy command-line options (the `name' option corresponds to the `language' command line option), except the `:args' option, which is used to override the default command line options, listed in Table 3 (for details see the section below). Command line options have preference over the metadata. It's possible to use the `%app-root%' macro (expands to the actual application root directory path) in the options which require path specification.
The `depends-on' subexpression may contain names of ASDF dependencies used by the Common Lisp application, which will have been preloaded before the load of the `application.lispx' file.
The `actions' subexpression allows to add action items to the application system tray context menu (Windows only), the URL specified in an action definition will be retreived by lispx-proxy using a HTTP GET request. The double dash (--) inserts a menu separator.
It's possible to override the default command line options (see Table 3) with the `:args' metadata key or the `lispx.<impl. name>.args' environment variable, where <impl. name> is the corresponding short implementation name from the Table 3.
The %app-root% macro could be used in the override, the options with spaces should be placed inside the double quotes (escaped with the backslashes in the case of metadata), for example:
(lispx-meta (application :name "Sample Clojure Server" :version "v0.1") (language :name clojure :classpath "%app-root%/source" :args "-server \"-Duser.home=%app-root%\" clojure.main"))
An executable source distribution could be packaged by executing the `lispx' command inside the distribution directory with the `--package' command line option which accepts destination package file name as an argument. It's also possible to create packages using any archiving tool which is able to produce files in zip/deflate format.
Examples of lispx-proxy scripts and executable source distributions could be downloaded separately at the project's sourceforge download group.
This work uses parts of Conrad Barski's Lisp Logo.
© 2010-2012 g/christensen (gchristnsngmail.com)