# Obtaining, Installing, and Running &CCL;

## Releases and System Requirements

As of this writing, &CCL; 1.7 is the latest release; it was made in August 2011. For up-to-date information about releases, please see .

&CCL; 1.7 runs on the following platforms:

- Linux (x86, x86-64, ppc32, ppc64, armv7)

- Mac OS X 10.5 and later (x86, x86-64)

- FreeBSD 6.x and later (x86, x86-64)

- Solaris (x86, x86-64)

- Microsoft Windows XP and later (x86, x86-64)

### 32- vs 64-bit versions

Naturally, 64-bit versions of &CCL; require 64-bit processors, for example, a G5 or Core 2. Some early Intel-based Macintoshes used processors that don't support 64-bit operation, so the 64-bit &CCL; will not run on them, although the 32-bit &CCL; will.

### 32-bit x86 versions require SSE2

The 32-bit x86 versions of &CCL; depend on the presence of the SSE2 instructions. Most x86 processors manufactured and sold in the last several years support SSE2 (all Apple Intel-based Macs do, for instance), but there are some exceptions. The Wikipedia article on SSE2 lists processor models that support SSE2 (and also mentions some of the more notable exceptions).

### LinuxPPC

&CCL; requires version 2.2.13 (or later) of the Linux kernel and version 2.1.3 (or later) of the GNU C library (glibc) at a bare minimum.

### Linux x86

Because of the nature of Linux distributions, it's difficult to give precise version number requirements. In general, a "fairly modern" (no more than 2 or three years old) kernel and C library are more likely to work well than older versions.

### Linux ARM v7

The Linux ARM port is relatively new and is still a work-in-progress. &CCL; needs some features (such as hardware floating-point, locking and memory-serialization primitives) that are only found in chips that implement architecture version 7 (ARMv7); technically, it needs the ARMv7 "application profile", which is sometimes called ARMv7a. In practice, most ARM consumer devices released in the last few years implement ARMv7, but there are exceptions, and it is not practical to enumerate all of the ARM devices that CCL should run on.

In addition to hardware issues, &CCL; expects Linux to run in little-endian mode and expects software to follow "soft float" calling conventions. The latter has to do with how C functions accept floating-point arguments and return floating-point values.

### FreeBSD x86

&CCL; should run on FreeBSD 6.x and 7.x. FreeBSD 7 users will need to install the "compat6x" package in order to use the distributed &CCL; kernel, which is built on a FreeBSD 6.x system.

### Mac OS X x86

&CCL; 1.7 runs on Mac OS X (x86) versions 10.5 and later, including 10.7 (Lion),

&CCL; 1.6 runs on Mac OS X PPC as well as x86 processors.

### Microsoft Windows

For &CCL; versions prior to 1.7, the 32-bit executable does not run under 64-bit Windows.

## Obtaining &CCL;

There are three ways to obtain &CCL;. For Mac OS X, there are disk images that can be used to install &CCL; in the usual Macintosh way. For other OSes, Subversion is the best way to obtain &CCL;. Mac OS X users can also use Subversion if they prefer. Tarballs are available for those who prefer them, but if you have Subversion installed, it is simpler and more flexible to use Subversion than tarballs.

There are three popular ways to use &CCL;: as a stand-alone double-clickable application (Mac OS X only), as a command-line application, or with Emacs and SLIME.

The following sections describe these options.

### The Mac Way

If you are using Mac OS X then you can install and use &CCL; in the usual Macintosh way. Download and mount a disk image, then drag the ccl folder to the Applications folder or wherever you wish. After that you can double-click the Clozure CL application found inside the ccl directory. The disk images for version 1.7 are available at

So that &CCL; can locate its source code, and for other reasons explained in , you keep the Clozure CL application in the `ccl` directory. If you use a shell, you can set the value of the `CCL_DEFAULT_DIRECTORY` environment variable to explicitly indicate the location of the `ccl` directory. If you choose to do that, then the `ccl` directory and the Clozure CL application can each be in any location you find convenient.

### Tarballs

Tarball distributions of &CCL; release version 1.7 are available at . Download and extract one on your local disk. Then edit the &CCL; shell script to set the value of `CCL_DEFAULT_DIRECTORY` and start up the appropriate &CCL; kernel. See for more information about the &CCL; shell scripts.

### Getting &CCL; with Subversion

It is very easy to download and configure &CCL; to obtain sources from the Subversion repository. This is the preferred way to get either the latest, or a specific version of &CCL;, unless you prefer the Mac Way. Subversion is a source code control system that is in wide use. Many OSes come with Subversion pre-installed. A complete, buildable and runnable set of &CCL; sources and binaries can be retrieved with a single Subversion command.

Unless stated otherwise, examples in this chapter are given for Mac OS X in particular or Unix-based host environments in general.

For Windows, special care must be taken to install a working development environment. For more information see the &CCL; Wiki at URL:

#### Checking Subversion Installation

Make sure that Subversion is installed on your system. Bring up a command line shell and type:

    shell> svn

If Subversion is installed, you will see something like:

    Type 'svn help' for usage

If Subversion is not installed, you will see something like:

    -bash: svn: command not found

If Subversion is not installed, you'll need to figure out how to install it on your OS. You can find information about obtaining and installing Subversion at the Subversion web page.

#### Downloading &CCL; Using Subversion

Before you download &CCL; you should consider: Do you want to run the most recent source code, or the current stable release version? If you don't know how to answer this question, then you probably want the release version.

##### Downloading the Trunk

Day-to-day development of &CCL; takes place in an area of the Subversion repository known as "the trunk". At most times, the trunk is perfectly usable, but occasionally it can be unstable or totally broken. If you wish to live on the bleeding edge, download sources from the trunk.

For example, the following command will fetch a copy of the trunk for Mac OS X (Darwin) with x86 processors (both 32- and 64-bit versions):

    svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx86/ccl

To get a trunk &CCL; for another platform, replace "darwinx86" with one of the following names (all versions include both 32- and 64-bit binaries):

- darwinx86

- linuxx86

- freebsdx86

- solarisx86

- windows

- linuxppc

- darwinppc

##### Downloading a Release Version

Release versions of &CCL; are intended to be stable. While bugs will be fixed in the release branches, enhancements and new features will go into the trunk. If you wish to run the stable release, the following command will fetch a copy of the release version 1.7 for Mac OS X (Darwin) with x86 processors (both 32- and 64-bit versions):

    svn co http://svn.clozure.com/publicsvn/openmcl/release/1.7/darwinx86/ccl

To get the release version of &CCL; for another platform, replace "darwinx86" with one of the following names:

- darwinx86

- linuxx86

- freebsdx86

- solarisx86

- windows

- linuxppc

- darwinppc

These distributions contain complete sources and binaries. They use Subversion's "externals" features to share common sources; the majority of source code is the same across all versions.

### Rebuilding &CCL; From Sources

This section explains how to peform a "full rebuild" of &CCL; from a source distribution.

After downloading &CCL; sources, you should rebuild &CCL; as described here. At the start of a full rebuild, object files in the `ccl` directory are deleted, which causes the build script to recompile the runtime kernel (C code) and high-level sources (Lisp), then save a new heap image. Doing a full rebuild helps to ensure that your local installation will run properly for your host OS environment.

In an interactive shell, a command sequence like the following will rebuild &CCL; in place:

    joe> cd /path/to/installed/ccl
    joe:ccl> ./kernel-filename --no-init
    Welcome to Clozure Common Lisp Version [...]
    ? (rebuild-ccl :full t)
    <...lots of compilation output...>
    ? (quit)
    joe:ccl>

Replace /path/to/installed/ccl with the path of the `ccl` directory that you downloaded.

Replace kernel-filename with the filename of the Lisp kernel program. To find the filename of a Lisp kernel image for your particular platform, see .

Specifying the `--no-init` option ensures that personal initializations do not interfere with rebuilding &CCL;.

The rest of this section covers the following topics in brief:

- Software prerequisites

- When to run the build process

- Using `ccl-rebuild`

- What happens during the full rebuild process

This section does not provide comprehensive documentation on the build process. Please refer to for more information. Those more detailed instructions are used mainly by developers who maintain, customize, and/or port &CCL;. If you are customizing &CCL;, or if you run into some exceptional situation, you may need to perform the individual build steps.

#### Software Requirements for Building &CCL;

In order to build &CCL; you must have a working system and development environment. There are different requirements and setup procedures for each platform, but the main requirement is to have a C compiler and a few other utilities: GNU `gcc` or `cc` with `ld` and `as`; `make`; and `m4`. Please refer to for details.

If you don't have the prerequisite C compiler toolchain installed, `rebuild-ccl` will not work. See for additional details.

Most distributions of Linux have all or most of the required development tools either pre-installed or readily available. On Debian-based Linux you can download and install the essential build tools using the package manager. For example:

    apt-get install build-essential

(You may need to install C header files separately.)

For Mac OS X, Xcode 4 is available from the App Store.

For Windows, install Cygwin and the MinGW toolchain for the 32- or 64-bit OS. More information about installing &CCL; on Windows is available in the &CCL; Wiki at URL:

#### When to Rebuild &CCL; From Sources

The most common scenario that requires a full rebuild is the standard installation after downloading the source tree. Users and application developers (who otherwise have no special build requirements) will generally need to run the full rebuild process just once for any given installation on a particular host system.

Another common scenario is installing a patch update: You can use Subversion (`svn update`) to download a more recent set of source files. (Be sure to download sources from the same path and branch in the source repository.) Then run a full rebuild to create new kernel and heap images. If you are running &CCL; from the trunk, you may need to update sources and run the full rebuild more often.

Another reason to do a full rebuild is to ensure that &CCL; will run properly in the host OS environment. This may be necessary, for example, when the target OS version is not identical to the one where the pre-built kernel was generated. The Lisp kernel uses some functionality defined in standard platform-provided libraries. On some platforms, applications (such as the Lisp kernel) are built in such a way as to depend on the specific versions of these libraries that were present at build time, and may not run on systems that have older or newer versions of these libraries. If you're affected by this, the simplest workaround is to build the Lisp kernel on the machine(s) that you intend to run it on and use that locally-built kernel instead of one distributed via Subversion.

#### Rebuilding &CCL; Using REBUILD-CCL

Once the checkout is complete, and provided that you have a working development setup, you can build &CCL; by running the Lisp kernel (an OS-native executable program) and running `REBUILD-CCL` in Lisp.

For example, to build a 64-bit &CCL; on Mac OS X:

    joe:ccl> ./dx86cl64 --no-init
    Welcome to Clozure Common Lisp Version 1.7  (DarwinX8664)!
    ? (rebuild-ccl :full t)
    Rebuilding Clozure Common Lisp using Version 1.7  (DarwinX8664)
    ;Building lisp-kernel ...
    ;Kernel built successfully.
    ;Compiling <...>
    ;Loading <...>

    <...lots of compilation output...>

    ;Wrote bootstrapping image: #P"/Users/joe/ccl/x86-boot64.image"
    ;Wrote heap image: #P"/Users/joe/ccl/dx86cl64.image"
    NIL
    ? (quit)
    joe:ccl>

If the build fails for any reason, the kernel and/or heap image files may be missing or corrupted. To recover, delete the image files and update the source directory from Subversion. For example:

    joe:ccl> rm dx86cl*
    joe:ccl> svn update
    <... lots of Subversion output...>
    joe:ccl> ./dx86cl64 --no-init
    Welcome to Clozure Common Lisp Version 1.7  (DarwinX8664)!
    ? (rebuild-ccl :full t)
    <... lots of compilation output...>
    ? (quit)
    joe:ccl>

Once the full rebuild is completed, you can run the new Lisp kernel from the command shell. However, running the OS- and processor-specific executable directly is not recommended for day-to-day use. &CCL; includes the `ccl` and `ccl64` command shell scripts. For details on configuring a shell script for your environment, see .

#### Summary of the Build Process Steps

Should the build fail, your first concern should be to confirm that all requirements are in place: the C compiler, utilities, and OS header files; source files for the trunk or release branch you want to build; and the Lisp kernel and heap image files. For assistance with trouble-shooting, here is an outline of the full build process, with links to the more detailed instructions in .

- Build the Lisp kernel ()

- Build the heap image ()

  - Create a bootstrapping heap image ()

  - Compile Lisp code to generate fasl files ()

  - Build a full image from bootstrapping image ()

    - Run new kernel with new bootstrapping image

    - Load Lisp code

    - Save a new full heap image

## Command Line Set Up

Sometimes it's convenient to use &CCL; from a Unix shell command line. This is especially true when using &CCL; as a way to run Common Lisp utilities.

### The ccl Shell Script

&CCL; needs to be able to find the `ccl` directory in order to support features such as `require` and `provide`, access to foreign interface information (see The Interface Database) and the Lisp build process (see Building &CCL; from its Source Code). Specifically, it needs to set up logical pathname translations for the `"ccl:"` logical host. If this logical host isn't defined (or isn't defined correctly), some things might work, some things might not, and it'll generally be hard to invoke and use &CCL; productively.

&CCL; uses the value of the environment variable `CCL_DEFAULT_DIRECTORY` to determine the filesystem location of the `ccl` directory; the ccl shell script is intended to provide a way to invoke &CCL; with that environment variable set correctly.

There are two versions of the shell script: `"ccl/scripts/ccl"` is used to invoke 32-bit implementations of &CCL; and `"ccl/scripts/ccl64"` is used to invoke 64-bit implementations. Install one script or the other or both as needed.

To use the script:

1. Copy the script to a directory that is on your `PATH`. This is often `/usr/local/bin` or `~/bin`. It is better to do this than to add `ccl/scripts` to your `PATH`, because the script needs to be edited, and editing it in-place means that Subversion sees the script as modified..

2. Edit the definition of `CCL_DEFAULT_DIRECTORY` near the beginning of the shell script so that it refers to your `ccl` directory. Alternately, set the value of the `CCL_DEFAULT_DIRECTORY` environment variable wherever you usually set per-user environment variables, in your `.cshrc`, `.tcshrc`, `.bashrc`, `.bash_profile`, or `.MacOSX/environment.plist` script, or system-wide in `/etc/profile` or `/etc/bashrc`. When the ccl script runs, if the process environment contains a definition of `CCL_DEFAULT_DIRECTORY`, the ccl script will not override it.

3. Ensure that the shell script is executable, for example:

   `$ chmod +x ~/ccl/ccl/scripts/ccl64`

   This command grants execute permission to the named script. If you are using a 32-bit platform, substitute "ccl" in place of "ccl64".

   The above command won't work if you are not the owner of the installed copy of &CCL;. In that case, you can use the "sudo" command like this:

   `$ sudo chmod +x ~/ccl/ccl/scripts/ccl64`

   Give your password when prompted.

   If the "sudo" command doesn't work, then you are not an administrator on the system you're using, and you don't have the appropriate "sudo" permissions. In that case you'll need to get help from the system's administrator.

Note that most people won't need both `ccl` and `ccl64` scripts. You only need both if you sometimes run 32-bit &CCL; and sometimes run 64-bit &CCL;. You can rename the script that you use to whatever you want. For example, if you are on a 64-bit system, and you only use &CCL; in 64-bit mode, then you can rename `ccl64` to `ccl` so that you only need to type "`ccl`" to run it.

Once this is done, it should be possible to invoke &CCL; by typing `ccl` or `ccl64` at a shell prompt:

    shell> ccl
    Welcome to Clozure Common Lisp Version 1.7  (DarwinX8632)!
    ?

The ccl shell script passes all of its arguments to the &CCL; kernel. See for more information about command-line arguments.

Assuming the shell script is configured and invoked properly, &CCL; should be able to initialize the `"ccl:"` logical host so that its translations refer to the `"ccl"` directory. To test this, you can call `probe-file` in &CCL;'s read-eval-print loop:

    ? (probe-file "ccl:level-1;level-1.lisp")  ;returns the physical pathname of the file
    #P"/Users/joe/my_lisp_stuff/ccl/level-1/level-1.lisp"

### Invocation

Assuming that the shell script is properly installed, it can be used to invoke &CCL; from a shell prompt:

    shell> ccl [args ...]

By convention `ccl` runs a 32-bit session; `ccl64` runs a 64-bit session. However, the name of the installed script(s) and the implementation that is invoked are customizable, as described in .

For details about command-line options see .

## Personal Customization with the Init File

By default &CCL; tries to load the file `"home:ccl-init.lisp"` or the compiled `"home:ccl-init.fasl"` upon starting up. &CCL; does this by executing `(load "home:ccl-init")`. If it's unable to load the file (for example because the file doesn't exist), &CCL; doesn't signal an error or warning, it just completes its startup normally.

On Unix systems, if `"ccl-init.lisp"` is not present, &CCL; will look for `".ccl-init.lisp"` (post 1.2 versions only).

The `"home:"` prefix to the filename is a Common Lisp logical host, which &CCL; initializes to refer to your home directory. &CCL; therefore looks for either of the files `~/ccl-init.lisp` or `~/ccl-init.fasl`.

Because the init file is loaded the same way as normal Lisp code is, you can put anything you want in it. For example, you can change the working directory, and load packages that you use frequently.

To suppress the loading of this init-file, invoke &CCL; with the `--no-init` option.

## Command Line Options

When using &CCL; from the command line, the following options may be used to modify its behavior. The exact set of &CCL; command-line arguments may vary per platform and slowly changes over time. The current set of command line options may be retrieved by using the `--help` option.

- `-h` (or `--help`). Provides a definitive (if somewhat terse) summary of the command line options accepted by the &CCL; implementation and then exits.

- `-V` (or `--version`). Prints the version of &CCL; then exits. The version string is the same value that is returned by `LISP-IMPLEMENTATION-VERSION`.

- `-K` `character-encoding-name` (or `--terminal-encoding` `character-encoding-name`). Specifies the character encoding to use for `*TERMINAL-IO*` (see ). Specifically, the `character-encoding-name` string is uppercased and interned in the KEYWORD package. If an encoding named by that keyword exists, `CCL:*TERMINAL-CHARACTER-ENCODING-NAME*` is set to the name of that encoding. `CCL:*TERMINAL-CHARACTER-ENCODING-NAME*` defaults to `NIL`, which is a synonym for `:ISO-8859-1`.

  For example:

      shell> ccl -K utf-8

  has the effect of making the standard CL streams use `:UTF-8` as their character encoding.

- `-n` (or `--no-init`). If this option is given, the init file is not loaded. This is useful if &CCL; is being invoked by a shell script that should not be affected by whatever customizations a user might have in place.

- `-e` `form` (or `--eval`). An expression is read (via `READ-FROM-STRING`) from the string `form` and evaluated. If `form` contains shell metacharacters, it may be necessary to escape or quote them to prevent the shell from interpreting them.

- `-l` `path` (or `--load` `path`). Loads file specified by `path`.

- `-T` `n` (or `--set-lisp-heap-gc-threshold` `n`). Sets the Lisp gc threshold to `n`. (see

- `-Q` (or `--quiet`). Suppresses printing of heralds and prompts when the `--batch` command line option is specified.

- `-R` `n` (or `--heap-reserve`). Reserves `n` bytes for heap expansion. The default is `549755813888`. (see )

- `-S` `n` (or `--stack-size` `n`). Sets the size of the initial control stack to `n`. (see )

- `-Z` `n` (or `--thread-stack-size` `n`). Sets the size of the first thread's stack to `n`. (see )

- `-b` (or `--batch`). Execute in "batch mode". End-of-file from `*STANDARD-INPUT*` causes &CCL; to exit, as do attempts to enter a break loop.

- `--no-sigtrap` An obscure option for running under GDB.

- `-I` `image-name` (or `--image-name` `image-name`). Specifies the image name for the kernel to load. Defaults to the kernel name with ".image" appended.

The `--load` and `--eval` options can each be provided multiple times. They're executed in the order specified on the command line, after the init file (if there is one) is loaded and before the toplevel read-eval-print loop is entered.

Finally, any arguments following the pseudo-argument `--` are not processed, and are made available to Lisp as the value of `ccl:*unprocessed-command-line-arguments*`.

## Using &CCL; with GNU Emacs and SLIME

SLIME (see the SLIME web page) is an Emacs mode for interacting with Common Lisp systems. &CCL; is well-supported by SLIME.

See the InstallingSlime topic on the &CCL; wiki for some tips on how to get SLIME running with &CCL;.

## Example Programs

A number (ok, a small number), of example programs are distributed in the "ccl:examples;" directory of the source distribution. See the README-OPENMCL-EXAMPLES text file in that directory for information about prerequisites and usage.

Some of the example programs are derived from C examples in textbooks, etc.; in those cases, the original author and work are cited in the source code.

Unless the original author or contributor claims other rights, you're free to incorporate any of this example code or derivative thereof in any of your own works without restriction. In doing so, you agree that the code was provided "as is", and that no other party is legally or otherwise responsible for any consequences of your decision to use it.

If you've developed &CCL; examples that you'd like to see added to the distribution, please send mail to the &CCL; mailing lists. Any such contributions would be welcome and appreciated (as would bug fixes and improvements to the existing examples.)