2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011, 2013
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section Invoking Guile
11 Many features of Guile depend on and can be changed by information that
12 the user provides either before or when Guile is started. Below is a
13 description of what information to provide and how to provide it.
16 * Command-line Options:: Command-line options understood by Guile.
17 * Environment Variables:: Variables that affect Guile's behavior.
20 @node Command-line Options
21 @subsection Command-line Options
22 @cindex Command-line Options
23 @cindex command-line arguments
24 @cindex arguments (command line)
25 @cindex options (command line)
26 @cindex switches (command line)
27 @cindex startup (command-line arguments)
28 @cindex invocation (command-line arguments)
30 Here we describe Guile's command-line processing in detail. Guile
31 processes its arguments from left to right, recognizing the switches
32 described below. For examples, see @ref{Scripting Examples}.
36 @item @var{script} @var{arg...}
37 @itemx -s @var{script} @var{arg...}
39 By default, Guile will read a file named on the command line as a
40 script. Any command-line arguments @var{arg...} following @var{script}
41 become the script's arguments; the @code{command-line} function returns
42 a list of strings of the form @code{(@var{script} @var{arg...})}.
44 It is possible to name a file using a leading hyphen, for example,
45 @file{-myfile.scm}. In this case, the file name must be preceded by
46 @option{-s} to tell Guile that a (script) file is being named.
48 Scripts are read and evaluated as Scheme source code just as the
49 @code{load} function would. After loading @var{script}, Guile exits.
51 @item -c @var{expr} @var{arg...}
52 @cindex evaluate expression, command-line argument
53 Evaluate @var{expr} as Scheme code, and then exit. Any command-line
54 arguments @var{arg...} following @var{expr} become command-line
55 arguments; the @code{command-line} function returns a list of strings of
56 the form @code{(@var{guile} @var{arg...})}, where @var{guile} is the
57 path of the Guile executable.
60 Run interactively, prompting the user for expressions and evaluating
61 them. Any command-line arguments @var{arg...} following the @option{--}
62 become command-line arguments for the interactive session; the
63 @code{command-line} function returns a list of strings of the form
64 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
67 @item -L @var{directory}
68 Add @var{directory} to the front of Guile's module load path. The given
69 directories are searched in the order given on the command line and
70 before any directories in the @env{GUILE_LOAD_PATH} environment
71 variable. Paths added here are @emph{not} in effect during execution of
72 the user's @file{.guile} file.
74 @item -x @var{extension}
75 Add @var{extension} to the front of Guile's load extension list
76 (@pxref{Load Paths, @code{%load-extensions}}). The specified extensions
77 are tried in the order given on the command line, and before the default
78 load extensions. Extensions added here are @emph{not} in effect during
79 execution of the user's @file{.guile} file.
82 Load Scheme source code from @var{file}, and continue processing the
85 @item -e @var{function}
86 Make @var{function} the @dfn{entry point} of the script. After loading
87 the script file (with @option{-s}) or evaluating the expression (with
88 @option{-c}), apply @var{function} to a list containing the program name
89 and the command-line arguments---the list provided by the
90 @code{command-line} function.
92 A @option{-e} switch can appear anywhere in the argument list, but Guile
93 always invokes the @var{function} as the @emph{last} action it performs.
94 This is weird, but because of the way script invocation works under
95 POSIX, the @option{-s} option must always come last in the list.
97 The @var{function} is most often a simple symbol that names a function
98 that is defined in the script. It can also be of the form @code{(@@
99 @var{module-name} @var{symbol})}, and in that case, the symbol is
100 looked up in the module named @var{module-name}.
102 For compatibility with some versions of Guile 1.4, you can also use the
103 form @code{(symbol ...)} (that is, a list of only symbols that doesn't
104 start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
105 main)}, or @code{(symbol ...) symbol} (that is, a list of only symbols
106 followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
107 symbol)}. We recommend to use the equivalent forms directly since they
108 correspond to the @code{(@@ ...)} read syntax that can be used in
109 normal code. See @ref{Using Guile Modules} and @ref{Scripting
113 Treat a final @option{-s} option as if it occurred at this point in the
114 command line; load the script here.
116 This switch is necessary because, although the POSIX script invocation
117 mechanism effectively requires the @option{-s} option to appear last, the
118 programmer may well want to run the script before other actions
119 requested on the command line. For examples, see @ref{Scripting
123 Read more command-line arguments, starting from the second line of the
124 script file. @xref{The Meta Switch}.
126 @item --use-srfi=@var{list}
127 @cindex loading srfi modules (command line)
128 The option @option{--use-srfi} expects a comma-separated list of numbers,
129 each representing a SRFI module to be loaded into the interpreter
130 before evaluating a script file or starting the REPL. Additionally,
131 the feature identifier for the loaded SRFIs is recognized by
132 the procedure @code{cond-expand} when this option is used.
134 Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13
135 ('string library') before the GUILE interpreter is started:
138 guile --use-srfi=8,13
142 @cindex debugging virtual machine (command line)
143 Start with the debugging virtual machine (VM) engine. Using the
144 debugging VM will enable support for VM hooks, which are needed for
145 tracing, breakpoints, and accurate call counts when profiling. The
146 debugging VM is slower than the regular VM, though, by about ten
147 percent. @xref{VM Hooks}, for more information.
149 By default, the debugging VM engine is only used when entering an
150 interactive session. When executing a script with @option{-s} or
151 @option{-c}, the normal, faster VM is used by default.
155 @cindex debugging virtual machine (command line)
156 Do not use the debugging VM engine, even when entering an interactive
159 Note that, despite the name, Guile running with @option{--no-debug}
160 @emph{does} support the usual debugging facilities, such as printing a
161 detailed backtrace upon error. The only difference with
162 @option{--debug} is lack of support for VM hooks and the facilities that
163 build upon it (see above).
166 @cindex init file, not loading
167 @cindex @file{.guile} file, not loading
168 Do not load the initialization file, @file{.guile}. This option only
169 has an effect when running interactively; running scripts does not load
170 the @file{.guile} file. @xref{Init File}.
172 @item --listen[=@var{p}]
173 While this program runs, listen on a local port or a path for REPL
174 clients. If @var{p} starts with a number, it is assumed to be a local
175 port on which to listen. If it starts with a forward slash, it is
176 assumed to be a path to a UNIX domain socket on which to listen.
178 If @var{p} is not given, the default is local port 37146. If you look
179 at it upside down, it almost spells ``Guile''. If you have netcat
180 installed, you should be able to @kbd{nc localhost 37146} and get a
181 Guile prompt. Alternately you can fire up Emacs and connect to the
182 process; see @ref{Using Guile in Emacs} for more details.
184 Note that opening a port allows anyone who can connect to that port---in
185 the TCP case, any local user---to do anything Guile can do, as the user
186 that the Guile process is running as. Do not use @option{--listen} on
187 multi-user machines. Of course, if you do not pass @option{--listen} to
188 Guile, no port will be opened.
190 That said, @option{--listen} is great for interactive debugging and
196 Compile source files automatically (default behavior).
200 @item --fresh-auto-compile
201 Treat the auto-compilation cache as invalid, forcing recompilation.
205 @item --no-auto-compile
206 Disable automatic source file compilation.
211 Display help on invoking Guile, and then exit.
213 @item -v@r{, }--version
214 Display the current version of Guile, and then exit.
218 @node Environment Variables
219 @subsection Environment Variables
220 @cindex environment variables
222 @cindex initialization
223 The @dfn{environment} is a feature of the operating system; it consists
224 of a collection of variables with names and values. Each variable is
225 called an @dfn{environment variable} (or, sometimes, a ``shell
226 variable''); environment variable names are case-sensitive, and it is
227 conventional to use upper-case letters only. The values are all text
228 strings, even those that are written as numerals. (Note that here we
229 are referring to names and values that are defined in the operating
230 system shell from which Guile is invoked. This is not the same as a
231 Scheme environment that is defined within a running instance of Guile.
232 For a description of Scheme environments, @pxref{About Environments}.)
234 How to set environment variables before starting Guile depends on the
235 operating system and, especially, the shell that you are using. For
236 example, here is how to tell Guile to provide detailed warning messages
237 about deprecated features by setting @env{GUILE_WARN_DEPRECATED} using
241 $ export GUILE_WARN_DEPRECATED="detailed"
246 Or, detailed warnings can be turned on for a single invocation using:
249 $ env GUILE_WARN_DEPRECATED="detailed" guile
252 If you wish to retrieve or change the value of the shell environment
253 variables that affect the run-time behavior of Guile from within a
254 running instance of Guile, see @ref{Runtime Environment}.
256 Here are the environment variables that affect the run-time behavior of
260 @item GUILE_AUTO_COMPILE
261 @vindex GUILE_AUTO_COMPILE
262 This is a flag that can be used to tell Guile whether or not to compile
263 Scheme source files automatically. Starting with Guile 2.0, Scheme
264 source files will be compiled automatically, by default.
266 If a compiled (@file{.go}) file corresponding to a @file{.scm} file is
267 not found or is not newer than the @file{.scm} file, the @file{.scm}
268 file will be compiled on the fly, and the resulting @file{.go} file
269 stored away. An advisory note will be printed on the console.
271 Compiled files will be stored in the directory
272 @file{$XDG_CACHE_HOME/@/guile/@/ccache}, where @env{XDG_CACHE_HOME}
273 defaults to the directory @file{$HOME/.cache}. This directory will be
274 created if it does not already exist.
276 Note that this mechanism depends on the timestamp of the @file{.go} file
277 being newer than that of the @file{.scm} file; if the @file{.scm} or
278 @file{.go} files are moved after installation, care should be taken to
279 preserve their original timestamps.
281 Set @env{GUILE_AUTO_COMPILE} to zero (0), to prevent Scheme files from
282 being compiled automatically. Set this variable to ``fresh'' to tell
283 Guile to compile Scheme files whether they are newer than the compiled
289 @vindex GUILE_HISTORY
290 This variable names the file that holds the Guile REPL command history.
291 You can specify a different history file by setting this environment
292 variable. By default, the history file is @file{$HOME/.guile_history}.
294 @item GUILE_INSTALL_LOCALE
295 @vindex GUILE_INSTALL_LOCALE
296 This is a flag that can be used to tell Guile whether or not to install
297 the current locale at startup, via a call to @code{(setlocale LC_ALL
298 "")}. @xref{Locales}, for more information on locales.
300 You may explicitly indicate that you do not want to install
301 the locale by setting @env{GUILE_INSTALL_LOCALE} to @code{0}, or
302 explicitly enable it by setting the variable to @code{1}.
304 Usually, installing the current locale is the right thing to do. It
305 allows Guile to correctly parse and print strings with non-ASCII
306 characters. However, for compatibility with previous Guile 2.0
307 releases, this option is off by default. The next stable release series
308 of Guile (the 2.2 series) will install locales by default.
310 @item GUILE_STACK_SIZE
311 @vindex GUILE_STACK_SIZE
312 Guile currently has a limited stack size for Scheme computations.
313 Attempting to call too many nested functions will signal an error. This
314 is good to detect infinite recursion, but sometimes the limit is reached
315 for normal computations. This environment variable, if set to a
316 positive integer, specifies the number of Scheme value slots to allocate
319 In the future we will implement stacks that can grow and shrink, but for
320 now this hack will have to do.
322 @item GUILE_LOAD_COMPILED_PATH
323 @vindex GUILE_LOAD_COMPILED_PATH
324 This variable may be used to augment the path that is searched for
325 compiled Scheme files (@file{.go} files) when loading. Its value should
326 be a colon-separated list of directories. If it contains the special
327 path component @code{...} (ellipsis), then the default path is put in
328 place of the ellipsis, otherwise the default path is placed at the end.
329 The result is stored in @code{%load-compiled-path} (@pxref{Load Paths}).
331 Here is an example using the Bash shell that adds the current directory,
332 @file{.}, and the relative directory @file{../my-library} to
333 @code{%load-compiled-path}:
336 $ export GUILE_LOAD_COMPILED_PATH=".:../my-library"
337 $ guile -c '(display %load-compiled-path) (newline)'
338 (. ../my-library /usr/local/lib/guile/2.0/ccache)
341 @item GUILE_LOAD_PATH
342 @vindex GUILE_LOAD_PATH
343 This variable may be used to augment the path that is searched for
344 Scheme files when loading. Its value should be a colon-separated list
345 of directories. If it contains the special path component @code{...}
346 (ellipsis), then the default path is put in place of the ellipsis,
347 otherwise the default path is placed at the end. The result is stored
348 in @code{%load-path} (@pxref{Load Paths}).
350 Here is an example using the Bash shell that prepends the current
351 directory to @code{%load-path}, and adds the relative directory
352 @file{../srfi} to the end:
355 $ env GUILE_LOAD_PATH=".:...:../srfi" \
356 guile -c '(display %load-path) (newline)'
357 (. /usr/local/share/guile/2.0 \
358 /usr/local/share/guile/site/2.0 \
359 /usr/local/share/guile/site \
360 /usr/local/share/guile \
364 (Note: The line breaks, above, are for documentation purposes only, and
365 not required in the actual example.)
367 @item GUILE_WARN_DEPRECATED
368 @vindex GUILE_WARN_DEPRECATED
369 As Guile evolves, some features will be eliminated or replaced by newer
370 features. To help users migrate their code as this evolution occurs,
371 Guile will issue warning messages about code that uses features that
372 have been marked for eventual elimination. @env{GUILE_WARN_DEPRECATED}
373 can be set to ``no'' to tell Guile not to display these warning
374 messages, or set to ``detailed'' to tell Guile to display more lengthy
375 messages describing the warning. @xref{Deprecation}.
379 Guile uses the environment variable @env{HOME}, the name of your home
380 directory, to locate various files, such as @file{.guile} or
381 @file{.guile_history}.
383 @item LTDL_LIBRARY_PATH
384 @vindex LTDL_LIBRARY_PATH
385 Guile now adds its install prefix to the @env{LTDL_LIBRARY_PATH}.
387 Users may now install Guile in non-standard directories and run
388 `/path/to/bin/guile', without having also to set @env{LTDL_LIBRARY_PATH}
389 to include `/path/to/lib'.
395 @c TeX-master: "guile"