Index: /trunk/source/doc/src/build.xml =================================================================== --- /trunk/source/doc/src/build.xml (revision 15043) +++ /trunk/source/doc/src/build.xml (revision 15044) @@ -250,23 +250,19 @@ the Subversion source control system. - For example, to get a released version (1.3 in this example), + For example, to get a released version (1.7 in this example), use a command like: - - svn co http://svn.clozure.com/publicsvn/openmcl/release/1.3/xxx/ccl - + svn co http://svn.clozure.com/publicsvn/openmcl/release/1.7/xxx/ccl To get the trunk version, use: - - svn co http://svn.clozure.com/publicsvn/openmcl/trunk/xxx/ccl - + svn co http://svn.clozure.com/publicsvn/openmcl/trunk/xxx/ccl - Change the "xxx" to one of the following names: + Change the xxx to one of the following names: darwinx86, linuxx86, freebsdx86, solarisx86, - window, + windows, linuxppc, or @@ -274,14 +270,51 @@ - In the case of released versions, there may also be tar archives - available. See the Clozure CL - Trac for details. + Tarball distributions of released versions are also available for download via ftp from: + . + For additional information about availability of source and distributions see the + Clozure CL Trac. Subversion client programs are pre-installed on Mac OS X 10.5 and later and are typically either pre-installed or readily available - on Linux and FreeBSD platforms. The Subversion web page contains links to subversion client programs - for many platforms; users of Mac OS X 10.4 can also - install Subversion clients via Fink or MacPorts. + on Linux and FreeBSD platforms. The Subversion web page contains links to Subversion client programs + for many platforms. + Users of Mac OS X 10.4 or later can also + install Subversion clients via Fink or MacPorts. + On Debian Linux (and on related Linux distros such as Ubuntu) run + apt-get install subversion or equivalent in the command-line or interactive package manager. + + + + + + + Kernel Build Prerequisites + The &CCL; kernel can be built with the following widely + available tools: + + cc or gcc — the GNU C compiler + ld — the GNU linker + m4 or gm4 — the GNU m4 macro processor + as — the GNU assembler (version 2.10.1 or later) + make — either GNU make or, on FreeBSD, the default BSD make program + + In general, the more recent the versions of those + tools, the better; some versions of gcc 3.x on Linux have + difficulty compiling some of the kernel source code correctly + (so gcc 4.0 should be used, if possible.) On Mac OS X, the + versions of the tools distributed with Xcode should work fine; + on Linux, the versions of the tools installed with the OS (or + available through its package management system) should work + fine if they're "recent enough". On FreeBSD, the installed + version of the m4 program doesn't support + some features that the kernel build process depends on; the + GNU version of the m4 macroprocessor (called + gm4 on FreeBSD) should be installed. + + In order to build the lisp kernel on Mac OS X + 10.6 Snow Leopard, you must install the optional 10.4 + support when installing Xcode. + @@ -327,5 +360,5 @@ Runs another external process, which causes the newly compiled lisp kernel to load the new bootstrapping image. - The bootsrtrapping image then loads the “higher + The bootstrapping image then loads the “higher level” fasl files and a new copy of the platform's full heap image is then saved. @@ -345,5 +378,5 @@ - Building the kernel + Building the Kernel The Lisp kernel is the executable that you run to use Lisp. It doesn't actually contain the entire Lisp @@ -370,36 +403,4 @@ - - - - - Kernel build prerequisites - The &CCL; kernel can be bult with the following widely - available tools: - - cc or gcc- the GNU C compiler - ld - the GNU linker - m4 or gm4- the GNU m4 macro processor - as - the GNU assembler (version 2.10.1 or later) - make - either GNU make or, on FreeBSD, the default BSD make program - - In general, the more recent the versions of those - tools, the better; some versions of gcc 3.x on Linux have - difficulty compiling some of the kernel source code correctly - (so gcc 4.0 should be used, if possible.) On Mac OS X, the - versions of the tools distributed with Xcode should work fine; - on Linux, the versions of the tools installed with the OS (or - available through its package management system) should work - fine if they're "recent enough". On FreeBSD, the installed - version of the m4 program doesn't support - some features that the kernel build process depends on; the - GNU version of the m4 macroprocessor (called - gm4 on FreeBSD) should be installed. - - In order to build the lisp kernel on Mac OS X - 10.6 Snow Leopard, you must install the optional 10.4 - support when installing Xcode. - - @@ -421,5 +422,5 @@ - Building the heap image + Building the Heap Image The initial heap image is loaded by the Lisp kernel, and provides most of the language implementation The heap image @@ -487,5 +488,5 @@ Given a bootstrapping image and a set of up-to-date fasl files, the development cycle usually involves editing lisp - sources (or updating those sources via cvs update), + sources (or updating those sources via svn update), recompiling modified files, and using the bootstrapping image to produce a new heap image. @@ -518,9 +519,9 @@ then calling ccl:xload-level-0 at the - lisp prompt + lisp prompt: ? (ccl:xload-level-0) - This function compiles the lisp sources in the ccl/level-0 + This function compiles the lisp sources in the ccl/level-0 directory if they're newer than the corresponding fasl files and then loads the resulting fasl files into a simulated lisp @@ -531,5 +532,5 @@ whenever your existing boot image is out-of-date with respect to the source files in ccl:level-0; - : + — For example: ? (ccl:xload-level-0 :force) @@ -575,5 +576,5 @@ $ cd ccl # wherever your ccl directory is -$ ./KERNEL BOOT_IMAGE +$ ./KERNEL BOOT_IMAGE Where KERNEL and @@ -587,5 +588,5 @@ can in the environment provided by a "real" heap image. If you're confident that things loaded OK, you can save that - image. + image: ? (ccl:save-application "image_name") ; Overwiting the existing heap image Index: /trunk/source/doc/src/install.xml =================================================================== --- /trunk/source/doc/src/install.xml (revision 15043) +++ /trunk/source/doc/src/install.xml (revision 15044) @@ -16,16 +16,16 @@ 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, + 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; runs on the following platforms: + &CCL; 1.7 runs on the following platforms: - Linux (x86, x86-64, ppc32, ppc64) + Linux (x86, x86-64, ppc32, ppc64, armv7) - Mac OS X 10.4 and later (x86, x86-64, ppc32, ppc64) + Mac OS X 10.5 and later (x86, x86-64) @@ -41,4 +41,24 @@ + 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 @@ -60,4 +80,47 @@ + 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 @@ -68,16 +131,10 @@ - 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. - + 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 @@ -91,5 +148,5 @@ Obtaining &CCL; - There two main ways to obtain &CCL;. For Mac OS X, + 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 @@ -102,6 +159,8 @@ 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. + command-line application, or with Emacs and SLIME. + + + The following sections describe these options. @@ -112,6 +171,6 @@ 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 - + 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 @@ -129,9 +188,20 @@ + + 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, install, and build &CCL; - using Subversion. This is the preferred way to get either the + 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 @@ -141,16 +211,57 @@ + + 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: + svn]]> + + If Subversion is installed, you will see something like: + + + If Subversion is not installed, you will see something + like: + + + 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, + 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): - - - - - + 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 + @@ -168,21 +279,22 @@ 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. To get the 1.4 release - of &CCL; type: - - - - - - 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): - - + 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 @@ -192,72 +304,209 @@ 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: - - - ./dx86cl64 -Welcome to Clozure Common Lisp Version 1.2 (DarwinX8664)! + 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 + - - ? (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: - - svn]]> - - If Subversion is installed, you will see something like: - - - - If Subversion is not installed, you will see something - like: - - - - 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. - - +<...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 . + + + 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, follow the procedure outlined 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: + + ./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: + + 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> +]]> + + Follow this same procedure to perform the fuil rebuild from scratch, for example + in the case where the saved Lisp image contains code that was loaded inadvertently. + (Classic mistake: forgetting to specify the --no-init command option.) + + + 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 + + + + + + + + + + @@ -293,5 +542,7 @@ 32-bit implementations of &CCL; and "ccl/scripts/ccl64" is used to invoke - 64-bit implementations. + 64-bit implementations. + Install one script or the other or both as needed. + To use the script: @@ -312,8 +563,12 @@ 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 + 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. @@ -356,22 +611,27 @@ 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)! -? + or ccl64 at a shell prompt: + + 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 these arguments. When invoked this way, the - Lisp should be able to initialize the "ccl:" + 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/alms/my_lisp_stuff/ccl/level-1/level-1.lisp" +#P"/Users/joe/my_lisp_stuff/ccl/level-1/level-1.lisp" @@ -381,10 +641,14 @@ Invocation Assuming that the shell script is properly installed, it can be used to invoke &CCL; from a shell prompt: - -shell>ccl args - + 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 + . + @@ -461,6 +725,6 @@ is a synonym for :ISO-8859-1. For example: - - ccl -K utf-8]]> + ccl -K utf-8]]> has the effect of making the standard CL streams use @@ -562,5 +826,5 @@ Finally, any arguments following the pseudo-argument -- are not processed, and are made - available to the lisp as the value of + available to Lisp as the value of ccl:*unprocessed-command-line-arguments*.