Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
This is the source code distribution for Racket. For license information, please see the file racket/doc/release-notes/COPYING.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 X, or any Unix/X platform (including Linux). Per-platform instructions are below. Please report bugs via one of the following: - DrRacket's "submit bug report" menu (preferred) - http://bugs.racket-lang.org/ - the mailing list (email@example.com) (last resort) -PLT firstname.lastname@example.org ======================================================================== Compiling for Windows ======================================================================== To compile with Microsoft Visual C, read the instructions in "racket\src\worksp\README". To compile with Cygwin tools, follow the Unix instructions below, and be sure to configure with `--enable-shared'. 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 X ======================================================================== First, install the Mac OS X Developer Tools from Apple. Then, 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 X 10.6 and later, to build Racket in 32-bit mode, use `--disable-mac64'. ======================================================================== Compiling for supported Unix variants (including Linux) or Cygwin ======================================================================== Quick instructions: From this directory (where the `configure' file is), run the following commands: mkdir build cd build ../configure make make install This will create an in-place installation of Racket and store the results of C/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 install. These libraries are not distributed with Racket, and they are not needed for compilation, except for building documentation that uses `racket/draw'. 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 must 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.rkt" module in a "config" collection, 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. 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, and builds documentation. 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 accumlate many unused versions of the dynamic libraries in your installation target. After an "in-place" install without git, 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' * `--enable-racket=RACKET', where RACKET is a path to a Racket executable for the version being compiled that runs on the build (i.e., you must compile on the build machine to cross-compile) The `--enable-racket' flag is needed because building and installing Racket requires running (an intermediate version of) Racket. You may also need to set CC_FOR_BUILD to a compiler for the host platform (for building binaries to execute during the build process). If the target machine's stack grows up, you may have to supply `--enable-stackup'; if the target machine is big-endian, you may have to supply `--enable-bigendian'. ======================================================================== CGC versus 3m ======================================================================== 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. 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 exeuctable 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 mininum, to port Racket to a new platform, edit "racket/sconfig.h" to provide a platform-specific compilation information. As distributed, "racket/sconfig.h" contains configurations for the following platforms: Windows (x86, x86_64) Mac OS X (PPC, x86, x86_64) Linux (x86, x86_64, PPC, 68k) Cygwin (x86) Solaris (x86, Sparc) FreeBSD (x86, x86_64) OpenBSD (x86) NetBSD (x86) If your platfrom is not supported by the Boehm garbage collector (distributed with Racket source), provide the `--enable-sgc' flag to `configure'. ======================================================================== Additional Compilation Notes ======================================================================== Garbage Collector ----------------- The conservative garbage collector distributed with Racket (in the "gc" directory) has been modified slightly from Boehm's standard distribution. Mostly, the change modify the way that object finalization is handled. Configuration Options --------------------- Athough `configure' flags control most options, some configrations options can be modified by setting flags in "racket/sconfig.h". Modifying Racket ---------------- If you modify Racket and change any primitive syntax or the collection of built-in identifiers, be sure to turn off USE_COMPILED_STARTUP in "schminc.h". Otherwise, Racket won't start. See "schminc.h" for details.