lispx-proxy

About

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.

Motivation

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.

lispx-proxy Command Line Options

Usage: lispx [script/application file] [options] [script args¹]

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 implementation²
  -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 distribution³
  -C [ --change-dir ] arg     change the working directory
  --clear-cache               clear lispx-proxy application cache⁴
  --silent                    do not print anything to the standard output⁵
  --dump                      create a fast-loadable image of the application⁶
  --executable                produce an executable binary
  --repl                      launch the REPL
  --help                      print this help message
  --version                   display lispx-proxy version

¹ See Table 1 for the information about script argument access.
² See Table 3 for the list of supported implementations.
³ See the Creating packaged distributions section for details.
⁴ See the Usage section for details.
⁵ On Windows the application tray icon will also not be shown.
⁶ No access to the command-line arguments, the resulting application may be not relocable.

Usage

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.

Compatibility

Table 1, Supported Languages

Language Name	Variable to access script arguments	Variable get the application directory	Default Implementation
Common Lisp	lispx:argv	lispx:app-root	Clozure CL
Clojure	lispx/argv	lispx/app-root	Clojure for JVM
Scheme	lispx/argv	lispx/app-root	Racket

Table 2, Supported File Types

File extensions	Language	Comment
.lisp, .lsp, .cl	Common Lisp	-
.clj	Clojure	-
.scm, .rkt	Scheme	-
.lispx	Any of above	Language should be defined in metadata, Common Lisp is the default
.lispxz, .zip	Any of above	Packaged executable source distributions

Table 3, Implementation Details

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)
	SBCL	sbcl	sbcl	--noinform
	CLISP	clisp	clisp	--quiet --silent
	ABCL	abcl	java	org.armedbear.lisp.Main --noinform
	ECL	ecl	ecl	-q
Clojure	Clojure for JVM	clojure	java	clojure.main
Scheme	Racket	racket	racket

Configuration

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.

Per-language options

default_implementation - overrides the default language implementation (see Table 3 for details).

Per-implementation options

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.

Creating packaged distributions

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.

lispx-proxy Executable Source Distribution Filesystem Structure

All languages	Clojure specific¹	Description
shared/	lib/, lib/dev/, resources/	[shared libraries, Java jar-packages² 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]

¹ Clojure-specific filesystem structure corresponds to the structure of a Leiningen project. It's possible to launch a configured Leiningen 1 project as-is just by adding application.lispx and application.meta files to the project folder. Because Leiningen 2 loads dependencies directly from its Maven repository, it's necessary to add dependencies manually in this case.
² Will be automatically added to the classpath.

Preconditions

Entire directory subtree of the distribution `shared' folder will be added to the PATH environment variable of the launched Lisp process, so it's possible to launch applications and load shared libraries placed in these directories from the Lisp application. lispx-proxy will stop further directory scanning when it finds a file named `.noindex' contained in a directory, so it possible to exclude a directory subtree from being added to PATH, placing this file into the subtree root.
Paths of all subdirectories of the `source' and `systems' folders will be added to the Lisp asdf:*central-repository* variable (in the case of a Common Lisp application), therefore all ASDF systems placed there will be accessible by the application.
File `application.lispx' will be loaded before the application entry point invocation (see section on metadata).

lispx-proxy Metadata

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.

Overriding the Default Command Line Options

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"))

Packaging

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

Examples of lispx-proxy scripts and executable source distributions could be downloaded separately at the project's sourceforge download group.

Credits

This work uses parts of Conrad Barski's Lisp Logo.