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
========================================================================

To build the experimental variant of Racket that runs on Chez Scheme
see "cs/c/README.txt".

The rest of the instructions below are about building the traditional
Racket implementation, but a general "Implementation Organization"
note at the end applies to both variants.

========================================================================
 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

 "lt" --- libtool/configure support

 "utils" --- miscellaneous
 
 "setup-go.rkt" --- helper script used by parts of the build that need
        to run substantial Racket programs
