From 9b78847be0d288081fbf78afc8a2104dda038b79 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 19 May 2014 19:05:22 +0100 Subject: [PATCH] add `unix-style` makefile target Also, revise "INSTALL.txt" to better explain the build options. --- INSTALL.txt | 358 +++++++++++++++++++++------------------ Makefile | 41 ++++- racket/src/README | 2 +- racket/src/worksp/README | 14 +- 4 files changed, 243 insertions(+), 172 deletions(-) diff --git a/INSTALL.txt b/INSTALL.txt index 015ac259d3..e0734c7e42 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -1,38 +1,128 @@ -Quick Instructions -================== +Build Options +============= -On Unix or Mac OS X, `make' (or `make in-place') creates a build in -the "racket" directory --- but for Mac OS X, see the notes below on -`git submodule'. +For Unix platforms, instead of using this source repository, consider +getting source for the current Racket release from -On Windows, `nmake win32-in-place' creates a build in the "racket" -directory, but see the notes below on `git submodule'. + http://download.racket-lang.org/ -An in-place build includes (via links) packages that are in the "pkgs" +or get a source snapshot (updated daily) from + + http://pre.racket-lang.org/installers/ + +The "Source + built packages" options from those sites will build and +install especially quickly, because platform-independent bytecode and +documentation are pre-built. + +In contrast to this repository, release and snapshot source +distributions will work in the + configure --prefix=... && make && make install +way that you probably expect. + + +If you stick with this repository, then you have several options: + + * In-place build --- the default, creates a build in the "racket" + subdirectory that references the packages that reside in the "pkgs" + subdirectory. This is the most natural mode for developing Racket + itself or staying on the bleeding edge. See "Quick Instructions: + In-place Build" below. + + * Unix-style install --- installs to a given destination directory + (Unix and Mac OS X, only), leaving no reference to the source + directory. This is the most natural mode for installing once from + the source repository. See "Quick Instructions: Unix-style Install" + below. + + * Minimal --- as described in the "src" subdirectory of "racket" + (i.e., ignore this directory and "pkgs"). You can build a minimal + Racket using the usual `configure && make && make install' steps + (or similar for Windows), and then you can install packages from + the catalog server with `raco pkg'. + + * Installers --- create installers for a variety of platforms by + farming out work to machines that run those platforms. This is the + way that Racket snapshots and releases are created, and you can + create your own. See "Building Installers" below. + + +Quick Instructions: In-place Build +================================== + +On Unix, `make' (or `make in-place') creates a build in the "racket" directory. +On Mac OS X, see the notes below on git submodules, and then `make' +(or `make in-place') creates a build in the "racket" directory. -Building Racket -=============== +On Windows with Microsoft Visual Studio 9.0 (2008), see the notes +below on git submodules, and then `nmake win32-in-place' creates a +build in the "racket" directory. -The "racket" directory contains a stripped down version of Racket --- -enough to run `raco pkg' to install everything else. +In all cases, an in-place build includes (via links) packages that are +in the "pkgs" directory. -The "pkgs" directory contains the packages that are included in a -Racket distribution, plus some additional packages (such as tests). +See "More Instructions: Building Racket" below for more information. -On Unix and Mac OS X, you can build Racket plus the included packages -with `make in-place' (or just `make'). On Windows, you can use `nmake -win32-in-place', as long as you're using Microsoft Visual Studio 9.0 -(2008). The resulting build is in the "racket" subdirectory. If you -want more control over the process, see below. + +Quick Instructions: Unix-style Install +====================================== + +On Unix, `make PREFIX=' builds and installs into with +binaries in "/bin", packages in "/share/racket/pkgs", +documentation in "/share/racket/doc", etc. + +On Mac OS X, see the notes below on git submodules, and then `make +PREFIX=' builds and installs into "" with binaries in +"/bin", packges in "/share/pkgs", documentation in +"/doc", etc. + +On Windows, Unix-style install is not supported. + +A Unix-style install leaves no reference to this source directory. + +See "More Instructions: Building Racket" below for more information. + + +git Submodules (Mac OS X and Windows) +===================================== On Mac OS X and Windows, you'll need native-library packages in the -"native-pkgs" directory. In the git repository, "native-pkgs" is a git -submodule, so you'll need +"native-pkgs" directory for either an in-place build or a Unix-style +install. The "native-pkgs" directory is treated in the same way as +"pkgs"; for example, in-place build uses links into the "native-pkgs" +directory. + +The "native-pkgs" directory is a git submodule, so you'll need + git submodule init git submodule update -to get it set up. + +before you do anything else. + + +More Instructions: Building Racket +================================== + +The "racket" directory contains minimal Racket, which is just enough +to run `raco pkg' to install everything else. The first step of `make +in-place' or `make unix-style' is to build minimal Racket, and you can +read "racket/src/README" for more information. + +If you would like to provide arguments to `configure' for the minimal +Racket build, then you can supply them with by adding +`CONFIGURE_ARGS_qq="..."' to `make in-place' or `make +unix-style'. (The `_qq' suffix on the variable name is a convention +that indicates that single- and double-quote marks are allowed in the +value.) + +The "pkgs" directory contains the packages that are included in a +Racket distribution, plus some additional packages (such as tests). A +`make in-place' links to the package in-place, while `make unix-style' +copies packages out of "pkgs" to install them. + +Either way, if you're building on Mac OS X or Windows, be sure to +start with "git Submodules", above. To install a subset of the packages in "pkgs", supply `PKGS' value to `make'. For example, @@ -41,10 +131,11 @@ To install a subset of the packages in "pkgs", supply `PKGS' value to links only the "gui-lib" and "readline-lib" packages and their dependencies. The default value of `PKGS' reaches all packages in -"pkgs" among its dependencies. See "Linking Packages for Development -Mode", below, for more information on package links and using `again' -or `LINK_MODE' to use remembered `PKGS' values from previous `make -in-place's. +"pkgs" among its dependencies. See "Linking Packages for In-place +Development Mode", below, for more information on package links and +using `again' or `LINK_MODE' to use remembered `PKGS' values from +previous `make in-place's. Setting `PKGS' also works for `make +unix-style'. Using `make' (or `make in-place') sets the installation's name to "development", unless the installation has been previously configured @@ -62,17 +153,22 @@ makefile and the `raco setup' part, use make CPUS= -which recurs with `make -j JOB_OPTIONS="-j "'. +which recurs with `make -j JOB_OPTIONS="-j "'. Setting `CPUS' +also works with `make unix-style'. + +If you need even more control over the build, carry on to "Even More +Instructions: Building Racket Pieces". -Building Racket Pieces -====================== +Even More Instructions: Building Racket Pieces +============================================== -Instead of just using `make in-place', you can take more control over -the build. +Instead of just using `make in-place' or `make unix-style', you can +take more control over the build by understand how the pieces fit +together. -Building Base Racket --------------------- +Building Minimal Racket +----------------------- Instead of using the top-level makefile, you can go into "racket/src" and follow the "README" there, which gives you more configuration @@ -82,45 +178,47 @@ If you don't want any special configuration and you just want the base build, you can use `make base' (or `nmake win32-base') with the top-level makefile. -(The Racket base does not require additional native libraries to run, +Minimal Racket does not require additional native libraries to run, but under Windows, encoding-conversion, extflonum, and SSL functionality is hobbled until native libraries from the -`racket-win32-i386' or `racket-win32-x86_64' package are installed.) - -On Unix or Mac OS X, you can use `make in-place' and still set -`configure' options by supplying `CONFIGURE_ARGS_qq'. (The `_qq' -suffix on the variable name is a convention that indicates that -single- and double-quote marks are allowed in the value.) +`racket-win32-i386' or `racket-win32-x86_64' package are installed. On all platforms, `JOB_OPTIONS' as a makefile variable and `PLT_SETUP_OPTIONS' as an environment variable are passed on to the -`raco setup' that is used to build base libraries. +`raco setup' that is used to build minimal-Racket libraries. See the +documentation for `raco setup' for information on the options. Installing Packages ------------------- -In the near future, after you've built the base, you can install -packages via a package-catalog server (ignoring the content of -"pkgs"). That catalog server is not ready, yet. +After you've built and installed minimal Racket, you could install +packages via the package-catalog server --- ignoring the content of +"pkgs" and "native-pkgs". -Linking Packages for Development Mode -------------------------------------- +If you want to install packages manually out of the "pkgs" and +"native-pkgs" directories, the `local-catalog' target creates a +catalog as "build/local/catalog" that points to the sources in "pkgs" +and "native-pkgs". A Unix-style build works that way: it builds and +installs minimal Racket, and then it installs packags out of a catalog +that is created by `make local-catalog'. -Aside from the issue of native-library packages, using the -"main-distribution" package corresponds to a build that is like the -main Racket distribution. Furthermore, if you install all of those -packages with `raco pkg install -i --link ...', then you can edit -libraries or update via `git pull' plus `raco setup' (as opposed to -updating or reinstalling packages). +Linking Packages for In-place Development Mode +---------------------------------------------- + +Using the "main-distribution" package corresponds to a build that is +like the main Racket distribution. Furthermore, if you install all of +those packages with `raco pkg install -i --link ...', then you can +edit libraries or update via `git pull' plus `raco setup' (as opposed +to updating or reinstalling packages). That's how the in-place build +works. The `pkg-links' target of the makefile links (or re-links) packages -from "pkgs" into the "racket" build. (The `in-place' target of the -makefile uses `pkg-links'.) By default, `pkg-links' starts with the -"main-distribution" and "plt-services" packages and links all of their -dependencies, which includes all of the packages in "pkgs". Specify a -subset of the packages with `PKGS="...."' as an argument to `make -pkg-links'. Make the `pkg-links' target whenever the set of -dependencies can change. +from "pkgs" and "native-pkgs" into the "racket" build. By default, +`pkg-links' starts with the "main-distribution" and "plt-services" +packages and links all of their dependencies, which includes all of +the packages in "pkgs". Specify a subset of the packages with +`PKGS="...."' as an argument to `make pkg-links'. Make the `pkg-links' +target whenever the set of dependencies can change. Packages are linked in a database (at "racket/lib/devel-pkgs") that is added to the installation's search paths. As a result, the links @@ -144,56 +242,28 @@ same as `in-place' (or `win32-in-place'), but with `LINK_MODE=--save' is the default. The `pkg-links' makefile target installs links to a specific -"devel-pkgs" directory and adjusts the build's configuration to -include "devel-pkgs" in the search path for packages. As a result, the -package links are installation specific, but still isolated from any -`installation'-scope packages that you install later. The `pkg-links' -target also sets the default package scope for the build to -`installation' mode. Both of those configuration adjustments are made -only if no configuration file "racket/etc/config.rktd" exists already. - -Trying Packages Locally ------------------------ - -Suppose that you've built base "racket" and you want to see what it -looks like to install individual packages as if provided by a server -(i.e., not through development-mode links). - -Use `make local-catalog' to create a package catalog that provides -mappings for all of the packages in "pkgs" as well as packages for -pre-built native libraries. - -To install a package, try - - racket/bin/raco pkg install -i --catalog build/local/catalog --deps search-auto - -The `-i' flag makes the package install specific to the build in the -"racket" directory. The `--catalog build/local/catalog' causes the -installation to use the catalog created by the `local-catalog' -makefile target. The `--deps search-auto' flag installs dependencies -(from the local catalog) automatically. - -To remove the package, try - - racket/bin/raco pkg remove -i --auto - -The `--auto' flag undoes automatic installs from `--deps search-auto'. +"devel-pkgs" directory and also sets the default package scope for the +build to "installation" mode. Both of those configuration adjustments +are made only if no configuration file "racket/etc/config.rktd" exists +already. -Building Installers -=================== +The Whole Enchilada: Building Installers +======================================== -To build distribution installers, do not use `make in-place' or just -`make', but instead start from a clean repository. +To build installers that can be distributed to other users, do not use +`make in-place' or `make unix-style', but instead start from a clean +repository. -Use one non-Windows machine as a server[*], where packages will be -pre-built. Then, create platform-specific installers on N client -machines, each of which contacts the server machine to obtain -pre-built packages. The server can act as a client, naturally, to -create an installer for the server's platform. +Use one non-Windows machine as a server, where packages will be +pre-built. Then, as described below, create platform-specific +installers on N client machines, each of which contacts the server +machine to obtain pre-built packages. The server can act as a client, +naturally, to create an installer for the server's platform. - [*] GNU `make' is required on the server machine, but any `make' - should work on client machines. +GNU `make' is required on the server machine, `nmake' is required on +Windows client machines, and any `make' should work on other client +machines. Running Build Farms ------------------- @@ -217,7 +287,7 @@ If "my-site-config.rkt" is a configuration module, then drives the build farm, and the resulting installers are in "build/installers", with a hash table mapping descriptions to installer filenames in "build/installer/table.rktd". A log file -for each client are written to "build/log". +for each client is written to "build/log". The default CONFIG path is "build/site.rkt", so you could put your configuration file there and omit the `CONFIG' argument to @@ -247,8 +317,8 @@ where defaults to "racket" (but can be set via normalizing the Windows results to "i386-win32" and "x86_63-win32", - is omitted unless a `#:dist-suffix' string is specified for the client in the site configuration, and is -platform-specific: ".sh" for Unix, ".dmg" for Mac Os X, and ".exe" for -Windows. +platform-specific: ".sh" for Unix, ".dmg" or ".pkg" for Mac OS X, and +".exe" for Windows. Generating Installer Web Sites ------------------------------ @@ -312,64 +382,16 @@ Roughly, the steps are 1. On the server machine: make server PKGS="..." - Add `DOC_SEARCH="..."' to the `server' line to build documentation - so that it redirects to the given URL when a remote search is - necessary. - - Add `SERVER_PORT=...' to the `server' line to choose the port on - which the server listens to clients. The default is port 9440. - - Add `SERVER_HOSTS="..."' to determine the interfaces at which the - server listens. The default is "localhost" which listens only on - the loopback device (for security). Supply the empty string to - listen on all interfaces. Supply multiple addresses by separating - them with a comma. + See 1b below for more information on variables other than `PKGS' + that you can provide with `make'. 2. On each client machine: make client SERVER=... PKGS="..." or nmake win32-client SERVER=... PKGS="..." - Add `SERVER_PORT=...' to the `client' line if you picked an - alternate port in the `server` line; it should be the same as for - the `server' line. - - Add `DOC_SEARCH="..."' to the `client' line, if needed; - normally, it should be the same as for the `server' line. - - Add `RELEASE_MODE=--release' to the `client' line to build - a "release" installer, as opposed to a snapshot installer. - - Add `DIST_NAME="..."' to the `client' line to give an installer a - different human-readable distribution name, instead of "Racket". - - Add `DIST_BASE="..."' to the `client' line to adjust the installer - name's prefix, instead of starting with "racket". - - Add `DIST_DIR="..."' to the `client' line to make the installer - use a different directory name on installation on Unix, instead of - "racket". - - Add `DIST_SUFFIX="..."' to the `client' line to add a suffix - string for the installer's name, such as an identifier for a - particular variant of Linux. - - Add `DIST_DESC="..."' to the `client' line to set the installer's - description, which is used as a key in the generated table of - uploaded installer files (when UPLOAD is set). - - Add `DIST_CATALOGS_q='...'' to the `client' line to declare a - space-separated sequence of catalog URLs to set an installation's - initial package catalog URLs. Use the empty string in place of a - URL to indicate that the default path should be spliced. - - Add `README="..."' to specify a URL for a file to use as the - "README" file in the generated installer, or leave as empty for no - "README". - - Add `UPLOAD="..."` to specify a URL to use as an upload - destination for the created installed, where the installer's name - is added to the end of the URL, or leave as empty for no upload. + See 2b below for more information on variables other than `SERVER' + and `PKGS' that you can provide with `make'. In more detail: @@ -386,8 +408,15 @@ In more detail: Alternatively, use the `server' target, which combines `base' and `server-from-base' (i.e., steps 1a and 1b). - The `SERVER_PORT' and `SERVER_HOSTS' variables of the makefile - configure the port and interfaces of the server. + The `SERVER_PORT' variable of the makefile choose the port on + which the server listens to clients. The default is port 9440. + + The `SERVER_HOSTS' variable of the makefile determines the + interfaces at which the server listens. The default is + "localhost" which listens only on the loopback device (for + security). Supply the empty string to listen on all + interfaces. Supply multiple addresses by separating them with a + comma. The `PKGS' variable of the makefile determines which packages are built for potential inclusion in a distribution. @@ -450,7 +479,7 @@ In more detail: distribution name is "Racket". Whatever name you pick, the Racket version number is automatically added for various contexts. - To change the base name of the installer file, provide `DIST_BASE + To change the base name of the installer file, provide `DIST_BASE' to `make'. The default is "racket". To change the directory name for Unix installation, provide @@ -490,6 +519,11 @@ In more detail: `make server', and they are used mainly by `make client-from-site' (described below). + The `UPLOAD' makefile variable specifies a URL to use as an + upload destination for the created installed, where the + installer's name is added to the end of the URL, or leave as + empty for no upload. + On each client, step 2b produces a "bundle/installer.txt" file that contains the path to the generated installer on one line, followed by the description on a second line. The installer is also uploaded to diff --git a/Makefile b/Makefile index 05127ea8d3..93b4a038fe 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,8 @@ PKGS = main-distribution plt-services PLAIN_RACKET = racket/bin/racket WIN32_PLAIN_RACKET = racket\racket -MACOSX_CHECK = $(PLAIN_RACKET) -G build/config -I racket/base -e '(case (system-type) [(macosx) (exit 0)] [else (exit 1)])' +MACOSX_CHECK_ARGS = -I racket/base -e '(case (system-type) [(macosx) (exit 0)] [else (exit 1)])' +MACOSX_CHECK = $(PLAIN_RACKET) -G build/config $(MACOSX_CHECK_ARGS) LINK_MODE = --save @@ -38,7 +39,7 @@ CPUS = in-place: if [ "$(CPUS)" = "" ] ; \ then $(MAKE) plain-in-place PKGS="$(PKGS)" ; \ - else $(MAKE) cpus-in-place PKGS="$(PKGS)" ; fi + else $(MAKE) cpus-in-place CPUS="$(CPUS)" PKGS="$(PKGS)" ; fi cpus-in-place: $(MAKE) -j $(CPUS) plain-in-place JOB_OPTIONS="-j $(CPUS)" PKGS="$(PKGS)" @@ -67,6 +68,40 @@ IN_PLACE_COPY_ARGS = JOB_OPTIONS="$(JOB_OPTIONS)" PLT_SETUP_OPTIONS="$(PLT_SETUP win32-again: $(MAKE) LINK_MODE="--restore" $(IN_PLACE_COPY_ARGS) + +# ------------------------------------------------------------ +# Unix-style build (Unix and Mac OS X, only) + +PREFIX = + +CONFIG_PREFIX_ARGS = --prefix="$(PREFIX)" --enable-macprefix +UNIX_RACO_ARGS = $(JOB_OPTIONS) --catalog build/local/catalog --auto -i + +unix-style: + if [ "$(CPUS)" = "" ] ; \ + then $(MAKE) plain-unix-style ; \ + else $(MAKE) cpus-unix-style ; fi + +cpus-unix-style: + $(MAKE) -j $(CPUS) plain-unix-style JOB_OPTIONS="-j $(CPUS)" + +plain-unix-style: + if [ "$(PREFIX)" = "" ] ; then $(MAKE) error-need-prefix ; fi + $(MAKE) base CONFIGURE_ARGS_qq='$(CONFIGURE_ARGS_qq) $(CONFIG_PREFIX_ARGS)' SELF_FLAGS_qq="" + $(MAKE) local-catalog-maybe-native RACKET="$(PREFIX)/bin/racket" + "$(PREFIX)/bin/raco" pkg install $(UNIX_RACO_ARGS) $(REQUIRED_PKGS) $(PKGS) + +error-need-prefix: + : ================================================================ + : Please supply PREFIX="" to set the install destination + : ================================================================ + exit 1 + +local-catalog-maybe-native: + if $(RACKET) $(MACOSX_CHECK_ARGS) ; \ + then $(MAKE) local-catalog ; \ + else $(MAKE) local-source-catalog ; fi + # ------------------------------------------------------------ # Base build @@ -320,9 +355,11 @@ local-catalog: native-from-git: if [ ! -d native-pkgs/racket-win32-i386 ]; then $(MAKE) complain-no-submodule ; fi complain-no-submodule: + : ================================================================ : Native packages are not in the expected subdirectory. Probably, : you need to use 'git submodule init' and 'git submodule update' to get : the submodule for native packages. + : ================================================================ exit 1 # Create packages and a catalog for all native libraries: diff --git a/racket/src/README b/racket/src/README index 0f20b393a6..2e19fa02a1 100644 --- a/racket/src/README +++ b/racket/src/README @@ -1,4 +1,4 @@ -This is the source code distribution for Racket. For license +This is the source code distribution for minimal Racket. For license information, please see the file "COPYING_LESSER.txt". Compiled binaries, documentation, and up-to-date information are diff --git a/racket/src/worksp/README b/racket/src/worksp/README index d581c16b20..468b06db53 100644 --- a/racket/src/worksp/README +++ b/racket/src/worksp/README @@ -1,8 +1,8 @@ This directory contains - - solution files and project files for building Racket and GRacket - with Microsoft Visual Studio 2008 (a.k.a. version 9.0) and up, - which work with the Express version of Visual Studio; + - solution files and project files for building minimal Racket (and + GRacket) with Microsoft Visual Studio 2008 (a.k.a. version 9.0) + and up, which work with the Express version of Visual Studio; - mzconfig.h which is a manual version of information that is gathered automatically when using the "configure" script; @@ -97,10 +97,10 @@ Downloading Pre-Built Binaries ------------------------------- You must install some pre-built DLLs if you want text-encoding -converts, OpenSSL support, `racket/draw', or `racket/gui' support. -In principle, you could build them from scratch, but since they -are (mostly) maintained by people and organizations other than -PLT, we supply them in binary form. +conversion, OpenSSL support, `racket/draw', or `racket/gui' support. +In principle, you could build them from scratch, but since they are +(mostly) maintained by people and organizations other than PLT, we +supply them in binary form. The DLLs are distributed in packages, but they are also available from