From: Matt Birkholz Date: Sat, 14 Dec 2019 04:23:32 +0000 (-0700) Subject: user.texinfo: Merged with 10.1.10 and updated for Ubuntu 19.10. X-Git-Tag: mit-scheme-pucked-10.1.20~4 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=5d59273c9aa02b918773a9b397fee04d658b2305;p=mit-scheme.git user.texinfo: Merged with 10.1.10 and updated for Ubuntu 19.10. --- diff --git a/doc/user-manual/user.texinfo b/doc/user-manual/user.texinfo index 27646de4e..7a97d0e96 100644 --- a/doc/user-manual/user.texinfo +++ b/doc/user-manual/user.texinfo @@ -103,7 +103,7 @@ This experimental version is a snapshot of the @code{master} branch in the MIT/GNU Scheme project source repository on Savannah, with additional plugins. The differences between this ``pucked'' version and @code{master} have been kept to a minimum. At the moment they are -focused on replacing the microcode modules with plugins. A complete +focused on supporting a large library of plugins. A complete list of user-visible changes is provided in @ref{Release Notes}. @cindex Web site @@ -174,8 +174,8 @@ Copyright (C) 2019 Massachusetts Institute of Technology This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -Image saved on Saturday February 16, 2019 at 1:54:09 AM - Release 10.1.10 || SF || LIAR/x86-64 +Image saved on Friday December 13, 2019 at 4:34:49 PM + Release 10.1.20 || SF || LIAR/x86-64 ;Loading Edwin... done @end smallexample @@ -406,6 +406,24 @@ Specifies that Scheme is running as a subprocess of GNU Emacs. This option is automatically supplied by GNU Emacs, and should not be given under other circumstances. +@item --interactive +@opindex --interactive +If this option isn't specified, and Scheme's standard @acronym{I/O} is +not a terminal, Scheme will detach itself from its controlling +terminal, which prevents it from getting signals sent to the process +group of that terminal. If this option is specified, Scheme will not +detach itself from the controlling terminal. + +This detaching behavior is useful for running Scheme as a background +job. For example, using Bourne shell, the following will run Scheme +as a background job, redirecting its input and output to files, and +preventing it from being killed by keyboard interrupts or by logging +out: + +@example +mit-scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 & +@end example + @item --nocore @opindex --nocore Specifies that Scheme should not generate a core dump under any @@ -1418,7 +1436,8 @@ The default value is @code{#f}. @deffn procedure sf filename [destination] @code{sf} is the program that transforms a source-code file into binary -SCode form. It performs numerous optimizations that can make your +SCode form; it is used on machines that do not support native-code +compilation. It performs numerous optimizations that can make your programs run considerably faster than unoptimized interpreted code. Also, the binary files that it generates load very quickly compared to source-code files. @@ -2308,8 +2327,8 @@ kinds of number. A @dfn{fixnum} is an exact integer that is small enough to fit in a machine word. In MIT/GNU Scheme, fixnums are 26 bits on 32-bit machines, and 58 bits on 64-bit machines; it is reasonable to assume -that fixnums are at least 24 bits. Fixnums are signed and they are -encoded using 2's complement. +that fixnums are at least 24 bits. Fixnums are signed; they are encoded +using 2's complement. All exact integers that are small enough to be encoded as fixnums are always encoded as fixnums---in other words, any exact integer that is @@ -3837,11 +3856,11 @@ 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 in this ``pucked'' version is almost entirely -contained in the new plugins. One ``old'' plugin, Edwin, has -significant changes that accommodate Gtk screens, but this change -should not be apparent to casual users. If your code does not hack -Edwin and you previously said +The experimental code unique to this ``pucked'' version of Scheme is +almost entirely contained in the new plugins. One ``old'' plugin, +Edwin, has significant changes that accommodate Gtk screens, but this +change should not be apparent to casual users. If your code does not +hack Edwin and you previously said @example mit-scheme --load my-code @@ -3896,7 +3915,7 @@ only for your stable worlds. @appendix Installation MIT/GNU Scheme Pucked and its plugins are now available as packages -for recent versions of Ubuntu on Intel@registeredsymbol{}64 and IA-32 +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, @@ -3945,11 +3964,7 @@ sudo add-apt-repository \ "deb http://birchwood-abbey.net/ubuntu/18.04/ birchwood main" @end example -or by editing files in @file{/etc/apt/}. Note that if you are -installing to an amd64 machine with ``multiarch'' enabled (such that -the command @code{dpkg --print-foreign-architectures} prints -@code{i386}) you will want to add @code{[arch=amd64]} after @code{deb} -in the repository description to avoid spurious warnings. +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. @@ -3961,30 +3976,31 @@ original MIT/GNU Scheme. You could do this with Apt by entering the following commands. @example -sudo apt-get update -sudo apt-get install mit-scheme-pucked-x11-screen +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{three} packages named @code{mit-scheme-pucked} with the -@emph{same} version, each compiled for Ubuntu 16.04, 18.04 or 18.10. +be @emph{four} packages named @code{mit-scheme-pucked} with the +@emph{same} version, each compiled for Ubuntu 16.04, 18.04, 19.04 and +19.10. 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/18.10/}). +@url{http://birchwood-abbey.net/ubuntu/19.10/}). @example -sudo apt-get remove mit-scheme-pucked +sudo apt remove mit-scheme-pucked sudo add-apt-repository -r \ - "deb http://birchwood-abbey.net/ubuntu/18.04/ birchwood main" + "deb http://birchwood-abbey.net/ubuntu/19.04/ birchwood main" sudo add-apt-repository \ - "deb http://birchwood-abbey.net/ubuntu/18.10/ birchwood main" -sudo apt-get update -sudo apt-get install mit-scheme-pucked-x11-screen + "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. @@ -3994,7 +4010,7 @@ Links to the files can be found on the project home page. @uref{https://birchwood-abbey.net/~puck/Scheme/} @end example -You will need to know your Ubuntu version (e.g. 18.10) and Debian +You will need to know your Ubuntu version (e.g. 19.10) 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} @@ -4019,16 +4035,16 @@ gpg --import ~/Downloads/codemaster.txt Then verify the signature on the @file{.changes} file like this: @example -gpg --verify ~/Downloads/mit-scheme-pucked_10.1.10-1_amd64.changes +gpg --verify ~/Downloads/mit-scheme-pucked_10.1.20-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_10.1.10-1_amd64.deb \ - mit-scheme-pucked_10.1.10-1_amd64.changes -sha256sum mit-scheme-pucked_10.1.10-1_amd64.deb +grep mit-scheme-pucked_10.1.20-1_amd64.deb \ + mit-scheme-pucked_10.1.20-1_amd64.changes +sha256sum mit-scheme-pucked_10.1.20-1_amd64.deb @end example After you have downloaded and verified all of the required files, you @@ -4037,12 +4053,12 @@ can install them, required packages first, e.g.@: starting with @code{mit-scheme-pucked-x11-screen}. @verbatim P=~/Downloads/mit-scheme-pucked -sudo dpkg --install ${P}_10.1.10-1_amd64.deb -sudo dpkg --install ${P}-gdbm_0.2.1-1_amd64.deb -sudo dpkg --install ${P}-blowfish_0.2.1-1_amd64.deb -sudo dpkg --install ${P}-edwin_3.116.1-1_amd64.deb -sudo dpkg --install ${P}-x11_0.2.1-1_amd64.deb -sudo dpkg --install ${P}-x11-screen_0.2.1-1_amd64.deb +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 @@ -4066,7 +4082,7 @@ Debian-like systems: @code{gcc} @code{make} @code{libncurses-dev} @item CentOS-like systems: @code{gcc} @code{make} @code{ncurses-devel} @item -macOS systems: @code{Xcode} +macOS systems: Command line developer tools @samp{xcode-select --install} @end itemize The Scheme interpreter is built from C code and installed much like @@ -4080,33 +4096,30 @@ will need to know the name of your Scheme architecture. If your computer has an older Intel IA-32 (32 bit) CPU, your architecture is named @code{i386}. If it has a newer Intel64 CPU (64 bit, e.g. a Core or an i3 or i5 or i7), it is named @code{x86-64}. The binary archives -contain machine instructions for one of these, or for 32 and 64 bit -virtual machines named @code{svm1-32} and @code{svm1-64}. The virtual -machines are part of the Scheme interpreter and are about 6 times -slower than the native machine. +contain machine instructions for one of these. Click on the name of your Scheme machine architecture in the list of binaries for the core system. Save the file, which should be named -something like @file{mit-scheme-pucked-10.1.10-i386.tar.gz}. +something like @file{mit-scheme-pucked-10.1.20-x86-64.tar.gz}. Compile the Scheme interpreter using the following steps: @enumerate @item Unpack the archive to create your build directory, e.g.@: -@file{mit-scheme-pucked-10.1.10}. For example, +@file{mit-scheme-pucked-10.1.20}. For example, @example -tar xzf mit-scheme-pucked-10.1.10-i386.tar.gz +tar xzf mit-scheme-pucked-10.1.20-x86-64.tar.gz @end example -will create a new directory @file{mit-scheme-pucked-10.1.10}. +will create a new directory @file{mit-scheme-pucked-10.1.20}. @item Move into the @file{src} subdirectory of the new directory: @example -cd mit-scheme-pucked-10.1.10/src +cd mit-scheme-pucked-10.1.20/src @end example @item @@ -4119,18 +4132,14 @@ Configure the software: 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}, pass the -@option{--prefix} option to the configure script, as in the -command line below. - -@example -./configure --prefix=/opt -@end example +installed somewhere else, for example @file{/opt/mit-scheme}, pass the +@option{--prefix} option to the configure script, as in +@kbd{./configure --prefix=/opt/mit-scheme}. The configure script accepts all of the normal arguments for such scripts, and additionally accepts some that are specific to MIT/GNU Scheme. To see the possible arguments and their meanings, run the -command @code{./configure --help}. +command @kbd{./configure --help}. @item Build the software: @@ -4146,11 +4155,30 @@ Install the software: 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 -@section Plugin Selection and Installation +@heading Plugins The project home page lists the available plugins with short descriptions to help you choose from among them. Click on the