Changes between Version 4 and Version 5 of BuildingCmucl

Show
Ignore:
Timestamp:
03/04/12 09:25:10 (2 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