X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fsbcl.1;h=c08c1c141564a7d307110379a6add146926486e1;hb=be7adb92bf0012ab07adac2943e73772dfad7911;hp=a195b161a2fb3890957ace534e610679fe0abd40;hpb=3951e5fcc8f3e5e183e7bd240a2fa4ca8cb6960e;p=sbcl.git diff --git a/doc/sbcl.1 b/doc/sbcl.1 index a195b16..c08c1c1 100644 --- a/doc/sbcl.1 +++ b/doc/sbcl.1 @@ -58,13 +58,12 @@ give you another prompt, and wait for your next input. E.g. * Many people like to run SBCL, like other Lisp systems, as a subprocess -under Emacs. The Emacs "ilisp" mode provides many convenient features, -like command line editing, tab completion, and various kinds of -coupling between Common Lisp source files and the interactive SBCL -subprocess, but can be somewhat fragile because it tries to be so -clever and intimate in its interactions with the Lisp subprocess. In -case of ilisp problems, running SBCL in the Emacs "shell" mode can a -useful substitute. +under Emacs. The Emacs "Slime" and "ilisp" modes provide many +convenient features, like command line editing, tab completion, and +various kinds of coupling between Common Lisp source files and the +interactive SBCL subprocess, but they can be somewhat fragile wrt. +packages and readtables, in which case SBCL in the Emacs "shell" mode +can a useful substitute. .SH OVERVIEW @@ -79,10 +78,10 @@ the BUGS section below. SBCL also includes various non-ANSI extensions, described more fully in the User Manual. Some of these are in the base system and others are "contrib" modules loaded on request using REQUIRE. For example, -to load the SB-BSD-SOCKETS module that providces TCP/IP connectivity, +to load the SB\-BSD\-SOCKETS module that providces TCP/IP connectivity, * (require 'asdf) - * (require 'sb-bsd-sockets) + * (require 'sb\-bsd\-sockets) Many Lispy extensions have been retained from CMU CL: .TP 3 @@ -139,7 +138,7 @@ the two projects disagree about what would be an improvement. Most extensions supported by CMU CL have been unbundled from SBCL, including Motif support, the Hemlock editor, search paths, the low-level Unix interface, the WIRE protocol, various user-level macros -and functions (e.g. LETF, ITERATE, MEMQ, REQUIRED-ARGUMENT), and many +and functions (e.g. LETF, ITERATE, MEMQ, REQUIRED\-ARGUMENT), and many others. SBCL inplements multithreading, but in a completely different fashion @@ -156,7 +155,7 @@ interface to C, and Gray streams .TP 3 \-- things which are universally available in Unix scripting languages, -e.g. RUN-PROGRAM and POSIX argv and getenv +e.g. RUN\-PROGRAM and POSIX argv and getenv .TP 3 \-- hooks into the low level workings of the system which can be useful @@ -164,9 +163,9 @@ for debugging, e.g. requesting that a particular function be executed whenever GC occurs, or tuning compiler diagnostic output .TP 3 \-- -unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more +unportable performance hacks, e.g. FREEZE\-TYPE and PURIFY. For more information about these, look at the online documentation for symbols -in the SB-EXT package, and look at the user manual. +in the SB\-EXT package, and look at the user manual. .PP There are also a few retained extensions which don't fall into any @@ -176,9 +175,9 @@ executable files. Some of the retained extensions have new names and/or different options than their CMU CL counterparts. For example, the SBCL function which saves a Lisp image to disk and kills the running process is -called SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's -SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's -SAVE-LISP does. +called SAVE\-LISP\-AND\-DIE instead of SAVE\-LISP, and SBCL's +SAVE\-LISP\-AND\-DIE supports fewer keyword options than CMU CL's +SAVE\-LISP does. (Why doesn't SBCL support more extensions natively? Why drop all those nice extensions from CMU CL when the code already exists? This @@ -223,20 +222,6 @@ are used. For more information about the compiler, see the user manual. -.SH DOCUMENTATION - -Currently, the documentation for the system is -.TP 3 -\-- -this man page -.TP 3 -\-- -the user manual -.TP 3 -\-- -doc strings and online help built into the SBCL executable -.PP - .SH COMMAND LINE SYNTAX Command line syntax can be considered an advanced topic; for ordinary @@ -253,10 +238,10 @@ command line arguments are passed on to user code. The full, unambiguous syntax for invoking SBCL at the command line is .TP 3 -.B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options] +.B sbcl [runtime options] \-\-end\-runtime\-options [toplevel options] \-\-end\-toplevel\-options [user options] .PP -For convenience, the --end-runtime-options and --end-toplevel-options +For convenience, the \-\-end\-runtime\-options and \-\-end\-toplevel\-options elements can be omitted. Omitting these elements can be convenient when you are running the program interactively, and you can see that no ambiguities are possible with the option values you are using. @@ -268,101 +253,99 @@ even if they was intended for the runtime system or the Lisp system. Supported runtime options are .TP 3 -.B --core +.B \-\-core Run the specified Lisp core file instead of the default. (See the FILES section for the standard core, or the system documentation for -SB-INT:SAVE-LISP-AND-DIE for information about how to create a +SB\-INT:SAVE\-LISP\-AND\-DIE for information about how to create a custom core.) Note that if the Lisp core file is a user-created core file, it may run a nonstandard toplevel which does not recognize the standard toplevel options. .TP 3 -.B --noinform +.B \-\-noinform Suppress the printing of any banner or other informational message at startup. (This makes it easier to write Lisp programs which work -cleanly in Unix pipelines. See also the "--noprint" and -"--disable-debugger" options.) +cleanly in Unix pipelines. See also the "\-\-noprint" and +"\-\-disable\-debugger" options.) .TP 3 -.B --help +.B \-\-help Print some basic information about SBCL, then exit. .TP 3 -.B --version +.B \-\-version Print SBCL's version information, then exit. .PP In the future, runtime options may be added to control behavior such as lazy allocation of memory. -Runtime options, including any --end-runtime-options option, +Runtime options, including any \-\-end\-runtime\-options option, are stripped out of the command line before the Lisp toplevel logic gets a chance to see it. The toplevel options supported by the standard SBCL core are .TP 3 -.B --sysinit +.B \-\-sysinit Load filename instead of the default system-wide initialization file. (See the FILES section.) There is no special option to cause no system-wide initialization file to be read, but on a Unix system -"--sysinit /dev/null" can be used to achieve the same effect. +"\-\-sysinit /dev/null" can be used to achieve the same effect. .TP 3 -.B --userinit +.B \-\-userinit Load filename instead of the default user initialization file. (See the FILES section.) There is no special option to cause no user -initialization file to be read, but on a Unix system "--userinit +initialization file to be read, but on a Unix system "\-\-userinit /dev/null" can be used to achieve the same effect. .TP 3 -.B --eval +.B \-\-eval After executing any initialization file, but before starting the read-eval-print loop on standard input, read and evaluate the command -given. More than one --eval option can be used, and all will be read +given. More than one \-\-eval option can be used, and all will be read and executed, in the order they appear on the command line. .TP 3 -.B --load -This is equivalent to --eval '(load "")'. The special +.B \-\-load +This is equivalent to \-\-eval '(load "")'. The special syntax is intended to reduce quoting headaches when invoking SBCL from shell scripts. .TP 3 -.B --noprint +.B \-\-noprint When ordinarily the toplevel "read-eval-print loop" would be executed, execute a "read-eval loop" instead, i.e. don't print a prompt and -don't echo results. Combined with the --noinform runtime option, this +don't echo results. Combined with the \-\-noinform runtime option, this makes it easier to write Lisp "scripts" which work cleanly in Unix pipelines. .TP 3 -.B --disable-debugger -This is equivalent to --eval '(sb-ext:disable-debugger)'. By default, +.B \-\-disable\-debugger +This is equivalent to \-\-eval '(sb\-ext:disable\-debugger)'. By default, a Common Lisp system tries to ask the programmer for help when it gets in trouble (by printing a debug prompt, then listening, on -*DEBUG-IO*). However, this is not useful behavior for a system running +*DEBUG\-IO*). However, this is not useful behavior for a system running with no programmer available, and this option tries to set up more appropriate behavior for that situation. This is implemented by -redefining INVOKE-DEBUGGER so that any call exits the process with a -failure code after printing a backtrace, and by redefining *DEBUG-IO* -to send its output to *ERROR-OUTPUT* and to raise an error if any -input is requested from it. (Note that because it is implemented by -modifying special variables and FDEFINITIONs, its effects persist in -.core files created by SB-EXT:SAVE-LISP-AND-DIE. If you want to undo -its effects, e.g. if you build a system unattended and then want to -operate a derived system interactively, see the SB-EXT:ENABLE-DEBUGGER -command.) +redefining INVOKE\-DEBUGGER so that any call exits the process with a +failure code after printing a backtrace. (Note that because it is +implemented by modifying special variables and FDEFINITIONs, its +effects persist in .core files created by SB\-EXT:SAVE\-LISP\-AND\-DIE. If +you want to undo its effects, e.g. if you build a system unattended +and then want to operate a derived system interactively, see the +SB\-EXT:ENABLE\-DEBUGGER command.) .PP -Regardless of the order in which --sysinit, --userinit, and --eval +Regardless of the order in which \-\-sysinit, \-\-userinit, and \-\-eval options appear on the command line, the sysinit file, if it exists, is loaded first; then the userinit file, if it exists, is loaded; then -any --eval commands are read and executed in sequence; then the +any \-\-eval commands are read and executed in sequence; then the read-eval-print loop is started on standard input. At any step, error -conditions or commands such as SB-EXT:QUIT can cause execution to be +conditions or commands such as SB\-EXT:QUIT can cause execution to be terminated before proceeding to subsequent steps. -Note that when running SBCL with the --core option, using a core file -created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel +Note that when running SBCL with the \-\-core option, using a core file +created by a user call to the SB\-EXT:SAVE\-LISP\-AND\-DIE, the toplevel options may be under the control of user code passed as arguments to -SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options +SB\-EXT:SAVE\-LISP\-AND\-DIE. For this purpose, the \-\-end\-toplevel\-options option itself can be considered a toplevel option, i.e. the user core, at its option, may not support it. In the standard SBCL startup sequence (i.e. with no user core -involved) toplevel options and any --end-toplevel-options option are +involved) toplevel options and any \-\-end\-toplevel\-options option are stripped out of the command line argument list before user code gets a chance to see it. @@ -371,7 +354,7 @@ chance to see it. SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD), Alpha (Linux, Tru64), PPC (Linux, Darwin/MacOS X), SPARC (Linux and Solaris 2.x), and MIPS (Linux). For information on other ongoing and possible -ports, see the sbcl-devel mailing list, and/or the web site. +ports, see the sbcl\-devel mailing list, and/or the web site. SBCL requires on the order of 16Mb RAM to run on X86 systems, though all but the smallest programs would be happier with 32Mb or more. @@ -395,8 +378,8 @@ function causes the compiler to believe you without checking. Thus compiling a file containing (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES)) (DEFUN SOMETIMES (X) (ODDP X)) -(DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME)) -then running (FOO 1) gives NOT-THIS-TIME, because the compiler +(DEFUN FOO (X) (IF (SOMETIMES X) 'THIS\-TIME 'NOT\-THIS\-TIME)) +then running (FOO 1) gives NOT\-THIS\-TIME, because the compiler relied on the truth of the DECLAIM without checking it. Some things are implemented very inefficiently. @@ -406,7 +389,7 @@ Multidimensional arrays are inefficient, especially multidimensional arrays of floating point numbers. .TP 3 \-- -The DYNAMIC-EXTENT declaration isn't implemented at all, not even +The DYNAMIC\-EXTENT declaration isn't implemented at all, not even for &REST lists or upward closures, so such constructs always allocate their temporary storage from the heap, causing GC overhead. .TP 3 @@ -443,7 +426,7 @@ sometimes expanded inline, (DEFUN F ...) (DECLAIM (NOTINLINE F)), doesn't do what you'd expect. (Instead, you have to declare the -function as SB-EXT:MAYBE-INLINE to get the desired effect.) +function as SB\-EXT:MAYBE\-INLINE to get the desired effect.) .TP 3 \-- There are several nonconforming bits of type syntax. E.g. (1) The type @@ -471,14 +454,14 @@ As with any software bug report, it's most helpful if you can provide enough information to reproduce the symptoms reliably, and if you say clearly what the symptoms are. E.g. "There seems to be something wrong with TAN of very small negative arguments. When I execute -(TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my -Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error." +(TAN LEAST\-NEGATIVE\-SINGLE\-FLOAT) interactively on sbcl-1.2.3 on my +Linux 4.5 X86 box, I get an UNBOUND\-VARIABLE error." .SH SUPPORT Various information about SBCL is available at -. The mailing lists there are the -recommended place to look for support. +. The mailing lists there are the recommended +place to look for support. .SH ENVIRONMENT @@ -500,19 +483,38 @@ a loader, used to read sbcl.core .I sbcl.core dumped memory image containing most of SBCL, to be loaded by the 'sbcl' executable. Looked for in $SBCL_HOME, -unless overridden by the --core option. +unless overridden by the \-\-core option. .TP .I sbclrc optional system-wide startup script, looked for in $SBCL_HOME/sbclrc -then /etc/sbclrc, unless overridden by the --sysinit command line +then /etc/sbclrc, unless overridden by the \-\-sysinit command line option. .TP .I .sbclrc optional per-user customizable startup script (in user's home -directory, or as specified by --userinit) +directory, or as specified by \-\-userinit) .SH AUTHORS Dozens of people have made substantial contributions to SBCL and its subsystems, and to the CMU CL system on which it was based, over the years. See the CREDITS file in the distribution for more information. + +.SH SEE ALSO + +Full SBCL documentation is maintained as a Texinfo manual. If is has +been installed, the command +.IP +.B info sbcl +.PP +should give you access to the complete manual. Depending on your +installation it may also be available in HTML and PDF formats in eg. +.IP +.B /usr/local/share/doc/sbcl/ +.PP +See the SBCL homepage +.IP +.B http://www.sbcl.org/ +.PP +for more information, including directions on how to subscribe to the +sbcl\-devel and sbcl\-help mailing-lists.