Building Chez Scheme Version 9.5.7 (Racket variant)
Copyright 1984-2021 Cisco Systems, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


PREREQUISITES

On Unix variants:

 * GNU Make
 * GCC, Clang, or a similarly capable compiler
 * Header files and libraries for ncurses   [unless --disable-curses]
 * Header files and libraries for X windows [unless --disable-x11]

On Windows:

 * Microsoft Visual Studio 2022, 2019, 2017, or 2015

 or

 * Bash/WSL, MinGW/MSYS, or Cygwin with bash, git, grep, make, sed,
   etc.


GETTING STARTED

This directory contains the sources for Chez Scheme. It may also
contain boot and header files in "boot/pb" for the "portable bytecode"
Chez Scheme machine type, which can be used to build for native
machine types, or you may have to create initial boot files using
Racket.

In you're on Windows, see the WINDOWS VIA COMMAND PROMPT or WINDOWS
VIA SHELL section later in this file. Otherwise, to get further
instructions, try running

  ./configure
  make

The output will either suggest using using the pb boot files with

  ./configure --pb
  make <machine type>.bootquick

or Racket as

  racket rktboot/main.rkt --machine <machine type>

and then trying again with `./configure`. In the former case, you can
use "auto.bootquick" instead of "<machine type>.bootquick".

If you plan to build on multiple different machines and you don't have
pbb boot files, then it may be a good idea to generate pb boot files
via Racket:

  racket rktboot/main.rkt --machine pb

Then, you can use the pb boot files on different machines instead of
having to install Racket on each machine. Alternatively, after you
have a Chez Scheme build on one machine, you can use use

  make <machine type>.boot

to more quickly create boot files for any <machine type>.


CONFIGURING AND BUILDING

After you have boot files for the current platform, builing an
installing is the usual sequence:

  ./configure
  make
  sudo make install

This should not take more than a minute or so, after which the
commands `scheme` and `petite` can be used to run Chez Scheme and
Petite Chez Scheme, while `man scheme` and `man petite` can be used to
view the manual pages. Chez Scheme and Petite Chez Scheme are
terminal-based programs, not GUIs. They both incorporate sophisticated
command-line editing reminiscent of tcsh but with support for
expressions that span multiple lines.

Uninstalling on Unix-like systems is as simple as running:

  sudo make uninstall


DETAILS

The sources for Chez Scheme come in two parts:

 * A set of Scheme source files found in the subdirectory "s".
   Compiling these produces the boot files "petite.boot" and
   "scheme.boot", along with two header files, "equates.h" and
   "scheme.h".

 * A set of C source files found in the subdirectory "c". Compiling
   and linking these files produces the executable "scheme" (or
   "scheme.exe" on Windows). Compiling the C sources requires the two
   header files produced by compiling the Scheme sources.

The Scheme sources can be compiled only by a working version of Chez
Scheme or via Racket; it's not possible to build Chez Scheme from
source using only standard Unix tools, such as a C compiler, unless
the "pb" boot files are packaged with the source.

The "configure" script attempts to determine what type of machine it's
on and looks for boot files for the machine in a "boot" subdirectory
(either in the same directory as the "configure" script or the current
directory is "configure" is run from elsewhere). If it find suitable
boot files, "configure" creates several files and directories in the
current directory (which does not have to be the same as the source
directory):

 * "Makefile" in the root (top level) directory.

 * A workarea as a subdirectory named for the machine type (e.g.,
   "ta6le" for threaded 64-bit linux). The workarea is a mirror of the
   root directory, with subdirectories named "c", "s", and so on.
   Compilation takes place in the workarea.

 * Within the workarea, the files "Makefile", "Mf-install", "Mf-boot",
   etc.

The "configure" script recognizes various options for controlling the
type of build and the installation location. For example,
`--nothreads` requests a build without support for native threads,
`--32` requests a 32-bit build, and `--installprefix <pathname>`
specifies the installation root. Run `./configure --help` for
information on the supported options.

The makefile supports several targets:

 * `make` or `make build`

   Compiles and links the C sources to produce the executable, then
   bootstraps the Scheme sources. Bootstrapping involves using the
   freshly built scheme executable along with initial boot files to
   compile the Scheme sources. If the new boot files are equivalent to
   the old boot files, the system is bootstrapped. Otherwise, the new
   boot files are used to create a newer set, and those are compared.
   If this succeeds, the system is bootstrapped. Otherwise, the make
   fails --- which should not happen, unless the initial boot files
   are incorrect or become out of sync with the sources.

   When you make a modification to the system that causes the C side
   to get out of sync with the Scheme side so that the build fails,
   the simplest approach is to re-bootstrapp via Racket.

 * `make run`

   Runs the build Chez Scheme without installing.

   Alternatively, you can run the executable directly and tell it
   where to find boot files, either by setting `SCHEMEHEAPDIRS` as

     env SCHEMEHEAPDIRS=<workarea>/boot/<machine type> \
         <workarea>/bin/<machine type>/scheme

   or this through the `-b` command-line flag, which requires
   absolute paths:

     <workarea>/bin/<machine type>/scheme \
       -b /path/to/<workarea>/boot/<machine type>/petite.boot \
       -b /path/to/<workarea>/boot/<machine type>/scheme.boot

   Note that <workarea> and <machine type> are typically the same.

 * `sudo make install`

   Installs the built executables, boot files, example files, and
   manual pages. If the `--installprefix` used with "configure" is
   writable by the current user, then `sudo` is not necessary.

 * `sudo make uninstall`

   Uninstalls the executables, boot files, example files, and manual
   pages. As with `make install`, if the `--installprefix` used with
   "configure" is writable by the current user, then `sudo` is not
   necessary.

 * `make test`

   Runs the build plus runs a set of test programs in various
   different ways, e.g., with different compiler options. It can take
   on the order of an hour, depending on the speed of the machine.

   At the end of a complete run, the summary recorded in
   "<workarea>/mats/summary" is shown. It should contain one line per
   test configuration, something like this:

     -------- o=0 --------
     -------- o=3 --------
     -------- o=0 cp0=t --------
     -------- o=3 cp0=t --------
     -------- o=0 spi=t p=t --------
     -------- o=3 spi=t p=t --------
     -------- o=0 eval=interpret --------
     -------- o=3 eval=interpret --------
     -------- o=0 cp0=t eval=interpret --------
     -------- o=3 cp0=t eval=interpret --------
     -------- o=0 ehc=t eoc=f --------
     -------- o=3 ehc=t eval=interpret --------

   If there is anything else in "<workarea>/mats/summary", something
   unexpected occurred. See "IMPLEMENTATION.md" for more information.

 * `make <machine type>.boot` or `make <machine type>.bootquick`

   Creates boot files for a supported machine type, which is not
   necessarily the current machine type. The boot files aer written to
   a subdirectory in "boot".

   The difference between `boot` and `bootquick` is that the latter
   assumes that up-to-date boot files are in place for the current
   machine type, and it compile the cross compiler in unsafe mode. So,
   `bootquick` is faster, but `boot` is more helpful during
   development.

 * `make bootfiles`

   Runs the build plus uses the locally built system to recreate the
   boot and header files for multiple machine types --- each machine
   type for which a subdirectory exists in the top-level "boot"
   directory. To include a supported machine type that isn't already
   represented in "boot", simply add the appropriate subdirectory as
   empty or use `make <machine type>.boot` first.

 * `make docs`

   Runs the build plus generates HTML and PDF versions of the Chez
   Scheme Users Guide and the release notes. Unlike the other build
   targets, the documentation is not built in the workarea, but rather
   in the "csug" and "release_notes" directories (where "configure" is
   run).

   Building the documentation requires a few prerequisites not required
   to build the rest of Chez Scheme.  The following must be available
   in your PATH:

    * A TeX distribution (including latex, pdflatex, dvips, and gs)

    * ppmtogif and pnmcrop (from Netpbm)

   An X11 installation is not required, but ppmtogif does require an
   "rgb.txt" file, which it will automatically locate in the common
   X11 installation locations. If ppmtogif fails because it cannot
   find an "rgb.txt" file, you can use the `RGBDEF` environment
   variable to specify the path to a file. If your system has an Emacs
   installation, then you can find an "rgb.txt" file in the "etc"
   directory of the emacs installation. If your system has a Vim
   installation, then it might contain an "rgb.txt" in the directory
   identified by the `VIMRUNTIME` environment variable.

 * `make clean`

   Removes binaries from the workarea.

 * `make distclean`
   
    Removes "nanopass", "Makefile", built documentation, and all
    workareas.


WINDOWS VIA COMMAND PROMPT

To build on Windows with Microsoft Visual Studio, make sure you've set
up Microsoft Visual Studio command-line tools. The "c\vs.bat" script
can help if you supply `amd64` for a 64-bit Intel build, `x86` for a
32-bit Intel build, or `x64_arm64` for a 64-bit Arm build:

  c\vs.bat amd64

Next, you'll need boot files for the Chez Scheme target <machine type>,
which is one of the following:

 * ta6nt     (64-bit Intel threaded
 * a6nt      (64-bit Intel non-threaded
 * tarm64nt  (64-bit Arm threaded)
 * arm64nt   (64-bit Arm non-threaded)
 * ti3nt     (32-bit threaded)
 * i3nt      (32-bit non-threaded)

One approach to getting boot files is to install Racket and run (where
you may have to supply the full path to your Racket installation):

  racket rktboot/main.rkt --machine <machine type>

Another approach is to build a pb Chez Scheme to take advantage of pb
boot files, and then use that Chez Scheme to generate boot files for
the target machine type:

 c\build.bat pb
 s\boot.bat <machine type> pb

Finally, run "c\build.bat" with the same <machine type> as when
creating boot files:

  c\build.bat <machine type>

The resulting executable in "<machine type>\bin\<machine type>" relies
on generated boot files in "..\boot\<machine type>" relative to the
executable.


WINDOWS VIA SHELL

Building Chez Scheme under 64-bit Windows with Bash/WSL, MinGW/MSYS,
or Cygwin follows the instructions in GETTING STARTED above, except
that `make install` and `make uninstall` are not supported.
Alternatively, the main Chez Scheme executable can be built from the
Windows command line or cross-compiled using MinGW as described
further below.

On Bash/WSL, the build directory must be in a location with a Windows
path such as /mnt/c, and the `OS` environment variable must be set to
`Windows_NT` to indicate a build for Windows, as opposed to a build
for Linux on Windows:

  env OS=Windows_NT ./configure
  env OS=Windows_NT make

The generated executables "scheme.exe" and "petite.exe" are in
"<machine type>\bin\<machine type>", and each relies on generated boot
files in "..\boot\<machine type>" relative to the executable.

If you're using Visual Studio 2022 or 2019, install "Desktop
development with C++" on the "Workloads" tabs and the "C++ 20[xx]
Redistributable MSMs" on the "Individual components" tab under the
"Compilers, build tools, and runtimes" section.

The executables are dynamically linked against the Microsoft Visual
C++ run-time library vcruntime140.dll. If you distribute the
executables to a different system, be sure to include the
redistributable run-time library.

To create an installer:

  cd wininstall
  make workareas
  make

These commands will create workareas and compile binaries for the
`a6nt`, `i3nt`, `ta6nt`, and `ti3nt` machine types and then include
them in a single Windows installer package "Chez Scheme.exe". The
package also includes example files and the redistributable Microsoft
Visual C++ run-time libraries.

When testing on Windows, the iconv tests in "mats/io.ms" require that
a 32-bit or 64-bit (as appropriate) "iconv.dll", "libiconv.dll", or
"libiconv-2.dll" implementing GNU libiconv be located alongside the
executable or via the `PATH` environment variable. Windows sources for
libiconv can be found at:

  http://gnuwin32.sourceforge.net/packages/libiconv.htm

An alternative implementation that uses the Windows API can be found
at:

  https://github.com/burgerrg/win-iconv/releases

If the DLL is not present, the iconv tests will fail.  No other tests
should be affected.

Unset the `TZ` environment variable before running the tests, because
the Cygwin values are incompatible with the Microsoft C Runtime
Library.

Use 'make test' described above to run the tests.


WINDOWS VIA CROSS-COMPILER

To cross-compile the main Chez Scheme executable for Windows using
MinGW, specify suitable build tools to configure, perhaps using
--toolprefix= like this:

 ./configure -m=ta6nt --toolprefix=x86_64-w64-mingw32-

Then, make with "c/Mf-<machine type>" while supplying `cross=t` and
`o=o`, possibly like this:

  (cd ta6nt/c && make -f Mf-ta6nt cross=t o=o)

The executable is written to <machine type>/bin/<machine type>, and it
should be installed with boot files in ../boot/<machine type>/
relative to the executable.


EMSCRIPTEN

To target WebAssembly via Emscripten and `emcc`, use the
`--emscripten` flag:

 ./configure --emscripten

The default machine type is pb, but using the `--threads` and/or
`--pbarch` flags can adjust it to tpb, pb32l, or tpb32l. Boot files
for the machine type must be built already, and the configured
workarea is for building an executable and running output via node
with `make run`. The default workarea name is prefixed with "em-", so
output is written to "em-<machine type>/bin/"<machine type>",
including "scheme.js" and "scheme.html".

Boot files will be included in the result as preloads. Use
`--empetite` to omit the compiler as the "scheme.boot" boot file,
keeping only the runtime system as the "petite.boot" boot file.

To build Emscripten output that runs a specific program, compile the
program as a boot file that sets the `scheme-start` parameter, then
supply that boot file's path to `./configure` using the `--emboot=...`
flag. For example, suppose "demo.ss" contains the following:

 (define (go)
   (let loop ([i 10000000])
     (unless (zero? i)
       (loop (sub1 i)))))

 (scheme-start (lambda ()
                 (time (go))))

To compile this file, you'll need a build that runs on the current
machine for the target machine type, probably like this:

 ./configure --pb
 make
 make run

Using that build, create a boot file "demo.boot":

 (compile-file "demo.ss" "demo.so")
 (make-boot-file "/tmp/demo.boot" (list "petite") "/tmp/demo.so")

Finally, configure the Emscripten build to use "demo.boot":

 ./configure --pb --emscripten --emboot=demo.boot
 make


CROSS-COMPILING SCHEME PROGRAMS

Using

  make <machine type>.bootquick

creates a "boot" subdirectory for <machine type> containing boot file,
and in the process create a cross-compilation patch file as
"xc-<machine type>/s/xpatch". Loading that "xpatch" file into Chez
Scheme for the current platform changes functions like `compile-file`
and `make-boot-file` to generate code for the target <machine type>.
