Changeset 15044


Ignore:
Timestamp:
Oct 26, 2011, 1:44:33 AM (8 years ago)
Author:
kmcorbett
Message:

Updates for version 1.7; clarify update and build procedures.

Location:
trunk/source/doc/src
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/build.xml

    r14508 r15044  
    250250    the Subversion source control system.</para>
    251251    <para>
    252       For example, to get a released version (1.3 in this example),
     252      For example, to get a released version (1.7 in this example),
    253253      use a command like:
    254       <programlisting>
    255         svn co http://svn.clozure.com/publicsvn/openmcl/release/1.3/xxx/ccl
    256       </programlisting>
     254      <programlisting>svn co http://svn.clozure.com/publicsvn/openmcl/release/1.7/<replaceable>xxx</replaceable>/ccl</programlisting>
    257255    </para>
    258256    <para>
    259257      To get the trunk version, use:
    260       <programlisting>
    261         svn co http://svn.clozure.com/publicsvn/openmcl/trunk/xxx/ccl
    262       </programlisting>
     258      <programlisting>svn co http://svn.clozure.com/publicsvn/openmcl/trunk/<replaceable>xxx</replaceable>/ccl</programlisting>
    263259    </para>
    264260    <para>
    265       Change the "xxx" to one of the following names:
     261      Change the <emphasis><literal>xxx</literal></emphasis> to one of the following names:
    266262      <literal>darwinx86</literal>,
    267263      <literal>linuxx86</literal>,
    268264      <literal>freebsdx86</literal>,
    269265      <literal>solarisx86</literal>,
    270       <literal>window</literal>,
     266      <literal>windows</literal>,
    271267      <literal>linuxppc</literal>,
    272268      or
     
    274270    </para>
    275271    <para>
    276       In the case of released versions, there may also be tar archives
    277       available.  See the <ulink url="http://trac.clozure.com/ccl/">Clozure CL
    278       Trac</ulink> for details.
     272      Tarball distributions of released versions are also available for download via ftp from:
     273      <ulink url="ftp://clozure.com/pub/release/"/>.
     274      For additional information about availability of source and distributions see the
     275      <ulink url="http://trac.clozure.com/ccl/">Clozure CL Trac</ulink>.
    279276    </para>
    280277    <para>Subversion client programs are pre-installed on Mac OS X 10.5 and
    281278      later and are typically either pre-installed or readily available
    282       on Linux and FreeBSD platforms.  The <ulink url="http://subversion.tigris.org">Subversion web page</ulink> contains links to subversion client programs
    283       for many platforms; users of Mac OS X 10.4 can also
    284       install Subversion clients via Fink or MacPorts.</para>
     279      on Linux and FreeBSD platforms.  The <ulink url="http://subversion.tigris.org">Subversion web page</ulink> contains links to Subversion client programs
     280      for many platforms.
     281      Users of Mac OS X 10.4 or later can also
     282      install Subversion clients via Fink or MacPorts.
     283      On Debian Linux (and on related Linux distros such as Ubuntu) run
     284      <literal>apt-get install subversion</literal> or equivalent in the command-line or interactive package manager.
     285    </para>
    285286   
     287  </sect1>
     288
     289 
     290  <!-- ******************************************************** -->
     291  <sect1 id="Kernel-build-prerequisites">
     292    <title>Kernel Build Prerequisites</title>
     293        <para>The &CCL; kernel can be built with the following widely
     294          available tools:</para>
     295    <itemizedlist>
     296      <listitem><para>cc or gcc &mdash; the GNU C compiler</para></listitem>
     297      <listitem><para>ld &mdash; the GNU linker</para></listitem>
     298      <listitem><para>m4 or gm4 &mdash; the GNU m4 macro processor</para></listitem>
     299      <listitem><para>as &mdash; the GNU assembler (version 2.10.1 or later)</para></listitem>
     300      <listitem><para>make &mdash; either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
     301        </itemizedlist>
     302        <para> In general, the more recent the versions of those
     303          tools, the better; some versions of gcc 3.x on Linux have
     304          difficulty compiling some of the kernel source code correctly
     305          (so gcc 4.0 should be used, if possible.)  On Mac OS X, the
     306          versions of the tools distributed with Xcode should work fine;
     307          on Linux, the versions of the tools installed with the OS (or
     308          available through its package management system) should work
     309          fine if they're "recent enough".  On FreeBSD, the installed
     310          version of the <literal>m4</literal> program doesn't support
     311          some features that the kernel build process depends on; the
     312          GNU version of the m4 macroprocessor (called
     313          <literal>gm4</literal> on FreeBSD) should be installed.
     314        </para>
     315        <note><para>In order to build the lisp kernel on Mac OS X
     316        10.6 Snow Leopard, you must install the optional 10.4
     317        support when installing Xcode.</para>
     318        </note>
    286319  </sect1>
    287320
     
    327360            <para>Runs another external process, which causes the newly
    328361              compiled lisp kernel to load the new bootstrapping image.
    329               The bootsrtrapping image then loads the &ldquo;higher
     362              The bootstrapping image then loads the &ldquo;higher
    330363              level&rdquo; fasl files and a new copy of the platform's
    331364              full heap image is then saved.</para>
     
    345378  <!-- =========================================================== -->
    346379  <sect1 id="Building-the-kernel">
    347     <title>Building the kernel</title>
     380    <title>Building the Kernel</title>
    348381    <para>The Lisp kernel is the executable that you run to use
    349382      Lisp.  It doesn't actually contain the entire Lisp
     
    370403      </programlisting>
    371404    </para>
    372 
    373 
    374     <!-- ******************************************************** -->
    375     <sect2 id="Kernel-build-prerequisites">
    376       <title>Kernel build prerequisites</title>
    377           <para>The &CCL; kernel can be bult with the following widely
    378             available tools:</para>
    379       <itemizedlist>
    380         <listitem><para>cc or gcc- the GNU C compiler</para></listitem>
    381         <listitem><para>ld - the GNU linker</para></listitem>
    382         <listitem><para>m4 or gm4- the GNU m4 macro processor</para></listitem>
    383         <listitem><para>as - the GNU assembler (version 2.10.1 or later)</para></listitem>
    384             <listitem><para>make - either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
    385           </itemizedlist>
    386           <para> In general, the more recent the versions of those
    387             tools, the better; some versions of gcc 3.x on Linux have
    388             difficulty compiling some of the kernel source code correctly
    389             (so gcc 4.0 should be used, if possible.)  On Mac OS X, the
    390             versions of the tools distributed with Xcode should work fine;
    391             on Linux, the versions of the tools installed with the OS (or
    392             available through its package management system) should work
    393             fine if they're "recent enough".  On FreeBSD, the installed
    394             version of the <literal>m4</literal> program doesn't support
    395             some features that the kernel build process depends on; the
    396             GNU version of the m4 macroprocessor (called
    397             <literal>gm4</literal> on FreeBSD) should be installed.
    398           </para>
    399           <note><para>In order to build the lisp kernel on Mac OS X
    400           10.6 Snow Leopard, you must install the optional 10.4
    401           support when installing Xcode.</para>
    402           </note>
    403     </sect2>
    404405
    405406    <!-- ******************************************************** -->
     
    421422  <!-- =========================================================== -->
    422423  <sect1 id="Building-the-heap-image">
    423     <title>Building the heap image</title>
     424    <title>Building the Heap Image</title>
    424425    <para>The initial heap image is loaded by the Lisp kernel, and
    425426      provides most of the language implementation The heap image
     
    487488      <para>Given a bootstrapping image and a set of up-to-date fasl
    488489        files, the development cycle usually involves editing lisp
    489         sources (or updating those sources via cvs update),
     490        sources (or updating those sources via <literal>svn update</literal>),
    490491        recompiling modified files, and using the bootstrapping image
    491492        to produce a new heap image.</para>
     
    518519          </programlisting>
    519520          <para>then calling <literal>ccl:xload-level-0</literal> at the
    520             lisp prompt</para>
     521            lisp prompt:</para>
    521522          <programlisting>
    522523? (ccl:xload-level-0)
    523524          </programlisting>
    524       <para>This function compiles the lisp sources in the ccl/level-0
     525      <para>This function compiles the lisp sources in the <literal>ccl/level-0</literal>
    525526        directory if they're newer than the corresponding fasl files
    526527        and then loads the resulting fasl files into a simulated lisp
     
    531532        whenever your existing boot image is out-of-date with respect
    532533        to the source files in <literal>ccl:level-0;</literal>
    533         :</para>
     534        &mdash; For example:</para>
    534535      <programlisting>
    535536? (ccl:xload-level-0 :force)
     
    575576      <programlisting>
    576577$ cd ccl                        # wherever your ccl directory is
    577 $ ./KERNEL BOOT_IMAGE
     578$ ./<replaceable>KERNEL</replaceable> <replaceable>BOOT_IMAGE</replaceable>
    578579          </programlisting>
    579580      <para>Where <replaceable>KERNEL</replaceable> and
     
    587588        can in the environment provided by a "real" heap image. If
    588589        you're confident that things loaded OK, you can save that
    589         image.</para>
     590        image:</para>
    590591      <programlisting>
    591592? (ccl:save-application "<replaceable>image_name</replaceable>") ; Overwiting the existing heap image
  • trunk/source/doc/src/install.xml

    r14730 r15044  
    1616  <sect1 id="releases"><title>Releases and System Requirements</title>
    1717   
    18     <para>As of this writing, &CCL; 1.4 is the latest release; it was
    19     made in October 2009.  For up-to-date information about releases,
     18    <para>As of this writing, &CCL; 1.7 is the latest release; it was
     19    made in August 2011.  For up-to-date information about releases,
    2020    please see <ulink url="http://ccl.clozure.com/"/>.
    2121    </para>
    2222
    23    <para>&CCL; runs on the following platforms:</para>
     23   <para>&CCL; 1.7 runs on the following platforms:</para>
    2424    <itemizedlist>
    2525      <listitem>
    26         <para>Linux (x86, x86-64, ppc32, ppc64)</para>
     26        <para>Linux (x86, x86-64, ppc32, ppc64, armv7)</para>
    2727      </listitem>
    2828      <listitem>
    29         <para>Mac OS X 10.4 and later (x86, x86-64, ppc32, ppc64)</para>
     29        <para>Mac OS X 10.5 and later (x86, x86-64)</para>
    3030      </listitem>
    3131      <listitem>
     
    4141
    4242    <!-- ***************************************************** -->
     43    <sect2 id="ports32vs64"><title>32- vs 64-bit versions</title>
     44      <para>Naturally, 64-bit versions of &CCL; require 64-bit processors,
     45      for example, a G5 or Core 2.  Some early Intel-based Macintoshes
     46      used processors that don't support
     47      64-bit operation, so the 64-bit &CCL; will not run on them, although
     48      the 32-bit &CCL; will.
     49      </para>
     50    </sect2>
     51
     52    <!-- ***************************************************** -->
     53    <sect2 id="x86sse2"><title>32-bit x86 versions require SSE2</title>
     54      <para>The 32-bit x86 versions of &CCL; depend on the presence of the SSE2 instructions.
     55      Most x86 processors manufactured and sold in the last several years support SSE2 (all Apple Intel-based Macs do, for instance),
     56      but there are some exceptions.
     57      The <ulink url="http://en.wikipedia.org/wiki/SSE2">Wikipedia article on SSE2</ulink> lists processor models that support SSE2
     58      (and also mentions some of the more notable exceptions).
     59      </para>
     60    </sect2>
     61
     62    <!-- ***************************************************** -->
    4363    <sect2 id="linuxppc"><title>LinuxPPC</title>
    4464     
     
    6080
    6181    <!-- ***************************************************** -->
     82    <sect2 id="linuxarm"><title>Linux ARM v7</title>
     83      <para>The Linux ARM port is relatively new and is still a work-in-progress.
     84      &CCL;
     85needs some features (such as hardware floating-point, locking and
     86memory-serialization primitives) that are only found in chips
     87that implement architecture version 7 (ARMv7); technically, it needs
     88the ARMv7 "application profile", which is sometimes called ARMv7a.
     89<!--
     90Chips that're designed by ARM Ltd and which implement this
     91architecture include the Cortex A8 and Cortex A9 series, and many
     92manufacturers license these designs and implement them in hardware.
     93(At least one manufacturer designs their own ARMv7s).
     94-->
     95In practice, <emphasis>most</emphasis> ARM consumer devices released in the last few
     96years implement ARMv7, but there are exceptions, and it is
     97not practical to enumerate all of the ARM devices that CCL should
     98run on.
     99      </para>
     100      <para>
     101In addition to hardware issues, &CCL; expects Linux to run in little-endian
     102mode and expects software to follow "soft float" calling conventions.
     103The latter has to do with how C functions accept floating-point arguments
     104and return floating-point values.
     105<!-- The older "soft float" conventions can
     106be used on machines that don't have FPUs, and the "hard float" conventions
     107can be faster on ARMs that have FPUs.  From CCL's point of view, this issue
     108only affects foreign function calls and callbacks where floats are involved,
     109but the conventions used in those cases aren't binary-compatible.
     110
     111At this point, most Linux distributions still follow the soft-float
     112conventions (even though they may insist on modern hardware with
     113FPUs); some distributions use the newer hard-float conventions, and
     114it's likely that hard-float will become widely adopted over the next
     115few years.  (It does measurably improve the performance of
     116FP-intensive C code.)  CCL's FFI assumes that soft-float conventions
     117are used.  At some point, this will change and will introduce
     118binary-compatibility issues, and it's not yet clear how those issues
     119will be addressed.
     120-->
     121      </para>
     122    </sect2>
     123
     124    <!-- ***************************************************** -->
    62125    <sect2 id="freebsdx86"><title>FreeBSD x86</title>
    63126    <para>&CCL; should run on
     
    68131
    69132    <!-- ***************************************************** -->
    70     <sect2 id="macosx"><title>Mac OS X (ppc and x86)</title>
    71 
    72       <para> &CCL; runs under Mac OS X versions 10.4 and later.  Post-1.4
    73       versions will require at least 10.5.
    74       </para>
    75 
    76       <para>64-bit versions of &CCL; naturally require 64-bit processors
    77       (e.g., a G5 or Core 2 processor).  Some early Intel-based Macintoshes
    78       used processors that don't support
    79       64-bit operation, so the 64-bit &CCL; will not run on them, although
    80       the 32-bit &CCL; will.
    81       </para>
     133    <sect2 id="macosx"><title>Mac OS X x86</title>
     134
     135      <para> &CCL; 1.7 runs on Mac OS X (x86) versions 10.5 and later, including 10.7 (Lion),
     136      </para>
     137
     138      <para> &CCL; 1.6 runs on Mac OS X PPC as well as x86 processors.</para>
    82139    </sect2>
    83140    <sect2 id="windows"><title>Microsoft Windows</title>
     
    91148  <!-- ============================================================ -->
    92149  <sect1 id="obtaining-ccl"><title>Obtaining &CCL;</title>
    93     <para>There two main ways to obtain &CCL;.  For Mac OS X,
     150    <para>There are three ways to obtain &CCL;.  For Mac OS X,
    94151    there are disk images that can be used to install &CCL; in
    95152    the usual Macintosh way. For other OSes, Subversion is the best
     
    102159    <para> There are three popular ways to use &CCL;: as a
    103160      stand-alone double-clickable application (Mac OS X only), as a
    104       command-line application, or with Emacs and SLIME. The following
    105       sections describe these options.</para>
     161      command-line application, or with Emacs and SLIME.
     162    </para>
     163
     164    <para>The following sections describe these options.</para>
    106165
    107166    <!-- ***************************************************** -->
     
    112171         or wherever you wish.
    113172         After that you can double-click the Clozure CL application found
    114          inside the ccl directory.  The disk images are available at
    115          <ulink url="ftp://clozure.com/pub/release/1.4/"/> </para>
     173         inside the ccl directory.  The disk images for version 1.7 are available at
     174         <ulink url="ftp://clozure.com/pub/release/1.7/"/> </para>
    116175
    117176      <para>So that &CCL; can locate its source code, and for other
     
    129188    </sect2>
    130189   
     190    <!-- ***************************************************** -->
     191    <sect2 id="obtaining-via-tarballs"><title>Tarballs</title>
     192      <para>Tarball distributions of &CCL; release version 1.7 are available at
     193      <ulink url="ftp://clozure.com/pub/release/1.7/"/>.
     194      Download and extract
     195      one on your local disk.  Then edit the &CCL; shell script to set
     196      the value of <varname>CCL_DEFAULT_DIRECTORY</varname> and start
     197      up the appropriate &CCL; kernel. See <xref
     198      linkend="The-ccl-Shell-Script"/> for more information about the
     199      &CCL; shell scripts.</para>
     200    </sect2>
    131201
    132202    <!-- ***************************************************** -->
    133203    <sect2 id="obtaining-via-svn"><title>Getting &CCL; with Subversion</title>
    134       <para>It is very easy to download, install, and build &CCL;
    135       using Subversion. This is the preferred way to get either the
     204      <para>It is very easy to download and configure &CCL; to obtain sources from the Subversion repository.
     205      This is the preferred way to get either the
    136206      latest, or a specific version of &CCL;, unless you prefer
    137207      the Mac Way.  Subversion is a source code control system that is
     
    141211      </para>
    142212
     213      <note>
     214        <para>Unless stated otherwise, examples in this chapter are given for Mac OS X in particular
     215        or Unix-based host environments in general.
     216        </para>
     217
     218        <para>For Windows, special care must be taken to install a working development environment.
     219        For more information see the &CCL; Wiki at URL: <ulink url="http://trac.clozure.com/ccl/wiki/WindowsNotes"/>
     220        </para>
     221      </note>
     222
     223      <sect3 id="Checking-Subversion-Installation"><title>Checking Subversion Installation</title>
     224      <para>Make sure that Subversion is installed on your system.  Bring up a command
     225      line shell and type:
     226        <programlisting><![CDATA[
     227shell> svn]]>
     228        </programlisting>
     229        If Subversion is installed, you will see something like:
     230        <programlisting><![CDATA[
     231Type 'svn help' for usage]]>
     232        </programlisting>
     233        If Subversion is not installed, you will see something
     234        like:
     235        <programlisting><![CDATA[
     236-bash: svn: command not found]]>
     237        </programlisting>
     238        If Subversion is not installed, you'll need to figure out how
     239        to install it on your OS. You can find information about
     240        obtaining and installing Subversion at
     241        the <ulink url="http://subversion.tigris.org">Subversion
     242        web page</ulink>.</para>
     243      </sect3>
     244
     245      <sect3 id="Downloading-CCL"><title>Downloading &CCL; Using Subversion</title>
     246
     247      <para>Before you download &CCL; you should consider:
     248      Do you want to run the most recent source code, or the current stable release version?
     249      If you don't know how to answer this question, then you probably want the release version.
     250      </para>
     251
     252      <sect4 id="Downloading-CCL-Trunk"><title>Downloading the Trunk</title>
    143253      <para>Day-to-day development of &CCL; takes place in an area
    144       of the Subversion repository known as the trunk.  At most times,
     254      of the Subversion repository known as "the trunk".  At most times,
    145255      the trunk is perfectly usable, but occasionally it can be unstable
    146       or totally broken.  If you wish to live on the
    147       bleeding edge, the following command will fetch a copy of the trunk
    148       for Darwin x86 (both 32- and 64-bit versions):
    149       </para>
    150 
    151         <programlisting>
    152           <![CDATA[
    153 svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx86/ccl]]>
    154         </programlisting>
     256      or totally broken.
     257      If you wish to live on the bleeding edge, download sources from the trunk.
     258      </para>
     259
     260      <para> For example, the following command will fetch a copy of the trunk
     261      for Mac OS X (Darwin) with x86 processors (both 32- and 64-bit versions):
     262      </para>
     263
     264        <programlisting>svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx86/ccl
     265         </programlisting>
    155266
    156267        <para>
     
    168279          <listitem><para>darwinppc</para></listitem>
    169280        </itemizedlist>
    170 
     281      </sect4>
     282
     283      <sect4 id="Downloading-CCL-Release"><title>Downloading a Release Version</title>
    171284        <para>Release versions of &CCL; are intended to be stable.  While
    172285        bugs will be fixed in the release branches, enhancements
    173         and new features will go into the trunk.  To get the 1.4 release
    174         of &CCL; type:</para>
    175         <programlisting>
    176           <![CDATA[
    177 svn co http://svn.clozure.com/publicsvn/openmcl/release/1.4/darwinx86/ccl]]>
    178         </programlisting>
    179 
    180        
    181         <para>The above command will fetch the complete sources and binaries
    182         for the Darwin x86 build of &CCL;. To get a &CCL; for another platform,
    183         replace "darwinx86" with one of the following names (all versions
    184         include both 32- and 64-bit binaries):</para>
    185 
    186         <itemizedlist>
     286        and new features will go into the trunk.
     287        If you wish to run the stable release,
     288        the following command will fetch a copy of the release version 1.7
     289        for Mac OS X (Darwin) with x86 processors (both 32- and 64-bit versions):
     290        </para>
     291
     292        <programlisting>svn co http://svn.clozure.com/publicsvn/openmcl/release/1.7/darwinx86/ccl
     293          </programlisting>
     294
     295        <para>To get the release version of &CCL;  for another platform,
     296        replace "darwinx86" with one of the following names:
     297        </para>
     298        <itemizedlist>
    187299          <listitem><para>darwinx86</para></listitem>
    188300          <listitem><para>linuxx86</para></listitem>
     
    192304          <listitem><para>linuxppc</para></listitem>
    193305          <listitem><para>darwinppc</para></listitem>
    194         </itemizedlist>
     306        </itemizedlist>
    195307
    196308        <para>These distributions contain complete sources and
    197309        binaries. They use Subversion's "externals" features to share
    198310        common sources; the majority of source code is the same across
    199         all versions.</para>
    200 
    201         <para>Once the checkout is complete you can build &CCL; by
    202         running the lisp kernel and executing
    203         the <literal>rebuild-ccl</literal> function. For
    204         example:</para>
    205 
    206         <programlisting>
    207           <![CDATA[
    208 joe:ccl> ./dx86cl64
    209 Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
     311        all versions.</para>
     312
     313      </sect4>
     314      </sect3>
     315    </sect2>
     316
     317    <sect2 id="Rebuilding-CCL-From-Sources"><title>Rebuilding &CCL; From Sources</title>
     318
     319    <para>This section explains how to peform a "full rebuild" of &CCL; from a source distribution.</para>
     320   
     321    <para>After downloading &CCL; sources, you should rebuild &CCL; as described here.
     322    At the start of a full rebuild, object files in the <literal>ccl</literal> directory are deleted,
     323    which causes the build script to recompile the runtime kernel (C code) and high-level sources (Lisp),
     324    then save a new heap image.
     325    Doing a full rebuild helps to ensure that your local installation will run properly for your host OS environment.
     326    </para>
     327
     328    <para>In an interactive shell, a command sequence like the following will rebuild &CCL; in place:
     329
     330    <programlisting>
     331joe&gt; cd <replaceable>/path/to/installed/ccl</replaceable>
     332joe:ccl&gt; ./<replaceable>kernel-filename</replaceable> --no-init
     333<![CDATA[Welcome to Clozure Common Lisp Version [...]
    210334? (rebuild-ccl :full t)
    211 
    212 <lots of compilation output>
    213 
    214   ? (quit)
    215   joe:ccl>]]>
    216         </programlisting>
    217 
    218         <para>
    219           If you don't have a C compiler toolchain installed,
    220           <literal>rebuild-ccl</literal> will not work.  Please
    221           refer to <xref linkend="building-ccl-from-source"/> for
    222           addtional details.
    223         </para>
    224         <sect3 id="Checking-Subversion-Installation"><title>Checking Subversion Installation</title>
    225       <para>If <literal>svn co</literal> doesn't work, then make sure
    226       that Subversion is installed on your system.  Bring up a command
    227       line shell and type:
    228         <programlisting>
    229           <![CDATA[
    230 shell> svn]]>
    231         </programlisting>
    232         If Subversion is installed, you will see something like:
    233         <programlisting>
    234           <![CDATA[
    235 Type 'svn help' for usage]]>
    236         </programlisting>
    237         If Subversion is not installed, you will see something
    238         like:
    239         <programlisting>
    240           <![CDATA[
    241 -bash: svn: command not found]]>
    242         </programlisting>
    243         If Subversion is not installed, you'll need to figure out how
    244         to install it on your OS. You can find information about
    245         obtaining and installing Subversion at
    246         the <ulink url="http://subversion.tigris.org/project_packages.html">Subversion
    247         Packages page</ulink>.</para></sect3>
    248 
    249     </sect2>
    250 
    251     <!-- ***************************************************** -->
    252     <sect2 id="obtaining-via-tarballs"><title>Tarballs</title>
    253       <para>Tarballs are available at <ulink
    254       url="ftp://clozure.com/pub/release/1.4/"/>.  Download and extract
    255       one on your local disk.  Then edit the &CCL; shell script to set
    256       the value of <varname>CCL_DEFAULT_DIRECTORY</varname> and start
    257       up the appropriate &CCL; kernel. See <xref
    258       linkend="The-ccl-Shell-Script"/> for more information about the
    259       &CCL; shell scripts.</para>
    260     </sect2>
    261   </sect1>
     335<...lots of compilation output...>
     336? (quit)]]>
     337joe:ccl&gt;
     338    </programlisting>
     339    </para>
     340
     341    <para>Replace <replaceable>/path/to/installed/ccl</replaceable> with the path of the <literal>ccl</literal> directory
     342    that you downloaded.</para>
     343
     344    <para>Replace <replaceable>kernel-filename</replaceable> with the filename of the Lisp kernel program.
     345    To find the filename of a Lisp kernel image for your particular platform, see <xref linkend="filename_conventions"/>.
     346    </para>
     347
     348    <para>The rest of this section covers the following topics in brief:
     349    <itemizedlist>
     350      <listitem>
     351      <para><link linkend="Rebuilding-CCL-Requirements">Software prerequisites</link></para></listitem>
     352      <listitem><para><link linkend="When-Rebuild-CCL">When to run the build process</link></para></listitem>
     353      <listitem><para><link linkend="Rebuild-CCL-Overview">Using <literal>ccl-rebuild</literal></link></para></listitem>
     354      <listitem><para><link linkend="Rebuild-Process-Steps-Summary">What happens during the full rebuild process</link></para></listitem>
     355    </itemizedlist>
     356    </para>
     357
     358    <note><para>This section does <emphasis>not</emphasis> provide comprehensive documentation on the build process.
     359    Please refer to <xref linkend="building-ccl-from-source"/> for more information.
     360    Those more detailed instructions are used mainly by developers who maintain, customize, and/or port &CCL;.
     361    If you are customizing &CCL;, or if you run into some exceptional situation,
     362    you may need to perform the individual build steps.
     363    </para></note>
     364
     365    <sect3 id="Rebuilding-CCL-Requirements"><title>Software Requirements for Building &CCL;</title>
     366
     367    <para>In order to build &CCL; you must have a working system and development environment.
     368    There are different requirements and setup procedures for each platform, but the main requirement is to have
     369    a C compiler and a few other utilities:
     370    GNU <literal>gcc</literal> or <literal>cc</literal> with <literal>ld</literal> and <literal>as</literal>;
     371    <literal>make</literal>; and <literal>m4</literal>.
     372    Please refer to <xref linkend="building-ccl-from-source"/> for details.
     373    </para>
     374
     375    <note><para>If you don't have the prerequisite C compiler toolchain installed, <literal>rebuild-ccl</literal> will not work.
     376    See <xref linkend="Kernel-build-prerequisites"/> for additional details.
     377    </para></note>
     378
     379    <para>Most distributions of Linux have all or most of the required development tools either pre-installed
     380    or readily available.
     381    On Debian-based Linux you can download and install the essential build tools using the package manager.
     382    For example: <programlisting>apt-get install build-essential</programlisting>
     383    (You may need to install C header files separately.)
     384    </para>
     385
     386    <para>For Mac OS X, Xcode 4 is available from the App Store.</para>
     387
     388    <para>For Windows, follow the procedure outlined in the &CCL; Wiki
     389    at URL: <ulink url="http://trac.clozure.com/ccl/wiki/WindowsNotes"/>
     390    </para>
     391
     392    </sect3>
     393
     394    <sect3 id="When-Rebuild-CCL"><title>When to Rebuild &CCL; From Sources</title>
     395
     396    <para>The most common scenario that requires a full rebuild is the standard installation after downloading the source tree.
     397    Users and application developers (who otherwise have no special build requirements)
     398    will generally need to run the full rebuild process just once
     399    for any given installation on a particular host system.
     400    </para>
     401
     402    <para>Another common scenario is installing a patch update:
     403    You can use Subversion (<literal>svn update</literal>) to download a more recent set of source files.
     404    (Be sure to download sources from the same path and branch in the source repository.)
     405    Then run a full rebuild to create new kernel and heap images.
     406    If you are running &CCL; from the trunk, you may need to update sources and run the full rebuild more often.
     407    </para>
     408
     409    <para>Another reason to do a full rebuild is to ensure that &CCL; will run properly in the host OS environment.
     410    This may be necessary, for example, when the target OS version
     411    is not identical to the one where the pre-built kernel was generated.
     412    The Lisp kernel uses some functionality defined in standard platform-provided libraries.
     413    On some platforms, applications (such as the Lisp kernel) are built in
     414    such a way as to depend on the specific versions of these libraries that were
     415    present at build time, and may not run on systems that have older or newer versions
     416    of these libraries.
     417    If you're affected by this, the simplest workaround is to build the Lisp kernel
     418    on the machine(s) that you intend to run it on and use that locally-built kernel instead of one distributed via Subversion.
     419    </para>
     420
     421    </sect3>
     422
     423    <sect3 id="Rebuild-CCL-Overview"><title>Rebuilding &CCL; Using REBUILD-CCL</title>
     424
     425    <para>Once the checkout is complete, and provided that you have a working development setup,
     426    you can build &CCL; by running the Lisp kernel (an OS-native executable program)
     427    and running <function>REBUILD-CCL</function> in Lisp.
     428    </para>
     429
     430    <para>For example, to build a 64-bit &CCL; on Mac OS X:
     431
     432    <programlisting><![CDATA[
     433joe:ccl> ./dx86cl64 --no-init
     434Welcome to Clozure Common Lisp Version 1.7  (DarwinX8664)!
     435? (rebuild-ccl :full t)
     436Rebuilding Clozure Common Lisp using Version 1.7  (DarwinX8664)
     437;Building lisp-kernel ...
     438;Kernel built successfully.
     439;Compiling <...>
     440;Loading <...>
     441
     442<...lots of compilation output...>
     443
     444;Wrote bootstrapping image: #P"/Users/joe/ccl/x86-boot64.image"
     445;Wrote heap image: #P"/Users/joe/ccl/dx86cl64.image"
     446NIL
     447? (quit)
     448joe:ccl>]]>
     449    </programlisting>
     450    </para>
     451
     452    <para>If the build fails for any reason, the kernel and/or heap image files may be missing or corrupted.
     453    To recover, delete the image files and update the source directory from Subversion.
     454    For example:
     455
     456    <programlisting><![CDATA[
     457joe:ccl> rm dx86cl*
     458joe:ccl> svn update
     459<... lots of Subversion output...>
     460joe:ccl> ./dx86cl64 --no-init
     461Welcome to Clozure Common Lisp Version 1.7  (DarwinX8664)!
     462? (rebuild-ccl :full t)
     463<... lots of compilation output...>
     464? (quit)
     465joe:ccl>
     466]]>
     467    </programlisting>
     468    Follow this same procedure to perform the fuil rebuild from scratch, for example
     469    in the case where the saved Lisp image contains code that was loaded inadvertently.
     470    (Classic mistake: forgetting to specify the <literal>--no-init</literal> command option.)
     471    </para>
     472
     473    <para>Once the full rebuild is completed, you can run the new Lisp kernel from the command shell.
     474    However, running the OS- and processor-specific executable directly is not recommended
     475    for day-to-day use.
     476    &CCL; includes the <literal>ccl</literal> and <literal>ccl64</literal> command shell scripts.
     477    For details on configuring a shell script for your environment, see <xref linkend="The-ccl-Shell-Script"/>.
     478    </para>
     479
     480    </sect3>
     481
     482    <sect3 id="Rebuild-Process-Steps-Summary"><title>Summary of the Build Process Steps</title>
     483    <para>Should the build fail, your first concern should be to confirm that all requirements are in place:
     484    the C compiler, utilities, and OS header files;
     485    source files for the trunk or release branch you want to build;
     486    and the Lisp kernel and heap image files.
     487    For assistance with trouble-shooting, here is an outline of the full build process,
     488    with links to the more detailed instructions in <xref linkend="building-ccl-from-source"/>.
     489    <itemizedlist>
     490      <listitem><para>Build the Lisp kernel (<xref linkend="Building-the-kernel"/>)</para></listitem>
     491      <listitem><para>Build the heap image (<xref linkend="Building-the-heap-image"/>)</para>
     492      <itemizedlist>
     493        <listitem><para>Create a bootstrapping heap image (<xref linkend="Generating-a-bootstrapping-image"/>)</para></listitem>
     494        <listitem><para>Compile Lisp code to generate fasl files (<xref linkend="Generating-fasl-files"/>)</para></listitem>
     495        <listitem><para>Build a full image from bootstrapping image
     496        (<xref linkend="Building-a-full-image-from-a-bootstrapping-image"/>)</para>
     497        <itemizedlist>
     498          <listitem><para>Run new kernel with new bootstrapping image</para></listitem>
     499          <listitem><para>Load Lisp code</para></listitem>
     500          <listitem><para>Save a new full heap image</para></listitem>
     501        </itemizedlist>
     502        </listitem>
     503      </itemizedlist>
     504      </listitem>
     505    </itemizedlist>
     506    </para>
     507
     508    </sect3>
     509  </sect2>
     510</sect1>
    262511
    263512  <!-- ============================================================ -->
     
    293542        32-bit implementations of &CCL; and
    294543        <literal>"ccl/scripts/ccl64"</literal> is used to invoke
    295         64-bit implementations.</para>
     544        64-bit implementations.
     545        Install one script or the other or both as needed.
     546      </para>
    296547      <para>To use the script:</para>
    297548      <orderedlist>
     
    312563            your <literal>ccl</literal> directory.  Alternately, set
    313564            the value of the <literal>CCL_DEFAULT_DIRECTORY</literal>
    314             environment variable in your .cshrc, .tcshrc,
    315             .bashrc,.bash_profile, .MacOSX/environment.plist, or
    316             wherever you usually set environment variables.  If there
    317             is an existing definition of the variable, the ccl
     565            environment variable
     566            wherever you usually set per-user environment variables, in your
     567            <literal>.cshrc</literal>, <literal>.tcshrc</literal>,
     568            <literal>.bashrc</literal>, <literal>.bash_profile</literal>,
     569            or <literal>.MacOSX/environment.plist</literal> script,
     570            or system-wide in <literal>/etc/profile</literal> or <literal>/etc/bashrc</literal>.
     571            When the ccl script runs, if the process environment contains
     572            a definition of <literal>CCL_DEFAULT_DIRECTORY</literal>, the ccl
    318573            script will not override it.
    319574          </para>
     
    356611      <para>Once this is done, it should be possible to invoke &CCL;
    357612        by typing <literal>ccl</literal>
    358         or <literal>ccl64</literal> at a shell prompt:</para>
    359       <programlisting>
    360 &gt; ccl [args ...]
    361 Welcome to &CCL; Version 1.2 (DarwinPPC32)!
    362 ?
     613        or <literal>ccl64</literal> at a shell prompt:
     614
     615      <programlisting><![CDATA[
     616shell> ccl
     617Welcome to Clozure Common Lisp Version 1.7  (DarwinX8632)!
     618?]]>
    363619      </programlisting>
    364      
     620      </para>
     621
    365622      <para>The ccl shell script passes all of its arguments to the
    366623      &CCL; kernel.  See <xref linkend="Invocation"/> for more
    367       information about these arguments.  When invoked this way, the
    368       Lisp should be able to initialize the <literal>"ccl:"</literal>
     624      information about command-line arguments.
     625      </para>
     626      <para>Assuming the shell script is configured and invoked properly, &CCL;
     627      should be able to initialize the <literal>"ccl:"</literal>
    369628      logical host so that its translations refer to the
    370629      <literal>"ccl"</literal> directory. To test this, you can call
    371630      <literal>probe-file</literal> in &CCL;'s read-eval-print
    372631      loop:</para>
     632
    373633      <programlisting>
    374634? (probe-file "ccl:level-1;level-1.lisp")  ;returns the physical pathname of the file
    375 #P"/Users/alms/my_lisp_stuff/ccl/level-1/level-1.lisp"
     635#P"/Users/joe/my_lisp_stuff/ccl/level-1/level-1.lisp"
    376636      </programlisting>
    377637    </sect2>
     
    381641          <title>Invocation</title>
    382642          <para>Assuming that the shell script is properly installed, it can be used to invoke &CCL; from a shell prompt:
    383             <programlisting>
    384 shell&gt;<replaceable>ccl</replaceable> <emphasis>args</emphasis>
    385             </programlisting>
     643            <programlisting>shell&gt; <replaceable>ccl</replaceable> <replaceable>[args ...]</replaceable></programlisting>
     644            By convention
    386645            <literal>ccl</literal> runs a 32-bit session;
    387646            <literal>ccl64</literal> runs a 64-bit session.
     647            However, the name of the installed script(s) and the implementation that is invoked are customizable,
     648            as described in <xref linkend="The-ccl-Shell-Script"/>.
    388649          </para>
     650          <para>For details about command-line options see
     651          <xref linkend="Command-Line-Options"/>.
     652          </para>
    389653    </sect2>
    390654  </sect1>
     
    461725              is a synonym for <literal>:ISO-8859-1</literal>.</para>
    462726            <para>For example:
    463               <programlisting>
    464 <![CDATA[shell> ccl -K utf-8]]>
     727              <programlisting><![CDATA[
     728shell> ccl -K utf-8]]>
    465729              </programlisting>
    466730              has the effect of making the standard CL streams use
     
    562826        Finally, any arguments following the pseudo-argument
    563827        <literal>--</literal> are not processed, and are made
    564         available to the lisp as the value of
     828        available to Lisp as the value of
    565829        <literal>ccl:*unprocessed-command-line-arguments*</literal>.
    566830      </para>
Note: See TracChangeset for help on using the changeset viewer.