suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reorganize and update "README.txt"s about sources and builds

Browse Source 
Integrate Racket-on-Chez information better and reorganize information
to reflect the way that the makefiles and build scripts have evolved.
This commit is contained in:
Matthew Flatt 2018-11-15 22:06:47 -07:00
parent 337aec3436
commit 709258d88c
13 changed files with 1180 additions and 1090 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
INSTALL.txt
View File

@ -193,11 +193,10 @@ will bootstrap by building a traditional variant of Racket and by
downloading and building Chez Scheme. downloading and building Chez Scheme.
If you have a sufficiently recent Racket installation already with at If you have a sufficiently recent Racket installation already with at
least the "compiler-lib" and "parser-tools-libs" packages installed, least the "compiler-lib" package installed, you can supply
you can supply `RACKET=...` with `make cs` to skip that part of the `RACKET=...` with `make cs` to skip that part of the bootstrap. And if
bootstrap. And if you have a Chez Scheme source directory already[*], you have a Chez Scheme source directory already[*], you can supply
you can supply that with `SCHEME_SRC=...` instead of downloading a new that with `SCHEME_SRC=...` instead of downloading a new copy.
copy.
make cs RACKET=racket SCHEME_SRC=path/to/ChezScheme make cs RACKET=racket SCHEME_SRC=path/to/ChezScheme
@ -216,7 +215,7 @@ Building Minimal Racket
----------------------- -----------------------
Instead of using the top-level makefile, you can go into "racket/src" Instead of using the top-level makefile, you can go into "racket/src"
and follow the "README" there, which gives you more configuration and follow the "README.txt" there, which gives you more configuration
options. options.
If you don't want any special configuration and you just want the base If you don't want any special configuration and you just want the base
@ -235,7 +234,7 @@ libraries. See the documentation for `raco setup` for information on
the options. the options.
For cross compilation, add configuration options to For cross compilation, add configuration options to
`CONFIGURE_ARGS_qq="..."` as described in the "README" of `CONFIGURE_ARGS_qq="..."` as described in the "README.txt" of
"racket/src", but also add a `PLAIN_RACKET=...` argument for the "racket/src", but also add a `PLAIN_RACKET=...` argument for the
top-level makefile to specify the same executable as in an top-level makefile to specify the same executable as in an
`--enable-racket=...` for `configure`. In general, the `PLAIN_RACKET` `--enable-racket=...` for `configure`. In general, the `PLAIN_RACKET`

3
README.md
View File

@ -15,9 +15,6 @@ the IRC channel.
License License
------- -------
Racket
Copyright (c) 2010-2018 PLT Design Inc.
Racket is distributed under the GNU Lesser General Public License Racket is distributed under the GNU Lesser General Public License
(LGPL). This implies that you may link Racket into proprietary (LGPL). This implies that you may link Racket into proprietary
applications, provided you follow the rules stated in the LGPL. You can applications, provided you follow the rules stated in the LGPL. You can

579
racket/src/README
View File

@ -1,579 +0,0 @@
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
available at http://racket-lang.org/; pre-compiled nightly builds are
available at http://pre.racket-lang.org/installers/.
The Racket and GRacket source code should compile and execute on
Windows, Mac OS, or any Unix/X platform (including Linux).
Per-platform instructions are below.
Please report bugs via one of the following:
- https://github.com/racket/racket/issues (preferred)
- DrRacket's "submit bug report" menu
- http://bugs.racket-lang.org/
- the mailing list (users@racket-lang.org) (last resort)
-PLT
racket@racket-lang.org
========================================================================
Traditional Racket versus Racket-on-Chez
========================================================================
By default, `configure` and the Windows scripts build the traditional
3m variant of Racket. The rest of the instructions below are about
building the traditional Racket implementation, except for a general
"Implementation Organization" note at the end applies to both
variants.
Supplying `--enable-cs` or `--enable-csdefault` builds Racket on Chez
Scheme in addition to the traditional variant of Racket, while
`--enable-csonly` builds only Racket-on-Chez. Building Racket-on-Chez
requires either a "ChezScheme" build checkout in the build directory
or `--enable-scheme=...` to specify the Chez Scheme build directory
location. For more information on building Racket-on-Chez see
"cs/c/README.txt".
========================================================================
Compiling for Windows
========================================================================
To compile with Microsoft Visual C, read the instructions in
"racket\src\worksp\README".
To compile with MinGW tools, follow the Unix instructions below; do not
use `--enable-shared`, because DLLs will be generated automatically.
The result is a Windows-style build. If you are using a variant of
MinGW without "libdelayimp.a", get the implementation of "delayimp.c"
from MinGW-w64 and compile it to "libdelayimp.a".
To compile with Cygwin tools, follow the Unix instructions below. The
result is a Unix-style build, not a Windows-style build (e.g.,
Racket's `system-type` procedure returns 'unix, not 'windows, and
`racket/gui` uses Gtk instead of Win32).
========================================================================
Compiling for Mac OS
========================================================================
First, install developer command-line tools from Apple. As of this
writing, install by getting "Xcode" from the AppStore; then, in
Xcode's preferences window and in the "Downloads" panel, install
"Command Line Tools".
After installing developer tools, follow the Unix instructions below,
but note the following:
* The Racket build creates a framework, "Racket.framework", which is
installed into "racket/lib". This framework is used by the `racket`
executable that goes into "racket/bin".
* The GRacket build creates a GUI-executable variant of the Racket
executable. The GRacket build process also downloads (from github)
pre-built libraries for Cairo, Pango, etc.
* The `--enable-shared` flag for `configure` must not be used, because
builds create and use frameworks by default. Furthermore,
`--disable-shared` is not supported. (Unless you use
`--enable-xonx`...)
* To build an X11- and Gtk-based GRacket, run `configure` with the
`--enable-xonx` flag. Frameworks are not used for such builds, so
`--enable-shared` is allowed. The `--enable-xonx` flag also affects
the Racket build, so that `system-type` reports 'unix. Pre-built
libraries are not downloaded in this mode; you must have Cairo,
Pango, and GTk installed.
* To use `--prefix` without `--enable-xonx`, you must also supply
`--enable-macprefix`. BEWARE! The directory structure for a
non-xonx build does not fit a typical Unix directory structure. For
example, frameworks are written directly to a "lib" subdirectory, and
executables like "GRacket.app" are written directly to the prefix
directory. (Requiring `--enable-macprefix` with `--prefix` for a
non-xonx build helps prevent accidental installation of a Mac-style
directory structure on top of an existing Unix-style directory
structure.)
* Under Mac OS 10.6 and later, to build Racket in 32-bit mode,
use `--disable-mac64`.
========================================================================
Compiling for supported Unix variants (including Linux) or Cygwin/MinGW
========================================================================
Quick instructions:
From this directory (where the `configure` file is), run the following
commands:
mkdir build
cd build
../configure
make
make install
Those commands will create an in-place installation of Racket and
store the results of C compilation in a separate "build"
subdirectory, which is useful if you need to update your sources,
delete the build, and start from scratch.
You can also run the typical `./configure && make && make install` if
you don't anticipate updating/rebuilding, but it will be harder to
restart from scratch should you need to.
Detailed instructions:
0. If you have an old Racket installation in the target directory,
remove it (unless you are using an "in-place" build from a
repository as described below).
To run `racket/draw` and `racket/gui` programs, you will need
Cairo, Pango, and GTk installed. These libraries are not
distributed with Racket, and they are not needed for compilation,
except for building documentation that uses `racket/draw`. More
info about required libs is available at
http://docs.racket-lang.org/draw/libs.html and
http://docs.racket-lang.org/gui/libs.html.
The content of the "foreign" subdirectory may require GNU `make`
if no installed "libffi" is detected. If the build fails with
another variant of `make`, please try using GNU `make`.
1. Select (or create) a build directory.
It's better to run the build in a directory other than the one
containing `configure`, especially if you're getting sources via
git. A common way to start a git-based build is:
cd [here]
mkdir build
cd build
where "[here]" is the directory containing this `README` file and
the `configure` script. The git repository is configured to support
this convention by ignoring `build` in this directory.
A separate build directory is better in case the Makefile
organization changes, or in case the Makefiles lack some
dependencies. In those cases, when using a "build" subdirectory,
you can just delete and re-create "build" without mangling your
source tree.
2. From your build directory, run the script `configure` (which is in
the same directory as this README), with optional command-line
arguments `--prefix=TARGETDIR` or `--enable-shared` (or both).
For example, if you want to install into "/usr/local/racket" using
dynamic libraries, then run:
[here]configure --prefix=/usr/local/racket --enable-shared
Again, "[here]" is the directory path containing the `configure`
script. If you follow the convention of running from a "build"
subdirectory, "[here]" is just "../". If you build from the current
directory, "[here]" is possibly unnecessary, or possibly just "./",
depending on your shell and PATH setting.
If the `--prefix` flag is omitted, the binaries are built for an
in-place installation (i.e., the parent of the directory containing
this README will be used directly). Unless `--enable-shared` is
used, the "racket" directory can be moved later; most system
administrators would recommend that you use `--enable-shared`, but
the Racket developers distribute binaries built without
`--enable-shared`.
The `configure` script generates the makefiles for building Racket
and/or GRacket. The current directory at the time `configure` is
run will be used as working space for building the executables
(independent of `--prefix`). This build directory does not have to
be in the source tree, even for an in-place build. It's ok to run
`configure` from its own directory (as in the first example above),
but it's better to pick a separate build directory that is otherwise
empty (as in the second example).
The `configure` script accepts many other flags that adjust the
build process. Run `configure --help` for more information. In
addition, a specific compiler can be selected through environment
variables. For example, to select the SGI compilers for Irix
instead of gcc, run configure as
env CC=cc CXX=CC [here]configure
To add an include path, be sure to use CPPFLAGS="-I..." instead
of CFLAGS="-I...". The CPPFLAGS variable controls C pre-processing,
which includes C compilation, and the Racket build normally uses
the C pre-processor directly for some parts of the build.
If you re-run `configure` after running `make`, then products of the
`make` may be incorrect due to changes in the compiler command line.
To be safe, run `make clean' each time after running `configure`.
To be even safer, run `configure` in a fresh build directory every
time.
When building for multiple platforms or configurations out of the
same source directory, beware of cached `configure` information in
"config.cache". Avoid this problem entirely by using a separate
build directory (but the same source) for each platform or
configuration.
3. Run `make`. [As noted in step 0, this might need to be GNU `make`.]
With Cygwin, you may need to use `make --unix`.
Binaries and libraries are placed in subdirectories of the build
directory. For example, the `racket3m` binary appears in the
"racket" directory.
4. Run `make install`.
This step copies binaries and libraries into place within the target
installation. For example, the "racket" binary is copied into the
"bin" directory for an in-place build, or into the executable
directory for a `--prefix` build.
For a `--prefix` build, this step also creates a "config.rktd" module
in an "etc" directory, so that various Racket tools and libraries
can find the installation directories. At this stage, in case you
are packaging an installation instead of installing directly, you
can redirect the installation by setting the "DESTDIR" environment
variable to an absolute path for the packaging area. For example,
`make DESTDIR=/tmp/racket-build install` places the installation
into "/tmp/racket-build" instead of the location originally
specified with `--prefix`. The resulting installation will not
work, however, until it is moved to the location originally
specified with `--prefix`.
Finally, the `make install` step compiles ".zo" bytecode files for
installed Racket source, generates launcher programs like DrRacket
(if it's already installed as a package), and builds documentation
(again, if installed). Use `make plain-install` to install without
compiling ".zo" files, creating launchers, or building
documentation.
If the installation fails because the target directory cannot be
created, or because the target directory is not the one you want,
then you can try repeating step 4 after running `configure` again
with a new `--prefix` value. That is, sometimes it is not necessary
to repeat step 3 (so try it and find out). On other platforms and
configurations, it is necessary to start with a clean build
directory when changing the `--prefix` value, because the path gets
wired into shared objects.
If you build frequently from the git-based sources, beware that you
may accumulate user- and version-specific information in your
"add-ons" directory, which you can most easily find by evaluating
(find-system-path 'addon-dir)
in Racket. In addition, if you configure with `--enabled-shared`,
you may accumulate many unused versions of the dynamic libraries in
your installation target.
After an "in-place" install from a source distribution, the
"racket/src" directory is no longer needed, and it can be safely
deleted. Build information is recorded in a "buildinfo" file in the
installation.
For a build without `--prefix` (or with `--enable-origtree`) and without
`--enable-shared`, you can safely move the install tree, because all
file references within the installation are relative.
========================================================================
Cross-compiling
========================================================================
Cross-compilation requires at least two flags to `configure`:
* `--host=OS`, where OS is something like `i386-gnu-linux` to
indicate the target platform.
The `configure` script uses OS to find suitable compilation tools,
such as `OS-gcc` and `OS-strip`.
* `--enable-racket=RACKET`, where RACKET is a path to a Racket
executable that runs on the build platform; the executable must be
the same version of Racket as being built for the target platform.
This flag is needed because building and installing Racket requires
running (an existing build of) Racket.
Use "auto" for RACKET to indicates that one should be built
automatically for the current platform. In that case, `make`
will run `configure` again (with no arguments) in a "local"
subdirectory to create a build for the current platform.
Some less commonly needed `configure` flags:
* `--enable-stackup`, if the target platform`s stack grows up.
* `--enable-bigendian`, if target platform is big-endian.
* `--enable-cify` or `--disable-cify` if the JIT availablity on the
target platform is different than the build platform; use
`--enable-cify` if the JIT is not abailable on the target
platform.
========================================================================
Cross-compiling for Android
========================================================================
As an example of cross-compiling, to compile for Android on ARM using
the NDK, use (all on one line)
configure --host=arm-linux-androideabi
--enable-sysroot="[ndk]/platforms/android-[N]/arch-arm"
--enable-racket=auto
where [ndk] is the path to the installed NDK, [N] is a target version
of Android (such as 14), and
[ndk]/toolchains/arm-linux-androideabi-[comp]/prebuilt/[platform]/bin
is in your PATH (so that a suitable `gcc`, `ar`, etc., are found) for
the [comp] of your choice and the [platform] used to compile.
========================================================================
Cross-compiling for iOS
========================================================================
To compile the Racket runtime system as a Framework for iOS, use (all
on one line)
configure --host=[arch]-apple-darwin
--enable-ios="[sdk]"
--enable-racket=racket
where [arch] is one of
- armv7, armv7s, or aarch64: to run on iOS
- i386 or x86_64: to run on the simulator
The [sdk] argument is a path to an iOS SDK, but if it is "iPhoneOS" or
"iPhoneSimulator", then the corresponding SDK is located in the
standard place within the XCode application. For example, "iPhoneOS"
becomes the path (all on one line)
/Applications/Xcode.app/Contents/Developer/Platforms/
iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk
========================================================================
CGC versus 3m
========================================================================
Traditional Racket and GRacket have two variants: CGC and 3m. The CGC
variant is older, and it cooperates more easily with extensions
written in C. The 3m variant is the default: it is more robust and
usually provides better overall performance.
The default build mode creates 3m binaries only (except for a CGC
binary that is used to build the 3m binary). To create CGC binaries
in addition, run `make cgc` in addition to `make`, or run `make both`.
To install both variants, use `make install-both` instead of just
`make install`. Alternately, use just `make cgc` and `make
install-cgc` to build and install just the CGC variants.
CGC variants are installed with a "cgc" suffix. To swap the default
build and install mode, supply `--enable-cgcdefault` to `configure`. In
that case, CGC variants are built by default, `make 3m` creates 3m
binaries, and `make install-both` installs CGC variants without a suffix
and 3m variants with a "3m" suffix.
========================================================================
Embedded Paths in the Executables
========================================================================
On all platforms, the Racket and GRacket binaries embed a path to the
main "collects" directory of library collections. This path can be
relative to the executable. Multiple paths can be provided, in which
case the first path is the main "collects" path, and additional paths
are placed before the main path (but after a user-specific "collects"
path) in the default collection path list.
The paths are embedded in the binary immediately after a special
"coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the entire
list of paths must end with an additional NUL terminator, and the
overall list must be less than 1024 bytes long.
As an alternative to editing an executable directly, the
`create-embedding-executable` procedure from `compiler/embed` can be
used to change the embedded path. For example, the following program
clones the Racket executable to "/tmp/mz" and changes the embedded path
in the clone to "/tmp/collects":
(require compiler/embed)
(create-embedding-executable "/tmp/mz" #:collects-path "/tmp/collects")
Similarly, `raco exe` mode accepts a `--collects` flag to set the
collection path in the generated executable.
Under Windows, executables also embed a path to DLLs. For more
information, see "worksp\README".
Paths to all other installation directories are found through the
"config.rkt" library of the "config" collection. Search the
documentation for "config search paths" for more information.
========================================================================
Porting to New Platforms
========================================================================
At a minimum, to port Racket to a new platform, edit "racket/sconfig.h"
and "rktio/rktio_platform.h" to provide a platform-specific compilation
information.
========================================================================
Additional Compilation Notes
========================================================================
CGC Build Options
-----------------
As noted above in "CGC versus 3m", Racket builds a CGC variant in the
process of creating the normal 3m variant. Within the CGC variant, two
implementations are possible.
By default, Racket CGC is implemented with SenoraGC (in the "sgc"
directory), which is relativey portable. Provide `--disable-sgc` to
instead use the Boehm GC (in the "gc" directory), which should perform
better and was the default for Racket CGC through version 6.1.
The variant of the Boehm GC that is included with Racket has been
modified slightly from Boehm's standard distribution; mostly, the
changes modify the way that object finalization is handled.
[Currently, the Windows build still uses the Boehm GC by default.]
Floating point, x87, SSE, Extflonums, and the JIT
-------------------------------------------------
Pre-processor tests in "sconfig.h" and "scheme.h" attempt to determine
when the x87 floating-point processor needs to be configured for
double-precision mode, when JIT can use SSE2 instructions, and when
extflonums can be supported because both the JIT and C code use SSE2
for double-precision floating-point while `long double` is available
for extflonums.
In particular, "scheme.h" looks for __SSE2_MATH__ to indicate that gcc
is compiling floating-point operations as SSE2, so be sure to include
flags like "-mfpmath=sse" or "-mfpmath=387" in CPPFLAGS, and not just
CFLAGS. See related configuration options below.
The Windows build using MSVC enables extflonum support through a
MinGW-compiled "longdouble.dll", since MSVC does not support `long
double` as extended-precision floating point.
Configuration Options
---------------------
Although `configure` flags control most options, some configurations
options can be modified by setting flags in "racket/sconfig.h".
Some CPP flags control default settings in "racket/sconfig.h":
* MZ_{USE_,NO_}JIT_SSE - {en,dis}ables use of SSE2 floating point
* MZ_USE_DETERMINSTIC_FUEL - disables use of itimer or pthread for
Racket thread scheduling.
* C_COMPILER_USES_SSE - declares that the C compiler is using SSE2
instructions to implement `double` floating-point operations.
Modifying Racket
----------------
If you modify Racket and change any primitive syntax or the collection
of built-in identifiers, be sure to update the version number in
"racket/src/schvers.h", so that various tools know to rebuild
bytecode. If you add or remove primitives, you'll also need to adjust
the counter in "racket/src/schminc.h" .
========================================================================
Implementation Organization
========================================================================
Everything in this "src" directory contributes to the implementation
of the `racket` executable (and variants), while "../collects"
contains the additional Racket libraries that are included in a
minimal Racket distribution.
Directories in "src":
"racket" --- starting point for the traditional Racket implementation
This implementation can build from "scratch" with a C
compiler, but first by building a CGC variant of Racket to
transform the C sourses to build a (normal) 3m variant.
"cs" --- starting point for the Racket-on-Chez implementation
Building the implementation requires both an existing Racket
(possibly created from the "racket" sources) and an existing
Chez Scheme build.
"rktio" --- portability layer for low-level I/O, used by "racket" and
"cs"
If you change "rktio.h", then be sure to regenerate
"rktio.rktl" and "rktio.inc" using an existing Racket
implementation that has the "parser-tools" package installed.
"start" --- main-executable wrapper, used by "racket" and "cs"
"foreign" --- the FFI implementation for "racket", including "libffi"
(as needed for some platforms)
"expander" --- the macro expander implementation, used by "racket"
and "cs"; doubles as the "expander" package
This expander is both included in Racket builds and used to
expand itself for including in "racket" or "cs". It's also
used to expand other libraries included in "cs".
If you change the expander, run `make` in its directory to
generate the "startup.inc" file that holds the expander's
implementation for inclusion in the traditional Racket
variant. The "cs" build (which needs an existing Racket to
build, anyway) picks up changes automatically.
"thread" --- the thread scheduler implementation, used by "cs"
"io" --- the I/O implementation, used by "cs"
"regexp" --- the regexp matcher implementation, used by "cs"
"schemify" --- a Racket-to-Scheme compiler, used by "cs" and "cify"
Similar to "expander", this layer is applied to itself and
other libraries for inclusion in "cs".
"cify" --- a Racket-to-C compiler, used by "racket"
This compiler is used only when embedding the expander as C
code, instead of Racket bytecode, which is the default for
platforms where the Racket JIT is not supported.
"common" --- Racket libraries used by "thread", "io", etc.
"gracket" --- implementation of the GRacket layer for the traditional
Racket implementation
"mzcom" --- implementation of the MzCOM layer (for Windows)for the
traditional Racket implementation
"mysink" --- `ffi/unsafe/com` helper DLL implementation (for Windows)
"mac" --- scripts for Mac OS ".app"s, used by "gracket" and "cs"
"worksp" --- Windows projects and build scripts for "racket" and "cs"
"native-libs" --- build scripts for some native-library packages
"ac" --- autoconf helpers
"lt" --- libtool/configure support
"utils" --- miscellaneous
"setup-go.rkt" --- helper script used by parts of the build that need
to run substantial Racket programs

537
racket/src/README.txt Normal file
View File

@ -0,0 +1,537 @@
This is the source code distribution for minimal Racket.
If this directory is part of a clone of the Git repository for Racket,
then the clone's root directory includes a makefile to both build
minimal Racket and install packages. See "INSTALL.txt" in the clone's
root directory.
========================================================================
License and external links
========================================================================
Racket is distributed under the GNU Lesser General Public License
(LGPL). See the file "COPYING_LESSER.txt" for more information.
Compiled executables, documentation, and up-to-date information:
http://racket-lang.org/
Pre-compiled daily snapshots:
http://pre.racket-lang.org/
Main development repository:
https://github.com/racket/racket
Report bugs:
https://github.com/racket/racket/issues
========================================================================
Traditional Racket versus Racket-on-Chez
========================================================================
This source directory contains implementations for two different
versions of Racket: the traditional implementation that is
substantially implemented in C, and an implementation that builds on
Chez Scheme.
Traditional Racket
------------------
By default, `configure` and the Windows scripts build the traditional
implementation of Racket.
If you need more information specific to the traditional
implementation of Racket, see "racket/README.txt".
Racket on Chez Scheme
---------------------
To build Racket-on-Chez on Unix variants or Mac OS:
* ... in addition to the traditional variant of Racket: supply
`--enable-cs` or `--enable-csdefault` to `configure`.
The generated Racket-on-Chez executables will have a "cs" suffix.
* ... by itself: supply `--enable-csonly` to `configure`.
The generated Racket-on-Chez executables will *not* have a "cs"
suffix.
Chez Scheme is not included with Racket sources, but building
Racket-on-Chez requires either a "ChezScheme" build checkout within
the build directory or at at an alternate location specified by the
`--enable-scheme=...` argument to `configure`.
For now, use the fork of Chez Scheme at
https://github.com/mflatt/ChezScheme
We hope to eventually return to the current development version from
https://github.com/cisco/ChezScheme
To build Racket-on-Chez on Windows, see See "worksp\README.txt" for
information.
If you need more information specific to Racket-on-Chez, see
"cs/README.txt".
========================================================================
Compiling for supported Unix variants (including Linux)
========================================================================
Quick instructions:
From this directory (where the `configure` file is), run the following
commands:
mkdir build
cd build
../configure
make
make install
Those commands will create an in-place installation of Racket and
store the results of C compilation in a separate "build"
subdirectory, which is useful if you need to update your sources,
delete the build, and start from scratch.
You can also run the typical `./configure && make && make install` if
you don't anticipate updating/rebuilding, but it will be harder to
restart from scratch should you need to.
Some build modes may require GNU `make`. For example, when building
the traditional Racket implementation, the content of the "foreign"
subdirectory requires GNU `make` if no installed "libffi" is
detected. If the build fails with another variant of `make`, please
try using GNU `make`.
Detailed instructions:
0. If you have an old Racket installation in the target directory,
remove it (unless you are using an "in-place" build from a
repository as described below).
On Unix variants other than Mac OS, to run `racket/draw` and
`racket/gui` programs, you will not only need the packages that
supply those libraries, you'll need Cairo, Pango, and GTk
installed. These libraries are not distributed with Racket, and
they are not needed for compilation, except for building
documentation that uses `racket/draw`. More info about required
libs is available at http://docs.racket-lang.org/draw/libs.html
and http://docs.racket-lang.org/gui/libs.html.
1. Select (or create) a build directory.
It's better to run the build in a directory other than the one
containing `configure`, especially if you're getting sources via
git. A common way to start a git-based build is:
cd [here]
mkdir build
cd build
where "[here]" is the directory containing this "README.txt" file
and the `configure` script. The Git repository is configured to
support this convention by ignoring `build` in this directory.
A separate build directory is better in case the makefile
organization changes, or in case the makefiles lack some
dependencies. In those cases, when using a "build" subdirectory,
you can just delete and re-create "build" without mangling your
source tree.
2. From your build directory, run the script `configure` (which is in
the same directory as this README), with optional command-line
arguments `--prefix=TARGETDIR` or `--enable-shared` (or both).
For example, if you want to install into "/usr/local/racket" using
dynamic libraries, then run:
[here]configure --prefix=/usr/local/racket --enable-shared
Again, "[here]" is the directory path containing the `configure`
script. If you follow the convention of running from a "build"
subdirectory, "[here]" is just "../". If you build from the
current directory, "[here]" is possibly unnecessary, or possibly
just "./", depending on your shell and PATH setting.
If the `--prefix` flag is omitted, the executables are built for
an in-place installation (i.e., the parent of the directory
containing this README will be used directly). Unless
`--enable-shared` is used, the "racket" directory can be moved
later; most system administrators would recommend that you use
`--enable-shared`, but the Racket developers distribute
executables built without `--enable-shared`.
The `configure` script generates the makefiles for building Racket
and/or GRacket. The current directory at the time `configure` is
run will be used as working space for building the executables
(independent of `--prefix`). This build directory does not have to
be in the source tree, even for an in-place build. It's ok to run
`configure` from its own directory (as in the first example
above), but it's better to pick a separate build directory that is
otherwise empty (as in the second example).
The `configure` script accepts many other flags that adjust the
build process. Run `configure --help` for more information. In
addition, a specific compiler can be selected through environment
variables. For example, to select the SGI compilers for Irix
instead of gcc, run configure as
env CC=cc CXX=CC [here]configure
To add an include path, be sure to use CPPFLAGS="-I..." instead of
CFLAGS="-I...". The CPPFLAGS variable controls C pre-processing,
which includes C compilation, and the Racket build normally uses
the C pre-processor directly for some parts of the build.
If you re-run `configure` after running `make`, then products of
the `make` may be incorrect due to changes in the compiler command
line. To be safe, run `make clean' each time after running
`configure`. To be even safer, run `configure` in a fresh build
directory every time.
When building for multiple platforms or configurations out of the
same source directory, beware of cached `configure` information in
"config.cache". Avoid this problem entirely by using a separate
build directory (but the same source) for each platform or
configuration.
3. Run `make`. [As noted above, this might need to be GNU `make`.]
Executables and libraries are placed in subdirectories of the
build directory. For example, the `racket3m` executable appears in
the "racket" directory.
You can run executables in-place before `make install`, but if you
haven't yet built ".zo" bytecode files from Racket sources in
"../collects", startup will be very slow.
4. Run `make install`.
This step copies executables and libraries into place within the
target installation. For example, the "racket" executable is
copied into the "bin" directory for an in-place build, or into the
executable directory for a `--prefix` build.
For a `--prefix` build, this step also creates a "config.rktd"
module in an "etc" directory, so that various Racket tools and
libraries can find the installation directories. At this stage, in
case you are packaging an installation instead of installing
directly, you can redirect the installation by setting the
"DESTDIR" environment variable to an absolute path for the
packaging area. For example, `make DESTDIR=/tmp/racket-build
install` places the installation into "/tmp/racket-build" instead
of the location originally specified with `--prefix`. The
resulting installation will not work, however, until it is moved
to the location originally specified with `--prefix`.
Finally, the `make install` step compiles ".zo" bytecode files for
installed Racket source, generates launcher programs like DrRacket
(if it's already installed as a package), and builds documentation
(again, if installed). Use `make plain-install` to install without
compiling ".zo" files, creating launchers, or building
documentation.
If the installation fails because the target directory cannot be
created, or because the target directory is not the one you want,
then you can try repeating step 4 after running `configure` again
with a new `--prefix` value. That is, sometimes it is not necessary
to repeat step 3 (so try it and find out). On other platforms and
configurations, it is necessary to start with a clean build
directory when changing the `--prefix` value, because the path gets
wired into shared objects.
If you build frequently from the Git-based sources, beware that you
may accumulate user- and version-specific information in your
"add-ons" directory, which you can most easily find by evaluating
(find-system-path 'addon-dir)
in Racket. In addition, if you configure with `--enabled-shared`,
you may accumulate many unused versions of the dynamic libraries in
your installation target.
After an "in-place" install from a source distribution, the
"racket/src" directory is no longer needed, and it can be safely
deleted. Build information is recorded in a "buildinfo" file in the
installation.
For a build without `--prefix` (or with `--enable-origtree`) and
without `--enable-shared`, you can safely move the install tree,
because all file references within the installation are relative.
========================================================================
Compiling for Mac OS
========================================================================
First, install Xcode and command-line tools from Apple.
After installing developer tools, follow the Unix instructions above,
but note the following:
* The Racket build creates a framework, "Racket.framework", which is
installed into "racket/lib". This framework is used by the `racket`
executable that goes into "racket/bin".
* The GRacket build creates a GUI-executable variant of the Racket
executable. The GRacket build process also downloads (from github)
pre-built libraries for Cairo, Pango, etc.
* The `--enable-shared` flag for `configure` must not be used,
because builds create and use frameworks by default. Furthermore,
`--disable-shared` is not supported. (Unless you use
`--enable-xonx`...)
* To build an X11- and Gtk-based GRacket, run `configure` with the
`--enable-xonx` flag. Frameworks are not used for such builds, so
`--enable-shared` is allowed. The `--enable-xonx` flag also affects
the Racket build, so that `system-type` reports 'unix. Pre-built
libraries are not downloaded in this mode; you must have Cairo,
Pango, and GTk installed.
* To use `--prefix` without `--enable-xonx`, you must also supply
`--enable-macprefix`. BEWARE! The directory structure for a
non-xonx build does not fit a typical Unix directory structure. For
example, frameworks are written directly to a "lib" subdirectory,
and executables like "GRacket.app" are written directly to the
prefix directory. (Requiring `--enable-macprefix` with `--prefix`
for a non-xonx build helps prevent accidental installation of a
Mac-style directory structure on top of an existing Unix-style
directory structure.)
* On Mac OS 10.6 and later, to build Racket in 32-bit mode, use
`--disable-mac64`.
========================================================================
Compiling for Windows
========================================================================
To compile with Microsoft Visual C, see the instructions in
"racket\src\worksp\README.txt".
To compile with MinGW tools, follow the Unix instructions above; do
not use `--enable-shared`, because DLLs will be generated
automatically. The result is a Windows-style build. If you are using a
variant of MinGW without "libdelayimp.a", get the implementation of
"delayimp.c" from MinGW-w64 and compile it to "libdelayimp.a".
========================================================================
Cross-compiling
========================================================================
[Currently, cross-compilation works only for the traditional Racket
implementation.]
Cross-compilation requires at least two flags to `configure`:
* `--host=OS`, where OS is something like `i386-gnu-linux` to
indicate the target platform.
The `configure` script uses OS to find suitable compilation tools,
such as `OS-gcc` and `OS-strip`.
* `--enable-racket=RACKET`, where RACKET is a path to a Racket
executable that runs on the build platform; the executable must be
the same version of Racket as being built for the target platform.
This flag is needed because building and installing Racket requires
running (an existing build of) Racket.
Use "auto" for RACKET to indicate that Racket should be built
automatically for the current platform. In that case, `make` will
run `configure` again (with no arguments) in a "local" subdirectory
to create a build for the current platform.
Some less commonly needed `configure` flags:
* `--enable-stackup`, if the target platform`s stack grows up.
* `--enable-bigendian`, if target platform is big-endian.
* `--enable-cify` or `--disable-cify` if the JIT availablity on the
target platform is different than the build platform; use
`--enable-cify` if the JIT is not abailable on the target
platform.
========================================================================
Cross-compiling for Android
========================================================================
[Currently, cross-compilation works only for the traditional Racket
implementation.]
As an example of cross-compiling, to compile for Android on ARM using
the NDK, use (all on one line)
configure --host=arm-linux-androideabi
--enable-sysroot="[ndk]/platforms/android-[N]/arch-arm"
--enable-racket=auto
where [ndk] is the path to the installed NDK, [N] is a target version
of Android (such as 14), and
[ndk]/toolchains/arm-linux-androideabi-[comp]/prebuilt/[platform]/bin
is in your PATH (so that a suitable `gcc`, `ar`, etc., are found) for
the [comp] of your choice and the [platform] used to compile.
========================================================================
Cross-compiling for iOS
========================================================================
[Currently, cross-compilation works only for the traditional Racket
implementation.]
To compile the Racket runtime system as a Framework for iOS, use (all
on one line)
configure --host=[arch]-apple-darwin
--enable-ios="[sdk]"
--enable-racket=racket
where [arch] is one of
- armv7, armv7s, or aarch64: to run on iOS
- i386 or x86_64: to run on the simulator
The [sdk] argument is a path to an iOS SDK, but if it is "iPhoneOS" or
"iPhoneSimulator", then the corresponding SDK is located in the
standard place within the XCode application. For example, "iPhoneOS"
becomes the path (all on one line)
/Applications/Xcode.app/Contents/Developer/Platforms/
iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk
========================================================================
Test Suite
========================================================================
Tests for the core Racket implementation are in a "racket-test-core"
package. The tests are developed in the same Git repository as the
core Racket implementation in a "pkgs" directory at the repository
root.
========================================================================
Implementation Organization
========================================================================
Everything in this "src" directory contributes to the implementation
of the `racket` executable (and variants), while "../collects"
contains the additional Racket libraries that are included in a
minimal Racket distribution.
Sources for the traditional Racket implementation
-------------------------------------------------
* "racket" --- traditional `racket` executable
This implementation can build from "scratch" with a C compiler, but
first by building a CGC variant of Racket to transform the C
sourses to build a (normal) 3m variant.
* "gracket" --- traditional `gracket` executable
* "foreign" --- FFI implementation for "racket"
This directory includes a copy of "libffi" (as needed for some
platforms).
* "mzcom" --- MzCOM executable (for Windows)
* "mysink" --- `ffi/unsafe/com` helper DLL (for Windows)
See also the shared sources below, which includes rktio and the macro
expander.
Sources for the Racket-on-Chez implementation
---------------------------------------------
* "cs" --- Racket-on-Chez `racket` executable
Building requires both an existing Racket (possibly created from
the "racket" sources) and an existing Chez Scheme build.
* "thread" --- thread scheduler
* "io" --- I/O
This layer uses the "racketio" library to access OS facilties.
* "regexp" --- regexp matcher
See also the shared sources below, which includes rktio, the macro
expander, and schemify.
Sources shared by both Racket implementations
---------------------------------------------
* "expander" --- macro expander implementation
This expander is both included in Racket executables and used to
expand itself for inclusion in executables. It's also used to
expand other libraries for inclusion in Racket-on-Chez executables.
If you change the expander, run `make` in its directory to generate
the "startup.inc" file that holds the expander's implementation for
the traditional Racket variant. The Racket-on-Chez build (which
needs an existing Racket to build, anyway) picks up changes to
"expander" automatically.
* "rktio" --- portability layer for low-level I/O
If you change "rktio.h", then be sure to regenerate "rktio.rktl"
and "rktio.inc" using an existing Racket implementation that has
the "parser-tools" package installed.
* "schemify" --- a Racket-to-Scheme compiler, used by "cs" and "cify"
Similar to "expander", this layer is applied to itself and
other libraries for inclusion in "cs".
* "cify" --- a Racket-to-C compiler
This compiler is used only when embedding the expander as C code,
instead of Racket bytecode, which is the default for platforms
where the traditional Racket JIT is not supported.
* "start" --- main-executable wrapper
Startup wrappers used by both the tradition and Racket-on-CS
implementations.
* "worksp" --- Windows projects and build scripts
* "mac" --- scripts for generating Mac OS ".app"s
* "setup-go.rkt" --- helper script
The "setup-go.rkt" script is a bootstrapping too that is used by
parts of the build that need to run Racket programs in the process
of building Racket.
More shared utilities
---------------------
* "native-libs" --- build scripts for some native-library packages
These script are not used when building Racket, but they are used
to build some separately distributed packages.
* "common" --- Racket libraries used by "thread", "io", etc.
* "ac" --- `autoconf` helpers
* "lt" --- `libtool` and `configure` support
* "utils" --- miscellaneous

278
racket/src/cs/README.txt
View File

@ -1,49 +1,179 @@
If you just want to build the variant of Racket that runs on Chez The implementation of Racket on Chez Scheme in this directory is
Scheme, then you probably meant to read "./c/README.txt" instead of organized into two layers:
this file.
If you're working on the implementation of Racket-on-Chez, then it's * The immediate directory contains Scheme sources to implement Racket
more convenient to work in this directory, so keep reading here. functionality on top of Chez Scheme. It references sibling
directories like "expander" and "io", which contain Racket code
that is compiled to Chez Scheme to implement Racket.
* The "c" subdirectory contains C sources and build scripts to create
wrapper executables that combine Chez Scheme with the Racket
functionality implemented in this immediate directory.
Requirements ========================================================================
------------ Requirements
========================================================================
* Chez Scheme --- for now, use a fork at Building Racket-on-Chez requires both an existing Racket build and
Chez Scheme build.
https://github.com/mflatt/ChezScheme The existing Racket must be "new enough" to build the current
Racket-on-Chez version. In the worst case, it must be exactly the same
version (using the traditional Racket implementation) as the one
you're trying to build.
but we will eventually return to the current development version When you use `configure --enable-cs` or similar as described in
from "../README.txt", then a bootstrapping variant of Racket is built
automatically. You can select a different Racket excutable by
supplying `--enable-racket=...` to `configure`.
https://github.com/cisco/ChezScheme The Chez Scheme build must also be sufficiently new. See
"../README.txt" for information on obtaining Chez Scheme.
If this build of Chez Scheme is not installed so that plain
`scheme` on the command line runs your installation, you can use
`make SCHEME=...` to set the command for `scheme`.
* Racket --- a recent version ========================================================================
Development versus Build
========================================================================
By default, `make` will use the enclosing Racket build. Go back to The Racket-on-Chez implementation can be built and run in two
the root of this repository/distribution and build so that at least different ways: development mode for running directly using a Chez
the "compiler-lib" package is installed, either with just `make` Scheme installation, and build mode for creating a `racket` or
(for a full build) or with `racketcs` executable that combines Chez Scheme and Racket
functionality into a single executable.
Development Mode
----------------
The makefile in this directory is set up for modifying the
implementation of Racket functionality and testing it out on a Chez
Scheme installation.
For this development mode, either Chez Scheme needs to be installed as
`scheme`, or you must use `make SCHEME=...` to set the command for
`scheme`.
Development mode also needs a Racket installation with at least the
"compiler-lib" package installed. By default, the makefile looks for
Racket installed as "../../bin/racket"; if this directory is in a
clone of the Git repository for Racket, you can get "../../bin/racket"
with
make PKGS="compiler-lib" make PKGS="compiler-lib"
Note that if you build as described in "./c/README.txt", then you in the clone's root directory. Alternatively, use use `make
don't need the "compiler-lib" package. RACKET=...` to set the command for `racket`.
If you'd like to use an existing installation of Racket, instead, The use of development mode is described in more detail further below.
you can use `make RACKET=...` to set the command for `racket`.
Development mode currently doesn't work on Windows, because the
makefile makes too many Unix-ish assuptions.
Build Mode
----------
To build a Racket-on-Chez executable, the `configure` script and
makefile in "c" subdirectory are normally used via `configure` and
`make` in the parent directory of this one, as described in
"../README.txt". However, you can use them directly with something
like
cd [build]
mkdir cs
cd cs
[here]/c/configure
make
make install
where [here] is the directory containing this "README.txt" and [build]
is a build directory (usually "../build" relative to [here]).
The `configure` script accepts flags like `--enable-racket=...` and
`--enable-scheme=...` to select an existing Racket and a Chez Scheme
build directory to use for building Racket-on-Chez:
* By default, the build uses Racket as "[build]/racket/racket3m" and
bootstraps bytecode from "[here]/../../collects".
If you supply `--enable-racket=...` to specify a Racket executable,
then it must be part of a (minimal) installation.
* By default, the build looks for a Chez Scheme build directory as
"build/ChezScheme".
Building Racket-on-Chez requires a Chez Scheme build directory, not
just a Chez Scheme installation that is accessible as `scheme`.
The resulting Racket-on-Chez executable has the suffix "cs". To
generate an executable without the "cs" suffix, supply
`--enable-csdefault` to `configure`. The precense or absence of "cs"
affects the location of ".zo" files.
Compilation on Windows does not use the `configure` script in "c".
Instead, from the directory "[here]\..\worksp", run "csbuild.rkt"
using an installed (minimal) Racket --- perhaps one created by running
"[here]\..\build.bat". The "csbuild.rkt" script puts intermediate
files in "[here]\..\build", including a Chez Scheme checkout if it's
not already present (in which case `git` must be available).
========================================================================
Machine Code versus JIT
========================================================================
Racket-on-Chez currently supports two compilation modes:
* Machine-code mode --- The compiled form of a module is machine code
generated by compiling either whole linklets (for small enough
linklets) or functions within linklets (with a "bytecode"
interpreter around the compiled parts).
Select this mode by seting the `PLT_CS_MACH` environment variable,
but it's currently the default.
In development mode or when the "cs" suffix is used for build mode,
compiled ".zo" files in this mode are written to a subdirectory of
"compiled" using the Chez Scheme platform name (e.g., "a6osx").
Set `PLT_CS_COMPILE_LIMIT` to set the maximum size of forms to
compile before falling back to interpreted "bytecode". The default
is 10000.
* JIT mode --- The compiled form of a module is an S-expression where
individual `lambda`s are compiled on demand.
Select this mode by seting the `PLT_CS_JIT` environment variable.
In development mode or when the "cs" suffix is used for build mode,
compiled ".zo" files in this mode are written to a "cs"
subdirectory of "compiled".
S-expressions fragments are hashed at compilation time, so that the
hash for each fragment is stored in the ".zo" file. At JIT time,
the hash is used to consult and/or update a cache (implemented as
an SQLite database) of machine-code forms. Set the `PLT_JIT_CACHE`
environment variable to change the cache file, or set the
environment variable to empty to disable the cache.
In development mode or when the "cs" suffix is used for build mode,
set the `PLT_ZO_PATH` environment variable to override the path used
for ".zo" files. For example, you may want to preserve a normal build
while also building in machine-code mode with `PLT_CS_DEBUG` set, in
which case setting `PLT_ZO_PATH` to something like "a6osx-debug" could
be a good idea.
========================================================================
Development Mode
========================================================================
Development mode is driven by the makefile in this directory.
Building Building
-------- --------
Running `make` will build the Racket-on-Chez implementation, although Running `make` will build the Racket-on-Chez implementation. Use `make
not in stand-alone form. Use `make expander-demo` to run a demo that expander-demo` to run a demo that loads `racket/base` from source.
loads `racket/base` from source.
Use `make setup` (or `make setup-v` for a verbose version) to build Use `make setup` (or `make setup-v` for a verbose version) to build
".zo" files for collection-based libraries. ".zo" files for collection-based libraries.
@ -55,46 +185,6 @@ an `ARGS` variable to make, such as
make setup ARGS="--clean -Dd" # clears ".zo" files make setup ARGS="--clean -Dd" # clears ".zo" files
make setup ARGS="--fail-fast" # stop at the first error make setup ARGS="--fail-fast" # stop at the first error
Machine Code versus JIT
-----------------------
Racket on Chez Scheme currently supports two modes:
* Machine-code mode --- The compiled form of a module is machine code
generated by compiling either whole linklets (for small enough
linklets) or functions within linklets (with a "bytecode"
interpreter around the compiled parts). Compiled ".zo" files in
this format are written to a subdirectory of "compiled" using the
Chez Scheme platform name (e.g., "a6osx").
Select this mode by seting the `PLT_CS_MACH` environment variable,
but it's currently the default.
Set `PLT_CS_COMPILE_LIMIT` to set the maximum size of forms to
compile before falling back to interpreted "bytecode". The default
is 10000.
* JIT mode --- The compiled form of a module is an S-expression where
individual `lambda`s are compiled on demand. Compiled ".zo" files
in this format are written to a "cs" subdirectory of "compiled".
Select this mode by seting the `PLT_CS_JIT` environment variable.
S-expressions fragments are hashed at compilation time, so that
the hash for each fragment is stored in the ".zo" file. At JIT
time, the hash is used to consult and/or update a cache
(implemented as an SQLite database) of machine-code forms. Set the
`PLT_JIT_CACHE` environment variable to change the cache file, or
set the environment variable to empty to disable the cache.
Set the `PLT_ZO_PATH` environment variable to override the path used
for ".zo" files. For example, you may want to preserve a normal build
while also building in machine-code mode with `PLT_CS_DEBUG` set, in
which case setting `PLT_ZO_PATH` to something like "a6osx-debug" could
be a good idea.
Running Running
------- -------
@ -102,28 +192,22 @@ Use `make run ARGS="..."` to run Racket on Chez Scheme analogous to
running plain `racket`, where command-line arguments are supplied in running plain `racket`, where command-line arguments are supplied in
`ARGS`. `ARGS`.
Structure Structure
--------- ---------
The reimplementation on Chez Scheme is meant to export the same The Racket-on-Chez implementation is in layers. The immediate layer
interface as the traditional Racket virtual machine in "../racket": over Chez Scheme is called "Rumble", and it implements delimited
the macro expander and primitive modules such as `#%kernel` and continuations, structures, chaperones and imperaontors, engines (for
`#%network`. threads), and similar base functionality. The Rumble layer is
implemented in Chez Scheme.
The implementation is in layers. The immediate layer over Chez Scheme
is called "Rumble", and it implements delimited continuations,
structures, chaperones and imperaontors, engines (for threads), and
similar base functionality. The Rumble layer is implemeneted in Chez
Scheme.
The rest of the layers are implemented in Racket: The rest of the layers are implemented in Racket:
thread thread
io io
regexp regexp
expander
schemify schemify
expander
Each of those layers is implemented in a sibling directory of this Each of those layers is implemented in a sibling directory of this
one. Each layer is expanded (using "expander", of course) and then one. Each layer is expanded (using "expander", of course) and then
@ -193,7 +277,6 @@ Files in this directory:
"demo/regexp.rkt". For example, you can run "demo/regexp.rkt" "demo/regexp.rkt". For example, you can run "demo/regexp.rkt"
and compare the reported timing to "demo/regexp.ss". and compare the reported timing to "demo/regexp.ss".
From Primitives to Modules From Primitives to Modules
-------------------------- --------------------------
@ -209,14 +292,12 @@ example, "primitive/network.scm" defines the content of the
Racket implementation in "../racket" provides those same primitive Racket implementation in "../racket" provides those same primitive
instances to the macro expander. instances to the macro expander.
Running "demo/expander.ss" Running "demo/expander.ss"
-------------------------- --------------------------
A `make expander-demo` builds and tries the expander on simple A `make expander-demo` builds and tries the expander on simple
examples, including loading `racket/base` from source. examples, including loading `racket/base` from source.
Dumping Linklets and Schemified Linklets Dumping Linklets and Schemified Linklets
---------------------------------------- ----------------------------------------
@ -240,9 +321,8 @@ compiled terms when a linklet is not compliled whole; set
those compiled parts; and/or set `PLT_LINKLET_SHOW_POST_INTERP` to see those compiled parts; and/or set `PLT_LINKLET_SHOW_POST_INTERP` to see
the "bytecode" form. the "bytecode" form.
Safety and Debugging Mode
Development Mode -------------------------
----------------
If you make changes to files in "rumble", you should turn off If you make changes to files in "rumble", you should turn off
`[RUMBLE_]UNSAFE_COMP` in the makefile. `[RUMBLE_]UNSAFE_COMP` in the makefile.
@ -265,10 +345,12 @@ compatibility. Set `compile-as-independent?` to #t in "expander.sls"
to make compiled Racket modules reliably compatible with changes to to make compiled Racket modules reliably compatible with changes to
the layers here (at the expense of some performance). the layers here (at the expense of some performance).
FFI Differences FFI Differences
--------------- ---------------
Compared to the traditional Racket implementation, Racket-on-Chez's
FFI behaves in several different ways:
* The `make-sized-byte-string` function always raises an exception, * The `make-sized-byte-string` function always raises an exception,
because a foreign address cannot be turned into a byte string whose because a foreign address cannot be turned into a byte string whose
content is stored in the foreign address. The options are to copy content is stored in the foreign address. The options are to copy
@ -306,7 +388,6 @@ FFI Differences
cannot be usefully passed to foreign functions, since the layout is cannot be usefully passed to foreign functions, since the layout is
not actually an array of pointers. not actually an array of pointers.
Threads, Threads, Atomicity, Atomicity, and Atomicity Threads, Threads, Atomicity, Atomicity, and Atomicity
----------------------------------------------------- -----------------------------------------------------
@ -386,35 +467,20 @@ Status and Thoughts on Various Racket Subsystems
* The Racket and Chez Scheme numeric systems likely differ in some * The Racket and Chez Scheme numeric systems likely differ in some
ways, and I don't know how much work that will be. ways, and I don't know how much work that will be.
* Places are implemented as Chez Scheme threads. Possibly because a
GC is stop-the-world across all threads, however, this
implementation currently does not scale as much as the traditional
Racket implementation's places.
* For futures, Chez Scheme exposes OS-level threads with limited * For futures, Chez Scheme exposes OS-level threads with limited
safety guarantees. An implementation of futures can probably take safety guarantees. An implementation of futures can probably take
advantage of threads with thread-unsafe primitives wrapped to advantage of threads with thread-unsafe primitives wrapped to
divert to a barrier when called in a future. divert to a barrier when called in a future.
* GC-based memory accounting similarly seems to require new support, * GC-based memory accounting requires new support from Chez Scheme.
but that can wait a while.
* Extflonums will probably exist only on the Racket VM for a long
while.
* For now, `make setup` builds platform-specific ".zo" files in a
subdirectory of "compiled" named by the Chez Scheme platform name
(e.g., "ta6osx"). Longer term, although bytecode as it currently
exists goes away, platform-independent ".zo" files might contain
fully expanded source (possibly also run through Chez Scheme's
source-to-source optimizer) with `raco setup` gaining a new step in
creating platform-specific compiled code.
* Extflonums will probably exist only on the traditional Racket
implementation for a long while.
Performance Notes Performance Notes
----------------- -----------------
The best-case scenario for performance is current the default The best-case scenario for performance is currently the default
configuration: configuration:
* `UNSAFE_COMP` is enabled in "Makefile" --- currently on by default. * `UNSAFE_COMP` is enabled in "Makefile" --- currently on by default.

73
racket/src/cs/c/README.txt
View File

@ -1,73 +1,2 @@
This directory contains a `configure` script and a makefile (template) This directory contains a `configure` script and a makefile (template)
for building the variant of Racket that runs on Chez Scheme. The for generating Racket-on-Chez executables. See "../README.txt".
result of the build is a `racketcs` executable that embeds both Chez
Scheme and the Racket startup code to behave the same as the
traditional `racket` executable.
If you have a checkout of the main Racket repo, you can just use `make
cs` in the top-level directory of the repo to build Racket-on-Chez.
See "INSTALL.txt" in the top-level directory for more information.
If you want to know more about how Racket-on-Chez is put together, see
"../README.txt".
========================================================================
Requirements
========================================================================
Building Racket-on-Chez requires both an existing Racket build and
Chez Scheme build:
* By default, the build uses Racket as built and installed in-place
in the same way as described in "../../README", so that the Racket
executable is "../../../bin/racket".
You can select a different Racket excutable by supplying
`--enable-racket=...` to `configure`.
* By default, the build uses Chez Scheme as built in a "ChezScheme"
sibling directory of the build directory. The Racket-on-Chez build
needs a Chez Scheme build directory, and not an end-user Chez
Scheme installation, because it needs "kernel.o" as created in a
Chez Scheme build; it may also need makefiles or other scripts in
the Chez Scheme build directory.
See "../README.txt" for information on the required Chez Scheme
version.
You can select a different Chez Scheme build path by supplying
`--enable-scheme=...` to `configure`.
========================================================================
Compiling for supported Unix variants (including Linux and Mac OS)
========================================================================
From two directories up, run the following commands:
mkdir build
cd build
../cs/c/configure
make
make install
Those commands will create an in-place installation of Racket and
store the results of various compilation steps in a separate "build"
subdirectory, which is useful if you need to update your sources,
delete the build, and start from scratch.
You can also run the typical `./configure && make && make install` if
you don't anticipate updating/rebuilding, but it will be harder to
restart from scratch should you need to.
========================================================================
Compiling for Windows
========================================================================
Compilation for Windows on Windows requires building the traditional
Racket implementation. Then, from the directory "..\..\worksp", run
..\..\racket csbuild.rkt
Many intermediate files will be put in "../../build", including a Chez
Scheme checkout if it's not already present (in whcih case `git` must
be available).

8
racket/src/native-libs/README.txt
View File

@ -1,4 +1,4 @@
The core `racket` executable has minimal library dependencies. In The core Racket executable has minimal library dependencies. In
contrast, libraries implemented in various packages, such as the contrast, libraries implemented in various packages, such as the
"draw" or "math" packages, rely on additional C-implemented libraries, "draw" or "math" packages, rely on additional C-implemented libraries,
such as Cairo, GMP, etc., all of which are loaded dynamically. On Unix such as Cairo, GMP, etc., all of which are loaded dynamically. On Unix
@ -6,9 +6,9 @@ variants, we expect users to install C-implemented libraries (usually
through the operating system's package manager). For Windows and Mac through the operating system's package manager). For Windows and Mac
OS, we supply pre-built libraries in platform-specific packages; the OS, we supply pre-built libraries in platform-specific packages; the
corresponding Racket packages include platform-specific dependencies corresponding Racket packages include platform-specific dependencies
on those packages. The "x86_64-linux-natipkg" variant of Racket on those packages. The "x86_64-linux-natipkg" variant of Racket is
is like Windows and Mac OS, expecting packages to supply native like Windows and Mac OS, expecting packages to supply native libraries
libraries for 64-bit Linux. for 64-bit Linux.
This directory contains scripts and patches to build Windows, Mac OS, This directory contains scripts and patches to build Windows, Mac OS,
and Linux libraries in a consistent and portable way. Naturally, the and Linux libraries in a consistent and portable way. Naturally, the

28
racket/src/racket/README
View File

@ -1,28 +0,0 @@
This is the Racket source code directory. See ../README for general
information on compiling it.
Compiled binaries, documentation, and up-to-date information about
Racket are at:
http://racket-lang.org/
----------------------------------------------------------------------
Some general guidelines for modying this code:
* Use `scheme_...` for a definition that is globally visible. In
particular, any non-`static` function name should start with
`scheme_`.
* If a globally visible function is meant for exporting to embedding
applications, extensions, or through the FFI, put the prototype in
"src/schemef.h" (and re-generate files with `make exports`).
Functions available only to embedding applications can go in
"scheme.h". Otherwise, put global function prototypes in
"schpriv.h".
* Don't use "//" comments, because we still use pre-C99 compilers
that don't support them.
* Declare all variables at the beginning of a block (again, for
pre-C99 compilers).

122
racket/src/racket/README.txt Normal file
View File

@ -0,0 +1,122 @@
This directory contains most of the source code to the traditional
implementation of Racket. See "../README.txt" for general information
on building.
========================================================================
CGC versus 3m
========================================================================
Traditional Racket and GRacket have two variants: CGC and 3m. The CGC
variant is older, and it cooperates more easily with extensions
written in C. The 3m variant is the default: it is more robust and
usually provides better overall performance.
The default build mode creates 3m executables only (except for a CGC
executable that is used to build the 3m executable). To create CGC
executables in addition to 3m executables, use `make cgc` in addition
to `make`, or run `make both`. To install both variants, use `make
install-both` instead of just `make install`. Alternatively, use just
`make cgc` and `make install-cgc` to build and install just the CGC
variants.
CGC variants are installed with a "cgc" suffix. To swap the default
build and install mode, supply `--enable-cgcdefault` to `configure`. In
that case, CGC variants are built by default, `make 3m` creates 3m
executables, and `make install-both` installs CGC variants without a suffix
and 3m variants with a "3m" suffix.
========================================================================
Additional Compilation Notes
========================================================================
CGC Build Options
-----------------
As noted above in "CGC versus 3m", Racket builds a CGC variant in the
process of creating the normal 3m variant. Within the CGC variant, two
implementations are possible.
By default, Racket CGC is implemented with SenoraGC (in the "sgc"
directory), which is relativey portable. Provide `--disable-sgc` to
instead use the Boehm GC (in the "gc" directory), which should perform
better and was the default for Racket CGC through version 6.1.
The variant of the Boehm GC that is included with Racket has been
modified slightly from Boehm's standard distribution; mostly, the
changes modify the way that object finalization is handled.
Floating point, x87, SSE, Extflonums, and the JIT
-------------------------------------------------
Pre-processor tests in "sconfig.h" and "scheme.h" attempt to determine
when the x87 floating-point processor needs to be configured for
double-precision mode, when JIT can use SSE2 instructions, and when
extflonums can be supported because both the JIT and C code use SSE2
for double-precision floating-point while `long double` is available
for extflonums.
In particular, "scheme.h" looks for __SSE2_MATH__ to indicate that gcc
is compiling floating-point operations as SSE2, so be sure to include
flags like "-mfpmath=sse" or "-mfpmath=387" in CPPFLAGS, and not just
CFLAGS. See related configuration options below.
The Windows build using MSVC enables extflonum support through a
MinGW-compiled "longdouble.dll", since MSVC does not support `long
double` as extended-precision floating point.
Configuration Options
---------------------
Although `configure` flags control most options, some configurations
options can be modified by setting flags in "racket/sconfig.h".
Some CPP flags control default settings in "racket/sconfig.h":
* MZ_{USE_,NO_}JIT_SSE - {en,dis}ables use of SSE2 floating point
* MZ_USE_DETERMINSTIC_FUEL - disables use of itimer or pthread for
Racket thread scheduling.
* C_COMPILER_USES_SSE - declares that the C compiler is using SSE2
instructions to implement `double` floating-point operations.
========================================================================
Porting to New Platforms
========================================================================
At a minimum, to port Racket to a new platform, edit "racket/sconfig.h"
and "rktio/rktio_platform.h" to provide a platform-specific compilation
information.
========================================================================
Modifying Racket
========================================================================
If you modify Racket and change any primitive syntax or the collection
of built-in identifiers, be sure to update the version number in
"racket/src/schvers.h", so that various tools know to rebuild
bytecode. If you add or remove primitives, you'll also need to adjust
the counter in "racket/src/schminc.h" .
Some general guidelines for modying this code:
* Use `scheme_...` for a definition that is globally visible. In
particular, any non-`static` function name should start with
`scheme_`.
* If a globally visible function is meant for exporting to embedding
applications, extensions, or through the FFI, put the prototype in
"src/schemef.h" (and re-generate files with `make exports`).
Functions available only to embedding applications can go in
"scheme.h". Otherwise, put global function prototypes in
"schpriv.h".
* Don't use "//" comments, because we still use pre-C99 compilers
that don't support them.
* Declare all variables at the beginning of a block (again, for
pre-C99 compilers).

35
racket/src/start/README.txt
View File

@ -2,3 +2,38 @@ This directory constaint source programs and fragments for wrapper
executables used to start/embed Racket. The programs and fragments are executables used to start/embed Racket. The programs and fragments are
used both for the traditional Racket virtual machine and Racket on used both for the traditional Racket virtual machine and Racket on
Chez Scheme. Chez Scheme.
========================================================================
Embedded Paths in the Executables
========================================================================
On all platforms, the Racket and GRacket executables embed a path to
the main "collects" directory of library collections. This path can be
relative to the executable. Multiple paths can be provided, in which
case the first path is the main "collects" path, and additional paths
are placed before the main path (but after a user-specific "collects"
path) in the default collection path list.
The paths are embedded in the executable immediately after a special
"coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the
entire list of paths must end with an additional NUL terminator, and
the overall list must be less than 1024 bytes long.
As an alternative to editing an executable directly, the
`create-embedding-executable` procedure from `compiler/embed` can be
used to change the embedded path. For example, the following program
clones the Racket executable to "/tmp/mz" and changes the embedded
path in the clone to "/tmp/collects":
(require compiler/embed)
(create-embedding-executable "/tmp/mz" #:collects-path "/tmp/collects")
Similarly, `raco exe` mode accepts a `--collects` flag to set the
collection path in the generated executable.
Under Windows, executables also embed a path to DLLs. For more
information, see "..\worksp\README.txt".
Paths to all other installation directories are found through the
"config.rkt" library of the "config" collection. Search the
documentation for "config search paths" for more information.

291
racket/src/worksp/README
View File

@ -1,291 +0,0 @@
This directory contains
- solution files and project files for building minimal Racket and
related executables with Microsoft Visual Studio 2008
(a.k.a. version 9.0) and up, including the Express versions of
Visual Studio;
- mzconfig.h which is a manual version of information that is gathered
automatically when using the "configure" script;
- scripts for building 3m variants of Racket and GRacket using Visual
Studio command-line tools;
- solution files and project files for building "myssink.dll" with
Microsoft Visual Studio 2008 (not Express), although the DLL is
normally downloaded along with other pre-built DLLs.
Visual Studio Express is available for free from Microsoft.
Racket and GRacket also compile with MinGW. To compile with MinGW,
follow the instructions in racket\src\README (which contains a short
Windows-specific section).
Finally, Racket and GRacket also compile with Cygwin gcc (a free
compiler from GNU and Cygnus Solutions), but the result is a
Unix-style installation, not a Window-style installation. To compile
with gcc, follow the instructions in racket\src\README (which contains
a short Windows-specific section).
With an MSVC-built Racket, compatible extensions can be built with other
compilers. Build with Cygwin and copy the installed racket\lib\gcc to a
MSVC-based build to support Cygwin-built extensions.
As always, please report bugs via one of the following:
- DrRacket's "submit bug report" menu (preferred)
- http://bugs.racket-lang.org/
- the mailing list (users@racket-lang.org) (last resort)
-PLT
racket@racket-lang.org
---------------------------
Building Racket and GRacket
---------------------------
If you're using Visual Studio, and if `cl.exe' and `msbuild.exe'
is in your path, then you can just run
racket\src\worksp\build.bat
from its own directory to perform all steps up to "Versioning",
including the MzCOM steps.
If `cl.exe' and `msbuild.exe' are not already in your path --- along
with many associated environment variables --- then you can run
"msvcprep.bat" to configure your environment, assuming that Visual
Studio is in one of its usual locations. The "msvcprep.bat" script
simply tries to find Visual Studio and run its "vcvarsall.bat". You
may need to provide an argument such as "x86" or "x86_amd64" to select
the build mode.
If your MSVC environment is configured for 64-bit builds (e.g., by
running "msvcprep.bat" or Microsoft's "vcvarsall.bat", with
"x86_amd64" or "amd64"), then a 64-bit build is created.
The CGC variants of Racket, GRacket, and MzCOM can be built via
Visual Studio projects. The 3m variants are built by a Racket script
that runs the MSVC command-line tools. (See "CGC versus 3m" in
racket\src\README if you don't know about the two variants.)
If you can't run "build.bat" or don't want to, you have to perform
several steps: first build RacketCGC, then build Racket3m, etc.
Building RacketCGC and GRacketCGC
---------------------------------
The CGC source code for RacketCGC and GRacketCGC is split into several
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,
but add `9' before ".sln" if you're using Visual Studio 2008 (i.e.,
version 9.0). The solution files without a number are for Visual
Studio 2010, but they should upgrade immediately for later versions.
[The .vcproj files are used by the ...9.sln solutions, while the
.vcxproj files are used by the other .sln solutions. The latter are
compatible with Visual Studio 2010. For Visual Studio versions later
than 2010, "build.bat" script auto-upgrades projects in a copy whose
file name ends with a literal "X" to match the current tool version,
but you can also just upgrade them within your version of Visual
Studio.]
To build RacketCGC, build the Racket solution in
racket\src\worksp\racket - makes racket\RacketCGC.exe
[When you open the solution, switch to a "Release" configuration
before building.]
To build GRacketCGC, build the GRacket solution:
racket\src\worksp\gracket - makes racket\GRacketCGC.exe
[Again, switch to a "Release" configuration if necessary.]
The build processes for RacketCGC and GRacketCGC automatically builds
libmzgc - makes racket\lib\libmzgcxxxxxxx.dll and
racket\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
libracket - makes racket\lib\libracketxxxxxxx.dll and
racket\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib
In addition, building RacketCGC executes
racket\src\racket\dynsrc\mkmzdyn.bat
which copies .exp, .obj, and .lib files into racket\lib\.
Downloading Pre-Built Binaries
-------------------------------
You must install some pre-built DLLs if you want text-encoding
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
https://github.com/racket/libs
and they must be installed into
racket\lib
Pre-built libraries use "msvcrt.dll", as opposed to the run-time
library for a particular version of MSVC. For more information on that
choice, in case you want to compile you own via MSVC, see
http://kobyk.wordpress.com/2007/07/20/
dynamically-linking-with-msvcrtdll-using-visual-c-2005/
See also "..\native-lib\README.txt".
Building Racket3m and GRacket3m
-------------------------------
After RacketCGC and GRacketCGC are built, you can can build 3m binaries:
1. Ensure that the Visual Studio command-line tools are in your
path. You may need to run "msvcprep.bat" here or "vcvarsall.bat"
from your Visual Studio installation, so that PATH and other
environment variables are set.
2. Change directories to racket\src\worksp\gc2 and run
..\..\..\racketcgc.exe -c make.rkt
The resulting Racket.exe and GRacket.exe will appear in the top-level
"racket" directory, along with DLLs libracket3mxxxxxxx.dll in
racket\lib. (There is no corresponding libmzgc3mxxxxxxx.dll. Instead,
it is merged with libracket3mxxxxxxx.dll.)
Building Collections and Other Executables
------------------------------------------
If you're building from scratch, you'll also want the starter programs
used by the launcher collection to create "raco.exe". Build the
following solutions:
racket\src\worksp\mzstart - makes racket\collects\launcher\mzstart.exe
racket\src\worksp\mrstart - makes racket\collects\launcher\mrstart.exe
[The "mzstart" and "mrstart" programs have no CGC versus 3m
distinction.]
Then, set up all the other executables (besides GRacket[CGC].exe and
Racket[CGC].exe) by running
racket.exe -l- setup
This last step makes the .zo files, too. To skip compiling .zos, add
`-n' to the end of the above command.
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.
Versioning
----------
[If you're going to build MzCOM, do that before running the
version-changing script. See instructions below.]
The obnoxious "xxxxxxx" in the DLL names is a placeholder for a version
number. Embedding a version number in a DLL name appears to be the
simplest and surest way to avoid version confusion.
For local testing, you can use the "xxxxxxx" libraries directly. For
any binaries that will be distributed, however, the placeholder should
be replaced with a specific version.
To replace the "xxxxxxx" with a specific version, run
racket -l setup/winvers
in a shell.
The "winvers.rkt" program will have to make a temporary copy of
racket.exe and the "lib" sub-directory (into the temporary directory),
and it will re-launch Racket a couple of times. Every ".exe", ".dll",
".lib", ".def", ".exp", and ".pdb" file within the "racket" tree is
updated to replace "xxxxxxxx" with a specific version number.
--------------
Building MzCOM
--------------
Building MzCOMCGC is similar to building RacketCGC. Building the 3m
variant is a little different.
To build MzCOMCGC, make the MzCOM solution in
racket\src\worksp\mzcom - makes racket\MzCOMCGC.exe
Use the "Release" configuration.
After building MzCOMCGC, you can build the 3m variant by
1. Change directories to racket\src\worksp\mzcom and run
..\..\..\racketcgc.exe -cu xform.rkt
2. Switch to the "3m" configuration in the MzCOM solution (in Visual
Studio).
3. Build (in Visual Studio).
The result is racket\MzCOM.exe.
------------
Finding DLLs
------------
Since the DLL libracket3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and
libracketxxxxxxx.dll) is installed into racket\lib\ instead of just
racket\, the normal search path for DLLs would not find them when
running "Racket.exe" or "GRacket.exe". To find the DLLs, the
executables are "delayload" linked with the DLLs, and the executables
explicitly load the DLLs from racket\lib\ on start-up.
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 the
executable in wide-character format, and it is stored immediately after
the wide-character tag "dLl dIRECTORy:" with a wide NUL terminator. The
path can be either absolute or relative; in the latter case, the
relative path is resolved with respect to the executable. Replacing the
first character of the path with "<" disables the explicit DLL load, so
that the DLLs must appear in the normal DLL search path.
See also ..\README for information on the embedded "collects" path in
the executables.
----------------
Embedding Racket
----------------
The Racket DLLs can be used within an embedding application.
The libraries
racket\lib\win32\msvc\libracket3mxxxxxxx.lib
racket\lib\win32\msvc\libracketxxxxxxx.lib
racket\lib\win32\msvc\libmzgcxxxxxxx.lib
which are created by the libracket and libmzgc projects, provide linking
information for using the libracket3mxxxxxxx.dll, libracketxxxxxxx.dll,
and libmzgcxxxxxxx.dll DLLs. The versioning script adjusts the names,
as described above.
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
statically linking to the C library within the Racket DLL), then compile
Racket with the /MD flag.
----------------------------
SenoraGC versus the Boehm GC
----------------------------
The "Release" and "Debug" solution configurations use SenoraGC (SGC),
while the "AltGCRelease" and "AltGCDebug" configurations use the
variant of the Boehm GC that is included with Racket.
In project files, "SRelease" and "SDebug" (as used by the "Release"
and "Debug" solution configurations) build against SGC, while
"BRelease" and "BDebug" (as used by the "AltGCRelease" and
"AltGCDebug" solution configurations) build against the Boehm GC.

293
racket/src/worksp/README.txt Normal file
View File

@ -0,0 +1,293 @@
This directory contains scripts, solution files, and project files for
building Racket using Visual Studio. Some parts or variants can be
built using projects, but most use Visual Studio command-line tools.
The traditional Racket implementation also compiles with MinGW; see
"...\README.txt".
========================================================================
Building from the Command Line via Visual Studio
========================================================================
If `cl.exe` and `msbuild.exe` are not already in your path --- along
with many associated environment variables --- then you can run
msvcprep.bat
from any directory to configure your environment, assuming that Visual
Studio is in one of its usual locations. The "msvcprep.bat" script
tries to find Visual Studio and run its "vcvarsall.bat". Provide an
argument such as "x86" (32-bit mode) or "x86_amd64" (64-bit mode) to
select the build mode.
After you have Visual Studio command-line tools set up, then you can
build either the traditional Racket implementation or Racket-on-Chez
(or both).
Traditional Racket
------------------
Build the traditional Racket implementation using
build.bat
The result is "..\..\Racket.exe", DLLs and "GRacket.exe" in
"..\..\lib", and other files in "..\..\lib", "..\..\etc", etc.
A "..\..\RacketCGC.exe" executable and associated DLLs are built in
the process of building "..\..\Racket.exe".
See also "Completing the Build" below.
Racket-on-Chez
--------------
Build the Racket-on-Chez implementation using
build-cs.bat
which builds "..\..\RacketCGC.exe" to bootstrap the build.
To instead build using an existing Racket installation, use
racket.exe csbuild.rkt --racketcs-suffix ""
The result is "..\..\Racket.exe", DLLs and "GRacket.exe" in
"..\..\lib", and other files in "..\..\lib", "..\..\etc", etc.
Many intermediate files will be put in "../build", including a Chez
Scheme checkout if it's not already present (in which case `git` must
be available).
See also "Completing the Build" below.
Both Traditional Racket and Racket-on-Chez
------------------------------------------
When using "csbuild.rkt" directly, omit the `--racketcs-suffix ""`
arguments to create "..\..\RacketCS.exe" executable instead of
"..\..\RacketCS.exe". A build with a "CS" suffix is also configured to
read and bytecode in a subdirectory of "compiled" as described in
"..\cs\README.txt".
A "CS" and using a subdirectoryu of "compiled" means that a
Racket-on-Chez build as "RacketCS.exe" can coexist with a
traditional build as "Racket.exe". So, the sequence
build.bat
..\..\Racket.exe csbuild.rkt
builds both.
Completing the Build
--------------------
The "build.bat" and "csbuild.rkt" scripts do not install support DLLs
for encoding conversion, extflonums, and OpenSLL. To install those
libraries, finish with
..\..\raco pkg install racket-lib
See also "..\native-lib\README.txt".
========================================================================
Building via Visual Studio Projects/Solutions
========================================================================
Traditional Racket implementation's CGC variant can be built and
debugged using visual Studio solutions and project. (See
"..\racket\README.txt" for information on traditional Racket
variants.) Further steps using the command line can then build the 3m
variant and related executables.
The CGC implementation is split into several 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, but add `9' before ".sln" if
you're using Visual Studio 2008 (i.e., version 9.0). The solution
files without a number are for Visual Studio 2010, but they should
upgrade automatically for later versions.
[The .vcproj files are used by the ...9.sln solutions, while the
.vcxproj files are used by the other .sln solutions. The latter are
compatible with Visual Studio 2010. For Visual Studio versions later
than 2010, "build.bat" script auto-upgrades projects in a copy whose
file name ends with a literal "X" to match the current tool version,
but you can also just upgrade them within your version of Visual
Studio.]
To build RacketCGC, build the Racket solution in
racket\src\worksp\racket - makes racket\RacketCGC.exe
[When you open the solution, switch to a "Release" configuration
before building.]
To build GRacketCGC, build the GRacket solution:
racket\src\worksp\gracket - makes racket\GRacketCGC.exe
[Again, switch to a "Release" configuration if necessary.]
The build processes for RacketCGC and GRacketCGC automatically builds
libmzgc - makes racket\lib\libmzgcxxxxxxx.dll and
racket\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
libracket - makes racket\lib\libracketxxxxxxx.dll and
racket\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib
In addition, building RacketCGC executes
..\racket\dynsrc\mkmzdyn.bat
which copies ".exp", ".obj", and ".lib" files into "..\..\lib".
Building Racket3m and GRacket3m
-------------------------------
After "RacketCGC.exe" is built, you can can build 3m executables:
1. Ensure that the Visual Studio command-line tools are in your path
as described above in "Building from the Command Line via Visual
Studio".
2. Change directories to "gc2" and run
..\..\..\racketcgc.exe -c make.rkt
The resulting "..\..\Racket.exe" will appear with the DLL
"libracket3mxxxxxxx.dll" in "..\..\\lib". (Unlike the CGC build, there
is no corresponding "libmzgc3mxxxxxxx.dll". Instead, it is merged with
"libracket3mxxxxxxx.dll".)
Building Collections and Other Executables
------------------------------------------
If you're building from scratch, you'll also want the starter programs
used by the launcher collection to create "raco.exe". Build the
following solutions:
racket\src\worksp\mzstart - makes racket\collects\launcher\mzstart.exe
racket\src\worksp\mrstart - makes racket\collects\launcher\mrstart.exe
[The "mzstart" and "mrstart" programs have no CGC versus 3m
distinction.]
Then, set up all the other executables (besides GRacket[CGC].exe and
Racket[CGC].exe) by running
racket.exe -l- setup
Building MzCOM
--------------
Building "MzCOMCGC.exe" is similar to building "RacketCGC.exe".
Building the 3m variant "MzCOM.exe" is a little different.
To build MzCOMCGC, make the MzCOM solution in
racket\src\worksp\mzcom - makes racket\MzCOMCGC.exe
Use the "Release" configuration. The result is
"..\..\lib\MzCOMCGC.exe".
After building MzCOMCGC, you can build the 3m variant by
1. Change directories to "mzcom" and run
..\..\..\racketcgc.exe -c xform.rkt
2. Switch to the "3m" configuration in the MzCOM solution (in Visual
Studio).
3. Build (in Visual Studio).
The result is "..\..\lib\MzCOM.exe".
SenoraGC versus the Boehm GC
----------------------------
The "Release" and "Debug" solution configurations use SenoraGC (SGC),
while the "AltGCRelease" and "AltGCDebug" configurations use the
variant of the Boehm GC that is included with Racket.
In project files, "SRelease" and "SDebug" (as used by the "Release"
and "Debug" solution configurations) build against SGC, while
"BRelease" and "BDebug" (as used by the "AltGCRelease" and
"AltGCDebug" solution configurations) build against the Boehm GC.
========================================================================
Versioning
========================================================================
The "xxxxxxx" in DLL names is a placeholder for a version number.
Embedding a version number in a DLL name appears to be the simplest
and surest way to avoid version confusion.
For local testing, you can use the "xxxxxxx" libraries directly. For
any executables that will be distributed, however, the placeholder
should be replaced with a specific version.
To replace the "xxxxxxx" with a specific version, run
racket -l setup/winvers
The `setup/winvers` module will have to make a temporary copy of
"Racket.exe" and the "lib" sub-directory (into the temporary
directory), and it will re-launch Racket a couple of times. Every
".exe", ".dll", ".lib", ".def", ".exp", and ".pdb" file within the
"racket" tree is updated to replace "xxxxxxxx" with a specific version
number.
========================================================================
Finding DLLs
========================================================================
Since the "libracket3mxxxxxxx.dll" or "libracketcsxxxxxxx.dll" (or
"libmzgcxxxxxxx.dll" and "libracketxxxxxxx.dll") is installed in a
"lib" subdirectory next to the executable, the normal search path for
DLLs would not find them when running "Racket.exe". To find the DLLs,
the executables are "delayload" linked with the DLLs, and the
executables explicitly load the DLLs from "lib" on start-up.
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
the executable in wide-character format, and it is stored immediately
after the wide-character tag "dLl dIRECTORy:" with a wide NUL
terminator. The path can be either absolute or relative; in the latter
case, the relative path is resolved with respect to the executable.
Replacing the first character of the path with "<" disables the
explicit DLL load, so that the DLLs must appear in the normal DLL
search path.
See also "..\start\README.txt" for information on the embedded
"collects" path in executables.
========================================================================
Embedding
========================================================================
The traditional Racket implementation's DLLs can be used within an
embedding application.
The libraries
racket\lib\win32\msvc\libracket3mxxxxxxx.lib
racket\lib\win32\msvc\libracketxxxxxxx.lib
racket\lib\win32\msvc\libmzgcxxxxxxx.lib
provide linking information for using the "libracket3mxxxxxxx.dll",
"libracketxxxxxxx.dll", and "libmzgcxxxxxxx.dll" DLLs. The versioning
script adjusts the names, as described above.
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
statically linking to the C library within the Racket DLL), then
compile Racket with the /MD flag.

10
racket/src/worksp/build-cs.bat Normal file
View File

@ -0,0 +1,10 @@
set BUILD_LEVEL=cgc
call build.bat
..\..\RacketCGC.exe -O "info@compiler/cm" -l- setup --boot ../setup-go.rkt ../build/compiled ^
ignored ../build/ignored.d ^
csbuild.rkt ^
--racketcs-suffix "" --pull ^
-- --depth 1
..\..\Racket.exe -N "raco" -l- setup