Some fixes and some reformatting.

This commit is contained in:
Eli Barzilay 2010-05-18 17:15:58 -04:00
parent 4336f29273
commit 4e7fb7f62c
2 changed files with 241 additions and 251 deletions

View File

@ -1,5 +1,4 @@
This is the source code distribution for Racket. For license
This is the source code distribution for Racket. For license
information, please see the file racket/notes/COPYING.LIB. information, please see the file racket/notes/COPYING.LIB.
Compiled binaries, documentation, and up-to-date information are Compiled binaries, documentation, and up-to-date information are
@ -24,55 +23,54 @@ Please report bugs via one of the following:
======================================================================== ========================================================================
To compile with Microsoft Visual C, read the instructions in To compile with Microsoft Visual C, read the instructions in
racket\src\worksp\README. "racket\src\worksp\README".
To compile with Cygwin tools, follow the Unix instructions below, and To compile with Cygwin tools, follow the Unix instructions below, and be
be sure to configure with --enable-shared. The result is a Unix-style sure to configure with `--enable-shared'. The result is a Unix-style
build, not a Windows-style build (e.g., Racket's `system-type' build, not a Windows-style build (e.g., Racket's `system-type' procedure
procedure returns 'unix, not 'windows, and GRacket uses X11). returns 'unix, not 'windows, and GRacket uses X11).
======================================================================== ========================================================================
Compiling for Mac OS X Compiling for Mac OS X
======================================================================== ========================================================================
First, install the Mac OS X Developer Tools from Apple. Then, follow First, install the Mac OS X Developer Tools from Apple. Then, follow
the Unix instructions below, but note the following: the Unix instructions below, but note the following:
* The Racket build creates a framework, Racket.framework, which is * The Racket build creates a framework, "Racket.framework", which is
installed into racket/lib. This framework is used by the executable installed into "racket/lib". This framework is used by the `racket'
`racket' that goes into racket/bin. executable that goes into "racket/bin".
* The GRacket build creates a framework, GRacket.framework, which is * The GRacket build creates a framework, "GRacket.framework", which is
installed into racket/lib. This framework is used by the executable installed into "racket/lib". This framework is used by the
bundle GRacket.app that goes into the "racket" directory. executable bundle GRacket.app that goes into the "racket" directory.
Installation creates a script, racket/bin/mred, that runs the The installation creates a script, "racket/bin/gracket", that runs
bundle. the bundle.
* The --enable-shared flag for `configure' must not be used, because * The `--enable-shared' flag for `configure' must not be used, because
builds create and use frameworks by default. Furthermore, builds create and use frameworks by default. Furthermore,
--disable-shared is not supported. (Unless you use `--disable-shared' is not supported. (Unless you use
--enable-xonx...) `--enable-xonx'...)
* To build an X11-based GRacket, run `configure' with the * To build an X11-based GRacket, run `configure' with the
--enable-xonx flag. Frameworks are not used for such builds, so `--enable-xonx' flag. Frameworks are not used for such builds, so
--enable-shared is allowed. The --enable-xonx flag also affects the --enable-shared is allowed. The `--enable-xonx' flag also affects
Racket build, so that `system-type' reports 'unix. the Racket build, so that `system-type' reports 'unix.
* To use --prefix without --enable-xonx, you must also supply * To use `--prefix' without `--enable-xonx', you must also supply
--enable-macprefix. BEWARE! The directory structure for a non-xonx `--enable-macprefix'. BEWARE! The directory structure for a
build does not fit a typical Unix directory structure. For example, non-xonx build does not fit a typical Unix directory structure. For
frameworks are written directly to a "lib" subdirectory, and example, frameworks are written directly to a "lib" subdirectory, and
executables like "GRacket.app" are written directly to the prefix executables like "GRacket.app" are written directly to the prefix
directory. (Requiring --enable-macprefix with --prefix for a directory. (Requiring `--enable-macprefix' with `--prefix' for a
non-xonx build helps prevent accidental installation of a Mac-style non-xonx build helps prevent accidental installation of a Mac-style
directory structure on top of an existing Unix-style directory directory structure on top of an existing Unix-style directory
structure.) structure.)
* Under Mac OS X 10.6 and later, `configure' by default selects * Under Mac OS X 10.6 and later, `configure' by default selects 32-bit
32-bit mode for building Racket and GRacket. To build Racket in mode for building Racket and GRacket. To build Racket in 64-bit mode
64-bit mode (GRacket is not support in that mode), use the (GRacket is not support in that mode), use the following arguments to
following arguments to `configure': --enable-mac64, --enable-sgc, `configure': `--enable-mac64', `--enable-sgc', and `--disable-mred'.
and --disable-mred.
======================================================================== ========================================================================
Compiling for supported Unix variants (including Linux) or Cygwin Compiling for supported Unix variants (including Linux) or Cygwin
@ -80,8 +78,8 @@ the Unix instructions below, but note the following:
Quick instructions: Quick instructions:
From this directory (where the `README' and `configure' files are), From this directory (where the `configure' file is), run the following
run the following commands: commands:
mkdir build mkdir build
cd build cd build
@ -90,9 +88,9 @@ Quick instructions:
make install make install
This will create an in-place installation of Racket and store the This will create an in-place installation of Racket and store the
results of C/C++ compilation in a separate `build' subdirectory, results of C/C++ compilation in a separate "build" subdirectory, which
which is useful if you need to update your sources, delete the build, is useful if you need to update your sources, delete the build, and
and start from scratch. start from scratch.
You can also run the typical `./configure && make && make install' if You can also run the typical `./configure && make && make install' if
you don't anticipate updating/rebuilding, but it will be harder to you don't anticipate updating/rebuilding, but it will be harder to
@ -104,18 +102,18 @@ Detailed instructions:
remove it (unless you are using an "in-place" build from a remove it (unless you are using an "in-place" build from a
repository as described below). repository as described below).
Also, make sure that you have libraries and header files for Xft Also, make sure that you have libraries and header files for Xft and
and Cairo (v1.23 and up) if you would like support for font Cairo (v1.23 and up) if you would like support for font smoothing
smoothing (Xft) and graphics smoothing (Cairo). These libraries (Xft) and graphics smoothing (Cairo). These libraries are not
are not distributed with Racket. The configure process checks distributed with Racket. The configure process checks automatically
automatically whether these libraries are available. whether these libraries are available.
OpenGL support for GRacket sometimes requires special configuration OpenGL support for GRacket sometimes requires special configuration
(though generally not under Linux). See the note at the end of (though generally not under Linux). See the note at the end of this
this section if OpenGL fails to work. section if OpenGL fails to work.
Finally, the content of the "foreign" subdirectory may require GNU Finally, the content of the "foreign" subdirectory may require GNU
`make'. If the build fails with another variant of `make', please `make'. If the build fails with another variant of `make', please
try using GNU `make'. try using GNU `make'.
1. Select (or create) a build directory. 1. Select (or create) a build directory.
@ -134,188 +132,187 @@ Detailed instructions:
A separate build directory is better in case the Makefile A separate build directory is better in case the Makefile
organization changes, or in case the Makefiles lack some organization changes, or in case the Makefiles lack some
dependencies. In those cases, when using a "build" subdirectory, dependencies. In those cases, when using a "build" subdirectory,
you can just delete and re-create "build" without mangling your you can just delete and re-create "build" without mangling your
source tree. source tree.
2. From your build directory, run the script `configure' (which is in 2. From your build directory, run the script `configure' (which is in
the same directory as this README), with optional command-line the same directory as this README), with optional command-line
arguments --prefix=TARGETDIR or --enable-shared (or both). arguments `--prefix=TARGETDIR' or `--enable-shared' (or both).
For example, if you want to install into /usr/local/racket using For example, if you want to install into "/usr/local/racket" using
dynamic libraries, then run: dynamic libraries, then run:
[here]configure --prefix=/usr/local/racket --enable-shared [here]configure --prefix=/usr/local/racket --enable-shared
Again, "[here]" is the directory path containing the `configure' Again, "[here]" is the directory path containing the `configure'
script. If you follow the convention of running from a "build" script. If you follow the convention of running from a "build"
subdirectory, "[here]" is just "../". If you build from the subdirectory, "[here]" is just "../". If you build from the current
current directory, "[here]" is possibly unnecessary, or possibly directory, "[here]" is possibly unnecessary, or possibly just "./",
just "./", depending on your shell and PATH setting. depending on your shell and PATH setting.
If the --prefix flag is omitted, the binaries are built for an If the `--prefix' flag is omitted, the binaries are built for an
in-place installation (i.e., the parent of the directory in-place installation (i.e., the parent of the directory containing
containing this README will be used directly). Unless this README will be used directly). Unless `--enable-shared' is
--enable-shared is used, the "racket" directory can be moved used, the "racket" directory can be moved later; most system
later; most system administrators would recommend that you use administrators would recommend that you use `--enable-shared', but
--enable-shared, but the Racket developers distribute binaries the Racket developers distribute binaries built without
built without --enable-shared. `--enable-shared'.
The `configure' script generates the makefiles for building The `configure' script generates the makefiles for building Racket
Racket and/or GRacket. The current directory at the time and/or GRacket. The current directory at the time `configure' is
`configure' is run will be used as working space for building the run will be used as working space for building the executables
executables (independent of --prefix). This build directory does (independent of `--prefix'). This build directory does not have to
not have to be in the source tree, even for an "in-place" be in the source tree, even for an "in-place" build. It's ok to run
build. It's ok to run `configure' from its own directory (as in `configure' from its own directory (as in the first example above),
the first example above), but it's better to pick a separate build but it's better to pick a separate build directory that is otherwise
directory that is otherwise empty (as in the second example). empty (as in the second example).
The `configure' script accepts many other flags that adjust the The `configure' script accepts many other flags that adjust the
build process. Run `configure --help' for more information. In build process. Run `configure --help' for more information. In
addition, a specific compiler can be selected through environment addition, a specific compiler can be selected through environment
variables. For example, to select the SGI compilers for Irix variables. For example, to select the SGI compilers for Irix
instead of gcc, run configure as instead of gcc, run configure as
env CC=cc CXX=CC [here]configure env CC=cc CXX=CC [here]configure
For cross compilation, set the compiler variables to a compiler For cross compilation, set the compiler variables to a compiler for
for the target platform compiler, but also set CC_FOR_BUILD to a the target platform compiler, but also set CC_FOR_BUILD to a
compiler for the host platform (for building binaries to execute compiler for the host platform (for building binaries to execute
during the build process). If the target machine's stack grows up, during the build process). If the target machine's stack grows up,
you'll have to supply --enable-stackup; if the target machine is you'll have to supply `--enable-stackup'; if the target machine is
big-endian, you may have to supply --enable-bigendian. big-endian, you may have to supply `--enable-bigendian'.
If you re-run `configure' after running `make', then products of If you re-run `configure' after running `make', then products of the
the `make' may be incorrect due to changes in the compiler command `make' may be incorrect due to changes in the compiler command line.
line. To be safe, run `make clean' each time after running To be safe, run `make clean' each time after running `configure'.
`configure'. To be even safer, run `configure' in a fresh build To be even safer, run `configure' in a fresh build directory every
directory every time. time.
When building for multiple platforms or configurations out of the When building for multiple platforms or configurations out of the
same source directory, beware of cached `configure' information in same source directory, beware of cached `configure' information in
`config.cache'. Avoid this problem entirely by using a separate "config.cache". Avoid this problem entirely by using a separate
build directory (but the same source) for each platform or build directory (but the same source) for each platform or
configuration. configuration.
3. Run `make'. [As noted in step 0, this must be GNU `make'.] 3. Run `make'. [As noted in step 0, this must be GNU `make'.]
With Cygwin, you may need to use `make --unix'. With Cygwin, you may need to use `make --unix'.
Binaries and libraries are placed in subdirectories of the build Binaries and libraries are placed in subdirectories of the build
directory. For example, the `racket3m' binary appears in the directory. For example, the `racket3m' binary appears in the
`racket' directory. "racket" directory.
4. Run `make install'. 4. Run `make install'.
This step copies binaries and libraries into place within the This step copies binaries and libraries into place within the target
target installation. For example, the `racket' binary is copied installation. For example, the "racket" binary is copied into the
into the "bin" directory for an in-place build, or into the "bin" directory for an in-place build, or into the executable
executable directory for a --prefix build. directory for a --prefix build.
For a --prefix build, this step also creates a "config.rkt" module For a `--prefix' build, this step also creates a "config.rkt" module
in a "config" collection, so that various Racket tools and in a "config" collection, so that various Racket tools and libraries
libraries can find the installation directories. At this stage, in can find the installation directories. At this stage, in case you
case you are packaging an installation instead of installing are packaging an installation instead of installing directly, you
directly, you can redirect the installation by setting the can redirect the installation by setting the "DESTDIR" environment
"DESTDIR" environment variable. For example, `make variable. For example, `make DESTDIR=/tmp/racket-build install'
DESTDIR=/tmp/racket-build install' places the installation into places the installation into "/tmp/racket-build" instead of the
"/tmp/racket-build" instead of the location originally specified location originally specified with `--prefix'. The resulting
with --prefix. The resulting installation will not work, however, installation will not work, however, until it is moved to the
until it is moved to the location originally specified with location originally specified with `--prefix'.
--prefix.
Finally, the `make install' step compiles ".zo" bytecode files for Finally, the `make install' step compiles ".zo" bytecode files for
installed Racket source, and generates launcher programs like installed Racket source, and generates launcher programs like
DrRacket. Use `make plain-install' to install without compiling DrRacket. Use `make plain-install' to install without compiling
".zo" files or creating launchers. ".zo" files or creating launchers.
If the installation fails because the target directory cannot be If the installation fails because the target directory cannot be
created, or because the target directory is not the one you created, or because the target directory is not the one you want,
want, then you can try repeating step 4 after running `configure' then you can try repeating step 4 after running `configure' again
again with a new --prefix value. That is, sometimes it is not with a new `--prefix' value. That is, sometimes it is not necessary
necessary to repeat step 3 (so try it and find out). On other to repeat step 3 (so try it and find out). On other platforms and
platforms and configurations, it is necessary to start with a configurations, it is necessary to start with a clean build
clean build directory when changing the --prefix value, because directory when changing the `--prefix' value, because the path gets
the path gets wired into shared objects. wired into shared objects.
If you build frequently from the git-based sources, beware that If you build frequently from the git-based sources, beware that you
you may accumulate user- and version-specific information in your may accumulate user- and version-specific information in your
"add-ons" directory, which you can most easily find by evaluating "add-ons" directory, which you can most easily find by evaluating
(find-system-path 'addon-dir) (find-system-path 'addon-dir)
in Racket. In addition, if you configure with --enabled-shared, in Racket. In addition, if you configure with `--enabled-shared',
you may accumlate many unused versions of the dynamic libraries in you may accumlate many unused versions of the dynamic libraries in
your installation target. your installation target.
After an "in-place" install without git, the racket/src directory is After an "in-place" install without git, the "racket/src" directory is
no longer needed, and it can be safely deleted. Build information is no longer needed, and it can be safely deleted. Build information is
recorded in a "buildinfo" file in the installation. recorded in a "buildinfo" file in the installation.
For a build without --prefix (or with --enable-origtree) and without For a build without `--prefix' (or with `--enable-origtree') and without
--enable-shared, you can safely move the install tree, because all `--enable-shared', you can safely move the install tree, because all
file references within the installation are relative. file references within the installation are relative.
OpenGL, Unix, and pthreads OpenGL, Unix, and pthreads
-------------------------- --------------------------
On some Unix systems, programs that use the OpenGL library must also On some Unix systems, programs that use the OpenGL library must also
link to pthreads. To use GRacket's OpenGL support on these systems, GRacket link to pthreads. To use GRacket's OpenGL support on these systems,
must be configured with the --enable-pthread option. Unfortunately, GRacket must be configured with the `--enable-pthread' option.
Racket's normal stack handling and use of signals (for its own Unfortunately, Racket's normal stack handling and use of signals (for
thread scheduling) do not interact well with pthreads. Thus, when its own thread scheduling) do not interact well with pthreads. Thus,
pthreads are enabled, Racket and GRacket cannot use interupt timers, when pthreads are enabled, Racket and GRacket cannot use interupt
and the stack is limited to 1MB. These restrictions can degrade timers, and the stack is limited to 1MB. These restrictions can degrade
performance and thread-responsiveness. performance and thread-responsiveness.
If `configure' detects that OpenGL requires -lpthread for linking, If `configure' detects that OpenGL requires -lpthread for linking, and
and if --enable-pthread is not specified, `configure' prints a warning if `--enable-pthread' is not specified, `configure' prints a warning and
and disables GL support. On some systems, including at least FreeBSD disables GL support. On some systems, including at least FreeBSD with
with the MESA GL implementation (but not the NVIDIA implementation, the MESA GL implementation (but not the NVIDIA implementation, which
which does not need pthreads), `configure' cannot detect the need for does not need pthreads), `configure' cannot detect the need for
pthreads. On these platforms, GL support will be included in GRacket, pthreads. On these platforms, GL support will be included in GRacket,
but it will not work properly unless --enable-pthread is specified. but it will not work properly unless `--enable-pthread' is specified.
======================================================================== ========================================================================
CGC versus 3m CGC versus 3m
======================================================================== ========================================================================
Racket and GRacket have two variants: CGC and 3m. The CGC variant is Racket and GRacket have two variants: CGC and 3m. The CGC variant is
older, and it cooperates more easily with extensions written in C. older, and it cooperates more easily with extensions written in C. The
The 3m variant is the default, and it usually provides better overall 3m variant is the default: it is more robust and usually provides better
performance. overall performance.
The default build mode creates 3m binaries only. To create CGC The default build mode creates 3m binaries only. To create CGC binaries
binaries in addition, run `make cgc' in addition to `make', or run in addition, run `make cgc' in addition to `make', or run `make both'.
`make both'. To install both variants, use `make install-both' instead To install both variants, use `make install-both' instead of just `make
of just `make install'. Alternately, use just `make cgc' and `make install'. Alternately, use just `make cgc' and `make install-cgc' to
install-cgc' to build and install just the CGC variants. build and install just the CGC variants.
CGC variants are installed with a "cgc" suffix. To swap the default CGC variants are installed with a "cgc" suffix. To swap the default
build and install mode, supply --enable-cgcdefault to `configure'. In build and install mode, supply `--enable-cgcdefault' to `configure'. In
that case, CGC variants are built by default, `make 3m' creates 3m that case, CGC variants are built by default, `make 3m' creates 3m
binaries, and `make install-both' installs CGC variants without a binaries, and `make install-both' installs CGC variants without a suffix
suffix and 3m variants with a "3m" suffix. and 3m variants with a "3m" suffix.
======================================================================== ========================================================================
Embedded Paths in the Executables Embedded Paths in the Executables
======================================================================== ========================================================================
On all platforms, the Racket and GRacket binaries embed a path to the On all platforms, the Racket and GRacket binaries embed a path to the
main "collects" directory of library collections. This path can be main "collects" directory of library collections. This path can be
relative to the executable. Multiple paths can be provided, in which relative to the executable. Multiple paths can be provided, in which
case the first path is the main "collects" path, and additional paths case the first path is the main "collects" path, and additional paths
are placed before the main path (but after a user-specific "collects" are placed before the main path (but after a user-specific "collects"
path) in the default collection path list. path) in the default collection path list.
The paths are embedded in the binary immediately after a special The paths are embedded in the binary immediately after a special
"coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the "coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the entire
entire list of paths must end with an additional NUL terminator, and list of paths must end with an additional NUL terminator, and the
the overall list must be less than 1024 bytes long. overall list must be less than 1024 bytes long.
As an alternative to editing an exeuctable directly, the As an alternative to editing an exeuctable directly, the
`create-embedding-executable' procedure from `compiler/embed' can be `create-embedding-executable' procedure from `compiler/embed' can be
used to change the embedded path. For example, the following program used to change the embedded path. For example, the following program
clones the Racket executable to "/tmp/mz" and changes the embedded clones the Racket executable to "/tmp/mz" and changes the embedded path
path in the clone to "/tmp/collects": in the clone to "/tmp/collects":
(require compiler/embed) (require compiler/embed)
(create-embedding-executable "/tmp/mz" #:collects-path "/tmp/collects") (create-embedding-executable "/tmp/mz" #:collects-path "/tmp/collects")
@ -323,21 +320,20 @@ path in the clone to "/tmp/collects":
Similarly, `raco exe' mode accepts a `--collects' flag to set the Similarly, `raco exe' mode accepts a `--collects' flag to set the
collection path in the generated executable. collection path in the generated executable.
Under Windows, executables also embed a path to DLLs. For more Under Windows, executables also embed a path to DLLs. For more
information, see worksp\README. information, see "worksp\README".
Paths to all other installation directories are found through the Paths to all other installation directories are found through the
"config.rkt" library of the "config" collection. Search the "config.rkt" library of the "config" collection. Search the
documentation for "config search paths" for more information. documentation for "config search paths" for more information.
======================================================================== ========================================================================
Porting to New Platforms Porting to New Platforms
======================================================================== ========================================================================
At a mininum, to port Racket to a new platform, edit At a mininum, to port Racket to a new platform, edit "racket/sconfig.h"
racket/sconfig.h to provide a platform-specific compilation to provide a platform-specific compilation information. As distributed,
information. As distributed, racket/sconfig.h contains "racket/sconfig.h" contains configurations for the following platforms:
configurations for the following platforms:
Windows (x86) Windows (x86)
Mac OS X (PPC, x86, x86_64) Mac OS X (PPC, x86, x86_64)
@ -359,22 +355,22 @@ If your platfrom is not supported by the Boehm garbage collector
Garbage Collector Garbage Collector
----------------- -----------------
The conservative garbage collector distributed with Racket (in the The conservative garbage collector distributed with Racket (in the "gc"
gc directory) has been modified slightly from Boehm's standard directory) has been modified slightly from Boehm's standard
distribution. Mostly, the change modify the way that object distribution. Mostly, the change modify the way that object
finalization is handled. finalization is handled.
Configuration Options Configuration Options
--------------------- ---------------------
By default, Racket is compiled without support for single-precision By default, Racket is compiled without support for single-precision
floating point numbers. This and other options can be modified by floating point numbers. This and other options can be modified by
setting flags in racket/sconfig.h. setting flags in "racket/sconfig.h".
Modifying Racket Modifying Racket
------------------ ----------------
If you modify Racket and change any primitive syntax or the If you modify Racket and change any primitive syntax or the collection
collection of built-in identifers, be sure to turn off of built-in identifers, be sure to turn off USE_COMPILED_MACROS in
USE_COMPILED_MACROS in schminc.h. Otherwise, Racket won't start. "schminc.h". Otherwise, Racket won't start. See "schminc.h" for
See schminc.h for details. details.

View File

@ -18,14 +18,14 @@ Visual Studio Express is available for free from Microsoft; it can be
used to build Racket and GRacket, but not MzCOM and MysterX. used to build Racket and GRacket, but not MzCOM and MysterX.
Racket and GRacket also compile with Cygwin gcc (a free compiler from Racket and GRacket also compile with Cygwin gcc (a free compiler from
GNU and Cygnus Solutions), but the result is a Unix-style GNU and Cygnus Solutions), but the result is a Unix-style installation,
installation, not a Window-style installation. To compile with gcc, not a Window-style installation. To compile with gcc, follow the
follow the instructions in racket\src\README (which contains a short instructions in racket\src\README (which contains a short
Windows-specific section). Windows-specific section).
With an MSVC-built Racket, compatible extensions can be built with With an MSVC-built Racket, compatible extensions can be built with other
other compilers. Build with Cygwin and copy the installed racket\lib\gcc compilers. Build with Cygwin and copy the installed racket\lib\gcc to a
to a MSVC-based build to support Cygwin-built extensions. To support MSVC-based build to support Cygwin-built extensions. To support
Borland-built extensions, cd to racket\src\racket\dynsrc and run Borland-built extensions, cd to racket\src\racket\dynsrc and run
mkbordyn.bat (which requires bcc23.exe, of course). mkbordyn.bat (which requires bcc23.exe, of course).
@ -37,20 +37,20 @@ As always, please report bugs via one of the following:
-PLT -PLT
racket@racket-lang.org racket@racket-lang.org
---------------------------------------------------------------------- ---------------------------
Building Racket and GRacket Building Racket and GRacket
---------------------------------------------------------------------- ---------------------------
If you're using MSVC 8.0 (not Express), and if `devenv.exe' is in your If you're using MSVC 8.0 (not Express), and if `devenv.exe' is in your
path, then you can just run path, then you can just run
racket\src\worksp\build.bat racket\src\worksp\build.bat
from its own directory to perform all steps up to "Versioning", from its own directory to perform all steps up to "Versioning",
including the MzCOM and MysterX steps. including the MzCOM and MysterX steps.
The CGC variants of Racket, MzCOM, GRacket, and MysterX can be built The CGC variants of Racket, MzCOM, GRacket, and MysterX can be built via
via Visual Studio projects. The 3m variants are built by a Racket Visual Studio projects. The 3m variants are built by a Racket script
script that runs the MSVC command-line tools. (See "CGC versus 3m" that runs the MSVC command-line tools. (See "CGC versus 3m" in
in racket\src\README if you don't know about the two variants.) racket\src\README if you don't know about the two variants.)
The 3m build requires some parts of the CGC build: The 3m build requires some parts of the CGC build:
racket\src\worksp\racket racket\src\worksp\racket
@ -58,15 +58,14 @@ The 3m build requires some parts of the CGC build:
racket\src\worksp\jpeg racket\src\worksp\jpeg
racket\src\worksp\png racket\src\worksp\png
racket\src\worksp\zlib racket\src\worksp\zlib
It's simplest to just build the main CGC solutions, which It's simplest to just build the main CGC solutions, which automatically
automatically build all of the above projects, and then build build all of the above projects, and then build 3m.
3m.
Building RacketCGC and GRacketCGC Building RacketCGC and GRacketCGC
-------------------------------- ---------------------------------
The CGC source code for RacketCGC and GRacketCGC is split into several The CGC source code for RacketCGC and GRacketCGC is split into several
projects that are grouped into a few solutions. To build the `X' projects that are grouped into a few solutions. To build the `X'
solution with Visual Studio, open the file racket\src\worksp\X\X.sln. solution with Visual Studio, open the file racket\src\worksp\X\X.sln.
To build RacketCGC, build the Racket solution in To build RacketCGC, build the Racket solution in
@ -81,37 +80,36 @@ To build GRacketCGC, build the GRacket solution:
[Again, switch to the "Release" configuration if necessary.] [Again, switch to the "Release" configuration if necessary.]
The build processes for RacketCGC automatically builds The build processes for RacketCGC automatically builds
libmzgc - makes racket\lib\libmzgcxxxxxxx.dll and libmzgc - makes racket\lib\libmzgcxxxxxxx.dll and
racket\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib racket\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
libracket - makes racket\lib\libracketxxxxxxx.dll and libracket - makes racket\lib\libracketxxxxxxx.dll and
racket\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib racket\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib
The build process for GRacketCGC automatically builds The build process for GRacketCGC automatically builds
libmzgc - as above libmzgc - as above
libracket - as above libracket - as above
libgracket - makes racket\lib\libgracketxxxxxxx.dll and libgracket - makes racket\lib\libgracketxxxxxxx.dll and
racket\src\worksp\libgracket\Release\libgracketxxxxxxx.lib racket\src\worksp\libgracket\Release\libgracketxxxxxxx.lib
wxutils - makes racket\src\worksp\wxutils\Release\wxutils.lib wxutils - makes racket\src\worksp\wxutils\Release\wxutils.lib
wxwin - makes racket\src\worksp\wxwin\Release\wxwin.lib wxwin - makes racket\src\worksp\wxwin\Release\wxwin.lib
wxs - makes racket\src\worksp\wxs\Release\wxs.lib wxs - makes racket\src\worksp\wxs\Release\wxs.lib
wxme - makes racket\src\worksp\wxme\Release\wxme.lib wxme - makes racket\src\worksp\wxme\Release\wxme.lib
jpeg - makes racket\src\worksp\jpeg\Release\jpeg.lib jpeg - makes racket\src\worksp\jpeg\Release\jpeg.lib
png - makes racket\src\worksp\jpeg\Release\png.lib png - makes racket\src\worksp\jpeg\Release\png.lib
zlib - makes racket\src\worksp\jpeg\Release\zlib.lib zlib - makes racket\src\worksp\jpeg\Release\zlib.lib
In addition, building RacketCGC executes In addition, building RacketCGC executes
racket\src\racket\dynsrc\mkmzdyn.bat racket\src\racket\dynsrc\mkmzdyn.bat
which copies .exp, .obj, and .lib files into racket\lib\, and also copies which copies .exp, .obj, and .lib files into racket\lib\, and also
DLLs from the "extradlls" directory to to racket\lib\. copies DLLs from the "extradlls" directory to to racket\lib\.
Building Racket3m and GRacket3m Building Racket3m and GRacket3m
------------------------------ -------------------------------
After RacketCGC and GRacketCGC are built, you can can build 3m After RacketCGC and GRacketCGC are built, you can can build 3m binaries:
binaries:
1. Ensure that the Visual Studio command-line tools are in your 1. Ensure that the Visual Studio command-line tools are in your path.
path. You may need to run "vsvars32.bat" from your Visual Studio You may need to run "vsvars32.bat" from your Visual Studio
installation, so that PATH and other environment variables are set. installation, so that PATH and other environment variables are set.
2. Change directories to racket\src\worksp\gc2 and run 2. Change directories to racket\src\worksp\gc2 and run
@ -120,7 +118,7 @@ binaries:
The resulting Racket.exe and GRacket.exe will appear in the top-level The resulting Racket.exe and GRacket.exe will appear in the top-level
"racket" directory, along with DLLs libracket3mxxxxxxx.dll and "racket" directory, along with DLLs libracket3mxxxxxxx.dll and
libgracket3mxxxxxxx.dll in racket/lib. (There is no corresponding libgracket3mxxxxxxx.dll in racket/lib. (There is no corresponding
libmzgc3mxxxxxxx.dll. Instead, it is merged with libmzgc3mxxxxxxx.dll. Instead, it is merged with
libracket3mxxxxxxx.dll.) libracket3mxxxxxxx.dll.)
@ -128,7 +126,7 @@ Building Collections and Other Executables
------------------------------------------ ------------------------------------------
If you're building from scratch, you'll also want the starter programs If you're building from scratch, you'll also want the starter programs
used by the launcher collection to create "raco.exe". Build the used by the launcher collection to create "raco.exe". Build the
following solutions: following solutions:
racket\src\worksp\mzstart - makes racket\collects\launcher\mzstart.exe racket\src\worksp\mzstart - makes racket\collects\launcher\mzstart.exe
@ -142,8 +140,8 @@ Racket[CGC].exe) by running
racket.exe -l- setup racket.exe -l- setup
This last step makes the .zo files, too. To skip compiling .zos, add This last step makes the .zo files, too. To skip compiling .zos, add
-n to the end of the above command. `-n' to the end of the above command.
If you've already built before, then this step can be simplied: just If you've already built before, then this step can be simplied: just
re-run `raco setup', where "raco.exe" was created the first time. re-run `raco setup', where "raco.exe" was created the first time.
@ -152,13 +150,13 @@ Versioning
---------- ----------
[If you're going to build MzCOM and/or MysterX, do that before running [If you're going to build MzCOM and/or MysterX, do that before running
the version-changing script. See instructions below.] the version-changing script. See instructions below.]
The obnoxious "xxxxxxx" in the DLL names is a placeholder for a The obnoxious "xxxxxxx" in the DLL names is a placeholder for a version
version number. Embedding a version number in a DLL name appears to number. Embedding a version number in a DLL name appears to be the
be the simplest and surest way to avoid version confusion. simplest and surest way to avoid version confusion.
For local testing, you can use the "xxxxxxx" libraries directly. For For local testing, you can use the "xxxxxxx" libraries directly. For
any binaries that will be distributed, however, the placeholder should any binaries that will be distributed, however, the placeholder should
be replaced with a specific version. be replaced with a specific version.
@ -169,20 +167,18 @@ To replace the "xxxxxxx" with a specific version, run
in a shell. in a shell.
The "winvers.rkt" program will have to make a temporary copy of The "winvers.rkt" program will have to make a temporary copy of
racket.exe and the "lib" sub-directory (into the temporary racket.exe and the "lib" sub-directory (into the temporary directory),
directory), and it will re-launch Racket a couple of times. Every and it will re-launch Racket a couple of times. Every ".exe", ".dll",
".exe", ".dll", ".lib", ".def", ".exp", and ".pdb" file within the ".lib", ".def", ".exp", and ".pdb" file within the "racket" tree is
"racket" tree is updated to replace "xxxxxxxx" with a specific version updated to replace "xxxxxxxx" with a specific version number.
number.
---------------------------------------------------------------------- --------------------------
Building MzCOM and MysterX Building MzCOM and MysterX
---------------------------------------------------------------------- --------------------------
Beware that MzCOM and MysterX do not build with Express versions of Beware that MzCOM and MysterX do not build with Express versions of
Visual Studio. Otherwise, building MzCOMCGC and MysterXCGC is similar Visual Studio. Otherwise, building MzCOMCGC and MysterXCGC is similar
to building RacketCGC. Building the 3m variants is a little to building RacketCGC. Building the 3m variants is a little different.
different.
Building MzCOM Building MzCOM
-------------- --------------
@ -192,14 +188,14 @@ To build MzCOMCGC, make the MzCOM solution in
Use the "Release" configuration. Use the "Release" configuration.
After building MzCOMCGC, you can build the 3m variant by After building MzCOMCGC, you can build the 3m variant by
1. Change directories to racket\src\worksp\mzcom and run 1. Change directories to racket\src\worksp\mzcom and run
..\..\..\racketcgc.exe -cu xform.rkt ..\..\..\racketcgc.exe -cu xform.rkt
2. Switch to the "3m" configuration in the MzCOM solution 2. Switch to the "3m" configuration in the MzCOM solution (in Visual
(in Visual Studio). Studio).
3. Build (in Visual Studio). 3. Build (in Visual Studio).
@ -215,48 +211,47 @@ To build MysterXCGC, make the MysterX solution in
Use the "Release" configuration. Use the "Release" configuration.
After building MysterXCGC, you can build the 3m variant by After building MysterXCGC, you can build the 3m variant by
1. Change directories to racket\src\worksp\libmysterx and run 1. Change directories to racket\src\worksp\libmysterx and run
..\..\..\racketcgc.exe -cu xform.rkt ..\..\..\racketcgc.exe -cu xform.rkt
2. Switch to the "3m" configuration in the libmysterx solution 2. Switch to the "3m" configuration in the libmysterx solution (in
(in Visual Studio). Visual Studio).
3. Build (in Visual Studio). 3. Build (in Visual Studio).
The result is mxmain.dll (no 3m suffix) in The result is mxmain.dll (no 3m suffix) in
collects\mysterx\private\compiled\native\win32\i386\3m collects\mysterx\private\compiled\native\win32\i386\3m
---------------------------------------------------------------------- ------------
Finding DLLs Finding DLLs
---------------------------------------------------------------------- ------------
Since the DLLs libracket3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and Since the DLLs libracket3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and
libracketxxxxxxx.dll) and libgracket3mxxxxxxx.dll (or libracketxxxxxxx.dll) and libgracket3mxxxxxxx.dll (or
libgracketxxxxxxx.dll) are installed into racket\lib\ instead of just libgracketxxxxxxx.dll) are installed into racket\lib\ instead of just
racket\, the normal search path for DLLs would not find them when running racket\, the normal search path for DLLs would not find them when
"Racket.exe" or "GRacket.exe". To find the DLLs, the executables are running "Racket.exe" or "GRacket.exe". To find the DLLs, the
"delayload" linked with the DLLs, and the executables explicitly load executables are "delayload" linked with the DLLs, and the executables
the DLLs from racket\lib\ on start-up. explicitly load the DLLs from racket\lib\ on start-up.
The relative DLL path is embedded in each executable, and it can be The relative DLL path is embedded in each executable, and it can be
replaced with a path of up to 512 characters. The path is stored in replaced with a path of up to 512 characters. The path is stored in the
the executable in wide-character format, and it is stored immediately executable in wide-character format, and it is stored immediately after
after the wide-character tag "dLl dIRECTORy:" with a wide NUL the wide-character tag "dLl dIRECTORy:" with a wide NUL terminator. The
terminator. The path can be either absolute or relative; in the latter path can be either absolute or relative; in the latter case, the
case, the relative path is resolved with respect to the relative path is resolved with respect to the executable. Replacing the
executable. Replacing the first character of the path with "<" first character of the path with "<" disables the explicit DLL load, so
disables the explicit DLL load, so that the DLLs must appear in the that the DLLs must appear in the normal DLL search path.
normal DLL search path.
See also ..\README for information on the embedded "collects" path in See also ..\README for information on the embedded "collects" path in
the executables. the executables.
---------------------------------------------------------------------- ----------------
Embedding Racket Embedding Racket
---------------------------------------------------------------------- ----------------
The Racket DLLs can be used within an embedding application. The Racket DLLs can be used within an embedding application.
@ -267,14 +262,13 @@ The libraries
racket\lib\win32\msvc\libmzgcxxxxxxx.lib racket\lib\win32\msvc\libmzgcxxxxxxx.lib
which are created by the mzsrc and gc projects, provide linking which are created by the mzsrc and gc projects, provide linking
information for using the libracket3mxxxxxxx.dll, information for using the libracket3mxxxxxxx.dll, libracketxxxxxxx.dll,
libracketxxxxxxx.dll, and libmzgcxxxxxxx.dll DLLs. The versioning and libmzgcxxxxxxx.dll DLLs. The versioning script adjusts the names,
script adjusts the names, as described above. as described above.
See the "Inside Racket" manual for more information about using
these libraries to embed Racket in an application.
See the "Inside Racket" manual for more information about using these
libraries to embed Racket in an application.
If you need Racket to link to a DLL-based C library (instead of If you need Racket to link to a DLL-based C library (instead of
statically linking to the C library within the Racket DLL), then statically linking to the C library within the Racket DLL), then compile
compile Racket with the /MD flag. Racket with the /MD flag.