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.

You can read more about the deliver function in 4 Delivering your Application.

5 Keywords to the Delivery Function describes all the optional keyword arguments available.

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

The name of a startup function. This is the first function called when the application is run.
A pathname specifying where to write the delivered image.
A delivery level. This is an integer in the range 0 to 5. It controls how much work is done to make the image smaller during delivery. At level 0, little effort is put into making a smaller image, while at level 5 a variety of strategies are employed.

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 (macOS) 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 2.2.2 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 2.2.2 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" 
         0 
         :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-8-0-0-x86-win32.exe -build deliver.lisp
```
On Linux and other Unix-like platforms type the following into a shell:
```
% lispworks-8-0-0-x86-linux -build deliver.lisp
```
Note: the image name varies between the supported platforms.

On macOS, use Terminal.app. Ensure you're in the directory of the image first:
```
% cd "/Applications/LispWorks 8.0 (64-bit)/LispWorks (64-bit).app/Contents/MacOS"
% ./lispworks-8-0-0-macos64-universal -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 macOS, 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 macOS, if hcl:create-macos-application-bundle does not do what you need, please see 13.3.2 Alternative application bundle creation code for an alternative, but also please inform Lisp Support.

2.2.3 Further examples

There is another more detailed example later in this manual. This is in 13 Example: Delivering CAPI Othello, and shows how to deliver a small CAPI application. The application is an implementation of the board game Othello.

Further examples with complete code for delivering small applications are supplied in the LispWorks library. See 15 Self-contained examples of delivery.