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
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{Loading, @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
160 @cindex init file, not loading
161 @cindex @file{.guile} file, not loading
162 Do not load the initialization file, @file{.guile}. This option only
163 has an effect when running interactively; running scripts does not load
164 the @file{.guile} file. @xref{Init File}.
166 @item --listen[=@var{p}]
167 While this program runs, listen on a local port or a path for REPL
168 clients. If @var{p} starts with a number, it is assumed to be a local
169 port on which to listen. If it starts with a forward slash, it is
170 assumed to be a path to a UNIX domain socket on which to listen.
172 If @var{p} is not given, the default is local port 37146. If you look
173 at it upside down, it almost spells ``Guile''. If you have netcat
174 installed, you should be able to @kbd{nc localhost 37146} and get a
175 Guile prompt. Alternately you can fire up Emacs and connect to the
176 process; see @ref{Using Guile in Emacs} for more details.
178 Note that opening a port allows anyone who can connect to that port---in
179 the TCP case, any local user---to do anything Guile can do, as the user
180 that the Guile process is running as. Do not use @option{--listen} on
181 multi-user machines. Of course, if you do not pass @option{--listen} to
182 Guile, no port will be opened.
184 That said, @option{--listen} is great for interactive debugging and
190 Compile source files automatically (default behavior).
194 @item --fresh-auto-compile
195 Treat the auto-compilation cache as invalid, forcing recompilation.
199 @item --no-auto-compile
200 Disable automatic source file compilation.
205 Display help on invoking Guile, and then exit.
207 @item -v@r{, }--version
208 Display the current version of Guile, and then exit.
212 @node Environment Variables
213 @subsection Environment Variables
214 @cindex environment variables
216 @cindex initialization
217 The @dfn{environment} is a feature of the operating system; it consists
218 of a collection of variables with names and values. Each variable is
219 called an @dfn{environment variable} (or, sometimes, a ``shell
220 variable''); environment variable names are case-sensitive, and it is
221 conventional to use upper-case letters only. The values are all text
222 strings, even those that are written as numerals. (Note that here we
223 are referring to names and values that are defined in the operating
224 system shell from which Guile is invoked. This is not the same as a
225 Scheme environment that is defined within a running instance of Guile.
226 For a description of Scheme environments, @pxref{About Environments}.)
228 How to set environment variables before starting Guile depends on the
229 operating system and, especially, the shell that you are using. For
230 example, here is how to tell Guile to provide detailed warning messages
231 about deprecated features by setting @env{GUILE_WARN_DEPRECATED} using
235 $ export GUILE_WARN_DEPRECATED="detailed"
240 Or, detailed warnings can be turned on for a single invocation using:
243 $ env GUILE_WARN_DEPRECATED="detailed" guile
246 If you wish to retrieve or change the value of the shell environment
247 variables that affect the run-time behavior of Guile from within a
248 running instance of Guile, see @ref{Runtime Environment}.
250 Here are the environment variables that affect the run-time behavior of
254 @item GUILE_AUTO_COMPILE
255 @vindex GUILE_AUTO_COMPILE
256 This is a flag that can be used to tell Guile whether or not to compile
257 Scheme source files automatically. Starting with Guile 2.0, Scheme
258 source files will be compiled automatically, by default.
260 If a compiled (@file{.go}) file corresponding to a @file{.scm} file is
261 not found or is not newer than the @file{.scm} file, the @file{.scm}
262 file will be compiled on the fly, and the resulting @file{.go} file
263 stored away. An advisory note will be printed on the console.
265 Compiled files will be stored in the directory
266 @file{$XDG_CACHE_HOME/@/guile/@/ccache}, where @env{XDG_CACHE_HOME}
267 defaults to the directory @file{$HOME/.cache}. This directory will be
268 created if it does not already exist.
270 Note that this mechanism depends on the timestamp of the @file{.go} file
271 being newer than that of the @file{.scm} file; if the @file{.scm} or
272 @file{.go} files are moved after installation, care should be taken to
273 preserve their original timestamps.
275 Set @env{GUILE_AUTO_COMPILE} to zero (0), to prevent Scheme files from
276 being compiled automatically. Set this variable to ``fresh'' to tell
277 Guile to compile Scheme files whether they are newer than the compiled
283 @vindex GUILE_HISTORY
284 This variable names the file that holds the Guile REPL command history.
285 You can specify a different history file by setting this environment
286 variable. By default, the history file is @file{$HOME/.guile_history}.
288 @item GUILE_LOAD_COMPILED_PATH
289 @vindex GUILE_LOAD_COMPILED_PATH
290 This variable may be used to augment the path that is searched for
291 compiled Scheme files (@file{.go} files) when loading. Its value should
292 be a colon-separated list of directories, which will be prefixed to the
293 value of the default search path stored in @code{%load-compiled-path}.
295 Here is an example using the Bash shell that adds the current directory,
296 @file{.}, and the relative directory @file{../my-library} to
297 @code{%load-compiled-path}:
300 $ export GUILE_LOAD_COMPILED_PATH=".:../my-library"
301 $ guile -c '(display %load-compiled-path) (newline)'
302 (. ../my-library /usr/local/lib/guile/2.0/ccache)
305 @item GUILE_LOAD_PATH
306 @vindex GUILE_LOAD_PATH
307 This variable may be used to augment the path that is searched for
308 Scheme files when loading. Its value should be a colon-separated list
309 of directories, which will be prefixed to the value of the default
310 search path stored in @code{%load-path}.
312 Here is an example using the Bash shell that adds the current directory
313 and the parent of the current directory to @code{%load-path}:
316 $ env GUILE_LOAD_PATH=".:.." \
317 guile -c '(display %load-path) (newline)'
318 (. .. /usr/local/share/guile/2.0 \
319 /usr/local/share/guile/site/2.0 \
320 /usr/local/share/guile/site /usr/local/share/guile)
323 (Note: The line breaks, above, are for documentation purposes only, and
324 not required in the actual example.)
326 @item GUILE_WARN_DEPRECATED
327 @vindex GUILE_WARN_DEPRECATED
328 As Guile evolves, some features will be eliminated or replaced by newer
329 features. To help users migrate their code as this evolution occurs,
330 Guile will issue warning messages about code that uses features that
331 have been marked for eventual elimination. @env{GUILE_WARN_DEPRECATED}
332 can be set to ``no'' to tell Guile not to display these warning
333 messages, or set to ``detailed'' to tell Guile to display more lengthy
334 messages describing the warning. @xref{Deprecation}.
338 Guile uses the environment variable @env{HOME}, the name of your home
339 directory, to locate various files, such as @file{.guile} or
340 @file{.guile_history}.
342 @item LTDL_LIBRARY_PATH
343 @vindex LTDL_LIBRARY_PATH
344 Guile now adds its install prefix to the @env{LTDL_LIBRARY_PATH}.
346 Users may now install Guile in non-standard directories and run
347 `/path/to/bin/guile', without having also to set @env{LTDL_LIBRARY_PATH}
348 to include `/path/to/lib'.
354 @c TeX-master: "guile"