2.2 Delivering the program

Having developed and tested the program, the next step is to attempt delivery. You will compile the file containing the program source code, and load the fasl and call deliver in a fresh LispWorks session.

Programs are delivered with the function deliver. This function takes three mandatory arguments. There are also many optional keyword arguments to help Delivery make the smallest image possible, and also control some aspects of the behavior of the runtime that is created.

In this example, we use just one of the optional keyword arguments, and of course we provide the mandatory arguments. These are:

You can deliver and run the application in two ways: either use the LispWorks IDE, or use a command shell. This means a DOS command window (on Microsoft Windows), Terminal.app (Mac OS X) or a shell (Unix/Linux etc).

2.2.1 Delivering the program using the LispWorks IDE

You can use the Application Builder tool in the LispWorks IDE to deliver your application. This performs the same steps as described in Delivering the program using a command shell, but provides a windowing interface which is easier to use.

To start, you will need a script which loads your compiled application code. This can be as simple as

(in-package "CL-USER")

(example-compile-file "delivery/hello/hello" :load t)

but you can also start with a complete delivery script such as that shown in Delivering the program using a command shell.

For full instructions on using the Application Builder tool, see the LispWorks IDE User Guide .

2.2.2 Delivering the program using a command shell

Continuing with the example:

Write a delivery script file (deliver.lisp) that compiles and loads the program, and then calls deliver:

(in-package "CL-USER")

(load-all-patches)

(example-compile-file "delivery/hello/hello" :load t)

(deliver 'hello-world

         #+:cocoa

         (create-macos-application-bundle

          "~/Desktop/Hello.app"

          ;; Do not copy file associations...

          :document-types nil

          ;; ...or CFBundleIdentifier from the LispWorks bundle

          :identifier "com.example.Hello"

         #-:cocoa "~/hello"

         :interface :capi)

Run the LispWorks image passing your file as the build script. For example, on Microsoft Windows open a DOS window. Ensure you are in the folder containing the LispWorks image and type:


MS-DOS> lispworks-7-1-0-x86-win32.exe -build deliver.lisp

On Linux and other Unix-like platforms type the following into a shell:


% lispworks-7-1-0-x86-linux -build deliver.lisp

Note: the image name varies between the supported platforms.

On Mac OS X, use Terminal.app. Ensure you're in the directory of the image first:


% cd "/Applications/LispWorks 7.1 (32-bit)/LispWorks (32-bit).app/Contents/MacOS"

% ./lispworks-7-1-0-x86-darwin -build deliver.lisp

If you want to see the output, you can redirect the output with > to a file or use |, if it works on your system.

Run the application, which is saved in hello.exe on Microsoft Windows, Hello.app on Mac OS X, and hello on Linux and other Unix-like platforms.
Now generate a smaller executable by discarding unused code while delivering. Do this by editing your file deliver.lisp to specify a higher level argument in the call to deliver. Try changing it to 5 for the largest effect.

Note: On Mac OS X, if hcl:create-macos-application-bundle does not do what you need, please see Alternative application bundle creation code for an alternative, but also please inform Lisp Support.