Changeset 9199


Ignore:
Timestamp:
Apr 20, 2008, 12:49:09 AM (11 years ago)
Author:
mikel
Message:

mecanical and style edits in using, build, and ide

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

Legend:

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

    r9071 r9199  
    11<?xml version="1.0" encoding="utf-8"?>
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    3 <!ENTITY rest "<varname>&amp;rest</varname>">
    4 <!ENTITY key "<varname>&amp;key</varname>">
    5 <!ENTITY optional "<varname>&amp;optional</varname>">
    6 <!ENTITY body "<varname>&amp;body</varname>">
    7 <!ENTITY aux "<varname>&amp;aux</varname>">
    8 <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "Clozure CL">
    10 ]>
    11   <chapter><title>Building &CCL; from its Source Code</title>
    12     <anchor id="Building-CCL"/>
    13     <para>&CCL;, like many other Lisp implementations, consists of a
     3          <!ENTITY rest "<varname>&amp;rest</varname>">
     4          <!ENTITY key "<varname>&amp;key</varname>">
     5          <!ENTITY optional "<varname>&amp;optional</varname>">
     6          <!ENTITY body "<varname>&amp;body</varname>">
     7          <!ENTITY aux "<varname>&amp;aux</varname>">
     8          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
     9          <!ENTITY CCL "Clozure CL">
     10          ]>
     11<chapter><title>Building &CCL; from its Source Code</title>
     12  <anchor id="Building-CCL"/>
     13  <para>&CCL;, like many other Lisp implementations, consists of a
    1414    kernel and a heap image.  The kernel is an ordinary C program, and
    1515    is built with a C compiler.  It provides very basic and
     
    2020    nor the heap image can stand alone.</para>
    2121
    22     <para>You may already know that, when you have a C compiler which
     22  <para>You may already know that, when you have a C compiler which
    2323    is written in C, you need a working C compiler to build the
    2424    compiler. Similarly, the &CCL; heap image includes a Lisp
    2525    compiler, which is written in Lisp. You therefore need a working
    2626    Lisp compiler in order to build the Lisp heap image.</para>
    27    
    28     <para>Where will you get a working Lisp compiler?  No worries; you
     27 
     28  <para>Where will you get a working Lisp compiler?  No worries; you
    2929    can use a precompiled copy of a (slightly older and compatible)
    3030    version of &CCL;. This section explains how to do all this.</para>
    3131
    32     <para>In principle it should be possible to use another
     32  <para>In principle it should be possible to use another
    3333    implementation of Common Lisp as the host compiler, rather than an
    3434    older &CCL;; this would be a challenging and experimental way to
    3535    build, and is not described here.</para>
    3636
    37     <sect1 id="building-definitions"><title>Building Definitions</title>
    38       <para>The following terms are used in subsequent sections; it
     37  <sect1 id="building-definitions"><title>Building Definitions</title>
     38    <para>The following terms are used in subsequent sections; it
    3939      may be helpful to refer to these definitions.</para>
    4040
    41       <para><indexterm><primary>fasl
    42       files</primary></indexterm><glossterm linkend="fasl-file">fasl
    43       files</glossterm> are the object files produced
     41    <para><indexterm><primary>fasl
     42          files</primary></indexterm><glossterm linkend="fasl-file">fasl
     43        files</glossterm> are the object files produced
    4444      by <literal>compile-file</literal>.  fasl files store the
    4545      machine code associated with function definitions and the
     
    5252      <xref linkend="Platform-specific-filename-conventions"/> </para>
    5353
    54       <para>The <indexterm><primary>lisp
    55       kernel</primary></indexterm> <glossterm linkend="lisp_kernel">Lisp
    56       kernel</glossterm> is a C program with a fair amount of
     54    <para>The <indexterm><primary>lisp
     55          kernel</primary></indexterm> <glossterm linkend="lisp_kernel">Lisp
     56        kernel</glossterm> is a C program with a fair amount of
    5757      platform-specific assembly language code. Its basic job is to
    5858      map a lisp heap image into memory, transfer control to some
     
    6464      <xref linkend="Platform-specific-filename-conventions"/>.</para>
    6565
    66       <para>A <indexterm><primary>heap
    67       image</primary></indexterm> <glossterm linkend="lisp_image">heap
    68       image</glossterm> is a file that can be quickly mapped into a
     66    <para>A <indexterm><primary>heap
     67          image</primary></indexterm> <glossterm linkend="lisp_image">heap
     68        image</glossterm> is a file that can be quickly mapped into a
    6969      process' address space. Conceptually, it's not too different
    7070      from an executable file or shared library in the OS's native
     
    7777      <xref linkend="Platform-specific-filename-conventions"/>.</para>
    7878
    79       <para>A <indexterm><primary>bootstrapping
    80       image</primary></indexterm> bootstrapping image is a minimal
     79    <para>A <indexterm><primary>bootstrapping
     80          image</primary></indexterm> bootstrapping image is a minimal
    8181      heap image used in the process of building &CCL; itself.  The
    8282      bootstrapping image contains just enough code to load the rest
     
    8888      .</para>
    8989
    90       <para>Each supported platform (and possibly a few
     90    <para>Each supported platform (and possibly a few
    9191      as-yet-unsupported ones) has a uniquely named subdirectory of
    9292      <literal>ccl/lisp-kernel/</literal>; each such
     
    9898      <xref linkend="Platform-specific-filename-conventions"/>.</para>
    9999
    100       <sect2 id="filename_conventions">
    101        <title>Platform-specific filename conventions</title>
    102        <table id ="Platform-specific-filename-conventions">
    103          <title>Platform-specific filename conventions</title>
    104          <tgroup cols="6">
    105            <thead>
     100    <sect2 id="filename_conventions">
     101      <title>Platform-specific filename conventions</title>
     102      <table id ="Platform-specific-filename-conventions">
     103            <title>Platform-specific filename conventions</title>
     104            <tgroup cols="6">
     105              <thead>
    106106            <row>
    107                 <entry>Platform</entry>
    108                 <entry>kernel</entry>
    109                 <entry>full-image</entry>
    110                 <entry>boot-image</entry>
    111                 <entry>fasl extension</entry>
    112                 <entry>kernel-build directory</entry>
    113             </row>
    114            </thead>
    115            <tbody>
    116              <row>
    117                <entry>DarwinPPC32</entry>
    118                 <entry>dppccl</entry>
    119                 <entry>dppccl.image</entry>
    120                 <entry>ppc-boot.image</entry>
    121                 <entry>.dfsl</entry>
    122                 <entry>darwinppc</entry>
    123              </row>
    124              <row>
    125                <entry>LinuxPPC32</entry>
    126                 <entry>ppccl</entry>
    127                 <entry>PPCCL</entry>
    128                 <entry>ppc-boot</entry>
    129                 <entry>.pfsl</entry>
    130                 <entry>linuxppc</entry>
    131              </row>
    132              <row>
    133                <entry>DarwinPPC64</entry>
    134                <entry>dppccl64</entry>
    135                <entry>dppccl64.image</entry>
    136                <entry>ppc-boot64.image</entry>
    137                <entry>.d64fsl</entry>
    138                <entry>darwinppc64</entry>
    139              </row>
    140               <row>
    141                 <entry>LinuxPPC64</entry>
    142                 <entry>ppccl64</entry>
    143                 <entry>PPCCL64</entry>
    144                 <entry>ppc-boot64</entry>
    145                 <entry>.p64fsl</entry>
    146                 <entry>linuxppc64</entry>
    147               </row>
    148               <row>
    149                 <entry>LinuxX8664</entry>
    150                 <entry>lx86cl64</entry>
    151                 <entry>LX86CL64</entry>
    152                 <entry>x86-boot64</entry>
    153                 <entry>.lx64fsl</entry>
    154                 <entry>linuxx8664</entry>
    155               </row>
    156               <row>
    157                 <entry>DarwinX8664</entry>
    158                 <entry>dx86cl64</entry>
    159                 <entry>dx86cl64.image</entry>
    160                 <entry>x86-boot64.image</entry>
    161                 <entry>.dx64fsl</entry>
    162                 <entry>darwinx8664</entry>
    163               </row>
    164               <row>
    165                 <entry>FreeBSDX8664</entry>
    166                 <entry>fx86cl64</entry>
    167                 <entry>FX86CL64</entry>
    168                 <entry>fx86-boot64</entry>
    169                 <entry>.fx64fsl</entry>
    170                 <entry>freebsdx8664</entry>
    171               </row>
    172            </tbody>
    173          </tgroup>
    174        </table>
    175       </sect2>
    176     </sect1>
    177 
    178     <sect1 id="Setting-Up-to-Build">
    179       <title>Setting Up to Build</title>
    180       <para>There are currently three versions of &CCL; that you
     107              <entry>Platform</entry>
     108              <entry>kernel</entry>
     109              <entry>full-image</entry>
     110              <entry>boot-image</entry>
     111              <entry>fasl extension</entry>
     112              <entry>kernel-build directory</entry>
     113                </row>
     114              </thead>
     115              <tbody>
     116                <row>
     117                  <entry>DarwinPPC32</entry>
     118              <entry>dppccl</entry>
     119              <entry>dppccl.image</entry>
     120              <entry>ppc-boot.image</entry>
     121              <entry>.dfsl</entry>
     122              <entry>darwinppc</entry>
     123                </row>
     124                <row>
     125                  <entry>LinuxPPC32</entry>
     126              <entry>ppccl</entry>
     127                      <entry>PPCCL</entry>
     128              <entry>ppc-boot</entry>
     129              <entry>.pfsl</entry>
     130              <entry>linuxppc</entry>
     131                </row>
     132                <row>
     133                  <entry>DarwinPPC64</entry>
     134                  <entry>dppccl64</entry>
     135                  <entry>dppccl64.image</entry>
     136                  <entry>ppc-boot64.image</entry>
     137                  <entry>.d64fsl</entry>
     138                  <entry>darwinppc64</entry>
     139            </row>
     140            <row>
     141                      <entry>LinuxPPC64</entry>
     142              <entry>ppccl64</entry>
     143              <entry>PPCCL64</entry>
     144              <entry>ppc-boot64</entry>
     145              <entry>.p64fsl</entry>
     146              <entry>linuxppc64</entry>
     147            </row>
     148                <row>
     149                      <entry>LinuxX8664</entry>
     150              <entry>lx86cl64</entry>
     151              <entry>LX86CL64</entry>
     152              <entry>x86-boot64</entry>
     153              <entry>.lx64fsl</entry>
     154              <entry>linuxx8664</entry>
     155            </row>
     156                <row>
     157                      <entry>DarwinX8664</entry>
     158                      <entry>dx86cl64</entry>
     159              <entry>dx86cl64.image</entry>
     160              <entry>x86-boot64.image</entry>
     161              <entry>.dx64fsl</entry>
     162              <entry>darwinx8664</entry>
     163            </row>
     164                <row>
     165                      <entry>FreeBSDX8664</entry>
     166              <entry>fx86cl64</entry>
     167              <entry>FX86CL64</entry>
     168              <entry>fx86-boot64</entry>
     169              <entry>.fx64fsl</entry>
     170              <entry>freebsdx8664</entry>
     171            </row>
     172              </tbody>
     173            </tgroup>
     174      </table>
     175    </sect2>
     176  </sect1>
     177
     178  <sect1 id="Setting-Up-to-Build">
     179    <title>Setting Up to Build</title>
     180    <para>There are currently three versions of &CCL; that you
    181181      might want to use (and therefore might want to build from
    182182      source):</para>
    183       <itemizedlist>
    184         <listitem><para>Version 1.0 - the more stable version</para></listitem>
    185         <listitem><para>Version 1.1 - the more recent version, which
    186         runs on more platforms (including x86-64 platforms) and
    187         supports Unicode</para></listitem>
    188         <listitem><para>Version 1.2 - supports (at least) all of the
    189         features and platforms as 1.1, but is distributed and updated
    190         differently</para></listitem>
    191       </itemizedlist>
    192       <para>All versions are available for download from the &CCL;
     183    <itemizedlist>
     184      <listitem><para>Version 1.0 - the more stable version</para></listitem>
     185      <listitem><para>Version 1.1 - the more recent version, which
     186          runs on more platforms (including x86-64 platforms) and
     187          supports Unicode</para></listitem>
     188          <listitem><para>Version 1.2 - supports (at least) all of the
     189              features and platforms as 1.1, but is distributed and updated
     190              differently</para></listitem>
     191    </itemizedlist>
     192    <para>All versions are available for download from the &CCL;
    193193      website in the form of archives that contain everything you need
    194194      to work with &CCL;, including the complete sources, a full
    195195      heap image, and the foreign-function interface database.</para>
    196       <para>Version 1.0 archives are named
     196    <para>Version 1.0 archives are named
    197197      <literal>openmcl-</literal><replaceable>platform</replaceable><literal>-all-1.0.tar.gz</literal>,
    198198      where <replaceable>platform</replaceable> is either
     
    201201      undergoing active development, you won't ever need to update
    202202      these sources.</para>
    203       <para>Version 1.1 archives are named
     203    <para>Version 1.1 archives are named
    204204      <literal>openmcl-</literal><replaceable>platform</replaceable><literal>-snapshot-</literal><replaceable>yymmdd</replaceable><literal>.tar.gz</literal>,
    205205      where <replaceable>platform</replaceable> is either
     
    209209      <replaceable>yymmdd</replaceable> is the year, month, and day
    210210      the snapshot was released.</para>
    211       <para>Because version 1.1 is undergoing active development,
     211    <para>Because version 1.1 is undergoing active development,
    212212      there may be times when you want to get sources that are more
    213213      recent than the most recent snapshot and use them to build
     
    218218      working-copy information in it, so all you need to do to update
    219219      is</para>
    220       <programlisting>
     220    <programlisting>
    221221$ cd ccl
    222222$ cvs login             # password is "cvs"
    223                         # this step only needs to be done once,
    224                         # that'll store the trivially encrypted
    225                         # password in ~/.cvspas
     223# this step only needs to be done once,
     224# that'll store the trivially encrypted
     225# password in ~/.cvspas
    226226$ cvs update
    227       </programlisting>
    228       <para>Unless you tell it to, cvs won't delete ("prune") empty
     227    </programlisting>
     228    <para>Unless you tell it to, cvs won't delete ("prune") empty
    229229      directories or create new ones when the repository changes.
    230230      It's generally a good habit to use</para>
    231       <programlisting>
     231    <programlisting>
    232232$ cvs update -d -P      # create dirs as needed, prune empty ones
    233       </programlisting>
    234       <para>Version 1.2 archives follow naming conventions that are
     233    </programlisting>
     234    <para>Version 1.2 archives follow naming conventions that are
    235235      similar to those used by 1.0 (though more platforms are supported.)
    236236      However, rather than containing CVS working-copy information, the
    237237      1.2 (and, presumably, later) archives contain metainformation used
    238238      by the Subversion (svn) source-code control system.</para>
    239       <para>Subversion client programs are pre-installed on OSX 10.5 and
     239    <para>Subversion client programs are pre-installed on OSX 10.5 and
    240240      later and are typically either pre-installed or readily available
    241241      on Linux and FreeBSD platforms.  The <ulink url="http://subversion.tigris.org">Subversion web page</ulink> contains links to subversion client programs
    242242      for many platforms; users of OSX versions 10.4 and earlier can also
    243243      install Subversion clients via Fink or MacPorts.</para>
    244      
    245     </sect1>
    246 
    247     <sect1 id="Building-Everything">
    248       <title>Building Everything</title>
    249       <para>Given that you now have everything you need, do the
     244   
     245  </sect1>
     246
     247  <sect1 id="Building-Everything">
     248    <title>Building Everything</title>
     249    <para>Given that you now have everything you need, do the
    250250      following in a running &CCL; to bring your Lisp system
    251251      completely up to date.</para>
    252       <programlisting>
     252    <programlisting>
    253253? (ccl:rebuild-ccl :full t)
    254       </programlisting>
    255       <para>That call to the function <literal>rebuild-ccl</literal>
    256       will perform the following steps:</para>
    257       <itemizedlist>
    258         <listitem>
    259           <para>Deletes all fasl files and other object files in the
    260           <literal>ccl</literal>directory tree</para>
    261         </listitem>
    262         <listitem>
    263           <para>Runs an external process which does a
    264           <literal>make</literal> in the currentplatform's kernel
    265           build directory to create a new kernel</para>
    266         </listitem>
    267         <listitem>
    268           <para>Does <literal>(compile-ccl t)</literal> in the running
    269           lisp, to produce aset of fasl files from the &ldquo;higher
    270           level&rdquo; lisp sources.</para>
    271         </listitem>
    272         <listitem>
    273           <para>Does <literal>(xload-level-0 :force)</literal> in the
    274           running lisp, to compile thelisp sources in the
    275           &ldquo;ccl:level-0;&rdquo; directory into fasl files and
    276           then createa bootstrapping image from those fasl
    277           files.</para>
    278         </listitem>
    279         <listitem>
    280           <para>Runs another external process, which causes the newly
    281           compiled lispkernel to load the new bootstrapping image.
    282           The bootsrtrapping image then loadsthe &ldquo;higher
    283           level&rdquo; fasl files and a new copy of the platform's
    284           full heap imageis then saved.</para>
    285         </listitem>
    286       </itemizedlist>
    287       <para>If all goes well, it'll all happen without user
     254    </programlisting>
     255    <para>That call to the function <literal>rebuild-ccl</literal>
     256      performs the following steps:</para>
     257    <itemizedlist>
     258      <listitem>
     259            <para>Deletes all fasl files and other object files in the
     260              <literal>ccl</literal> directory tree</para>
     261          </listitem>
     262      <listitem>
     263            <para>Runs an external process that does a
     264              <literal>make</literal> in the current platform's kernel
     265              build directory to create a new kernel</para>
     266          </listitem>
     267      <listitem>
     268            <para>Does <literal>(compile-ccl t)</literal> in the running
     269              lisp, to produce a set of fasl files from the &ldquo;higher
     270              level&rdquo; lisp sources.</para>
     271          </listitem>
     272      <listitem>
     273            <para>Does <literal>(xload-level-0 :force)</literal> in the
     274              running lisp, to compile the lisp sources in the
     275              &ldquo;ccl:level-0;&rdquo; directory into fasl files and
     276              then create a bootstrapping image from those fasl
     277              files.</para>
     278          </listitem>
     279      <listitem>
     280            <para>Runs another external process, which causes the newly
     281              compiled lisp kernel to load the new bootstrapping image.
     282              The bootsrtrapping image then loads the &ldquo;higher
     283              level&rdquo; fasl files and a new copy of the platform's
     284              full heap image is then saved.</para>
     285          </listitem>
     286    </itemizedlist>
     287    <para>If all goes well, it'll all happen without user
    288288      intervention and with some simple progress messages.  If
    289289      anything goes wrong during execution of either of the external
    290290      processes, the process output is displayed as part of a lisp
    291291      error message.</para>
    292       <para><literal>rebuild-ccl</literal> is essentially just a short
     292    <para><literal>rebuild-ccl</literal> is essentially just a short
    293293      cut for running all the individual steps involved in rebuilding
    294294      the system.  You can also execute these steps individually, as
    295295      described below.</para>
    296     </sect1>
    297 
    298     <sect1 id="Building-the-kernel">
    299       <title>Building the kernel</title>
    300       <para>The Lisp kernel is the executable which you run to use
     296  </sect1>
     297
     298  <sect1 id="Building-the-kernel">
     299    <title>Building the kernel</title>
     300    <para>The Lisp kernel is the executable that you run to use
    301301      Lisp.  It doesn't actually contain the entire Lisp
    302302      implementation; rather, it loads a heap image which contains the
    303       specifics - the "library", as it might be called if this was a C
     303      specifics&mdash;the "library", as it might be called if this was a C
    304304      program.  The kernel also provides runtime support to the heap
    305305      image, such as garbage collection, memory allocation, exception
    306306      handling, and the OS interface.</para>
    307307
    308       <para>The Lisp kernel file has different names on different
    309       platforms. See FIXTHIS . On all platforms the lisp kernel sources reside
     308    <para>The Lisp kernel file has different names on different
     309      platforms. See
     310      <xref linkend="Platform-specific-filename-conventions"/>. On all
     311      platforms the lisp kernel sources reside
    310312      in <literal>ccl/lisp-kernel</literal>.</para>
    311313
    312       <para>This section gives directions on how to rebuild the Lisp
     314    <para>This section gives directions on how to rebuild the Lisp
    313315      kernel from its source code.  Most &CCL; users will rarely
    314316      have to do this.  You probably will only need to do it if you are
     
    319321? (rebuild-ccl :full t)
    320322      </programlisting>
    321       </para>
    322 
    323 
    324       <sect2 id="Kernel-build-prerequisites">
    325         <title>Kernel build prerequisites</title>
    326         <para>The &CCL; kernel can be bult with the following widely
    327         available tools:</para>
    328         <itemizedlist>
    329           <listitem><para>cc or gcc- the GNU C compiler</para></listitem>
    330           <listitem><para>ld - the GNU linker</para></listitem>
    331           <listitem><para>m4 or gm4- the GNU m4 macro processor</para></listitem>
    332           <listitem><para>as - the GNU assembler (version 2.10.1 or later)</para></listitem>
    333           <listitem><para>make - either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
    334         </itemizedlist>
    335         <para> In general, the more recent the versions of those
    336         tools, the better; some versions of gcc 3.x on Linux have
    337         difficulty compiling some of the kernel source code correctly
    338         (so gcc 4.0 should be used, if possible.)  On OSX, the
    339         versions of the tools distributed with XCode should work fine;
    340         on Linux, the versions of the tools installed with the OS (or
    341         available through its package management system) should work
    342         fine if they're "recent enough".  On FreeBSD, the installed
    343         version of the <literal>m4</literal> program doesn't support
    344         some features that the kernel build process depends on; the
    345         GNU version of the m4 macroprocessor (called
    346         <literal>gm4</literal> on FreeBSD) should be installed
    347 
    348         </para>
    349       </sect2>
    350       <sect2 id="kernel-build-command">
    351         <title>Using "make" to build the lisp kernel</title>
    352         <para>With those tools in place, do:
     323    </para>
     324
     325
     326    <sect2 id="Kernel-build-prerequisites">
     327      <title>Kernel build prerequisites</title>
     328          <para>The &CCL; kernel can be bult with the following widely
     329            available tools:</para>
     330      <itemizedlist>
     331        <listitem><para>cc or gcc- the GNU C compiler</para></listitem>
     332        <listitem><para>ld - the GNU linker</para></listitem>
     333        <listitem><para>m4 or gm4- the GNU m4 macro processor</para></listitem>
     334        <listitem><para>as - the GNU assembler (version 2.10.1 or later)</para></listitem>
     335            <listitem><para>make - either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
     336          </itemizedlist>
     337          <para> In general, the more recent the versions of those
     338            tools, the better; some versions of gcc 3.x on Linux have
     339            difficulty compiling some of the kernel source code correctly
     340            (so gcc 4.0 should be used, if possible.)  On OSX, the
     341            versions of the tools distributed with XCode should work fine;
     342            on Linux, the versions of the tools installed with the OS (or
     343            available through its package management system) should work
     344            fine if they're "recent enough".  On FreeBSD, the installed
     345            version of the <literal>m4</literal> program doesn't support
     346            some features that the kernel build process depends on; the
     347            GNU version of the m4 macroprocessor (called
     348            <literal>gm4</literal> on FreeBSD) should be installed.
     349
     350          </para>
     351    </sect2>
     352    <sect2 id="kernel-build-command">
     353          <title>Using "make" to build the lisp kernel</title>
     354      <para>With those tools in place, do:
    353355        <programlisting>
    354356shell> cd ccl/lisp-kernel/<replaceable>PLATFORM</replaceable>
    355357shell> make
    356         </programlisting>
    357         </para>
    358         <para>That'll assemble several assembly language source files,
     358            </programlisting>
     359          </para>
     360      <para>That'll assemble several assembly language source files,
    359361        compile several C source files, and link
    360362        ../../<replaceable>the kernel</replaceable>.
    361         </para>
    362       </sect2>
    363     </sect1>
    364     <sect1 id="Building-the-heap-image">
    365       <title>Building the heap image</title>
    366       <para>The initial heap image is loaded by the Lisp kernel, and
    367       provides most all of the language implementation The heap image
     363          </para>
     364    </sect2>
     365  </sect1>
     366  <sect1 id="Building-the-heap-image">
     367    <title>Building the heap image</title>
     368    <para>The initial heap image is loaded by the Lisp kernel, and
     369      provides most of the language implementation The heap image
    368370      captures the entire state of a running Lisp (except for external
    369371      resources, such as open files and TCP sockets).  After it is
     
    371373      exactly the same as those of the old Lisp process when the image
    372374      was created.</para>
    373       <para>The heap image is how we get around the fact that we can't
     375    <para>The heap image is how we get around the fact that we can't
    374376      run Lisp code until we have a working Lisp implementation, and
    375377      we can't make our Lisp implementation work until we can run Lisp
     
    377379      implementation, all we need to do is load it into memory and
    378380      start using it.</para>
    379       <para>If you're building a new version of &CCL;, you need to
     381    <para>If you're building a new version of &CCL;, you need to
    380382      build a new heap image.</para>
    381       <para>(You might also wish to build a heap image if you have a
    382       large program which it is very complicated or time-consuming to
     383    <para>(You might also wish to build a heap image if you have a
     384      large program that is very complicated or time-consuming to
    383385      load, so that you will be able to load it once, save an image,
    384386      and thenceforth never have to load it again. At any time, a heap
     
    387389      <literal>ccl:save-application</literal>.)</para>
    388390
    389       <sect2 id="Development-cycle">
    390         <title>Development cycle</title>
    391         <para>Creating a new &CCL; full heap image consists of the
     391    <sect2 id="Development-cycle">
     392          <title>Development cycle</title>
     393      <para>Creating a new &CCL; full heap image consists of the
    392394        following steps:</para>
    393         <orderedlist>
    394           <listitem><para>Using your existing &CCL;, create a
    395           bootstrapping image</para></listitem>
    396           <listitem><para>Using your existing &CCL;, recompile your
    397           updated &CCL; sources</para></listitem>
    398           <listitem><para>Invoke &CCL; with the bootstrapping image
    399           you just created (rather than with the existing full heap
    400           image).</para></listitem>
    401         </orderedlist>
    402         <para>When you invoke &CCL; with the bootstrapping image, it
    403         will start up, load al of the &CCL; fasl files, and save out
    404         a new full heap image.  Voila.  You've created a new heap
    405         image.</para>
    406         <para>A few points worth noting:</para>
    407         <itemizedlist>
    408           <listitem>
    409             <para>There's a circular dependency between the full heap
    410             image and thebootstrapping image, in that each is used to
    411             build the other.</para>
    412           </listitem>
    413           <listitem>
    414             <para>There are some minor implementation
    415             differences, but the environment in effect after the
    416             bootstrapping image has loaded its fasl files is essentially
    417             equivalent to the environment provided by the full heap
    418             image; the latter loads a lot faster and is easier to
    419             distribute, of course.</para>
    420           </listitem>
    421           <listitem>
    422             <para>If the full heap image doesn't work (because
    423             of an OScompatibilty problem or other bug), it's very likely
    424             that thebootstrapping image will suffer the same
    425             problems.</para>
    426           </listitem>
    427         </itemizedlist>
    428         <para>Given a bootstrapping image and a set of up-to-date fasl
     395      <orderedlist>
     396        <listitem><para>Using your existing &CCL;, create a
     397            bootstrapping image</para></listitem>
     398        <listitem><para>Using your existing &CCL;, recompile your
     399            updated &CCL; sources</para></listitem>
     400        <listitem><para>Invoke &CCL; with the bootstrapping image
     401            you just created (rather than with the existing full heap
     402            image).</para></listitem>
     403          </orderedlist>
     404          <para>When you invoke &CCL; with the bootstrapping image, it
     405            starts up, loads all of the &CCL; fasl files, and saves out a
     406            new full heap image.  Voila.  You've created a new heap
     407            image.</para>
     408      <para>A few points worth noting:</para>
     409          <itemizedlist>
     410        <listitem>
     411              <para>There's a circular dependency between the full heap
     412                image and the bootstrapping image, in that each is used to
     413                build the other.</para>
     414            </listitem>
     415        <listitem>
     416              <para>There are some minor implementation
     417                differences, but the environment in effect after the
     418                bootstrapping image has loaded its fasl files is essentially
     419                equivalent to the environment provided by the full heap
     420                image; the latter loads a lot faster and is easier to
     421                distribute, of course.</para>
     422            </listitem>
     423        <listitem>
     424              <para>If the full heap image doesn't work (because
     425                of an OS compatibilty problem or other bug), it's very likely
     426                that the bootstrapping image will suffer the same
     427                problems.</para>
     428            </listitem>
     429          </itemizedlist>
     430      <para>Given a bootstrapping image and a set of up-to-date fasl
    429431        files, the development cycle usually involves editing lisp
    430432        sources (or updating those sources via cvs update),
    431433        recompiling modified files, and using the bootstrapping image
    432434        to produce a new heap image.</para>
    433       </sect2>
    434 
    435       <sect2 id="Generating-a-bootstrapping-image">
    436         <title>Generating a bootstrapping image</title>
    437         <para>The bootstrapping image isn't provided in &CCL;
     435    </sect2>
     436
     437    <sect2 id="Generating-a-bootstrapping-image">
     438      <title>Generating a bootstrapping image</title>
     439      <para>The bootstrapping image isn't provided in &CCL;
    438440        distributions. It can be built from the source code provided
    439441        in distributions (using a lisp image and kernel provided in
     
    441443        below.</para>
    442444
    443         <para>The bootstrapping image is built by invoking a special
     445      <para>The bootstrapping image is built by invoking a special
    444446        utility inside a running &CCL; heap image to load files
    445447        contained in the <literal>ccl/level-0</literal> directory. The
     
    449451        "cross-dumping".</para>
    450452
    451         <para>Given a source distribution, a lisp kernel, and aheap
    452         image, one can produce a bootstapping image by first invoking
     453      <para>Given a source distribution, a lisp kernel, and a heap
     454        image, one can produce a bootstrapping image by first invoking
    453455        &CCL; from the shell:</para>
    454         <programlisting>
     456      <programlisting>
    455457shell&gt; openmcl
    456458Welcome to &CCL; .... !
    457459?
    458         </programlisting>
    459         <para>then calling <literal>ccl:xload-level-0</literal> at the
    460         lisp prompt</para>
    461         <programlisting>
     460          </programlisting>
     461          <para>then calling <literal>ccl:xload-level-0</literal> at the
     462            lisp prompt</para>
     463          <programlisting>
    462464? (ccl:xload-level-0)
    463         </programlisting>
    464         <para>This will compile the lisp sources in the ccl/level-0
     465          </programlisting>
     466      <para>This function compiles the lisp sources in the ccl/level-0
    465467        directory if they're newer than the corresponding fasl files
    466         and will then load the resulting fasl files into a simulated
    467         lisp heap contained inside data structures inside the running
     468        and then loads the resulting fasl files into a simulated lisp
     469        heap contained in data structures inside the running
    468470        lisp. That simulated heap image is then written to
    469471        disk.</para>
    470         <para><literal>xload-level-0</literal> should be called
     472      <para><literal>xload-level-0</literal> should be called
    471473        whenever your existing boot image is out-of-date with respect
    472474        to the source files in <literal>ccl:level-0;</literal>
    473475        :</para>
    474         <programlisting>
     476      <programlisting>
    475477? (ccl:xload-level-0 :force)
    476 </programlisting>
    477         <para>will force recompilation of the level-0 sources.</para>
    478       </sect2>
    479 
    480       <sect2 id="Generating-fasl-files">
    481         <title>Generating fasl files</title>
    482         <para> Calling:</para>
    483         <programlisting>
     478      </programlisting>
     479      <para>forces recompilation of the level-0 sources.</para>
     480    </sect2>
     481
     482    <sect2 id="Generating-fasl-files">
     483      <title>Generating fasl files</title>
     484          <para> Calling:</para>
     485      <programlisting>
    484486? (ccl:compile-ccl)
    485         </programlisting>
    486         <para>at the lisp prompt will compile any fasl files that are
    487         out-of-date with respect to the corresponding lisp sources;
    488         <literal>(ccl:compile-ccl t)</literal> will force
    489         recompilation. <literal>ccl:compile-ccl</literal> will reload
    490         newly-compiled versions of some files;
    491         <literal>ccl:xcompile-ccl</literal> is analogous, but skips
    492         this reloading step.</para>
    493         <para>Unless there are bootstrapping considerations involved,
    494         it usually doesn't matter whether these files reloaded after
     487          </programlisting>
     488          <para>at the lisp prompt compiles any fasl files that are
     489            out-of-date with respect to the corresponding lisp sources;
     490            <literal>(ccl:compile-ccl t)</literal> forces
     491            recompilation. <literal>ccl:compile-ccl</literal> reloads
     492            newly-compiled versions of some files;
     493            <literal>ccl:xcompile-ccl</literal> is analogous, but skips
     494            this reloading step.</para>
     495      <para>Unless there are bootstrapping considerations involved, it
     496        usually doesn't matter whether these files are reloaded after
    495497        they're recompiled.</para>
    496         <para>Calling <literal>compile-ccl</literal> or
     498      <para>Calling <literal>compile-ccl</literal> or
    497499        <literal>xcompile-ccl</literal> in an environment where fasl
    498500        files don't yet exist may produce warnings to that effect
     
    504506        warnings about undefined functions, etc. They should be
    505507        cleaned up at some point.</para>
    506       </sect2>
    507 
    508       <sect2 id="Building-a-full-image-from-a-bootstrapping-image">
    509         <title>Building a full image from a bootstrapping image</title>
    510         <para>To build a full image from a bootstrapping image, just
    511         invoke the kernel with the bootstrapping image is an
    512         argument</para>
    513         <programlisting>
     508    </sect2>
     509
     510    <sect2 id="Building-a-full-image-from-a-bootstrapping-image">
     511          <title>Building a full image from a bootstrapping image</title>
     512          <para>To build a full image from a bootstrapping image, just
     513            invoke the kernel with the bootstrapping image as an
     514            argument</para>
     515      <programlisting>
    514516$ cd ccl                        # wherever your ccl directory is
    515517$ ./KERNEL BOOT_IMAGE
    516         </programlisting>
    517         <para>Where <replaceable>KERNEL</replaceable> and
     518          </programlisting>
     519      <para>Where <replaceable>KERNEL</replaceable> and
    518520        <replaceable>BOOT_IMAGE</replaceable> are the names of
    519521        the kernel and boot image appropriate to the platform you are
    520         running on.  See FIXTHIS</para>
    521         <para>That should load a few dozen fasl files (printing a
     522        running on.  See <xref linkend="Platform-specific-filename-conventions"/></para>
     523      <para>That should load a few dozen fasl files (printing a
    522524        message as each file is loaded.) If all of these files
    523525        successfully load, the lisp will print a prompt. You should be
     
    526528        you're confident that things loaded OK, you can save that
    527529        image.</para>
    528         <programlisting>
     530      <programlisting>
    529531? (ccl:save-application "<replaceable>image_name</replaceable>") ; Overwiting the existing heap image
    530         </programlisting>
    531         <para>Where <replaceable>image_name</replaceable> is the name
    532         of the full heap image for your platform. See FIXTHIS.</para>
    533         <para>If things go wrong in the early stages of the loading
     532          </programlisting>
     533          <para>Where <replaceable>image_name</replaceable> is the name of
     534        the full heap image for your platform. See
     535        <xref linkend="Platform-specific-filename-conventions"/>.</para>
     536      <para>If things go wrong in the early stages of the loading
    534537        sequence, errors are often difficult to debug; until a fair
    535538        amount of code (CLOS, the CL condition system, streams, the
     
    539542        cause the lisp kernel debugger (see ) to be invoked; it's
    540543        primitive, but can sometimes help one to get oriented.</para>
    541       </sect2>
    542     </sect1>
    543   </chapter>
     544    </sect2>
     545  </sect1>
     546</chapter>
  • trunk/source/doc/src/ide.xml

    r8981 r9199  
    4343      <listitem>
    4444        <para>Run ccl from the shell. The easiest way to do this is
    45           generally to execute the openmcl or openmcl64 command.</para>
     45          generally to execute the ccl or ccl64 command.</para>
    4646      </listitem>
    4747      <listitem>
     
    5555
    5656    <programlisting>
    57       oshirion:ccl mikel$ openmcl64
    58       Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
    59       ? (require :cocoa-application)
    60       ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
    61       ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
    62 
    63       [...many lines of "Compiling" and "Loading" omitted...]
    64 
    65       Saving application to /usr/local/ccl/Clozure CL.app/
    66 
    67       oshirion:ccl mikel$
     57oshirion:ccl mikel$ ccl64
     58Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk  (DarwinX8664)!
     59? (require :cocoa-application)
     60;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
     61;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
     62
     63[...many lines of "Compiling" and "Loading" omitted...]
     64
     65Saving application to /usr/local/ccl/Clozure CL.app/
     66
     67oshirion:ccl mikel$
    6868
    6969    </programlisting>
  • trunk/source/doc/src/using.xml

    r9071 r9199  
    514514
    515515    <para>&CCL; supports character names of the form
    516     <literal>u+xxxx</literal> - where <literal>x</literal> is a
     516    <literal>u+xxxx</literal>&mdash;where <literal>x</literal> is a
    517517    sequence of one or more hex digits.  The value of the hex digits
    518518    denotes the code of the character.  The <literal>+</literal>
     
    530530    character names, look just below the definition for
    531531    <function>register-character-name</function> in
    532     <literal>ccl:level-1;l1-reader.lisp</literal> see the complete
    533     list of char</para>
     532    <literal>ccl:level-1;l1-reader.lisp</literal>.</para>
    534533  </sect2>
    535534
     
    545544    keyword (see <xref linkend="Character-Encodings"/>), an
    546545    external-format object created using
    547     <function>CCL::MAKE-EXTERNAL-FORMAT</function>(see <xref
     546    <function>CCL::MAKE-EXTERNAL-FORMAT</function> (see <xref
    548547    linkend="f_make-external-format"/>), or a plist with keys:
    549548    <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
     
    650649          </varlistentry>
    651650          <varlistentry>
    652             <term>[result]</term>
    653             <listitem>
    654               <para>[description]</para>
     651            <term>external-format</term>
     652            <listitem>
     653              <para>An external-format object as described above.</para>
    655654            </listitem>
    656655          </varlistentry>
     
    661660        <title>Description</title>
    662661       
    663         <para>Despite the function's name, it doesn't necessarily
    664         create a new, unique EXTERNAL-FORMAT object: two calls to
    665         MAKE-EXTERNAL-FORMAT with the same arguments made in the
    666         same dynamic environment will return the same (eq) object.
     662        <para>Despite the function's name, it doesn't necessarily create a
     663        new, unique EXTERNAL-FORMAT object: two calls to
     664        MAKE-EXTERNAL-FORMAT with the same arguments made in the same
     665        dynamic environment return the same (eq) object.
    667666        </para>
    668667      </refsect1>
     
    769768    <sect3><title>Encoding Problems</title>
    770769      <para>On output to streams with character encodings that can
    771       encode the full range of Unicode - and on input from any stream
    772       - "unencodable characters" are represented using the Unicode
    773       #\Replacement_Character (= #\U+fffd); the presence of such a
    774       character usually indicates that something got lost in
     770      encode the full range of Unicode&mdash;and on input from any
     771      stream&mdash;"unencodable characters" are represented using the
     772      Unicode #\Replacement_Character (= #\U+fffd); the presence of
     773      such a character usually indicates that something got lost in
    775774      translation.  Either data wasn't encoded properly or there was a
    776775      bug in the decoding process.</para>
     
    788787      indicate that the encoding is UTF-8.)</para>
    789788
    790       <para>Clozure CL will write a byte order mark as the first
    791       character of a file or socket stream when the endianness of the
    792       character encoding is not explicit.  Clozure CL also expects a
    793       byte order mark on input from streams where the endianness is
    794       not explicit. If a byte order mark is missing from input data,
    795       that data is assumed to be in big-endian order.</para>
     789      <para>Clozure CL writes a byte order mark as the first character
     790      of a file or socket stream when the endianness of the character
     791      encoding is not explicit.  Clozure CL also expects a byte order
     792      mark on input from streams where the endianness is not
     793      explicit. If a byte order mark is missing from input data, that
     794      data is assumed to be in big-endian order.</para>
    796795
    797796      <para>A byte order mark from a UTF-8 encoded input stream is not
    798       treated specially and and will just appear as normal character
    799       from the input stream.  It is probably a good idea to skip over
    800       this character.</para>
     797      treated specially and just appears as a normal character from
     798      the input stream.  It is probably a good idea to skip over this
     799      character.</para>
    801800    </sect3>
    802801
Note: See TracChangeset for help on using the changeset viewer.