Changes between Version 4 and Version 5 of BuildingCmucl

Timestamp:

03/04/12 09:25:10 (15 months ago)

Author:

rtoy

Comment:

More cleanups.

BuildingCmucl

@@ -26 +26 @@
  </li>
  <li> GNU make.
-   <p>This has to be available either as gmake or make in your PATH, or
-   the MAKE environment variable has to be set to point to the correct
+   <p>This has to be available either as gmake or make in your <code>PATH</code>, or
+   the <code>MAKE</code> environment variable has to be set to point to the correct
    binary.</p>
  </li>
@@ -39 +39 @@
 If you want to build CMU CL's Motif interface/toolkit, you'll need a
 working version of the Motif libraries, either true-blue OSF/Motif, or
-OpenMotif, or Lesstif.  The code was developed against 1.2 Motif,
-though recompilation against 2.x Motif probably works as well.
+[http://www.openmotif.org OpenMotif], or [http://www.lestif.org LessTif].  The code
+was developed against 1.2 Motif, though recompilation against 2.x
+Motif probably works as well.
 
 == Setting up a build environment ==
@@ -58 +59 @@
   <pre>
     git clone git://common-lisp.net/projects/cmucl/cmucl.git
-  </pre> <p>Whatever you do, the sources must be in a directory named src
+  </pre> <p>Whatever you do, the sources must be in a directory named <code>src</code>
     inside the base directory.  Since the build tools keep all
     generated files in separate target directories, the src directory
@@ -118 +119 @@
 
 How do you know which of the three options above apply?  The easiest
-way is to look in src/bootfiles/<version>/* for boot files.  If the
+way is to look in {{{src/bootfiles/<version>/*}}} for boot files.  If the
 file date of a boot file is later than the version of CMUCL you are
 building from, then you need to use b) or c) above.  You may need to
@@ -125 +126 @@
 If there are no bootfiles, then you can use a) above.
 
-The build.sh script supports other options, and bin/build.sh -?
-will give a quick summary.  Read bin/build.sh for more
+The {{{build.sh}}} script supports other options, and {{{bin/build.sh -?}}}
+will give a quick summary.  Read {{{bin/build.sh}}} for more
 information. 
 
@@ -141 +142 @@
    <p>This happens in your current CMU CL process, using your current
    CMU CL's normal file compiler.  This phase currently consists of 3
-   sub-phases, namely those controlled by src/tools/worldcom.lisp,
-   which compiles all the runtime files, src/tools/comcom.lisp, which
+   sub-phases, namely those controlled by <code>src/tools/worldcom.lisp</code>,
+   which compiles all the runtime files, <code>src/tools/comcom.lisp</code>, which
    compiles the compiler (including your chosen backend), and finally
    src/tools/pclcom.lisp, which compiles PCL, CMU CL's CLOS
@@ -151 +152 @@
  <li> Building a new kernel.core file out of the so created files
    <p>This process, which is generally called genesis, and which is
-   controlled by src/tools/worldbuild.lisp, uses the newly compiled
+   controlled by <code>src/tools/worldbuild.lisp</code>, uses the newly compiled
    files in order to build a new, basic core file, which is then used
    by the last phase to create a fully functional normal core file.
@@ -159 +160 @@
    core is started.</p>
 
-   <p>As part of this process, it also creates the file internals.h,
+   <p>As part of this process, it also creates the file <code>internals.h</code>,
    which contains information about the general memory layout of the
    new core and its basic types, their type tags, and the location of
@@ -293 +294 @@
 features may require a cross-compile instead of a normal compile.
 
- bin/clean-target.sh [-l] target-directory [more dirs]::
+ {{{bin/clean-target.sh [-l] target-directory [more dirs]}}}::
  Cleans the given target directory, so that all created files will be
  removed.  This is useful to force recompilation.  If the -l flag is
@@ -300 +301 @@
  and the config file.
 
- bin/build-world.sh target-directory [build-binary] [build-flags...]::
+ {{{bin/build-world.sh target-directory [build-binary] [build-flags...]}}}::
  Starts a complete world build for the given target, using the lisp
  binary/core specified as a build host.  The recompilation step will
@@ -310 +311 @@
  world build process with build-world.sh
 
- bin/rebuild-lisp.sh target-directory::
+ {{{bin/rebuild-lisp.sh target-directory}}}::
  This script will force a complete recompilation of the C runtime code
  of CMU CL (aka the lisp executable).  Doing this will necessitate
  building a new kernel.core file, using build-world.sh.
 
- bin/load-world.sh target-directory version::
+ {{{bin/load-world.sh target-directory version}}}::
  This will finish the CMU CL rebuilding process, by loading the
  remaining compiled files generated in the world build process into the
@@ -329 +330 @@
 post the 18d release.
 
- bin/build-utils.sh target-directory::
+ {{{bin/build-utils.sh target-directory}}}::
  This script will build auxiliary libraries packaged with CMU CL,
  including CLX, CMUCL/Motif, the Motif debugger, inspector, and control
@@ -335 +336 @@
  core of the given target.
 
- bin/make-dist.sh [-bg] [-G group] [-O owner] target-directory version arch os::
+ {{{bin/make-dist.sh [-bg] [-G group] [-O owner] target-directory version arch os}}}::
  This script creates both main and extra distribution tarballs from the
  given target directory, using the make-main-dist.sh and
@@ -376 +377 @@
 simple streams.
 
-This is intended to be run from make-dist.sh.
-
- bin/make-extra-dist.sh target-directory version arch os::
+This is intended to be run from {{{make-dist.sh}}}.
+
+ {{{bin/make-extra-dist.sh target-directory version arch os}}}::
  This is script is not normally invoked by the user; make-dist will do
  it appropriately.
@@ -387 +388 @@
 tarballs, i.e. the auxiliary libraries such as CLX, CLM, and Hemlock.
 
-This is intended to be run from make-dist.sh.
-
-
- cross-build-world.sh target-directory cross-directory cross-script [build-binary] [build-flags...]::
+
+ {{{cross-build-world.sh target-directory cross-directory cross-script [build-binary] [build-flags...]}}}::
  This is a script that can be used instead of build-world.sh for
  cross-compiling CMUCL.  In addition to the arguments of build-world.sh
@@ -485 +484 @@
 that change.  There are two forms of boostrapping that can be
 required:
-
- a. Bootfiles
-
-   The maintainers try to make bootfiles available, that allow going
+{{{
+#!html
+<ol style="list-style-type:lower-alpha">
+ <li> Bootfiles
+   <p>The maintainers try to make bootfiles available, that allow going
    from an old release to the next release.  These are located in the
-   src/bootfiles/<old-release>/ directory of the CMU CL sources.
-
-   I.e. if you have binaries that match release 18d, then you'll need
+   src/bootfiles/<old-release>/ directory of the CMU CL sources.</p>
+
+   <p>I.e. if you have binaries that match release 18d, then you'll need
    to use all the bootfiles in src/bootfiles/18d/ in order to go to
    the next release (or current sources, if no release has been made
    yet).  If you already used some of the bootstrap files to compile
    your current lisp, you obviously don't need to use those to get to
-   later versions.
-
-   You can use the bootfiles by concatenating them into a file called
+   later versions.</p>
+
+   <p>You can use the bootfiles by concatenating them into a file called
    bootstrap.lisp in the target directory (i.e. target:bootstrap.lisp)
    in the order they are numbered.  Be sure to remove the bootstrap
-   file once it is no longer needed.
-
-   Alternatively, the bootstrap file can just "load" the individual
-   bootfiles as needed.
-
- a. Cross-compiling
-
-   Under some circumstances, bootstrap code will not be sufficient,
+   file once it is no longer needed.</p>
+
+   <p>Alternatively, the bootstrap file can just "load" the individual
+   bootfiles as needed.</p>
+ </li>
+ <li> Cross-compiling
+   <p>Under some circumstances, bootstrap code will not be sufficient,
    and a cross-compilation is needed.  In that case you will have to
    use cross-build-world.sh, instead of build-world.sh.  Please read
    the instructions of that script for details of the more complex
-   procedure.
-
-   << This isn't really true anymore, and we should place a more
-      elaborate description of the cross-compiling process here >>
-
-   When cross-compiling, there are two sorts of bootscripts that can be
+   procedure.</p>
+
+   <p><< This isn't really true anymore, and we should place a more
+      elaborate description of the cross-compiling process here >></p>
+
+   <p>When cross-compiling, there are two sorts of bootscripts that can be
    used:  Those that want to be executed prior to compiling and loading
    the cross-compiler, which should be placed in the file called
@@ -524 +523 @@
    cross-compiler has been compiled and loaded, just prior to compiling
    the target, which should be placed in target:bootstrap.lisp, just
-   like when doing a normal recompile.
-
-   Additionally, sometimes customized cross-compiler setup scripts
+   like when doing a normal recompile.</p>
+
+   <p>Additionally, sometimes customized cross-compiler setup scripts
    (to be used in place of e.g. cross-x86-x86.lisp) are required,
    which are also placed in one of the bootfiles/*/* files.  In those
    cases follow the instructions provided in that file, possibly merging
-   the changed contents thereof with your normal cross-script.
-
+   the changed contents thereof with your normal cross-script.</p>
+ </li>
+</ol>
+}}}
 == Step-by-Step Example of Cross-Compiling ==
 
@@ -542 +543 @@
 add a bootstrap file to get any bootfiles to make your lisp
 up-to-date with the current sources.
-
- 1.  Select a directory for the cross-compiler and compiled target:
-
-        Create a cross-compiler directory to hold the cross-compiler
-        and a target directory to hold the result:
-{{{
+{{{
+#!html
+<ol>
+ <li>  Select a directory for the cross-compiler and compiled target:
+
+        <p>Create a cross-compiler directory to hold the cross-compiler
+        and a target directory to hold the result:</p>
+<pre>
                bin/create-target.sh xcross
                bin/create-target.sh xtarget
-}}}
- 1.  Adjust cross-compilation script
-
-        Copy the src/tools/cross-scripts/cross-sparc-sparc.lisp to
+</pre>
+ </li>
+ <li>  Adjust cross-compilation script
+
+        <p>Copy the src/tools/cross-scripts/cross-sparc-sparc.lisp to
         xtarget/cross.lisp.  Edit it appropriately.  In this case, it
-        should look something like:
-{{{
+        should look something like:</p>
+<pre>
             (c::new-backend "SPARC"
                ;; Features to add here
@@ -577 +581 @@
             (setf *features* (remove :sparc-v9 *features*))
             (pushnew :sparc-v8 *features*)
-}}}
+</pre>
         It's important to add frob *features* here as well as in the
         new-backend.  If you don't adjust *features*, they won't be
         set appropriately in the result.
-
- 1.  Build the cross compiler and target
-        Now compile the result:
-{{{
+ </li>
+ <li>  Build the cross compiler and target
+        <p>Now compile the result:</p>
+<pre>
             bin/cross-build-world.sh xtarget xcross xtarget/cross.lisp [v9 binary]
-}}}
-
- 1.  Rebuild the lisp files:
-
-        When this finishes, you need to compile the C code:
-{{{
+</pre>
+
+ <li>  Rebuild the lisp files:
+
+        <p>When this finishes, you need to compile the C code:</p>
+<pre>
                 bin/rebuild-lisp.sh xtarget
-}}}
-        At this point, you may want to run cross-build-world.sh again
+</pre>
+        <p>At this point, you may want to run cross-build-world.sh again
         to generate a new kernel.core.  It shouldn't build anything;
-        just loads everything and creates a kernel.core.
-
- 1.  Build the world:
-
-        With the new kernel.core, we need to create a lisp.core:
-{{{
+        just loads everything and creates a kernel.core.</p>
+
+ <li>  Build the world:
+
+        <p>With the new kernel.core, we need to create a lisp.core:</p>
+<pre>
                 bin/load-world.sh xtarget "new lisp"
-}}}
-        Test the result with
-{{{
+</pre>
+        <p>Test the result with</p>
+<pre>
                 xtarget/lisp/lisp -noinit
-}}}
-
+</pre>
+}}}
 However, this lisp will be missing some functionality like PCL.  You
 probably now want to use the compiler to rebuild everything once
@@ -624 +628 @@
 To simplify things, we assume that both platforms have access to the
 same file system, via NFS or something else.
-
- 1. As above, we need to create directories for the cross-compiler and
+{{{
+#!html
+<ol>
+ <li> As above, we need to create directories for the cross-compiler and
    compiled target.  We assume we are on ppc/darwin.  So, when running
    create-target.sh we need to specify the target:
-{{{
+<pre>
         bin/create-target.sh x86-cross x86
         bin/create-target.sh x86-target x86
-}}}
- 1. Adjust the cross-compilation script.  An example for ppc/darwin to
+</pre>
+ <li> Adjust the cross-compilation script.  An example for ppc/darwin to
    x86/linux is in src/tools/cross-scripts/cross-ppc-x86.lisp.
 
- 1. Build the cross compiler and target, as above, using the specified
+ <li> Build the cross compiler and target, as above, using the specified
    cross-compile script:
-{{{
+<pre>
         bin/cross-build-world.sh x86-target x86-cross cross.lisp [ppc binary]
-}}}
+</pre>
    where cross.lisp is the cross-compile script from 2) above.
 
- 1. Everything has now been compiled for the x86/linux target.  We need
+ <li> Everything has now been compiled for the x86/linux target.  We need
    to compile the C code for x86 and create a lisp.core from the
    kernel.core.  This is where it's useful to have both platforms be
@@ -649 +655 @@
    everything in xtarget needs to be copied.
 
-   Note carefully that you may have to edit lisp/internals.h and/or
+   <p>Note carefully that you may have to edit lisp/internals.h and/or
    lisp/internals.inc to have the correct features.  This is a known
-   bug in the generation of these files during cross-compilation.
+   bug in the generation of these files during cross-compilation.</p>
 
    Compile the lisp code:
-{{{
+<pre>
         bin/rebuild-lisp.sh x86-target   
-}}}
- 1. Now run load-world.sh to create the desired lisp.core from lisp and
+</pre>
+ <li> Now run load-world.sh to create the desired lisp.core from lisp and
    kernel.core.  As above, PCL has not been compiled, so select
    restart 3 (return nil from pclload) to create lisp.core
-{{{
+<pre>
         bin/load-world.sh x86-target "new x86"
-}}}
-
+</pre>
+</ol>
+}}}
 At this point, you will have a shiny new lisp on the new platform.
 Since it's missing PCL, you will need to do at least one normal build