Changes between Version 4 and Version 5 of BuildingCmucl


Ignore:
Timestamp:
03/04/12 17:25:10 (3 years ago)
Author:
rtoy
Comment:

More cleanups.

Legend:

Unmodified
Added
Removed
Modified
  • BuildingCmucl

    v4 v5  
    2626 </li>
    2727 <li> GNU make.
    28    <p>This has to be available either as gmake or make in your PATH, or
    29    the MAKE environment variable has to be set to point to the correct
     28   <p>This has to be available either as gmake or make in your <code>PATH</code>, or
     29   the <code>MAKE</code> environment variable has to be set to point to the correct
    3030   binary.</p>
    3131 </li>
     
    3939If you want to build CMU CL's Motif interface/toolkit, you'll need a
    4040working version of the Motif libraries, either true-blue OSF/Motif, or
    41 OpenMotif, or Lesstif.  The code was developed against 1.2 Motif,
    42 though recompilation against 2.x Motif probably works as well.
     41[http://www.openmotif.org OpenMotif], or [http://www.lestif.org LessTif].  The code
     42was developed against 1.2 Motif, though recompilation against 2.x
     43Motif probably works as well.
    4344
    4445== Setting up a build environment ==
     
    5859  <pre>
    5960    git clone git://common-lisp.net/projects/cmucl/cmucl.git
    60   </pre> <p>Whatever you do, the sources must be in a directory named src
     61  </pre> <p>Whatever you do, the sources must be in a directory named <code>src</code>
    6162    inside the base directory.  Since the build tools keep all
    6263    generated files in separate target directories, the src directory
     
    118119
    119120How do you know which of the three options above apply?  The easiest
    120 way is to look in src/bootfiles/<version>/* for boot files.  If the
     121way is to look in {{{src/bootfiles/<version>/*}}} for boot files.  If the
    121122file date of a boot file is later than the version of CMUCL you are
    122123building from, then you need to use b) or c) above.  You may need to
     
    125126If there are no bootfiles, then you can use a) above.
    126127
    127 The build.sh script supports other options, and bin/build.sh -?
    128 will give a quick summary.  Read bin/build.sh for more
     128The {{{build.sh}}} script supports other options, and {{{bin/build.sh -?}}}
     129will give a quick summary.  Read {{{bin/build.sh}}} for more
    129130information.
    130131
     
    141142   <p>This happens in your current CMU CL process, using your current
    142143   CMU CL's normal file compiler.  This phase currently consists of 3
    143    sub-phases, namely those controlled by src/tools/worldcom.lisp,
    144    which compiles all the runtime files, src/tools/comcom.lisp, which
     144   sub-phases, namely those controlled by <code>src/tools/worldcom.lisp</code>,
     145   which compiles all the runtime files, <code>src/tools/comcom.lisp</code>, which
    145146   compiles the compiler (including your chosen backend), and finally
    146147   src/tools/pclcom.lisp, which compiles PCL, CMU CL's CLOS
     
    151152 <li> Building a new kernel.core file out of the so created files
    152153   <p>This process, which is generally called genesis, and which is
    153    controlled by src/tools/worldbuild.lisp, uses the newly compiled
     154   controlled by <code>src/tools/worldbuild.lisp</code>, uses the newly compiled
    154155   files in order to build a new, basic core file, which is then used
    155156   by the last phase to create a fully functional normal core file.
     
    159160   core is started.</p>
    160161
    161    <p>As part of this process, it also creates the file internals.h,
     162   <p>As part of this process, it also creates the file <code>internals.h</code>,
    162163   which contains information about the general memory layout of the
    163164   new core and its basic types, their type tags, and the location of
     
    293294features may require a cross-compile instead of a normal compile.
    294295
    295  bin/clean-target.sh [-l] target-directory [more dirs]::
     296 {{{bin/clean-target.sh [-l] target-directory [more dirs]}}}::
    296297 Cleans the given target directory, so that all created files will be
    297298 removed.  This is useful to force recompilation.  If the -l flag is
     
    300301 and the config file.
    301302
    302  bin/build-world.sh target-directory [build-binary] [build-flags...]::
     303 {{{bin/build-world.sh target-directory [build-binary] [build-flags...]}}}::
    303304 Starts a complete world build for the given target, using the lisp
    304305 binary/core specified as a build host.  The recompilation step will
     
    310311 world build process with build-world.sh
    311312
    312  bin/rebuild-lisp.sh target-directory::
     313 {{{bin/rebuild-lisp.sh target-directory}}}::
    313314 This script will force a complete recompilation of the C runtime code
    314315 of CMU CL (aka the lisp executable).  Doing this will necessitate
    315316 building a new kernel.core file, using build-world.sh.
    316317
    317  bin/load-world.sh target-directory version::
     318 {{{bin/load-world.sh target-directory version}}}::
    318319 This will finish the CMU CL rebuilding process, by loading the
    319320 remaining compiled files generated in the world build process into the
     
    329330post the 18d release.
    330331
    331  bin/build-utils.sh target-directory::
     332 {{{bin/build-utils.sh target-directory}}}::
    332333 This script will build auxiliary libraries packaged with CMU CL,
    333334 including CLX, CMUCL/Motif, the Motif debugger, inspector, and control
     
    335336 core of the given target.
    336337
    337  bin/make-dist.sh [-bg] [-G group] [-O owner] target-directory version arch os::
     338 {{{bin/make-dist.sh [-bg] [-G group] [-O owner] target-directory version arch os}}}::
    338339 This script creates both main and extra distribution tarballs from the
    339340 given target directory, using the make-main-dist.sh and
     
    376377simple streams.
    377378
    378 This is intended to be run from make-dist.sh.
    379 
    380  bin/make-extra-dist.sh target-directory version arch os::
     379This is intended to be run from {{{make-dist.sh}}}.
     380
     381 {{{bin/make-extra-dist.sh target-directory version arch os}}}::
    381382 This is script is not normally invoked by the user; make-dist will do
    382383 it appropriately.
     
    387388tarballs, i.e. the auxiliary libraries such as CLX, CLM, and Hemlock.
    388389
    389 This is intended to be run from make-dist.sh.
    390 
    391 
    392  cross-build-world.sh target-directory cross-directory cross-script [build-binary] [build-flags...]::
     390
     391 {{{cross-build-world.sh target-directory cross-directory cross-script [build-binary] [build-flags...]}}}::
    393392 This is a script that can be used instead of build-world.sh for
    394393 cross-compiling CMUCL.  In addition to the arguments of build-world.sh
     
    485484that change.  There are two forms of boostrapping that can be
    486485required:
    487 
    488  a. Bootfiles
    489 
    490    The maintainers try to make bootfiles available, that allow going
     486{{{
     487#!html
     488<ol style="list-style-type:lower-alpha">
     489 <li> Bootfiles
     490   <p>The maintainers try to make bootfiles available, that allow going
    491491   from an old release to the next release.  These are located in the
    492    src/bootfiles/<old-release>/ directory of the CMU CL sources.
    493 
    494    I.e. if you have binaries that match release 18d, then you'll need
     492   src/bootfiles/<old-release>/ directory of the CMU CL sources.</p>
     493
     494   <p>I.e. if you have binaries that match release 18d, then you'll need
    495495   to use all the bootfiles in src/bootfiles/18d/ in order to go to
    496496   the next release (or current sources, if no release has been made
    497497   yet).  If you already used some of the bootstrap files to compile
    498498   your current lisp, you obviously don't need to use those to get to
    499    later versions.
    500 
    501    You can use the bootfiles by concatenating them into a file called
     499   later versions.</p>
     500
     501   <p>You can use the bootfiles by concatenating them into a file called
    502502   bootstrap.lisp in the target directory (i.e. target:bootstrap.lisp)
    503503   in the order they are numbered.  Be sure to remove the bootstrap
    504    file once it is no longer needed.
    505 
    506    Alternatively, the bootstrap file can just "load" the individual
    507    bootfiles as needed.
    508 
    509  a. Cross-compiling
    510 
    511    Under some circumstances, bootstrap code will not be sufficient,
     504   file once it is no longer needed.</p>
     505
     506   <p>Alternatively, the bootstrap file can just "load" the individual
     507   bootfiles as needed.</p>
     508 </li>
     509 <li> Cross-compiling
     510   <p>Under some circumstances, bootstrap code will not be sufficient,
    512511   and a cross-compilation is needed.  In that case you will have to
    513512   use cross-build-world.sh, instead of build-world.sh.  Please read
    514513   the instructions of that script for details of the more complex
    515    procedure.
    516 
    517    << This isn't really true anymore, and we should place a more
    518       elaborate description of the cross-compiling process here >>
    519 
    520    When cross-compiling, there are two sorts of bootscripts that can be
     514   procedure.</p>
     515
     516   <p><< This isn't really true anymore, and we should place a more
     517      elaborate description of the cross-compiling process here >></p>
     518
     519   <p>When cross-compiling, there are two sorts of bootscripts that can be
    521520   used:  Those that want to be executed prior to compiling and loading
    522521   the cross-compiler, which should be placed in the file called
     
    524523   cross-compiler has been compiled and loaded, just prior to compiling
    525524   the target, which should be placed in target:bootstrap.lisp, just
    526    like when doing a normal recompile.
    527 
    528    Additionally, sometimes customized cross-compiler setup scripts
     525   like when doing a normal recompile.</p>
     526
     527   <p>Additionally, sometimes customized cross-compiler setup scripts
    529528   (to be used in place of e.g. cross-x86-x86.lisp) are required,
    530529   which are also placed in one of the bootfiles/*/* files.  In those
    531530   cases follow the instructions provided in that file, possibly merging
    532    the changed contents thereof with your normal cross-script.
    533 
     531   the changed contents thereof with your normal cross-script.</p>
     532 </li>
     533</ol>
     534}}}
    534535== Step-by-Step Example of Cross-Compiling ==
    535536
     
    542543add a bootstrap file to get any bootfiles to make your lisp
    543544up-to-date with the current sources.
    544 
    545  1.  Select a directory for the cross-compiler and compiled target:
    546 
    547         Create a cross-compiler directory to hold the cross-compiler
    548         and a target directory to hold the result:
    549 {{{
     545{{{
     546#!html
     547<ol>
     548 <li>  Select a directory for the cross-compiler and compiled target:
     549
     550        <p>Create a cross-compiler directory to hold the cross-compiler
     551        and a target directory to hold the result:</p>
     552<pre>
    550553               bin/create-target.sh xcross
    551554               bin/create-target.sh xtarget
    552 }}}
    553  1.  Adjust cross-compilation script
    554 
    555         Copy the src/tools/cross-scripts/cross-sparc-sparc.lisp to
     555</pre>
     556 </li>
     557 <li>  Adjust cross-compilation script
     558
     559        <p>Copy the src/tools/cross-scripts/cross-sparc-sparc.lisp to
    556560        xtarget/cross.lisp.  Edit it appropriately.  In this case, it
    557         should look something like:
    558 {{{
     561        should look something like:</p>
     562<pre>
    559563            (c::new-backend "SPARC"
    560564               ;; Features to add here
     
    577581            (setf *features* (remove :sparc-v9 *features*))
    578582            (pushnew :sparc-v8 *features*)
    579 }}}
     583</pre>
    580584        It's important to add frob *features* here as well as in the
    581585        new-backend.  If you don't adjust *features*, they won't be
    582586        set appropriately in the result.
    583 
    584  1.  Build the cross compiler and target
    585         Now compile the result:
    586 {{{
     587 </li>
     588 <li>  Build the cross compiler and target
     589        <p>Now compile the result:</p>
     590<pre>
    587591            bin/cross-build-world.sh xtarget xcross xtarget/cross.lisp [v9 binary]
    588 }}}
    589 
    590  1.  Rebuild the lisp files:
    591 
    592         When this finishes, you need to compile the C code:
    593 {{{
     592</pre>
     593
     594 <li>  Rebuild the lisp files:
     595
     596        <p>When this finishes, you need to compile the C code:</p>
     597<pre>
    594598                bin/rebuild-lisp.sh xtarget
    595 }}}
    596         At this point, you may want to run cross-build-world.sh again
     599</pre>
     600        <p>At this point, you may want to run cross-build-world.sh again
    597601        to generate a new kernel.core.  It shouldn't build anything;
    598         just loads everything and creates a kernel.core.
    599 
    600  1.  Build the world:
    601 
    602         With the new kernel.core, we need to create a lisp.core:
    603 {{{
     602        just loads everything and creates a kernel.core.</p>
     603
     604 <li>  Build the world:
     605
     606        <p>With the new kernel.core, we need to create a lisp.core:</p>
     607<pre>
    604608                bin/load-world.sh xtarget "new lisp"
    605 }}}
    606         Test the result with
    607 {{{
     609</pre>
     610        <p>Test the result with</p>
     611<pre>
    608612                xtarget/lisp/lisp -noinit
    609 }}}
    610 
     613</pre>
     614}}}
    611615However, this lisp will be missing some functionality like PCL.  You
    612616probably now want to use the compiler to rebuild everything once
     
    624628To simplify things, we assume that both platforms have access to the
    625629same file system, via NFS or something else.
    626 
    627  1. As above, we need to create directories for the cross-compiler and
     630{{{
     631#!html
     632<ol>
     633 <li> As above, we need to create directories for the cross-compiler and
    628634   compiled target.  We assume we are on ppc/darwin.  So, when running
    629635   create-target.sh we need to specify the target:
    630 {{{
     636<pre>
    631637        bin/create-target.sh x86-cross x86
    632638        bin/create-target.sh x86-target x86
    633 }}}
    634  1. Adjust the cross-compilation script.  An example for ppc/darwin to
     639</pre>
     640 <li> Adjust the cross-compilation script.  An example for ppc/darwin to
    635641   x86/linux is in src/tools/cross-scripts/cross-ppc-x86.lisp.
    636642
    637  1. Build the cross compiler and target, as above, using the specified
     643 <li> Build the cross compiler and target, as above, using the specified
    638644   cross-compile script:
    639 {{{
     645<pre>
    640646        bin/cross-build-world.sh x86-target x86-cross cross.lisp [ppc binary]
    641 }}}
     647</pre>
    642648   where cross.lisp is the cross-compile script from 2) above.
    643649
    644  1. Everything has now been compiled for the x86/linux target.  We need
     650 <li> Everything has now been compiled for the x86/linux target.  We need
    645651   to compile the C code for x86 and create a lisp.core from the
    646652   kernel.core.  This is where it's useful to have both platforms be
     
    649655   everything in xtarget needs to be copied.
    650656
    651    Note carefully that you may have to edit lisp/internals.h and/or
     657   <p>Note carefully that you may have to edit lisp/internals.h and/or
    652658   lisp/internals.inc to have the correct features.  This is a known
    653    bug in the generation of these files during cross-compilation.
     659   bug in the generation of these files during cross-compilation.</p>
    654660
    655661   Compile the lisp code:
    656 {{{
     662<pre>
    657663        bin/rebuild-lisp.sh x86-target   
    658 }}}
    659  1. Now run load-world.sh to create the desired lisp.core from lisp and
     664</pre>
     665 <li> Now run load-world.sh to create the desired lisp.core from lisp and
    660666   kernel.core.  As above, PCL has not been compiled, so select
    661667   restart 3 (return nil from pclload) to create lisp.core
    662 {{{
     668<pre>
    663669        bin/load-world.sh x86-target "new x86"
    664 }}}
    665 
     670</pre>
     671</ol>
     672}}}
    666673At this point, you will have a shiny new lisp on the new platform.
    667674Since it's missing PCL, you will need to do at least one normal build