Raymond Toy pushed to branch master at cmucl / cmucl
Commits: 15655145 by Raymond Toy at 2018-12-10T15:02:13Z Fix some incorrect markdown markup
- - - - -
1 changed file:
- BUILDING.md
Changes:
===================================== BUILDING.md ===================================== @@ -12,13 +12,13 @@ General Requirements
In order to build CMU CL, you will need:
-a. A working CMU CL binary. There is no way around this requirement! +1. A working CMU CL binary. There is no way around this requirement!
This binary can either be for the platform you want to target, in that case you can either recompile or cross-compile, or for another supported platform, in that case you must cross-compile, obviously.
-a. A supported C compiler for the C runtime code. +1. A supported C compiler for the C runtime code.
Most of the time, this means GNU gcc, though for some ports it means the vendor-supplied C compiler. The compiler must be @@ -27,13 +27,13 @@ a. A supported C compiler for the C runtime code. Note for FreeBSD 10 and above: The build requires gcc (Clang will not work) and the lib32 compatiblity package.
-a. GNU make +1. GNU make
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 binary.
-a. The CMU CL source code +1. The CMU CL source code
Here you can either use one of the release source tarballs, or check out the source code directly from the public CMUCL git @@ -51,14 +51,14 @@ Setting up a build environment
mkdir cmucl ; cd cmucl
-2.) Fetch the sources and put them into the base directory - +2. Fetch the sources and put them into the base directory +``` tar xzf /tmp/cmucl-source.tar.gz - +``` or, if you want to use the git sources directly: - +``` git clone https://gitlab.common-lisp.net/cmucl/cmucl.git - +``` Whatever you do, the sources must be in a directory named src inside the base directory. Since the build tools keep all generated files in separate target directories, the src directory @@ -247,195 +247,195 @@ Overview of the included build scripts
* bin/build.sh [-123obvuBCU?]
-This is the main build script. It essentially calls the other build -scripts described below in the proper sequence to build cmucl from an -existing binary of cmucl. + This is the main build script. It essentially calls the other build + scripts described below in the proper sequence to build cmucl from an + existing binary of cmucl.
* bin/create-target.sh target-directory [lisp-variant [motif-variant]]
-This script creates a new target directory, which is a shadow of the -source directory, that will contain all the files that are created by -the build process. Thus, each target's files are completely separate -from the src directory, which could, in fact, be read-only. Hence you -can simultaneously build CMUCL for different targets from the same -source directory. - -The first argument is the name of the target directory to create. The -remaining arguments are optional. If they are not given, the script -tries to determine the lisp variant and motif variant from the system -the script is running on. - -The lisp-variant (i.e. the suffix of the src/lisp/Config.* to use as -the target's Config file), and optionally the motif-variant (again the -suffix of the src/motif/server/Config.* file to use as the Config file -for the target's CMUCL/Motif server code). If the lisp-variant is -given but the motif-variant is not, the motif-variant is determined -from the lisp-variant. - -The script will generate the target directory tree, link the relevant -Config files, and generate place-holder files for various files, in -order to ensure proper operation of the other build-scripts. It also -creates a sample setenv.lisp file in the target directory, which is -used by the build and load processes to set up the correct list of -*features* for your target lisp core. - -IMPORTANT: You will normally NOT have to modify the sample setenv.lisp -file, if you are building from a binary that has the desired features. -In fact, the sample has all code commented out, If you want to add or -remove features, you need to include code that puts at least a minimal -set of features onto the list (use PUSHNEW and/or REMOVE). You can -use the current set of *features* of your lisp as a first guide. The -sample setenv.lisp includes a set of features that should work for the -intended configuration. Note also that some adding or removing some -features may require a cross-compile instead of a normal compile. + This script creates a new target directory, which is a shadow of the + source directory, that will contain all the files that are created by + the build process. Thus, each target's files are completely separate + from the src directory, which could, in fact, be read-only. Hence you + can simultaneously build CMUCL for different targets from the same + source directory. + + The first argument is the name of the target directory to create. The + remaining arguments are optional. If they are not given, the script + tries to determine the lisp variant and motif variant from the system + the script is running on. + + The lisp-variant (i.e. the suffix of the src/lisp/Config.* to use as + the target's Config file), and optionally the motif-variant (again the + suffix of the src/motif/server/Config.* file to use as the Config file + for the target's CMUCL/Motif server code). If the lisp-variant is + given but the motif-variant is not, the motif-variant is determined + from the lisp-variant. + + The script will generate the target directory tree, link the relevant + Config files, and generate place-holder files for various files, in + order to ensure proper operation of the other build-scripts. It also + creates a sample setenv.lisp file in the target directory, which is + used by the build and load processes to set up the correct list of + *features* for your target lisp core. + + IMPORTANT: You will normally NOT have to modify the sample setenv.lisp + file, if you are building from a binary that has the desired features. + In fact, the sample has all code commented out, If you want to add or + remove features, you need to include code that puts at least a minimal + set of features onto the list (use PUSHNEW and/or REMOVE). You can + use the current set of *features* of your lisp as a first guide. The + sample setenv.lisp includes a set of features that should work for the + intended configuration. Note also that some adding or removing some + features may require a cross-compile instead of a normal compile.
* 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 -given, then the C runtime is also removed, including all the lisp -executable, any lisp cores, all object files, lisp.nm, internals.h, -and the config file. + Cleans the given target directory, so that all created files will be + removed. This is useful to force recompilation. If the -l flag is + given, then the C runtime is also removed, including all the lisp + executable, any lisp cores, all object files, lisp.nm, internals.h, + and the config file.
* 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 -only recompile changed files, or files for which the fasl files are -missing. It will also not recompile the C runtime code (the lisp -binary). If a (re)compilation of that code is needed, the genesis -step of the world build will inform you of that fact. In that case, -you'll have to use the rebuild-lisp.sh script, and then restart the -world build process with build-world.sh + Starts a complete world build for the given target, using the lisp + binary/core specified as a build host. The recompilation step will + only recompile changed files, or files for which the fasl files are + missing. It will also not recompile the C runtime code (the lisp + binary). If a (re)compilation of that code is needed, the genesis + step of the world build will inform you of that fact. In that case, + you'll have to use the rebuild-lisp.sh script, and then restart the + world build process with build-world.sh
* 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. + 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
-This will finish the CMU CL rebuilding process, by loading the -remaining compiled files generated in the world build process into the -kernel.core file, that also resulted from that process, creating the -final lisp.core file. + This will finish the CMU CL rebuilding process, by loading the + remaining compiled files generated in the world build process into the + kernel.core file, that also resulted from that process, creating the + final lisp.core file.
-You have to pass the version string as a second argument. The dumped -core will anounce itself using that string. Please don't use a string -consisting of an official release name only, (e.g. "18d"), since those -are reserved for official release builds. Including the build-date in -ISO8601 format is often a good idea, e.g. "18d+ 2002-05-06" for a -binary that is based on sources current on the 6th May, 2002, which is -post the 18d release. + You have to pass the version string as a second argument. The dumped + core will anounce itself using that string. Please don't use a string + consisting of an official release name only, (e.g. "18d"), since those + are reserved for official release builds. Including the build-date in + ISO8601 format is often a good idea, e.g. "18d+ 2002-05-06" for a + binary that is based on sources current on the 6th May, 2002, which is + post the 18d release.
* 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 -panel, and the Hemlock editor. It will use the lisp executable and -core of the given target. + This script will build auxiliary libraries packaged with CMU CL, + including CLX, CMUCL/Motif, the Motif debugger, inspector, and control + panel, and the Hemlock editor. It will use the lisp executable and + core of the given target.
-Note: To build with Motif (clm), you need to have the Motif libraries -available and headers available to build motifd, the clm Motif server. -OpenMotif is known to work. + Note: To build with Motif (clm), you need to have the Motif libraries + available and headers available to build motifd, the clm Motif server. + OpenMotif is known to work.
-You may need to adjust the include paths and library paths in -src/motif/server/Config.* to match where Motif is installed if the -paths therein are incorrect. + You may need to adjust the include paths and library paths in + src/motif/server/Config.* to match where Motif is installed if the + paths therein are incorrect.
-Unless you intend to use clm and motifd, you can safely ignore the -build failure. Everything else will have been compiled correctly; you -just can't use clm. + Unless you intend to use clm and motifd, you can safely ignore the + build failure. Everything else will have been compiled correctly; you + just can't use clm.
* 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 -make-extra-dist.sh scripts. The result will be two tar files. One -contains the main distribution including the runtime and lisp.core -with PCL (CLOS); the second contains the extra libraries such as -Gray-streams, simple-streams, CLX, CLM, and Hemlock. - -Some options that are available: - - -b Use bzip2 compression - -g Use gzip compression - -G group Group to use - -O owner Owner to use - -If you specify both -b and -g, you will get two sets of tarfiles. The --G and -O options will attempt to set the owner and group of the files -when building the tarfiles. This way, when you extract the tarfiles, -the owner and group will be set as specified. You may need to be root -to do this because many Unix systems don't normally let you change the -owner and group of a file. - -The remaining arguments used to create the name of the tarfiles. The -names will have the form: - + This script creates both main and extra distribution tarballs from the + given target directory, using the make-main-dist.sh and + make-extra-dist.sh scripts. The result will be two tar files. One + contains the main distribution including the runtime and lisp.core + with PCL (CLOS); the second contains the extra libraries such as + Gray-streams, simple-streams, CLX, CLM, and Hemlock. + + Some options that are available: + + -b Use bzip2 compression + -g Use gzip compression + -G group Group to use + -O owner Owner to use + + If you specify both -b and -g, you will get two sets of tarfiles. The + -G and -O options will attempt to set the owner and group of the files + when building the tarfiles. This way, when you extract the tarfiles, + the owner and group will be set as specified. You may need to be root + to do this because many Unix systems don't normally let you change the + owner and group of a file. + + The remaining arguments used to create the name of the tarfiles. The + names will have the form: +``` cmucl-<version>-<arch>-<os>.tar.bz2 cmucl-<version>-<arch>-<os>.extras.tar.bz2 - -Of course, the "bz2" will be "gz" if you specified gzip compression -instead of bzip. +``` + Of course, the "bz2" will be "gz" if you specified gzip compression + instead of bzip.
* /bin/make-main-dist.sh target-directory version arch os
-This is script is not normally invoked by the user; make-dist will do -it appropriately. + This is script is not normally invoked by the user; make-dist will do + it appropriately.
-This script creates a main distribution tarball (both in gzipped and -bzipped variants) from the given target directory. This will include -all the stuff that is normally included in official release tarballs -such as lisp.core and the PCL libraries, including Gray streams and -simple streams. + This script creates a main distribution tarball (both in gzipped and + bzipped variants) from the given target directory. This will include + all the stuff that is normally included in official release tarballs + such as lisp.core and the PCL libraries, including Gray streams and + simple streams.
-This is intended to be run from make-dist.sh. + 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. + This is script is not normally invoked by the user; make-dist will do + it appropriately.
-This script creates an extra distribution tarball (both in gzipped and -bzipped variants) from the given target directory. This will include -all the stuff that is normally included in official extra release -tarballs, i.e. the auxiliary libraries such as CLX, CLM, and Hemlock. + This script creates an extra distribution tarball (both in gzipped and + bzipped variants) from the given target directory. This will include + all the stuff that is normally included in official extra release + tarballs, i.e. the auxiliary libraries such as CLX, CLM, and Hemlock.
-This is intended to be run from make-dist.sh. + This is intended to be run from make-dist.sh.
* 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 -it takes two further required arguments: The name of a directory that -will contain the cross-compiler backend (the directory is created if -it doesn't exist, and must not be the same as the target-directory), -and the name of a Lisp cross-compilation script, which is responsible -for setting up, compiling, and loading the cross-compiler backend. -The latter argument is needed because each host/target combination of -platform's needs slightly different code to produce a working -cross-compiler. - -We include a number of working examples of cross-compiler scripts in -the cross-scripts directory. You'll have to edit the features section -of the given scripts, to specify the features that should be removed -from the current set of features in the host lisp, and those that -should be added, so that the backend features are correct for the -intended target. - -You can look at Eric Marsden's collection of build scripts for the -basis of more cross-compiler scripts. + 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 + it takes two further required arguments: The name of a directory that + will contain the cross-compiler backend (the directory is created if + it doesn't exist, and must not be the same as the target-directory), + and the name of a Lisp cross-compilation script, which is responsible + for setting up, compiling, and loading the cross-compiler backend. + The latter argument is needed because each host/target combination of + platform's needs slightly different code to produce a working + cross-compiler. + + We include a number of working examples of cross-compiler scripts in + the cross-scripts directory. You'll have to edit the features section + of the given scripts, to specify the features that should be removed + from the current set of features in the host lisp, and those that + should be added, so that the backend features are correct for the + intended target. + + You can look at Eric Marsden's collection of build scripts for the + basis of more cross-compiler scripts.
Step-by-Step Example of recompiling CMUCL for OpenBSD -----------------------------------------------------
Set up everything as described in the setup section above. Then execute: - +``` # Create a new target directory structure/config for OpenBSD: bin/create-target.sh openbsd OpenBSD_gencgc OpenBSD
@@ -487,10 +487,12 @@ bin/load-world.sh openbsd "18d+ 2002-05-06" # core will announce. Please always put the build-date and some # other information in there, to make it possible to differentiate # those builds from official builds, which only contain the release. +```
Now you should have a new lisp.core, which you can start with - +``` ./openbsd/lisp/lisp -core ./openbsd/lisp/lisp.core -noinit -nositeinit +```
Compiling sources that contain disruptive changes -------------------------------------------------
View it on GitLab: https://gitlab.common-lisp.net/cmucl/cmucl/commit/156551453481307a0e3405a2e5...