From f4ac15f540e22fc83d13005efaaebb75d4603fc3 Mon Sep 17 00:00:00 2001 From: Mark Harig Date: Sat, 23 Apr 2011 13:23:58 -0400 * 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 and which affect Guile's run-time behavior. --- doc/ref/guile-invoke.texi | 421 +++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 421 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..4d11c95 --- /dev/null +++ b/doc/ref/guile-invoke.texi @@ -0,0 +1,421 @@ 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 + 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 +Read and evaluate Scheme source code from the file @var{script}, as the address@hidden function would. After loading @var{script}, exit. 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...})}. + 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 +The option @option{--use-srfi} expects a comma-separated list of numbers, +each representing a SRFI number 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 using this option. + 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. Don't use @option{--listen} on +multi-user machines. Of course, if you don't 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, see @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's how to set the environment variable @env{ORGANIZATION} +to @samp{not very much} using Bash: + address@hidden +export ORGANIZATION="not very much" address@hidden example + address@hidden +and here's how to do it in csh or tcsh: + address@hidden +setenv ORGANIZATION "not very much" address@hidden example + +If you wish to retrieve or change the value of the shell environment +variables that effect the run-time behavior of Guile from within a +running instance of guile, see @xref{Runtime Environment}. + +Here are the environment variables that effect 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_HUSH address@hidden GUILE_HUSH +The @code{#/} notation for lists provokes a warning message from Guile. +This syntax will be removed from Guile in the near future. + +To disable the warning message, set the @env{GUILE_HUSH} environment +variable to any non-empty value. + address@hidden GUILE_INIT_MALLOC_LIMIT address@hidden GUILE_INIT_MALLOC_LIMIT address@hidden GUILE_MIN_YIELD_MALLOC address@hidden GUILE_MIN_YIELD_MALLOC address@hidden garbage collecting +The garbage collector uses lazy sweeping. This is reflected in the +output of the procedure @code{gc-stats}; since cells are being freed +when they are allocated, the cells-allocated field stays roughly +constant. + +For malloc-related triggers, the garbage collector uses the same +heuristic as the cell-triggered collections. It may be tuned with the +environment variable @env{GUILE_MIN_YIELD_MALLOC}. This is the +percentage for minimum yield of malloc-related triggers. The default is +forty (40) percent. + address@hidden sets the size in kilobytes of the initial +trigger for garbage collection. The default is two hundred (200) +kilobytes. + address@hidden GUILE_MAX_SEGMENT_SIZE address@hidden GUILE_MAX_SEGMENT_SIZE address@hidden GUILE_INIT_SEGMENT_SIZE_2 address@hidden GUILE_INIT_SEGMENT_SIZE_2 address@hidden GUILE_INIT_SEGMENT_SIZE_1 address@hidden GUILE_INIT_SEGMENT_SIZE_1 address@hidden GUILE_MIN_YIELD_2 address@hidden GUILE_MIN_YIELD_2 +Debugging operations for the freelist have been deprecated, along with +the C variables that control garbage collection. The environment +variables @env{GUILE_MAX_SEGMENT_SIZE}, @env{GUILE_INIT_SEGMENT_SIZE_2}, address@hidden, and @env{GUILE_MIN_YIELD_2} should be +used (units: bytes? kilobytes?) + 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_SYSTEM_LOAD_COMPILED_PATH address@hidden GUILE_SYSTEM_LOAD_COMPILED_PATH +Please provide a description of me, or delete me if I am obsolete. + address@hidden GUILE_SYSTEM_PATH address@hidden GUILE_SYSTEM_PATH +Please provide a description of me, or delete me if I am obsolete. + address@hidden GUILE_SYSTEM_LTDL_PATH address@hidden GUILE_SYSTEM_LTDL_PATH +Please provide a description of me, or delete me if I am obsolete. + address@hidden GUILE_INIT_SEGMENT_SIZE_1 address@hidden GUILE_INIT_SEGMENT_SIZE_1 address@hidden memory allocation, heap +The application can set up other default values for the +garbage-collection heap allocation parameters. Allocation of two-word +cell heaps is controlled by the environment variables address@hidden and @env{GUILE_MIN_YIELD_1}. address@hidden is the size of initial heap segment in +bytes (default is 360000). + address@hidden GUILE_MIN_YIELD_1 address@hidden GUILE_MIN_YIELD_1 +Minimum number of freed cells at each garbage collection in percent of +total heap size (default is forty (40) percent). + address@hidden GUILE_INIT_SEGMENT_SIZE_2 address@hidden GUILE_INIT_SEGMENT_SIZE_2 +Allocation of four-word cell heaps is controlled by the environment +variables @env{GUILE_INIT_SEGMENT_SIZE_2} and @env{GUILE_MIN_YIELD_2}. +Four-word cell heaps are used for real numbers and miscellaneous other +objects. + +Please provide a description of @env{GUILE_INIT_SEGMENT_SIZE_2}. + address@hidden GUILE_MIN_YIELD_2 address@hidden GUILE_MIN_YIELD_2 +Please provide a description of @env{GUILE_MIN_YIELD_2}. + address@hidden GUILE_MAX_SEGMENT_SIZE address@hidden GUILE_MAX_SEGMENT_SIZE +Maximal segment size in bytes? kilobytes? (default is 2097000) + address@hidden GUILE_INIT_HEAP_SIZE_1 address@hidden GUILE_INIT_HEAP_SIZE_1 +Please provide a description of me. + address@hidden GUILE_INIT_HEAP_SIZE_2 address@hidden GUILE_INIT_HEAP_SIZE_2 +Please provide a description of me. + address@hidden GUILE_WARN_DEPRECATED address@hidden GUILE_WARN_DEPRECATED +Please provide a description of me. + 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