# Obtaining, Installing, and Running &CCL;

## Releases and System Requirements

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

&CCL; runs on the following platforms:

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

- Mac OS X 10.4 and later (x86, x86-64, ppc32, ppc64)

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

- Solaris (x86, x86-64)

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

### 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.

### 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 (ppc and x86)

&CCL; runs under Mac OS X versions 10.4 and later. Post-1.4 versions will require at least 10.5.

64-bit versions of &CCL; naturally require 64-bit processors (e.g., a G5 or Core 2 processor). 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.

### Microsoft Windows

At the moment, the 32-bit &CCL; does not run under 64-bit Windows.

## Obtaining &CCL;

There two main 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 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.

### Getting &CCL; with Subversion

It is very easy to download, install, and build &CCL; using Subversion. 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.

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, the following command will fetch a copy of the trunk for Darwin x86 (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

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. To get the 1.4 release of &CCL; type:

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

The above command will fetch the complete sources and binaries for the Darwin x86 build of &CCL;. To get a &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

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.

Once the checkout is complete you can build &CCL; by running the lisp kernel and executing the `rebuild-ccl` function. For example:

    joe:ccl> ./dx86cl64
    Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
    ? (rebuild-ccl :full t)

    <lots of compilation output>

      ? (quit)
      joe:ccl>

If you don't have a C compiler toolchain installed, `rebuild-ccl` will not work. Please refer to for addtional details.

#### Checking Subversion Installation

If `svn co` doesn't work, then 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 Packages page.

### Tarballs

Tarballs 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.

## 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.

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 in your .cshrc, .tcshrc, .bashrc,.bash_profile, .MacOSX/environment.plist, or wherever you usually set environment variables. If there is an existing definition of the variable, 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:

    > ccl [args ...]
    Welcome to &CCL; Version 1.2 (DarwinPPC32)!
    ?

The ccl shell script passes all of its arguments to the &CCL; kernel. See for more information about these arguments. When invoked this way, the Lisp 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/alms/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

`ccl` runs a 32-bit session; `ccl64` runs a 64-bit session.

## 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 the 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.)