Commit | Line | Data |
---|---|---|
94906b75 MH |
1 | @c -*-texinfo-*- |
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. | |
6 | ||
7 | @node Invoking Guile | |
8 | @section Invoking Guile | |
9 | @cindex invocation | |
10 | ||
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. | |
14 | ||
15 | @menu | |
16 | * Command-line Options:: Command-line options understood by Guile. | |
17 | * Environment Variables:: Variables that affect Guile's behavior. | |
18 | @end menu | |
19 | ||
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) | |
29 | ||
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}. | |
33 | ||
34 | @table @code | |
35 | ||
36 | @item @var{script} @var{arg...} | |
37 | @itemx -s @var{script} @var{arg...} | |
38 | @cindex script mode | |
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...})}. | |
43 | ||
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. | |
47 | ||
48 | Scripts are read and evaluated as Scheme source code just as the | |
49 | @code{load} function would. After loading @var{script}, Guile exits. | |
50 | ||
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. | |
58 | ||
59 | @item -- @var{arg...} | |
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 | |
65 | Guile executable. | |
66 | ||
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. | |
73 | ||
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. | |
80 | ||
81 | @item -l @var{file} | |
82 | Load Scheme source code from @var{file}, and continue processing the | |
83 | command line. | |
84 | ||
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. | |
91 | ||
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. | |
96 | ||
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}. | |
101 | ||
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 | |
110 | Examples}. | |
111 | ||
112 | @item -ds | |
113 | Treat a final @option{-s} option as if it occurred at this point in the | |
114 | command line; load the script here. | |
115 | ||
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 | |
120 | Examples}. | |
121 | ||
122 | @item \ | |
123 | Read more command-line arguments, starting from the second line of the | |
124 | script file. @xref{The Meta Switch}. | |
125 | ||
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. | |
133 | ||
134 | Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13 | |
135 | ('string library') before the GUILE interpreter is started: | |
136 | ||
137 | @example | |
138 | guile --use-srfi=8,13 | |
139 | @end example | |
140 | ||
141 | @item --debug | |
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. | |
148 | ||
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. | |
152 | ||
153 | @vnew{1.8} | |
154 | @item --no-debug | |
155 | @cindex debugging virtual machine (command line) | |
156 | Do not use the debugging VM engine, even when entering an interactive | |
157 | session. | |
158 | ||
c8286111 LC |
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). | |
164 | ||
94906b75 MH |
165 | @item -q |
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}. | |
171 | ||
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. | |
177 | ||
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. | |
183 | ||
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. | |
189 | ||
190 | That said, @option{--listen} is great for interactive debugging and | |
191 | development. | |
192 | ||
193 | @vnew{2.0} | |
194 | ||
195 | @item --auto-compile | |
196 | Compile source files automatically (default behavior). | |
197 | ||
198 | @vnew{2.0.1} | |
199 | ||
200 | @item --fresh-auto-compile | |
201 | Treat the auto-compilation cache as invalid, forcing recompilation. | |
202 | ||
203 | @vnew{2.0} | |
204 | ||
205 | @item --no-auto-compile | |
206 | Disable automatic source file compilation. | |
207 | ||
208 | @vnew{2.0} | |
209 | ||
210 | @item -h@r{, }--help | |
211 | Display help on invoking Guile, and then exit. | |
212 | ||
213 | @item -v@r{, }--version | |
214 | Display the current version of Guile, and then exit. | |
215 | ||
216 | @end table | |
217 | ||
218 | @node Environment Variables | |
219 | @subsection Environment Variables | |
220 | @cindex environment variables | |
221 | @cindex shell | |
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}.) | |
233 | ||
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 | |
238 | Bash: | |
239 | ||
240 | @example | |
241 | $ export GUILE_WARN_DEPRECATED="detailed" | |
242 | $ guile | |
243 | @end example | |
244 | ||
245 | @noindent | |
246 | Or, detailed warnings can be turned on for a single invocation using: | |
247 | ||
248 | @example | |
249 | $ env GUILE_WARN_DEPRECATED="detailed" guile | |
250 | @end example | |
251 | ||
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}. | |
255 | ||
256 | Here are the environment variables that affect the run-time behavior of | |
257 | Guile: | |
258 | ||
259 | @table @env | |
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. | |
265 | ||
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. | |
270 | ||
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. | |
275 | ||
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. | |
280 | ||
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 | |
284 | files or not. | |
285 | ||
286 | @xref{Compilation}. | |
287 | ||
288 | @item GUILE_HISTORY | |
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}. | |
293 | ||
294 | @item GUILE_LOAD_COMPILED_PATH | |
295 | @vindex GUILE_LOAD_COMPILED_PATH | |
296 | This variable may be used to augment the path that is searched for | |
297 | compiled Scheme files (@file{.go} files) when loading. Its value should | |
298 | be a colon-separated list of directories, which will be prefixed to the | |
299 | value of the default search path stored in @code{%load-compiled-path}. | |
300 | ||
301 | Here is an example using the Bash shell that adds the current directory, | |
302 | @file{.}, and the relative directory @file{../my-library} to | |
303 | @code{%load-compiled-path}: | |
304 | ||
305 | @example | |
306 | $ export GUILE_LOAD_COMPILED_PATH=".:../my-library" | |
307 | $ guile -c '(display %load-compiled-path) (newline)' | |
308 | (. ../my-library /usr/local/lib/guile/2.0/ccache) | |
309 | @end example | |
310 | ||
311 | @item GUILE_LOAD_PATH | |
312 | @vindex GUILE_LOAD_PATH | |
313 | This variable may be used to augment the path that is searched for | |
314 | Scheme files when loading. Its value should be a colon-separated list | |
315 | of directories, which will be prefixed to the value of the default | |
316 | search path stored in @code{%load-path}. | |
317 | ||
318 | Here is an example using the Bash shell that adds the current directory | |
319 | and the parent of the current directory to @code{%load-path}: | |
320 | ||
321 | @example | |
322 | $ env GUILE_LOAD_PATH=".:.." \ | |
323 | guile -c '(display %load-path) (newline)' | |
324 | (. .. /usr/local/share/guile/2.0 \ | |
325 | /usr/local/share/guile/site/2.0 \ | |
326 | /usr/local/share/guile/site /usr/local/share/guile) | |
327 | @end example | |
328 | ||
329 | (Note: The line breaks, above, are for documentation purposes only, and | |
330 | not required in the actual example.) | |
331 | ||
332 | @item GUILE_WARN_DEPRECATED | |
333 | @vindex GUILE_WARN_DEPRECATED | |
334 | As Guile evolves, some features will be eliminated or replaced by newer | |
335 | features. To help users migrate their code as this evolution occurs, | |
336 | Guile will issue warning messages about code that uses features that | |
337 | have been marked for eventual elimination. @env{GUILE_WARN_DEPRECATED} | |
338 | can be set to ``no'' to tell Guile not to display these warning | |
339 | messages, or set to ``detailed'' to tell Guile to display more lengthy | |
340 | messages describing the warning. @xref{Deprecation}. | |
341 | ||
342 | @item HOME | |
343 | @vindex HOME | |
344 | Guile uses the environment variable @env{HOME}, the name of your home | |
345 | directory, to locate various files, such as @file{.guile} or | |
346 | @file{.guile_history}. | |
347 | ||
348 | @item LTDL_LIBRARY_PATH | |
349 | @vindex LTDL_LIBRARY_PATH | |
350 | Guile now adds its install prefix to the @env{LTDL_LIBRARY_PATH}. | |
351 | ||
352 | Users may now install Guile in non-standard directories and run | |
353 | `/path/to/bin/guile', without having also to set @env{LTDL_LIBRARY_PATH} | |
354 | to include `/path/to/lib'. | |
355 | ||
356 | @end table | |
357 | ||
358 | @c Local Variables: | |
359 | @c mode: texinfo | |
360 | @c TeX-master: "guile" | |
361 | @c End: |