state that prevents Edwin from running.
@end deffn
-@node GNU Free Documentation License, Environment-variable Index, Edwin, Top
+@node Release Notes
+@appendix Release Notes
+
+This experimental version of MIT/GNU Scheme got a new project name,
+MIT/GNU Scheme Pucked, and a new command name,
+@code{mit-scheme-pucked}, so that it can be installed alongside the
+stable release. While it comes with experimental plugins and a
+strange name, the core of the system is largely unchanged. Note that
+this is a @emph{bleeding edge} core. The head of the MIT/GNU Scheme
+project's development branch on Savannah is merged in frequently.
+
+The experimental code unique to this ``pucked'' version of Scheme is
+almost entirely contained in the new plugins. One ``old'' plugin,
+Edwin, contains significant changes to accommodate Gtk screens, but these
+changes should not be apparent to casual users. If your code does not
+hack Edwin and you previously said
+
+@example
+mit-scheme --load my-code
+@end example
+
+@noindent
+you should be able to say
+
+@example
+mit-scheme-pucked --load my-code
+@end example
+
+@noindent
+and be no worse off.
+
+@noindent
+Users may want to use the following enhancements in their code.
+
+@itemize @bullet
+@item
+The Debian packaging includes a @file{.desktop} file in
+@url{freedesktop.org} format. In the right place it makes this Scheme
+available through an icon (a lambda holding a fountain pen) in a
+@file{.desktop} aware application launcher.
+
+@item
+The installation process includes HTML documentation by default. In
+the right place these files are available in your web browser, whether
+online or offline, using a file URL like the following Ubuntu locator.
+
+@example
+@url{file:///usr/share/doc/mit-scheme-pucked/html/index.html}
+@end example
+
+HTML documentation for installed plugins is found in the same location.
+
+@item
+The @code{planetarium} plugin can draw a simple tellurion, but that's
+about all.
+
+@item
+The @code{gtk-screen} plugin allows Edwin to display text using Pango.
+@end itemize
+
+@cindex cond-expand feature
+@cindex feature, cond-expand
+The @code{cond-expand} feature @code{pucked} will be present, to keep
+your adaptations to this experiment separate from old code intended
+only for your stable worlds.
+
+@node Installation
+@appendix Installation
+
+MIT/GNU Scheme Pucked and its plugins are now available as packages
+for recent versions of Ubuntu on Intel@registeredsymbol{}64
+architecture machines. If
+@uref{https://birchwood-abbey.net/~puck/Scheme/} has links to packages
+for your Ubuntu, you can use your Ubuntu package manager to add,
+remove and update Scheme and its plugins. @xref{Ubuntu Installation}.
+
+Scheme is also available as ``binary'' archives that can be unpacked,
+compiled and installed on non-Ubuntu, even non-GNU/Linux operating
+systems, if they are sufficiently Unix-like. Installation requires
+something resembling the customary GNU tool chain. The Scheme
+interpreter will be built and installed much like any other (GNU) C
+program on your system. Detailed instructions for installing Scheme
+this way can be found below. @xref{Unix Installation}.
+
+@menu
+* Ubuntu Installation::
+* Unix Installation::
+@end menu
+
+@node Ubuntu Installation
+@section Ubuntu Installation
+
+Using an Ubuntu package manager, you can add Birchwood Abbey to your
+list of package sources and install or update Scheme and its plugins
+just like other packages.
+
+You would begin by installing the GPG key used to sign the packages.
+It is available at this URL:
+
+@example
+@url{https://birchwood-abbey.net/codemaster.txt}
+@end example
+
+You should save the page, e.g. as @file{codemaster.txt} in your
+downloads folder, then install the key with the @code{apt-key}
+command.
+
+@example
+sudo apt-key add ~/Downloads/codemaster.txt
+@end example
+
+Next add the repository to your list of package sources. On Ubuntu
+18.04 you would use this command:
+
+@example
+sudo add-apt-repository \
+ "deb http://birchwood-abbey.net/ubuntu/18.04/ birchwood main"
+@end example
+
+or by editing files in @file{/etc/apt/}.
+
+Finally, use your package manager to update its list of available
+packages and choose the Scheme plugins you would like to install.
+Scheme itself will be automatically selected because all of the
+plugins depend on it. You might choose the
+@code{mit-scheme-pucked-x11-screen} plugin because it depends on
+Scheme and Edwin and makes Scheme a graphical X11 application like the
+original MIT/GNU Scheme. You could do this with Apt by entering the
+following commands.
+
+@example
+sudo apt update
+sudo apt install mit-scheme-pucked-x11-screen
+@end example
+
+Note that the Ubuntu version number is part of the source URL. This
+allows new versions of Scheme and its plugins to be provided for old
+versions of Ubuntu. (Normally you would upgrade to new versions of
+Ubuntu to get new versions of Scheme.) However this means there may
+be @emph{four} packages named @code{mit-scheme-pucked} with the
+@emph{same} version, each compiled for Ubuntu 16.04, 18.04, 19.10 and
+20.04.
+
+When you upgrade to a new version of Ubuntu you should first remove
+the @code{mit-scheme-pucked} package (which will remove all of its
+plugins), then re-install them after changing the source URL (e.g. to
+@url{http://birchwood-abbey.net/ubuntu/19.10/}).
+
+@example
+sudo apt remove mit-scheme-pucked
+sudo add-apt-repository -r \
+ "deb http://birchwood-abbey.net/ubuntu/19.04/ birchwood main"
+sudo add-apt-repository \
+ "deb http://birchwood-abbey.net/ubuntu/19.10/ birchwood main"
+sudo apt update
+sudo apt install mit-scheme-pucked-x11-screen
+@end example
+
+You can also download the package files and install them by hand.
+Links to the files can be found on the project home page.
+
+@example
+@uref{https://birchwood-abbey.net/~puck/Scheme/}
+@end example
+
+You will need to know your Ubuntu version (e.g. 20.04) and Debian
+machine architecture (e.g. amd64), then click on the corresponding
+link. You will need to do this for your chosen plugin, all of the
+plugins it requires, and Scheme itself (the @code{mit-scheme-pucked}
+package).
+
+For example if you want Edwin to display in an X11 window you will
+want to install the @code{x11-screen} plugin which requires the
+@code{edwin} plugin which requires several more. Each entry on the
+project home page lists the package files available for a plugin
+and all of its required plugins.
+
+If you would like to verify that the downloaded files are authentic
+you will need the corresponding @file{.changes} files. Each contains
+checksums for the package files and is signed. If you saved Puck's
+GPG key in @file{~/Downloads/codemaster.txt}, you can add it to your
+keyring like this:
+
+@example
+gpg --import ~/Downloads/codemaster.txt
+@end example
+
+Then verify the signature on the @file{.changes} file like this:
+
+@example
+gpg --verify ~/Downloads/mit-scheme-pucked_@value{VERSION}-1_amd64.changes
+@end example
+
+And compare the checksum in the @file{.changes} file to one
+computed from your downloaded file.
+
+@example
+grep mit-scheme-pucked_@value{VERSION}-1_amd64.deb \
+ mit-scheme-pucked_@value{VERSION}-1_amd64.changes
+sha256sum mit-scheme-pucked_@value{VERSION}-1_amd64.deb
+@end example
+
+After you have downloaded and verified all of the required files, you
+can install them, required packages first, e.g.@: starting with
+@code{mit-scheme-pucked} and finishing with
+@code{mit-scheme-pucked-x11-screen}.
+@verbatim
+P=~/Downloads/mit-scheme-pucked
+sudo dpkg --install ${P}_10.1.20-1_amd64.deb
+sudo dpkg --install ${P}-gdbm_1.0.6-1_amd64.deb
+sudo dpkg --install ${P}-blowfish_1.1.6-1_amd64.deb
+sudo dpkg --install ${P}-edwin_3.117.7-1_amd64.deb
+sudo dpkg --install ${P}-x11_1.3.4-1_amd64.deb
+sudo dpkg --install ${P}-x11-screen_1.0.6-1_amd64.deb
+@end verbatim
+
+As mentioned above, when you upgrade to a new version of Ubuntu you
+should first remove the @code{mit-scheme-pucked} package (which should
+remove all of its plugins), then install the packages built for your
+new Ubuntu.
+
+@node Unix Installation
+@section Unix Installation
+
+We will use as an example the installation for GNU/Linux. The
+installation for other unix systems is similar. There are several
+references to @var{ARCH} below; these refer to the computer
+architecture that Scheme is compiled for: either @samp{i386}
+@samp{x86-64}, @samp{aarch64}, or @samp{svm1}.
+
+@mitgnu{} is distributed as a compressed `tar' file. The tar
+file contains both source and binary files; the binary files are
+pre-compiled Scheme code for a particular computer architecture. The
+source files are C programs that need to be compiled.
+
+@heading Requirements
+
+At a minimum, you will need a C compiler (e.g. @samp{gcc}) and a
+@samp{make} program, and a ``curses'' library. For example, here are
+the packages that must be installed on some popular systems:
+
+@itemize @bullet
+@item
- Debian-like systems: @code{gcc} @code{make} @code{libncurses-dev}
++Debian-like systems: @code{gcc} @code{make} @code{m4} @code{libncurses-dev}
+@item
- CentOS-like systems: @code{gcc} @code{make} @code{ncurses-devel}
++CentOS-like systems: @code{gcc} @code{make} @code{m4} @code{ncurses-devel}
+@item
+macOS systems: Command line developer tools @samp{xcode-select --install}
+@end itemize
+
+Additionally, if you want support for X11 graphics, you'll need:
+
+@itemize @bullet
+@item
+Debian-like systems: @code{libx11-dev}
+@item
+CentOS-like systems: @code{libX11-devel}
+@item
+macOS systems: @code{XQuartz} (from @url{https://www.xquartz.org/})
+@end itemize
+
+@heading Steps
+
+In order to install the software, it's necessary to configure and
+compile the C code, then to install the combined C and Scheme
+binaries, with the following steps.
+
+@enumerate
+@item
+Unpack the tar file,
+@file{mit-scheme-pucked-@var{VERSION}-@var{ARCH}.tar.gz}, into the directory
+@file{mit-scheme-pucked-@var{VERSION}}. For example,
+
+@example
- tar xzf mit-scheme-pucked-@value{VERSION}-x86-64.tar.gz
++tar xzf mit-scheme-pucked-@var{VERSION}-x86-64.tar.gz
+@end example
+
- will create a new directory @file{mit-scheme-pucked-@value{VERSION}}.
++will create a new directory @file{mit-scheme-pucked-@var{VERSION}}.
+
+@item
+Move into the @file{src} subdirectory of the new directory:
+
+@example
- cd mit-scheme-pucked-@value{VERSION}/src
++cd mit-scheme-pucked-@var{VERSION}/src
+@end example
+
+@item
+Configure the software:
+
+@example
+./configure
+@end example
+
+By default, the software will be installed in @file{/usr/local}, in
+the subdirectories @file{bin} and @file{lib}. If you want it
+installed somewhere else, for example @file{/opt/mit-scheme-pucked}, pass the
+@option{--prefix} option to the configure script, as in
+@kbd{./configure --prefix=/opt/mit-scheme-pucked}.
+
+The configure script accepts all the normal arguments for such
+scripts, and additionally accepts some that are specific to @mitgnu{}.
+To see all the possible arguments and their meanings, run the command
+@kbd{./configure --help}. However, do not specify the following
+options, which are all preconfigured to the right values; doing so
+will probably cause the build to fail:
+
+@example
+--enable-native-code
+--enable-host-scheme-test
+--enable-cross-compiling
+--with-compiler-target
+--with-default-target
+--with-scheme-build
+@end example
+
+@item
+Build the software:
+
+@example
+make
+@end example
+
+@item
+Install the software:
+
+@example
+make install
+@end example
+
+Depending on configuration options and file-system permissions, you
+may need super-user privileges to do the installation steps.
+
+@item
+Build the documentation:
+
+@example
+cd ../doc
+./configure
+make
+@end example
+
+@item
+Install the documentation:
+
+@example
+make install-info install-html install-pdf
+@end example
+
+Depending on configuration options and file-system permissions, you
+may need super-user privileges to do the installation step.
+@end enumerate
+
+@heading Plugins
+
+After you have installed Scheme you may want to install several
+@dfn{plugins}. Scheme no longer uses dynamically loaded microcode
+modules installed with Scheme. The micromodules have been converted
+into plugins: new subsystems that use the C/FFI to dynamically load
+the same code. Instead you configure, build, and install additional
+plugins after installing the core system.
+
+By default, the following plugins are built and installed:
+@file{edwin}, @file{imail}, @file{x11}, and @file{x11-screen}. (The
+latter two only if X11 libraries are installed on your system.) To
+get all of the functionality previously available in version 9.2 you
+will need to build and install the remaining plugins included in the
+@file{src} subdirectory: @file{blowfish}, @file{gdbm},
+and @file{pgsql}. These plugins are all configured, built, and
+installed in the GNU standard way. See the @file{README} file in each
+plugin's source directory for complete details.
+
+More plugins can be found on the project home page. Short
+descriptions help to choose from among them. Click on the source
+archive link for each plugin you would like to use, and any plugins it
+requires. You will need to build and install each plugin before any
+that require it. These plugins are not distributed in binary form
+except as Ubuntu packages.
+
+@heading Cleanup
+
+After installing Scheme and your desired plugins, you can delete the
+source directory:
+
+@example
+cd ../..
+rm -rf mit-scheme-pucked-@value{VERSION}
+@end example
+
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
projects / mit-scheme.git / commitdiff