From 03136ac2a64c13451932f6581656e34b9db06568 Mon Sep 17 00:00:00 2001 From: Mark Harig Date: Sun, 24 Apr 2011 15:52:27 -0400 Subject: [PATCH 3/3] * doc/ref/guile-invoke.texi (node Invoking Guile): Initial revision. This file contains the former section "Invoking Guile" that was included in the chapter "Programming in Scheme" as a subsection named "Command-line Options." It also includes a new subsection "Environment Variables," which describes those variables that can be set in the operating system before Guile is started which affect Guile's run-time behavior. --- doc/ref/guile-invoke.texi | 346 +++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 346 insertions(+), 0 deletions(-) create mode 100644 doc/ref/guile-invoke.texi diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi new file mode 100644 index 0000000..2674a71 --- /dev/null +++ b/doc/ref/guile-invoke.texi @@ -0,0 +1,346 @@ address@hidden -*-texinfo-*- address@hidden This is part of the GNU Guile Reference Manual. address@hidden Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011 address@hidden Free Software Foundation, Inc. address@hidden See the file guile.texi for copying conditions. + address@hidden Invoking Guile address@hidden Invoking Guile address@hidden invocation + +Many features of Guile depend on and can be changed by information that +the user provides either before or when Guile is started. Below is a +description of what information to provide and how to provide it. + address@hidden +* Command-line Options:: Command-line options understood by Guile. +* Environment Variables:: Variables that affect Guile's behavior. address@hidden menu + address@hidden Command-line Options address@hidden Command-line Options address@hidden Command-line Options address@hidden command-line arguments address@hidden arguments (command line) address@hidden options (command line) address@hidden switches (command line) address@hidden startup (command-line arguments) address@hidden invocation (command-line arguments) + +Here we describe Guile's command-line processing in detail. Guile +processes its arguments from left to right, recognizing the switches +described below. For examples, see @ref{Scripting Examples}. + address@hidden @code + address@hidden -s @var{script} @var{arg...} address@hidden script mode +By default, Guile will read a file named on the command line as a +script. However, it is possible to name a file using a leading hyphen, +for example, @file{-myfile.scm}. In this case, the file name must be +preceded by @option{-s} to tell Guile that a (script) file is being +named. Any command-line arguments @var{arg...} following @var{script} +become the script's arguments; the @code{command-line} function returns +a list of strings of the form @code{(@var{script} @var{arg...})}. +Scripts are read and evaluated as Scheme source code just as the address@hidden function would. After loading @var{script}, Guile exits. + address@hidden -c @var{expr} @var{arg...} address@hidden evaluate expression, command-line argument +Evaluate @var{expr} as Scheme code, and then exit. Any command-line +arguments @var{arg...} following @var{expr} become command-line +arguments; the @code{command-line} function returns a list of strings of +the form @code{(@var{guile} @var{arg...})}, where @var{guile} is the +path of the Guile executable. + address@hidden -- @var{arg...} +Run interactively, prompting the user for expressions and evaluating +them. Any command-line arguments @var{arg...} following the @option{--} +become command-line arguments for the interactive session; the address@hidden function returns a list of strings of the form address@hidden(@var{guile} @var{arg...})}, where @var{guile} is the path of the +Guile executable. + address@hidden -L @var{directory} +Add @var{directory} to the front of Guile's module load path. The given +directories are searched in the order given on the command line and +before any directories in the @env{GUILE_LOAD_PATH} environment +variable. Paths added here are @emph{not} in effect during execution of +the user's @file{.guile} file. + address@hidden -x @var{extension} +Add @var{extension} to the front of Guile's load extension list +(@pxref{Loading, @code{%load-extensions}}). The specified extensions +are tried in the order given on the command line, and before the default +load extensions. Extensions added here are @emph{not} in effect during +execution of the user's @file{.guile} file. + address@hidden -l @var{file} +Load Scheme source code from @var{file}, and continue processing the +command line. + address@hidden -e @var{function} +Make @var{function} the @dfn{entry point} of the script. After loading +the script file (with @option{-s}) or evaluating the expression (with address@hidden), apply @var{function} to a list containing the program name +and the command-line arguments---the list provided by the address@hidden function. + +A @option{-e} switch can appear anywhere in the argument list, but Guile +always invokes the @var{function} as the @emph{last} action it performs. +This is weird, but because of the way script invocation works under +POSIX, the @option{-s} option must always come last in the list. + +The @var{function} is most often a simple symbol that names a function +that is defined in the script. It can also be of the form @code{(@@ address@hidden @var{symbol})}, and in that case, the symbol is +looked up in the module named @var{module-name}. + +For compatibility with some versions of Guile 1.4, you can also use the +form @code{(symbol ...)} (that is, a list of only symbols that doesn't +start with @code{@@}), which is equivalent to @code{(@@ (symbol ...) +main)}, or @code{(symbol ...) symbol} (that is, a list of only symbols +followed by a symbol), which is equivalent to @code{(@@ (symbol ...) +symbol)}. We recommend to use the equivalent forms directly since they +correspond to the @code{(@@ ...)} read syntax that can be used in +normal code. See @ref{Using Guile Modules} and @ref{Scripting +Examples}. + address@hidden -ds +Treat a final @option{-s} option as if it occurred at this point in the +command line; load the script here. + +This switch is necessary because, although the POSIX script invocation +mechanism effectively requires the @option{-s} option to appear last, the +programmer may well want to run the script before other actions +requested on the command line. For examples, see @ref{Scripting +Examples}. + address@hidden \ +Read more command-line arguments, starting from the second line of the +script file. @xref{The Meta Switch}. + address@hidden address@hidden address@hidden loading srfi modules (command line) +The option @option{--use-srfi} expects a comma-separated list of numbers, +each representing a SRFI module to be loaded into the interpreter +before evaluating a script file or starting the REPL. Additionally, +the feature identifier for the loaded SRFIs is recognized by +the procedure @code{cond-expand} when this option is used. + +Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13 +('string library') before the GUILE interpreter is started: + address@hidden +guile --use-srfi=8,13 address@hidden example + address@hidden --debug address@hidden debugging virtual machine (command line) +Start with the debugging virtual machine (VM) engine. Using the +debugging VM will enable support for VM hooks, which are needed for +tracing, breakpoints, and accurate call counts when profiling. The +debugging VM is slower than the regular VM, though, by about ten +percent. @xref{VM Hooks}, for more information. + +By default, the debugging VM engine is only used when entering an +interactive session. When executing a script with @option{-s} or address@hidden, the normal, faster VM is used by default. + address@hidden address@hidden --no-debug address@hidden debugging virtual machine (command line) +Do not use the debugging VM engine, even when entering an interactive +session. + address@hidden -q address@hidden init file, not loading address@hidden @file{.guile} file, not loading +Do not load the initialization file, @file{.guile}. This option only +has an effect when running interactively; running scripts does not load +the @file{.guile} file. @xref{Init File}. + address@hidden address@hidden +While this program runs, listen on a local port or a path for REPL +clients. If @var{p} starts with a number, it is assumed to be a local +port on which to listen. If it starts with a forward slash, it is +assumed to be a path to a UNIX domain socket on which to listen. + +If @var{p} is not given, the default is local port 37146. If you look +at it upside down, it almost spells ``Guile''. If you have netcat +installed, you should be able to @kbd{nc localhost 37146} and get a +Guile prompt. Alternately you can fire up Emacs and connect to the +process; see @ref{Using Guile in Emacs} for more details. + +Note that opening a port allows anyone who can connect to that port---in +the TCP case, any local user---to do anything Guile can do, as the user +that the Guile process is running as. Do not use @option{--listen} on +multi-user machines. Of course, if you do not pass @option{--listen} to +Guile, no port will be opened. + +That said, @option{--listen} is great for interactive debugging and +development. + address@hidden + address@hidden --auto-compile +Compile source files automatically (default behavior). + address@hidden + address@hidden --no-auto-compile +Disable automatic source file compilation. + address@hidden + address@hidden address@hidden, }--help +Display help on invoking Guile, and then exit. + address@hidden address@hidden, }--version +Display the current version of Guile, and then exit. + address@hidden table + address@hidden Environment Variables address@hidden Environment Variables address@hidden environment variables address@hidden shell address@hidden initialization +The @dfn{environment} is a feature of the operating system; it consists +of a collection of variables with names and values. Each variable is +called an @dfn{environment variable} (or, sometimes, a ``shell +variable''); environment variable names are case-sensitive, and it is +conventional to use upper-case letters only. The values are all text +strings, even those that are written as numerals. (Note that here we +are referring to names and values that are defined in the operating +system shell from which Guile is invoked. This is not the same as a +Scheme environment that is defined within a running instance of Guile. +For a description of Scheme environments, @pxref{About Environments}.) + +How to set environment variables before starting Guile depends on the +operating system and, especially, the shell that you are using. For +example, here is how to tell Guile to provide detailed warning messages +about deprecated features by setting @env{GUILE_WARN_DEPRECATED} using +Bash: + address@hidden +$ export GUILE_WARN_DEPRECATED="detailed" +$ guile address@hidden example + address@hidden +Or, detailed warnings can be turned on for a single invocation using: + address@hidden +$ env GUILE_WARN_DEPRECATED="detailed" guile address@hidden example + +If you wish to retrieve or change the value of the shell environment +variables that affect the run-time behavior of Guile from within a +running instance of Guile, see @ref{Runtime Environment}. + +Here are the environment variables that affect the run-time behavior of +Guile: + address@hidden @env address@hidden GUILE_AUTO_COMPILE address@hidden GUILE_AUTO_COMPILE +This is a flag that can be used to tell Guile whether or not to compile +Scheme source files automatically. Starting with Guile 2.0, Scheme +source files will be compiled automatically, by default. If address@hidden is set to zero (0), then Scheme files are not +compiled automatically. + +If a compiled @file{.go} file corresponding to a @file{.scm} file is not +found or is not newer than the @file{.scm} file, the @file{.scm} file +will be compiled on the fly, and the resulting @file{.go} file stored +away. An advisory note will be printed on the console. + +Note that this mechanism depends on the timestamp of the @file{.go} file +being newer than that of the @file{.scm} file; if the @file{.scm} or address@hidden files are moved after installation, care should be taken to +preserve their original timestamps. + +Auto-compiled files will be stored in the directory address@hidden/guile/ccache}, where @env{XDG_CACHE_HOME} defaults +to the directory @file{$HOME/.cache}. This directory will be created if +it does not already exist. + +To inhibit automatic compilation, set the @env{GUILE_AUTO_COMPILE} +environment variable to zero (0), or pass @option{--no-auto-compile} on +the Guile command line. + address@hidden GUILE_HISTORY address@hidden GUILE_HISTORY +This variable names the file that holds the Guile REPL command history. +You can specify a different history file by setting this environment +variable. By default, the history file is @file{$HOME/.guile_history}. + address@hidden GUILE_LOAD_COMPILED_PATH address@hidden GUILE_LOAD_COMPILED_PATH +This variable may be used to augment the path that is searched for +compiled Scheme files (@file{.go} files) when loading. Its value should +be a colon-separated list of directories, which will be prefixed to the +value of the default search path stored in @code{%load-compiled-path}. + +Here is an example using the Bash shell that adds the current directory, address@hidden, and the relative directory @file{../my-library} to address@hidden: + address@hidden +$ export GUILE_LOAD_COMPILED_PATH=".:../my-library" +$ guile -c '(display %load-compiled-path) (newline)' +(. ../my-library /usr/local/lib/guile/2.0/ccache) address@hidden example + address@hidden GUILE_LOAD_PATH address@hidden GUILE_LOAD_PATH +This variable may be used to augment the path that is searched for +Scheme files when loading. Its value should be a colon-separated list +of directories, which will be prefixed to the value of the default +search path stored in @code{%load-path}. + +Here is an example using the Bash shell that adds the current directory +and the parent of the current directory to @code{%load-path}: + address@hidden +$ env GUILE_LOAD_PATH=".:.." \ +guile -c '(display %load-path) (newline)' +(. .. /usr/local/share/guile/2.0 \ +/usr/local/share/guile/site/2.0 \ +/usr/local/share/guile/site /usr/local/share/guile) address@hidden example + +(Note: The line breaks, above, are for documentation purposes only, and +not required in the actual example.) + address@hidden GUILE_WARN_DEPRECATED address@hidden GUILE_WARN_DEPRECATED +As Guile evolves, some features will be eliminated or replaced by newer +features. To help users migrate their code as this evolution occurs, +Guile will issue warning messages about code that uses features that +have been marked for eventual elimination. @env{GUILE_WARN_DEPRECATED} +can be set to ``no'' to tell Guile not to display these warning +messages, or set to ``detailed'' to tell Guile to display more lengthy +messages describing the warning. @xref{Deprecation}. + address@hidden HOME address@hidden HOME +Guile uses the environment variable @env{HOME}, the name of your home +directory, to locate various files, such as @file{.guile} or address@hidden + address@hidden LTDL_LIBRARY_PATH address@hidden LTDL_LIBRARY_PATH +Guile now adds its install prefix to the @env{LTDL_LIBRARY_PATH}. + +Users may now install Guile in non-standard directories and run +`/path/to/bin/guile', without having also to set @env{LTDL_LIBRARY_PATH} +to include `/path/to/lib'. + address@hidden table + address@hidden Local Variables: address@hidden mode: texinfo address@hidden TeX-master: "guile" address@hidden End: -- 1.7.4.4