update READMEs for path changes to date

svn: r2946

src/README

@@ -96,8 +96,9 @@ the Unix instructions below, but note the following:
     If the --prefix flag is omitted, the binaries are built for an
     in-place installation (i.e., the plt directory containing this
     README will be used directly). Unless --enable-shared is used, the
-    plt directory can be moved later, but most system administrators
+    plt directory can be moved later; most system administrators
-    would recommend that you use --enable-shared.
+    would recommend that you use --enable-shared, but the PLT Scheme
+    developers distribute binaries built without --enable-shared.
 
     The `configure' script generates the makefiles for building
     MzScheme and/or MrEd. The current directory at the time
@@ -193,7 +194,38 @@ pthreads. On these platforms, GL support will be included in MrEd,
 but it will not work properly unless --enable-pthread is specified.
 
 ========================================================================
- Compiling the OSKit-based kernel
+ Embedded Paths in the Executables
+========================================================================
+
+On all platforms, the MzScheme and MrEd 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 "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 `(lib "embed.ss"
+"compiler")' can be used to change the embedded path. For example, the
+following clones the MzScheme executable and changes the embedded path
+n the clone to "/tmp/collects":
+
+ (require (lib "embed.ss" "compiler"))
+ (create-embedding-executable "/tmp/mz" #:lib-path "/tmp/collects")
+
+Similarly, `mzc' in `--exe' or `--gui-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.
+
+========================================================================
+ Compiling the OSKit-based Kernel
 ========================================================================
 
 To build the OSKit-based MzScheme kernel, run the configure script

src/worksp-vc70/README

@@ -1,165 +1,4 @@
-This directory contains 
+This directory contains solution files and project files for building
-
+MzScheme and MrEd with Microsoft Visual Studio version 7.0. See
- - solution files and project files for building MzScheme and
+..\worksp\README (which provides files for MSVC 7.1 and up) for more
-    MrEd with Microsoft Visual Studio (which work with the .NET
+information.
-    and Express 2005 versions of Visual Studio);
-
- - mzconfig.h which is a manual version of information that is
-    gathered automatically when using the "configure" script.
-
-If you have downloaded MzCOM, the directory also contains Visual
-Studio files for MzCOM.
-
-Visual Studio Express is available for free from Microsoft, and it is
-the recommended compiler for building PLT Scheme.
-
-MzScheme and MrEd 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 plt\src\README (there is a short
-Windows-specific section in that file).
-
-With an MSVC-built MzScheme, compatible extensions can be built with
-other compilers. Build with Cygwin and copy the installed plt\lib\gcc
-to a MSVC-based build to support Cygwin-built extensions. To support
-Borland-built extensions, cd to plt\src\mzscheme\dynsrc and run
-mkbordyn.bat (which requires bcc23.exe, of course).
-
-As always, please report bugs via one of the following:
-  - Help Desk's "submit bug report" link  (preferred)
-  - http://bugs.plt-scheme.org/
-  - bugs@plt-scheme.org                   (last resort)
-
--PLT
- scheme@plt-scheme.org
-
-----------------------------------------------------------------------
-Building MzScheme, MzCOM, and MrEd
-----------------------------------------------------------------------
-
-The source code for MzScheme, MzCOM, and MrEd is split into several
-projects that are grouped into a few solutions. To make the `X'
-solution with Visual Studio, open the file plt\src\worksp\X\X.sln.
-[When you open a solution, the selected configuration will most likely
-be "Debug". Consider changing to "Release" before you build to enable
-optimization.]
-
-To build MzScheme, make the MzScheme solution in
-   plt\src\worksp\mzscheme - makes plt\mzscheme.exe
-
-To build MzCOM, make the MzCOM solution in
-   plt\src\worksp\mzcom - makes plt\collects\mzcom\mzcom.exe
-
-To build MrEd, make the MrEd solution:
-   plt\src\worksp\mred - makes plt\mred.exe
-
-The make processes for MzScheme and MzCOM automatically build
-   libmzgc - makes plt\libmzgcxxxxxxx.dll and
-             plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
-   mzsrc - makes plt\libmzschxxxxxxx.dll and
-                 plt\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib
-
-The make process for MrEd automatically builds
-   libmzgc - as above
-   libmzsch - as above
-   libmred - makes plt\libmredxxxxxxx.dll and
-                   plt\src\worksp\libmred\Release\libmredxxxxxxx.lib
-   wxutils - makes plt\src\worksp\wxutils\Release\wxutils.lib
-   wxwin - makes plt\src\worksp\wxwin\Release\wxwin.lib
-   wxs  - makes plt\src\worksp\wxs\Release\wxs.lib
-   wxme  - makes plt\src\worksp\wxme\Release\wxme.lib
-   jpeg  - makes plt\src\worksp\jpeg\Release\jpeg.lib
-   png  - makes plt\src\worksp\jpeg\Release\png.lib
-   zlib  - makes plt\src\worksp\jpeg\Release\zlib.lib
-
-In addition, building MzScheme executes
-   plt\src\mzscheme\dynsrc\mkmzdyn.bat
-which copies .exp, .obj, and .lib files into plt\lib\, and also copies
-DLLs from the extradlls directory to to plt\.  uniplt_xxxxxxx.dll is
-used only under Windows 95/98/Me for Unicode.
-
-To complete a build, run the versioning script described in the next
-section.
-
-----------------------------------------------------------------------
-Versioning
-----------------------------------------------------------------------
-
-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
-
-  mzscheme -mvqL winvers.ss setup
-
-in a shell. The "winvers.ss" program will have to make a temporary
-copy of mzscheme.exe, libmzschxxxxxxx.dll, and libmzgcxxxxxxx.dll (in
-the temporary directory), and it will re-launch MzScheme a couple of
-times. The resulting conversions are
-  plt\mzscheme.exe -> plt\mzscheme.exe (updated)
-  plt\mred.exe -> plt\mred.exe         (updated)
-  plt\mzcom.exe -> plt\mzcom.exe       (updated)
-  plt\libmzgcxxxxxxx.dll -> plt\libmzgc<version>.dll
-  plt\libmzschxxxxxxx.dll -> plt\libmzsch<version>.dll
-  plt\libmredxxxxxxx.dll -> plt\libmred<version>.dll
-  plt\src\worksp\libmzsch\Release\libmzschxxxxxxx.lib
-                          -> plt\lib\win32\msvc\libmzsch<version>.lib
-  plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
-                          -> plt\lib\win32\msvc\libmzgc<version>.lib
-  plt\uniplt_xxxxxxx.dll -> plt\uniplt_<version>.dll
-
-----------------------------------------------------------------------
-Extra stuff for MzScheme and MrEd
-----------------------------------------------------------------------
-
-If you're building from scratch, you'll also want the starter
-programs used by the launcher collection to make drscheme.exe
-and mzc.exe:
-
-   mzstart - makes plt\collects\launcher\mzstart.exe
-   mrstart - makes plt\collects\launcher\mrstart.exe
-
-Then, set up all the other executables (besides mred.exe
-and mzscheme.exe) by running
-
-   mzscheme.exe -mvqM- setup
-
-(This makes the .zo files, too. To skip compiling .zos, 
-add -n to the end of the above command.)
-
-----------------------------------------------------------------------
-Embedding MzScheme
-----------------------------------------------------------------------
-
-The MzScheme DLLs can be used within an embedding application.
-
-The libraries
-
-    plt\src\worksp\libmzsch\Release\libmzschxxxxxxx.lib
-    plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
-
-which are created by the mzsrc and gc projects, provide linking
-information for using the libmzschxxxxxxx.dll and libmzgcxxxxxxx.dll
-DLLs. The versioning script adjusts the names and puts them in
-    plt\lib\msvc\libmzsch<version>.lib
-    plt\lib\msvc\libmzgc<version>.lib
-
-See the "Inside PLT MzScheme" manual for more information about using
-these libraries to embed MzScheme in an application.
-
-
-If you need MzScheme to link to a DLL-based C library (instead of
-statically linking to the C library within the MzScheme DLL), then:
- 
- 1. Compile MzScheme with the /MD flag.
-
- 2. Define the pre-processor symbol USE_MSVC_MD_LIBRARY while
-    compiling the GC with /MD.
-
- 3. In your embedding application, call GC_pre_init() before calling
-    any MzScheme and GC function.

src/worksp/README

@@ -1,14 +1,13 @@
 This directory contains 
 
- - solution files and project files for building MzScheme and
+ - solution files and project files for building MzScheme and MrEd
-    MrEd with Microsoft Visual Studio (which work with the .NET
+    with Microsoft Visual Studio 7.1 and up (which work with the .NET
     and Express 2005 versions of Visual Studio);
 
  - mzconfig.h which is a manual version of information that is
     gathered automatically when using the "configure" script.
 
-If you have downloaded MzCOM, the directory also contains Visual
+For files that work with MSVC 7.0, see ..\worksp-vc70\.
-Studio files for MzCOM.
 
 Visual Studio Express is available for free from Microsoft, and it is
 the recommended compiler for building PLT Scheme.
@@ -16,8 +15,8 @@ the recommended compiler for building PLT Scheme.
 MzScheme and MrEd 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 plt\src\README (there is a short
+follow the instructions in plt\src\README (which contains a short
-Windows-specific section in that file).
+Windows-specific section).
 
 With an MSVC-built MzScheme, compatible extensions can be built with
 other compilers. Build with Cygwin and copy the installed plt\lib\gcc
@@ -54,15 +53,15 @@ To build MrEd, make the MrEd solution:
    plt\src\worksp\mred - makes plt\mred.exe
 
 The make processes for MzScheme and MzCOM automatically build
-   libmzgc - makes plt\libmzgcxxxxxxx.dll and
+   libmzgc - makes plt\lib\libmzgcxxxxxxx.dll and
              plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
-   mzsrc - makes plt\libmzschxxxxxxx.dll and
+   mzsrc - makes plt\lib\libmzschxxxxxxx.dll and
                  plt\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib
 
 The make process for MrEd automatically builds
    libmzgc - as above
    libmzsch - as above
-   libmred - makes plt\libmredxxxxxxx.dll and
+   libmred - makes plt\lib\libmredxxxxxxx.dll and
                    plt\src\worksp\libmred\Release\libmredxxxxxxx.lib
    wxutils - makes plt\src\worksp\wxutils\Release\wxutils.lib
    wxwin - makes plt\src\worksp\wxwin\Release\wxwin.lib
@@ -75,8 +74,7 @@ The make process for MrEd automatically builds
 In addition, building MzScheme executes
    plt\src\mzscheme\dynsrc\mkmzdyn.bat
 which copies .exp, .obj, and .lib files into plt\lib\, and also copies
-DLLs from the extradlls directory to to plt\.  uniplt_xxxxxxx.dll is
+DLLs from the extradlls directory to to plt\lib\.
-used only under Windows 95/98/Me for Unicode.
 
 To complete a build, run the versioning script described in the next
 section.
@@ -104,14 +102,13 @@ times. The resulting conversions are
   plt\mzscheme.exe -> plt\mzscheme.exe (updated)
   plt\mred.exe -> plt\mred.exe         (updated)
   plt\mzcom.exe -> plt\mzcom.exe       (updated)
-  plt\libmzgcxxxxxxx.dll -> plt\libmzgc<version>.dll
+  plt\lib\libmzgcxxxxxxx.dll -> plt\lib\libmzgc<version>.dll
-  plt\libmzschxxxxxxx.dll -> plt\libmzsch<version>.dll
+  plt\lib\libmzschxxxxxxx.dll -> plt\lib\libmzsch<version>.dll
-  plt\libmredxxxxxxx.dll -> plt\libmred<version>.dll
+  plt\lib\libmredxxxxxxx.dll -> plt\lib\libmred<version>.dll
   plt\src\worksp\libmzsch\Release\libmzschxxxxxxx.lib
                           -> plt\lib\win32\msvc\libmzsch<version>.lib
   plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
                           -> plt\lib\win32\msvc\libmzgc<version>.lib
-  plt\uniplt_xxxxxxx.dll -> plt\uniplt_<version>.dll
 
 ----------------------------------------------------------------------
 Extra stuff for MzScheme and MrEd
@@ -132,6 +129,30 @@ and mzscheme.exe) by running
 (This makes the .zo files, too. To skip compiling .zos, 
 add -n to the end of the above command.)
 
+----------------------------------------------------------------------
+Finding DLLs
+----------------------------------------------------------------------
+
+Since the DLLs libmzgcxxxxxxx.dll, libmzschxxxxxxx.dll, and
+libmzmredxxxxxxx.dll are installed into plt\lib\ instead of just plt\,
+the normal search path for DLLs would not find them when running
+"MzScheme.exe" or "MrEd.exe". To find the DLLs, the executables are
+"delayload" linked with the DLLs, and the executables explicitly load
+the DLLs from plt\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 exeuctable 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 MzScheme
 ----------------------------------------------------------------------
@@ -140,14 +161,12 @@ The MzScheme DLLs can be used within an embedding application.
 
 The libraries
 
-    plt\src\worksp\libmzsch\Release\libmzschxxxxxxx.lib
+    plt\lib\win32\msvc\libmzschxxxxxxx.lib
-    plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
+    plt\lib\win32\msvc\libmzgcxxxxxxx.lib
 
 which are created by the mzsrc and gc projects, provide linking
 information for using the libmzschxxxxxxx.dll and libmzgcxxxxxxx.dll
-DLLs. The versioning script adjusts the names and puts them in
+DLLs. The versioning script adjusts the names, as described above.
-    plt\lib\msvc\libmzsch<version>.lib
-    plt\lib\msvc\libmzgc<version>.lib
 
 See the "Inside PLT MzScheme" manual for more information about using
 these libraries to embed MzScheme in an application.