lispx-proxy

About

lispx-proxy (Lisp Execution Proxy) is a Windows utility that makes Lisp software easily invokable from the command-line and Windows Explorer. CLI *nix port is also available. It allows to create relatively complex self-contained cross platform executable source code distributions which require zero configuration to run.

Motivation

Because of the restricted Windows command processor abilities it is hard to create such scripting tools as cl-launch based on Windows command processor language. This tool relies mostly on metadata and predefined filesystem structure rather than the capabilities of system shell instead.

lispx-proxyDownloads

Examples

Examples of lispx-proxy scripts and executable source distributions could be downloaded separately (the examples may be a little bit outdated now).

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 type the `lispx' command in your command prompt followed by a script or a `.lispx' file name (it's not necessary to specify a file extension for the supported file types). You may also just type `lispx' without arguments under the directory of a preconfigured self-contained package. It is assummend that the language interpreter used by the application could be found through the PATH environment variable. All options unrecognized by lispx-proxy will be passed to the launched script or application and will be available as a list (which should be considered as constant) through the argument access variables specified in Table 1. If the 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 `~/.lispx/cache' 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 (a 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 (here, for example, you may register ASDF systems needed in plain Lisp scripts).

Configuration file options may be overriden by environment variables with the same name.

Creating packaged distributions

It's possible to create relatively complex self-contained Common Lisp, Clojure or Scheme source code distributions which could be executed by lispx-proxy. To make the launch process straightforward, lispx-proxy relies on 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 1.x project. It is 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.

What happens before launch

Entire directory subtree of the distribution `shared' folder will be added to the PATH environment variable of the launched Lisp process, so it is 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' (containing code in any supported language) will be loaded before the application entry point invocation (see the 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 is possible to override the default command line options of a language interpreter (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.

Options with spaces should be placed inside the double quotes (escaped with backslashes in the case of metadata), as in the example below. The %app-root% macro is substituted to the absolute path of the distribution could be used in metadata entries.

(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 into a single archive by executing the `lispx' command inside the distribution directory with the `--package' option which accepts destination package file name (without an extension) as an argument. It is also possible to create packages by using any archiving tool which is able to produce files in zip/deflate format.

Credits

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