From 709258d88c879c2489a977e85d34f77d760a0008 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 15 Nov 2018 22:06:47 -0700 Subject: [PATCH] reorganize and update "README.txt"s about sources and builds Integrate Racket-on-Chez information better and reorganize information to reflect the way that the makefiles and build scripts have evolved. --- INSTALL.txt | 13 +- README.md | 3 - racket/src/README | 579 ------------------------------ racket/src/README.txt | 537 +++++++++++++++++++++++++++ racket/src/cs/README.txt | 278 ++++++++------ racket/src/cs/c/README.txt | 73 +--- racket/src/native-libs/README.txt | 8 +- racket/src/racket/README | 28 -- racket/src/racket/README.txt | 122 +++++++ racket/src/start/README.txt | 35 ++ racket/src/worksp/README | 291 --------------- racket/src/worksp/README.txt | 293 +++++++++++++++ racket/src/worksp/build-cs.bat | 10 + 13 files changed, 1180 insertions(+), 1090 deletions(-) delete mode 100644 racket/src/README create mode 100644 racket/src/README.txt delete mode 100644 racket/src/racket/README create mode 100644 racket/src/racket/README.txt delete mode 100644 racket/src/worksp/README create mode 100644 racket/src/worksp/README.txt create mode 100644 racket/src/worksp/build-cs.bat diff --git a/INSTALL.txt b/INSTALL.txt index be2c7618eb..0f6ec43a66 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -193,11 +193,10 @@ will bootstrap by building a traditional variant of Racket and by downloading and building Chez Scheme. If you have a sufficiently recent Racket installation already with at -least the "compiler-lib" and "parser-tools-libs" packages installed, -you can supply `RACKET=...` with `make cs` to skip that part of the -bootstrap. And if you have a Chez Scheme source directory already[*], -you can supply that with `SCHEME_SRC=...` instead of downloading a new -copy. +least the "compiler-lib" package installed, you can supply +`RACKET=...` with `make cs` to skip that part of the bootstrap. And if +you have a Chez Scheme source directory already[*], you can supply +that with `SCHEME_SRC=...` instead of downloading a new copy. 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" -and follow the "README" there, which gives you more configuration +and follow the "README.txt" there, which gives you more configuration options. 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. 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 top-level makefile to specify the same executable as in an `--enable-racket=...` for `configure`. In general, the `PLAIN_RACKET` diff --git a/README.md b/README.md index c79e0f76c8..58bd044601 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,6 @@ the IRC channel. License ------- -Racket -Copyright (c) 2010-2018 PLT Design Inc. - Racket is distributed under the GNU Lesser General Public License (LGPL). This implies that you may link Racket into proprietary applications, provided you follow the rules stated in the LGPL. You can diff --git a/racket/src/README b/racket/src/README deleted file mode 100644 index 4e03d4cf9b..0000000000 --- a/racket/src/README +++ /dev/null @@ -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 diff --git a/racket/src/README.txt b/racket/src/README.txt new file mode 100644 index 0000000000..6190bc1397 --- /dev/null +++ b/racket/src/README.txt @@ -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 + diff --git a/racket/src/cs/README.txt b/racket/src/cs/README.txt index ca27e40d77..6c7ba68eb7 100644 --- a/racket/src/cs/README.txt +++ b/racket/src/cs/README.txt @@ -1,49 +1,179 @@ -If you just want to build the variant of Racket that runs on Chez -Scheme, then you probably meant to read "./c/README.txt" instead of -this file. +The implementation of Racket on Chez Scheme in this directory is +organized into two layers: -If you're working on the implementation of Racket-on-Chez, then it's -more convenient to work in this directory, so keep reading here. + * The immediate directory contains Scheme sources to implement Racket + 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 - from +When you use `configure --enable-cs` or similar as described in +"../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 root of this repository/distribution and build so that at least - the "compiler-lib" package is installed, either with just `make` - (for a full build) or with +The Racket-on-Chez implementation can be built and run in two +different ways: development mode for running directly using a Chez +Scheme installation, and build mode for creating a `racket` or +`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" - Note that if you build as described in "./c/README.txt", then you - don't need the "compiler-lib" package. +in the clone's root directory. Alternatively, use use `make +RACKET=...` to set the command for `racket`. - If you'd like to use an existing installation of Racket, instead, - you can use `make RACKET=...` to set the command for `racket`. +The use of development mode is described in more detail further below. +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 -------- -Running `make` will build the Racket-on-Chez implementation, although -not in stand-alone form. Use `make expander-demo` to run a demo that -loads `racket/base` from source. +Running `make` will build the Racket-on-Chez implementation. Use `make +expander-demo` to run a demo that loads `racket/base` from source. Use `make setup` (or `make setup-v` for a verbose version) to build ".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="--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 ------- @@ -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 `ARGS`. - Structure --------- -The reimplementation on Chez Scheme is meant to export the same -interface as the traditional Racket virtual machine in "../racket": -the macro expander and primitive modules such as `#%kernel` and -`#%network`. - -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 Racket-on-Chez 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 +implemented in Chez Scheme. The rest of the layers are implemented in Racket: thread io regexp - expander schemify + expander Each of those layers is implemented in a sibling directory of this 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" and compare the reported timing to "demo/regexp.ss". - 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 instances to the macro expander. - Running "demo/expander.ss" -------------------------- A `make expander-demo` builds and tries the expander on simple examples, including loading `racket/base` from source. - 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 the "bytecode" form. - -Development Mode ----------------- +Safety and Debugging Mode +------------------------- If you make changes to files in "rumble", you should turn off `[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 the layers here (at the expense of some performance). - 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, because a foreign address cannot be turned into a byte string whose 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 not actually an array of pointers. - 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 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 safety guarantees. An implementation of futures can probably take advantage of threads with thread-unsafe primitives wrapped to divert to a barrier when called in a future. - * GC-based memory accounting similarly seems to require new support, - 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. + * GC-based memory accounting requires new support from Chez Scheme. + * Extflonums will probably exist only on the traditional Racket + implementation for a long while. Performance Notes ----------------- -The best-case scenario for performance is current the default +The best-case scenario for performance is currently the default configuration: * `UNSAFE_COMP` is enabled in "Makefile" --- currently on by default. diff --git a/racket/src/cs/c/README.txt b/racket/src/cs/c/README.txt index 2e12ab9a30..bf552732e0 100644 --- a/racket/src/cs/c/README.txt +++ b/racket/src/cs/c/README.txt @@ -1,73 +1,2 @@ This directory contains a `configure` script and a makefile (template) -for building the variant of Racket that runs on Chez Scheme. The -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). +for generating Racket-on-Chez executables. See "../README.txt". diff --git a/racket/src/native-libs/README.txt b/racket/src/native-libs/README.txt index bbf6082b3d..ed1731b3e5 100644 --- a/racket/src/native-libs/README.txt +++ b/racket/src/native-libs/README.txt @@ -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 "draw" or "math" packages, rely on additional C-implemented libraries, 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 OS, we supply pre-built libraries in platform-specific packages; the corresponding Racket packages include platform-specific dependencies -on those packages. The "x86_64-linux-natipkg" variant of Racket -is like Windows and Mac OS, expecting packages to supply native -libraries for 64-bit Linux. +on those packages. The "x86_64-linux-natipkg" variant of Racket is +like Windows and Mac OS, expecting packages to supply native libraries +for 64-bit Linux. This directory contains scripts and patches to build Windows, Mac OS, and Linux libraries in a consistent and portable way. Naturally, the diff --git a/racket/src/racket/README b/racket/src/racket/README deleted file mode 100644 index 85029a7294..0000000000 --- a/racket/src/racket/README +++ /dev/null @@ -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). diff --git a/racket/src/racket/README.txt b/racket/src/racket/README.txt new file mode 100644 index 0000000000..ee17fff895 --- /dev/null +++ b/racket/src/racket/README.txt @@ -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). diff --git a/racket/src/start/README.txt b/racket/src/start/README.txt index 75967a26d5..7d00c814f3 100644 --- a/racket/src/start/README.txt +++ b/racket/src/start/README.txt @@ -2,3 +2,38 @@ This directory constaint source programs and fragments for wrapper executables used to start/embed Racket. The programs and fragments are used both for the traditional Racket virtual machine and Racket on 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. diff --git a/racket/src/worksp/README b/racket/src/worksp/README deleted file mode 100644 index fe3f96f6bc..0000000000 --- a/racket/src/worksp/README +++ /dev/null @@ -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. diff --git a/racket/src/worksp/README.txt b/racket/src/worksp/README.txt new file mode 100644 index 0000000000..256f0eec20 --- /dev/null +++ b/racket/src/worksp/README.txt @@ -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. diff --git a/racket/src/worksp/build-cs.bat b/racket/src/worksp/build-cs.bat new file mode 100644 index 0000000000..1bcf71f145 --- /dev/null +++ b/racket/src/worksp/build-cs.bat @@ -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