diff --git a/src/README b/src/README index 742395d059..478d72a20a 100644 --- a/src/README +++ b/src/README @@ -1,5 +1,4 @@ - -This is the source code distribution for Racket. For license +This is the source code distribution for Racket. For license information, please see the file racket/notes/COPYING.LIB. Compiled binaries, documentation, and up-to-date information are @@ -24,55 +23,54 @@ Please report bugs via one of the following: ======================================================================== To compile with Microsoft Visual C, read the instructions in -racket\src\worksp\README. +"racket\src\worksp\README". -To compile with Cygwin tools, follow the Unix instructions below, and -be sure to configure with --enable-shared. The result is a Unix-style -build, not a Windows-style build (e.g., Racket's `system-type' -procedure returns 'unix, not 'windows, and GRacket uses X11). +To compile with Cygwin tools, follow the Unix instructions below, and be +sure to configure with `--enable-shared'. The result is a Unix-style +build, not a Windows-style build (e.g., Racket's `system-type' procedure +returns 'unix, not 'windows, and GRacket uses X11). ======================================================================== Compiling for Mac OS X ======================================================================== -First, install the Mac OS X Developer Tools from Apple. Then, follow +First, install the Mac OS X Developer Tools from Apple. Then, follow the Unix instructions below, but note the following: - * The Racket build creates a framework, Racket.framework, which is - installed into racket/lib. This framework is used by the executable - `racket' that goes into racket/bin. + * 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 framework, GRacket.framework, which is - installed into racket/lib. This framework is used by the executable - bundle GRacket.app that goes into the "racket" directory. - Installation creates a script, racket/bin/mred, that runs the - bundle. + * The GRacket build creates a framework, "GRacket.framework", which is + installed into "racket/lib". This framework is used by the + executable bundle GRacket.app that goes into the "racket" directory. + The installation creates a script, "racket/bin/gracket", that runs + the bundle. - * 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...) + * 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-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. + `--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. - * 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 + * 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 + directory. (Requiring `--enable-macprefix' with `--prefix' for a non-xonx build helps prevent accidental installation of a Mac-style directory structure on top of an existing Unix-style directory structure.) - * Under Mac OS X 10.6 and later, `configure' by default selects - 32-bit mode for building Racket and GRacket. To build Racket in - 64-bit mode (GRacket is not support in that mode), use the - following arguments to `configure': --enable-mac64, --enable-sgc, - and --disable-mred. + * Under Mac OS X 10.6 and later, `configure' by default selects 32-bit + mode for building Racket and GRacket. To build Racket in 64-bit mode + (GRacket is not support in that mode), use the following arguments to + `configure': `--enable-mac64', `--enable-sgc', and `--disable-mred'. ======================================================================== Compiling for supported Unix variants (including Linux) or Cygwin @@ -80,8 +78,8 @@ the Unix instructions below, but note the following: Quick instructions: - From this directory (where the `README' and `configure' files are), - run the following commands: + From this directory (where the `configure' file is), run the following + commands: mkdir build cd build @@ -90,9 +88,9 @@ Quick instructions: make install This will create an in-place installation of Racket and store the - results of C/C++ compilation in a separate `build' subdirectory, - which is useful if you need to update your sources, delete the build, - and start from scratch. + results of C/C++ compilation in a separate "build" subdirectory, which + is useful if you need to update your sources, delete the build, and + start from scratch. You can also run the typical `./configure && make && make install' if you don't anticipate updating/rebuilding, but it will be harder to @@ -104,18 +102,18 @@ Detailed instructions: remove it (unless you are using an "in-place" build from a repository as described below). - Also, make sure that you have libraries and header files for Xft - and Cairo (v1.23 and up) if you would like support for font - smoothing (Xft) and graphics smoothing (Cairo). These libraries - are not distributed with Racket. The configure process checks - automatically whether these libraries are available. + Also, make sure that you have libraries and header files for Xft and + Cairo (v1.23 and up) if you would like support for font smoothing + (Xft) and graphics smoothing (Cairo). These libraries are not + distributed with Racket. The configure process checks automatically + whether these libraries are available. OpenGL support for GRacket sometimes requires special configuration - (though generally not under Linux). See the note at the end of - this section if OpenGL fails to work. + (though generally not under Linux). See the note at the end of this + section if OpenGL fails to work. Finally, the content of the "foreign" subdirectory may require GNU - `make'. If the build fails with another variant of `make', please + `make'. If the build fails with another variant of `make', please try using GNU `make'. 1. Select (or create) a build directory. @@ -134,188 +132,187 @@ Detailed instructions: 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, + 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). + arguments `--prefix=TARGETDIR' or `--enable-shared' (or both). - For example, if you want to install into /usr/local/racket using + For example, if you want to install into "/usr/local/racket" using dynamic libraries, then run: [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. + 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. + 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 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 + 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 + variables. For example, to select the SGI compilers for Irix instead of gcc, run configure as env CC=cc CXX=CC [here]configure - For cross compilation, set the compiler variables to a compiler - for the target platform compiler, but also set CC_FOR_BUILD to a + For cross compilation, set the compiler variables to a compiler for + the target platform compiler, but also set CC_FOR_BUILD to a compiler for the host platform (for building binaries to execute - during the build process). If the target machine's stack grows up, - you'll have to supply --enable-stackup; if the target machine is - big-endian, you may have to supply --enable-bigendian. + during the build process). If the target machine's stack grows up, + you'll have to supply `--enable-stackup'; if the target machine is + big-endian, you may have to supply `--enable-bigendian'. - 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. + 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 + "config.cache". Avoid this problem entirely by using a separate build directory (but the same source) for each platform or configuration. - 3. Run `make'. [As noted in step 0, this must be GNU `make'.] + 3. Run `make'. [As noted in step 0, this must be GNU `make'.] With Cygwin, you may need to use `make --unix'. Binaries and libraries are placed in subdirectories of the build - directory. For example, the `racket3m' binary appears in the - `racket' directory. + 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. + This step copies binaries and libraries into place within the target + installation. For example, the "racket" binary is copied into the + "bin" directory for an in-place build, or into the executable + directory for a --prefix build. - For a --prefix build, this step also creates a "config.rkt" module - in a "config" collection, so that various Racket tools and - libraries can find the installation directories. At this stage, in - case you are packaging an installation instead of installing - directly, you can redirect the installation by setting the - "DESTDIR" environment variable. For example, `make - DESTDIR=/tmp/racket-build install' places the installation into - "/tmp/racket-build" instead of the location originally specified - with --prefix. The resulting installation will not work, however, - until it is moved to the location originally specified with - --prefix. + For a `--prefix' build, this step also creates a "config.rkt" module + in a "config" collection, so that various Racket tools and libraries + can find the installation directories. At this stage, in case you + are packaging an installation instead of installing directly, you + can redirect the installation by setting the "DESTDIR" environment + variable. For example, `make DESTDIR=/tmp/racket-build install' + places the installation into "/tmp/racket-build" instead of the + location originally specified with `--prefix'. The resulting + installation will not work, however, until it is moved to the + location originally specified with `--prefix'. Finally, the `make install' step compiles ".zo" bytecode files for installed Racket source, and generates launcher programs like - DrRacket. Use `make plain-install' to install without compiling + DrRacket. Use `make plain-install' to install without compiling ".zo" files or creating launchers. 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. + 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 + 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, + in Racket. In addition, if you configure with `--enabled-shared', you may accumlate many unused versions of the dynamic libraries in your installation target. -After an "in-place" install without git, the racket/src directory is -no longer needed, and it can be safely deleted. Build information is +After an "in-place" install without git, the "racket/src" directory is +no longer needed, and it can be safely deleted. Build information is recorded in a "buildinfo" file in the installation. -For a build without --prefix (or with --enable-origtree) and without ---enable-shared, you can safely move the install tree, because all +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. OpenGL, Unix, and pthreads -------------------------- On some Unix systems, programs that use the OpenGL library must also -link to pthreads. To use GRacket's OpenGL support on these systems, GRacket -must be configured with the --enable-pthread option. Unfortunately, -Racket's normal stack handling and use of signals (for its own -thread scheduling) do not interact well with pthreads. Thus, when -pthreads are enabled, Racket and GRacket cannot use interupt timers, -and the stack is limited to 1MB. These restrictions can degrade +link to pthreads. To use GRacket's OpenGL support on these systems, +GRacket must be configured with the `--enable-pthread' option. +Unfortunately, Racket's normal stack handling and use of signals (for +its own thread scheduling) do not interact well with pthreads. Thus, +when pthreads are enabled, Racket and GRacket cannot use interupt +timers, and the stack is limited to 1MB. These restrictions can degrade performance and thread-responsiveness. -If `configure' detects that OpenGL requires -lpthread for linking, -and if --enable-pthread is not specified, `configure' prints a warning -and disables GL support. On some systems, including at least FreeBSD -with the MESA GL implementation (but not the NVIDIA implementation, -which does not need pthreads), `configure' cannot detect the need for -pthreads. On these platforms, GL support will be included in GRacket, -but it will not work properly unless --enable-pthread is specified. +If `configure' detects that OpenGL requires -lpthread for linking, and +if `--enable-pthread' is not specified, `configure' prints a warning and +disables GL support. On some systems, including at least FreeBSD with +the MESA GL implementation (but not the NVIDIA implementation, which +does not need pthreads), `configure' cannot detect the need for +pthreads. On these platforms, GL support will be included in GRacket, +but it will not work properly unless `--enable-pthread' is specified. ======================================================================== CGC versus 3m ======================================================================== -Racket and GRacket have two variants: CGC and 3m. The CGC variant is -older, and it cooperates more easily with extensions written in C. -The 3m variant is the default, and it usually provides better overall -performance. +Racket and GRacket have two variants: CGC and 3m. The CGC variant is +older, and it cooperates more easily with extensions written in C. The +3m variant is the default: it is more robust and usually provides better +overall performance. -The default build mode creates 3m binaries only. To create CGC -binaries in addition, run `make cgc' in addition to `make', or run -`make both'. To install both variants, use `make install-both' instead -of just `make install'. Alternately, use just `make cgc' and `make -install-cgc' to build and install just the CGC variants. +The default build mode creates 3m binaries only. To create CGC binaries +in addition, run `make cgc' in addition to `make', or run `make both'. +To install both variants, use `make install-both' instead of just `make +install'. Alternately, use just `make cgc' and `make install-cgc' to +build and install just the CGC variants. -CGC variants are installed with a "cgc" suffix. To swap the default -build and install mode, supply --enable-cgcdefault to `configure'. In +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. +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 +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. +"coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the entire +list of paths must end with an additional NUL terminator, and the +overall list must be less than 1024 bytes long. As an alternative to editing an exeuctable directly, the `create-embedding-executable' procedure from `compiler/embed' can be -used to change the embedded path. For example, the following program -clones the Racket executable to "/tmp/mz" and changes the embedded -path in the clone to "/tmp/collects": +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") @@ -323,21 +320,20 @@ path in the clone to "/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. +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 +"config.rkt" library of the "config" collection. Search the documentation for "config search paths" for more information. ======================================================================== Porting to New Platforms ======================================================================== -At a mininum, to port Racket to a new platform, edit -racket/sconfig.h to provide a platform-specific compilation -information. As distributed, racket/sconfig.h contains -configurations for the following platforms: +At a mininum, to port Racket to a new platform, edit "racket/sconfig.h" +to provide a platform-specific compilation information. As distributed, +"racket/sconfig.h" contains configurations for the following platforms: Windows (x86) Mac OS X (PPC, x86, x86_64) @@ -359,22 +355,22 @@ If your platfrom is not supported by the Boehm garbage collector Garbage Collector ----------------- -The conservative garbage collector distributed with Racket (in the -gc directory) has been modified slightly from Boehm's standard -distribution. Mostly, the change modify the way that object +The conservative garbage collector distributed with Racket (in the "gc" +directory) has been modified slightly from Boehm's standard +distribution. Mostly, the change modify the way that object finalization is handled. Configuration Options --------------------- By default, Racket is compiled without support for single-precision -floating point numbers. This and other options can be modified by -setting flags in racket/sconfig.h. +floating point numbers. This and other options can be modified by +setting flags in "racket/sconfig.h". Modifying Racket ------------------- +---------------- -If you modify Racket and change any primitive syntax or the -collection of built-in identifers, be sure to turn off -USE_COMPILED_MACROS in schminc.h. Otherwise, Racket won't start. -See schminc.h for details. +If you modify Racket and change any primitive syntax or the collection +of built-in identifers, be sure to turn off USE_COMPILED_MACROS in +"schminc.h". Otherwise, Racket won't start. See "schminc.h" for +details. diff --git a/src/worksp/README b/src/worksp/README index 7f408b9003..0bd6a4b331 100644 --- a/src/worksp/README +++ b/src/worksp/README @@ -18,14 +18,14 @@ Visual Studio Express is available for free from Microsoft; it can be used to build Racket and GRacket, but not MzCOM and MysterX. 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 +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. To support +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. To support Borland-built extensions, cd to racket\src\racket\dynsrc and run mkbordyn.bat (which requires bcc23.exe, of course). @@ -37,20 +37,20 @@ As always, please report bugs via one of the following: -PLT racket@racket-lang.org ----------------------------------------------------------------------- +--------------------------- Building Racket and GRacket ----------------------------------------------------------------------- +--------------------------- If you're using MSVC 8.0 (not Express), and if `devenv.exe' is in your -path, then you can just run +path, then you can just run racket\src\worksp\build.bat from its own directory to perform all steps up to "Versioning", including the MzCOM and MysterX steps. -The CGC variants of Racket, MzCOM, GRacket, and MysterX 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.) +The CGC variants of Racket, MzCOM, GRacket, and MysterX 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.) The 3m build requires some parts of the CGC build: racket\src\worksp\racket @@ -58,15 +58,14 @@ The 3m build requires some parts of the CGC build: racket\src\worksp\jpeg racket\src\worksp\png racket\src\worksp\zlib -It's simplest to just build the main CGC solutions, which -automatically build all of the above projects, and then build -3m. +It's simplest to just build the main CGC solutions, which automatically +build all of the above projects, and then build 3m. 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' +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. To build RacketCGC, build the Racket solution in @@ -81,37 +80,36 @@ To build GRacketCGC, build the GRacket solution: [Again, switch to the "Release" configuration if necessary.] The build processes for RacketCGC 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 + 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 The build process for GRacketCGC automatically builds - libmzgc - as above - libracket - as above + libmzgc - as above + libracket - as above libgracket - makes racket\lib\libgracketxxxxxxx.dll and racket\src\worksp\libgracket\Release\libgracketxxxxxxx.lib - wxutils - makes racket\src\worksp\wxutils\Release\wxutils.lib - wxwin - makes racket\src\worksp\wxwin\Release\wxwin.lib - wxs - makes racket\src\worksp\wxs\Release\wxs.lib - wxme - makes racket\src\worksp\wxme\Release\wxme.lib - jpeg - makes racket\src\worksp\jpeg\Release\jpeg.lib - png - makes racket\src\worksp\jpeg\Release\png.lib - zlib - makes racket\src\worksp\jpeg\Release\zlib.lib + wxutils - makes racket\src\worksp\wxutils\Release\wxutils.lib + wxwin - makes racket\src\worksp\wxwin\Release\wxwin.lib + wxs - makes racket\src\worksp\wxs\Release\wxs.lib + wxme - makes racket\src\worksp\wxme\Release\wxme.lib + jpeg - makes racket\src\worksp\jpeg\Release\jpeg.lib + png - makes racket\src\worksp\jpeg\Release\png.lib + zlib - makes racket\src\worksp\jpeg\Release\zlib.lib In addition, building RacketCGC executes racket\src\racket\dynsrc\mkmzdyn.bat -which copies .exp, .obj, and .lib files into racket\lib\, and also copies -DLLs from the "extradlls" directory to to racket\lib\. +which copies .exp, .obj, and .lib files into racket\lib\, and also +copies DLLs from the "extradlls" directory to to racket\lib\. Building Racket3m and GRacket3m ------------------------------- +------------------------------- -After RacketCGC and GRacketCGC are built, you can can build 3m -binaries: +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 "vsvars32.bat" from your Visual Studio + 1. Ensure that the Visual Studio command-line tools are in your path. + You may need to run "vsvars32.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 @@ -120,7 +118,7 @@ binaries: The resulting Racket.exe and GRacket.exe will appear in the top-level "racket" directory, along with DLLs libracket3mxxxxxxx.dll and -libgracket3mxxxxxxx.dll in racket/lib. (There is no corresponding +libgracket3mxxxxxxx.dll in racket/lib. (There is no corresponding libmzgc3mxxxxxxx.dll. Instead, it is merged with libracket3mxxxxxxx.dll.) @@ -128,7 +126,7 @@ 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 +used by the launcher collection to create "raco.exe". Build the following solutions: racket\src\worksp\mzstart - makes racket\collects\launcher\mzstart.exe @@ -142,8 +140,8 @@ 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. +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. @@ -152,13 +150,13 @@ Versioning ---------- [If you're going to build MzCOM and/or MysterX, do that before running - the version-changing script. See instructions below.] + the version-changing script. See instructions below.] -The obnoxious "xxxxxxx" in the DLL names is a placeholder for a -version number. Embedding a version number in a DLL name appears to -be the simplest and surest way to avoid version confusion. +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 +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. @@ -169,20 +167,18 @@ To replace the "xxxxxxx" with a specific version, run 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. +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 and MysterX ----------------------------------------------------------------------- +-------------------------- Beware that MzCOM and MysterX do not build with Express versions of -Visual Studio. Otherwise, building MzCOMCGC and MysterXCGC is similar -to building RacketCGC. Building the 3m variants is a little -different. +Visual Studio. Otherwise, building MzCOMCGC and MysterXCGC is similar +to building RacketCGC. Building the 3m variants is a little different. Building MzCOM -------------- @@ -192,14 +188,14 @@ To build MzCOMCGC, make the MzCOM solution in Use the "Release" configuration. -After building MzCOMCGC, you can build the 3m variant by +After building MzCOMCGC, you can build the 3m variant by 1. Change directories to racket\src\worksp\mzcom and run ..\..\..\racketcgc.exe -cu xform.rkt - 2. Switch to the "3m" configuration in the MzCOM solution - (in Visual Studio). + 2. Switch to the "3m" configuration in the MzCOM solution (in Visual + Studio). 3. Build (in Visual Studio). @@ -215,48 +211,47 @@ To build MysterXCGC, make the MysterX solution in Use the "Release" configuration. -After building MysterXCGC, you can build the 3m variant by +After building MysterXCGC, you can build the 3m variant by 1. Change directories to racket\src\worksp\libmysterx and run ..\..\..\racketcgc.exe -cu xform.rkt - 2. Switch to the "3m" configuration in the libmysterx solution - (in Visual Studio). + 2. Switch to the "3m" configuration in the libmysterx solution (in + Visual Studio). 3. Build (in Visual Studio). The result is mxmain.dll (no 3m suffix) in collects\mysterx\private\compiled\native\win32\i386\3m ----------------------------------------------------------------------- +------------ Finding DLLs ----------------------------------------------------------------------- +------------ Since the DLLs libracket3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and libracketxxxxxxx.dll) and libgracket3mxxxxxxx.dll (or libgracketxxxxxxx.dll) are 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. +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. +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. @@ -267,14 +262,13 @@ The libraries racket\lib\win32\msvc\libmzgcxxxxxxx.lib which are created by the mzsrc and gc 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. +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. +statically linking to the C library within the Racket DLL), then compile +Racket with the /MD flag.