Commit | Line | Data |
---|---|---|
94906b75 MH |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
7e466e02 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011, 2013, 2014 |
94906b75 MH |
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 | ||
b05257b9 MW |
74 | @item -C @var{directory} |
75 | Like @option{-L}, but adjusts the load path for @emph{compiled} files. | |
76 | ||
94906b75 MH |
77 | @item -x @var{extension} |
78 | Add @var{extension} to the front of Guile's load extension list | |
925172cf | 79 | (@pxref{Load Paths, @code{%load-extensions}}). The specified extensions |
94906b75 MH |
80 | are tried in the order given on the command line, and before the default |
81 | load extensions. Extensions added here are @emph{not} in effect during | |
82 | execution of the user's @file{.guile} file. | |
83 | ||
84 | @item -l @var{file} | |
85 | Load Scheme source code from @var{file}, and continue processing the | |
86 | command line. | |
87 | ||
88 | @item -e @var{function} | |
89 | Make @var{function} the @dfn{entry point} of the script. After loading | |
90 | the script file (with @option{-s}) or evaluating the expression (with | |
91 | @option{-c}), apply @var{function} to a list containing the program name | |
92 | and the command-line arguments---the list provided by the | |
93 | @code{command-line} function. | |
94 | ||
95 | A @option{-e} switch can appear anywhere in the argument list, but Guile | |
96 | always invokes the @var{function} as the @emph{last} action it performs. | |
97 | This is weird, but because of the way script invocation works under | |
98 | POSIX, the @option{-s} option must always come last in the list. | |
99 | ||
100 | The @var{function} is most often a simple symbol that names a function | |
101 | that is defined in the script. It can also be of the form @code{(@@ | |
102 | @var{module-name} @var{symbol})}, and in that case, the symbol is | |
103 | looked up in the module named @var{module-name}. | |
104 | ||
105 | For compatibility with some versions of Guile 1.4, you can also use the | |
106 | form @code{(symbol ...)} (that is, a list of only symbols that doesn't | |
107 | start with @code{@@}), which is equivalent to @code{(@@ (symbol ...) | |
108 | main)}, or @code{(symbol ...) symbol} (that is, a list of only symbols | |
109 | followed by a symbol), which is equivalent to @code{(@@ (symbol ...) | |
110 | symbol)}. We recommend to use the equivalent forms directly since they | |
111 | correspond to the @code{(@@ ...)} read syntax that can be used in | |
112 | normal code. See @ref{Using Guile Modules} and @ref{Scripting | |
113 | Examples}. | |
114 | ||
115 | @item -ds | |
116 | Treat a final @option{-s} option as if it occurred at this point in the | |
117 | command line; load the script here. | |
118 | ||
119 | This switch is necessary because, although the POSIX script invocation | |
120 | mechanism effectively requires the @option{-s} option to appear last, the | |
121 | programmer may well want to run the script before other actions | |
122 | requested on the command line. For examples, see @ref{Scripting | |
123 | Examples}. | |
124 | ||
125 | @item \ | |
126 | Read more command-line arguments, starting from the second line of the | |
127 | script file. @xref{The Meta Switch}. | |
128 | ||
129 | @item --use-srfi=@var{list} | |
130 | @cindex loading srfi modules (command line) | |
131 | The option @option{--use-srfi} expects a comma-separated list of numbers, | |
132 | each representing a SRFI module to be loaded into the interpreter | |
133 | before evaluating a script file or starting the REPL. Additionally, | |
134 | the feature identifier for the loaded SRFIs is recognized by | |
135 | the procedure @code{cond-expand} when this option is used. | |
136 | ||
137 | Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13 | |
138 | ('string library') before the GUILE interpreter is started: | |
139 | ||
140 | @example | |
141 | guile --use-srfi=8,13 | |
142 | @end example | |
143 | ||
144 | @item --debug | |
145 | @cindex debugging virtual machine (command line) | |
146 | Start with the debugging virtual machine (VM) engine. Using the | |
147 | debugging VM will enable support for VM hooks, which are needed for | |
148 | tracing, breakpoints, and accurate call counts when profiling. The | |
149 | debugging VM is slower than the regular VM, though, by about ten | |
150 | percent. @xref{VM Hooks}, for more information. | |
151 | ||
152 | By default, the debugging VM engine is only used when entering an | |
153 | interactive session. When executing a script with @option{-s} or | |
154 | @option{-c}, the normal, faster VM is used by default. | |
155 | ||
156 | @vnew{1.8} | |
157 | @item --no-debug | |
158 | @cindex debugging virtual machine (command line) | |
159 | Do not use the debugging VM engine, even when entering an interactive | |
160 | session. | |
161 | ||
c8286111 LC |
162 | Note that, despite the name, Guile running with @option{--no-debug} |
163 | @emph{does} support the usual debugging facilities, such as printing a | |
164 | detailed backtrace upon error. The only difference with | |
165 | @option{--debug} is lack of support for VM hooks and the facilities that | |
166 | build upon it (see above). | |
167 | ||
94906b75 MH |
168 | @item -q |
169 | @cindex init file, not loading | |
170 | @cindex @file{.guile} file, not loading | |
171 | Do not load the initialization file, @file{.guile}. This option only | |
172 | has an effect when running interactively; running scripts does not load | |
173 | the @file{.guile} file. @xref{Init File}. | |
174 | ||
175 | @item --listen[=@var{p}] | |
176 | While this program runs, listen on a local port or a path for REPL | |
177 | clients. If @var{p} starts with a number, it is assumed to be a local | |
178 | port on which to listen. If it starts with a forward slash, it is | |
179 | assumed to be a path to a UNIX domain socket on which to listen. | |
180 | ||
181 | If @var{p} is not given, the default is local port 37146. If you look | |
182 | at it upside down, it almost spells ``Guile''. If you have netcat | |
183 | installed, you should be able to @kbd{nc localhost 37146} and get a | |
184 | Guile prompt. Alternately you can fire up Emacs and connect to the | |
185 | process; see @ref{Using Guile in Emacs} for more details. | |
186 | ||
187 | Note that opening a port allows anyone who can connect to that port---in | |
188 | the TCP case, any local user---to do anything Guile can do, as the user | |
189 | that the Guile process is running as. Do not use @option{--listen} on | |
190 | multi-user machines. Of course, if you do not pass @option{--listen} to | |
191 | Guile, no port will be opened. | |
192 | ||
193 | That said, @option{--listen} is great for interactive debugging and | |
194 | development. | |
195 | ||
196 | @vnew{2.0} | |
197 | ||
198 | @item --auto-compile | |
199 | Compile source files automatically (default behavior). | |
200 | ||
201 | @vnew{2.0.1} | |
202 | ||
203 | @item --fresh-auto-compile | |
204 | Treat the auto-compilation cache as invalid, forcing recompilation. | |
205 | ||
206 | @vnew{2.0} | |
207 | ||
208 | @item --no-auto-compile | |
209 | Disable automatic source file compilation. | |
210 | ||
004094d3 LC |
211 | @vnew{2.0.8} |
212 | ||
213 | @item --language=@var{lang} | |
214 | For the remainder of the command line arguments, assume that files | |
215 | mentioned with @code{-l} and expressions passed with @code{-c} are | |
216 | written in @var{lang}. @var{lang} must be the name of one of the | |
217 | languages supported by the compiler (@pxref{Compiler Tower}). When run | |
218 | interactively, set the REPL's language to @var{lang} (@pxref{Using Guile | |
219 | Interactively}). | |
220 | ||
221 | The default language is @code{scheme}; other interesting values include | |
222 | @code{elisp} (for Emacs Lisp), and @code{ecmascript}. | |
223 | ||
224 | The example below shows the evaluation of expressions in Scheme, Emacs | |
225 | Lisp, and ECMAScript: | |
226 | ||
227 | @example | |
228 | guile -c "(apply + '(1 2))" | |
229 | guile --language=elisp -c "(= (funcall (symbol-function '+) 1 2) 3)" | |
230 | guile --language=ecmascript -c '(function (x) @{ return x * x; @})(2);' | |
231 | @end example | |
232 | ||
233 | To load a file written in Scheme and one written in Emacs Lisp, and then | |
234 | start a Scheme REPL, type: | |
235 | ||
236 | @example | |
237 | guile -l foo.scm --language=elisp -l foo.el --language=scheme | |
238 | @end example | |
239 | ||
94906b75 MH |
240 | @vnew{2.0} |
241 | ||
242 | @item -h@r{, }--help | |
243 | Display help on invoking Guile, and then exit. | |
244 | ||
245 | @item -v@r{, }--version | |
246 | Display the current version of Guile, and then exit. | |
247 | ||
248 | @end table | |
249 | ||
250 | @node Environment Variables | |
251 | @subsection Environment Variables | |
252 | @cindex environment variables | |
253 | @cindex shell | |
254 | @cindex initialization | |
255 | The @dfn{environment} is a feature of the operating system; it consists | |
256 | of a collection of variables with names and values. Each variable is | |
257 | called an @dfn{environment variable} (or, sometimes, a ``shell | |
258 | variable''); environment variable names are case-sensitive, and it is | |
259 | conventional to use upper-case letters only. The values are all text | |
260 | strings, even those that are written as numerals. (Note that here we | |
261 | are referring to names and values that are defined in the operating | |
262 | system shell from which Guile is invoked. This is not the same as a | |
263 | Scheme environment that is defined within a running instance of Guile. | |
264 | For a description of Scheme environments, @pxref{About Environments}.) | |
265 | ||
266 | How to set environment variables before starting Guile depends on the | |
267 | operating system and, especially, the shell that you are using. For | |
268 | example, here is how to tell Guile to provide detailed warning messages | |
269 | about deprecated features by setting @env{GUILE_WARN_DEPRECATED} using | |
270 | Bash: | |
271 | ||
272 | @example | |
273 | $ export GUILE_WARN_DEPRECATED="detailed" | |
274 | $ guile | |
275 | @end example | |
276 | ||
277 | @noindent | |
278 | Or, detailed warnings can be turned on for a single invocation using: | |
279 | ||
280 | @example | |
281 | $ env GUILE_WARN_DEPRECATED="detailed" guile | |
282 | @end example | |
283 | ||
284 | If you wish to retrieve or change the value of the shell environment | |
285 | variables that affect the run-time behavior of Guile from within a | |
286 | running instance of Guile, see @ref{Runtime Environment}. | |
287 | ||
288 | Here are the environment variables that affect the run-time behavior of | |
289 | Guile: | |
290 | ||
291 | @table @env | |
292 | @item GUILE_AUTO_COMPILE | |
293 | @vindex GUILE_AUTO_COMPILE | |
294 | This is a flag that can be used to tell Guile whether or not to compile | |
295 | Scheme source files automatically. Starting with Guile 2.0, Scheme | |
296 | source files will be compiled automatically, by default. | |
297 | ||
298 | If a compiled (@file{.go}) file corresponding to a @file{.scm} file is | |
299 | not found or is not newer than the @file{.scm} file, the @file{.scm} | |
300 | file will be compiled on the fly, and the resulting @file{.go} file | |
301 | stored away. An advisory note will be printed on the console. | |
302 | ||
303 | Compiled files will be stored in the directory | |
304 | @file{$XDG_CACHE_HOME/@/guile/@/ccache}, where @env{XDG_CACHE_HOME} | |
305 | defaults to the directory @file{$HOME/.cache}. This directory will be | |
306 | created if it does not already exist. | |
307 | ||
308 | Note that this mechanism depends on the timestamp of the @file{.go} file | |
309 | being newer than that of the @file{.scm} file; if the @file{.scm} or | |
310 | @file{.go} files are moved after installation, care should be taken to | |
311 | preserve their original timestamps. | |
312 | ||
313 | Set @env{GUILE_AUTO_COMPILE} to zero (0), to prevent Scheme files from | |
314 | being compiled automatically. Set this variable to ``fresh'' to tell | |
315 | Guile to compile Scheme files whether they are newer than the compiled | |
316 | files or not. | |
317 | ||
318 | @xref{Compilation}. | |
319 | ||
320 | @item GUILE_HISTORY | |
321 | @vindex GUILE_HISTORY | |
322 | This variable names the file that holds the Guile REPL command history. | |
323 | You can specify a different history file by setting this environment | |
324 | variable. By default, the history file is @file{$HOME/.guile_history}. | |
325 | ||
7f893030 LC |
326 | @item GUILE_INSTALL_LOCALE |
327 | @vindex GUILE_INSTALL_LOCALE | |
328 | This is a flag that can be used to tell Guile whether or not to install | |
329 | the current locale at startup, via a call to @code{(setlocale LC_ALL | |
7e466e02 LC |
330 | "")}@footnote{The @code{GUILE_INSTALL_LOCALE} environment variable was |
331 | ignored in Guile versions prior to 2.0.9.}. @xref{Locales}, for more | |
332 | information on locales. | |
7f893030 LC |
333 | |
334 | You may explicitly indicate that you do not want to install | |
335 | the locale by setting @env{GUILE_INSTALL_LOCALE} to @code{0}, or | |
336 | explicitly enable it by setting the variable to @code{1}. | |
337 | ||
338 | Usually, installing the current locale is the right thing to do. It | |
339 | allows Guile to correctly parse and print strings with non-ASCII | |
26d14806 | 340 | characters. Therefore, this option is on by default. |
7f893030 | 341 | |
aab9d46c SIT |
342 | @item GUILE_STACK_SIZE |
343 | @vindex GUILE_STACK_SIZE | |
344 | Guile currently has a limited stack size for Scheme computations. | |
345 | Attempting to call too many nested functions will signal an error. This | |
346 | is good to detect infinite recursion, but sometimes the limit is reached | |
347 | for normal computations. This environment variable, if set to a | |
348 | positive integer, specifies the number of Scheme value slots to allocate | |
349 | for the stack. | |
350 | ||
351 | In the future we will implement stacks that can grow and shrink, but for | |
352 | now this hack will have to do. | |
353 | ||
94906b75 MH |
354 | @item GUILE_LOAD_COMPILED_PATH |
355 | @vindex GUILE_LOAD_COMPILED_PATH | |
356 | This variable may be used to augment the path that is searched for | |
357 | compiled Scheme files (@file{.go} files) when loading. Its value should | |
bd31bce6 MW |
358 | be a colon-separated list of directories. If it contains the special |
359 | path component @code{...} (ellipsis), then the default path is put in | |
360 | place of the ellipsis, otherwise the default path is placed at the end. | |
361 | The result is stored in @code{%load-compiled-path} (@pxref{Load Paths}). | |
94906b75 MH |
362 | |
363 | Here is an example using the Bash shell that adds the current directory, | |
364 | @file{.}, and the relative directory @file{../my-library} to | |
365 | @code{%load-compiled-path}: | |
366 | ||
367 | @example | |
368 | $ export GUILE_LOAD_COMPILED_PATH=".:../my-library" | |
369 | $ guile -c '(display %load-compiled-path) (newline)' | |
f88e9510 | 370 | (. ../my-library /usr/local/lib/guile/2.2/ccache) |
94906b75 MH |
371 | @end example |
372 | ||
373 | @item GUILE_LOAD_PATH | |
374 | @vindex GUILE_LOAD_PATH | |
375 | This variable may be used to augment the path that is searched for | |
376 | Scheme files when loading. Its value should be a colon-separated list | |
bd31bce6 MW |
377 | of directories. If it contains the special path component @code{...} |
378 | (ellipsis), then the default path is put in place of the ellipsis, | |
379 | otherwise the default path is placed at the end. The result is stored | |
380 | in @code{%load-path} (@pxref{Load Paths}). | |
94906b75 | 381 | |
bd31bce6 MW |
382 | Here is an example using the Bash shell that prepends the current |
383 | directory to @code{%load-path}, and adds the relative directory | |
384 | @file{../srfi} to the end: | |
94906b75 MH |
385 | |
386 | @example | |
bd31bce6 | 387 | $ env GUILE_LOAD_PATH=".:...:../srfi" \ |
94906b75 | 388 | guile -c '(display %load-path) (newline)' |
f88e9510 AW |
389 | (. /usr/local/share/guile/2.2 \ |
390 | /usr/local/share/guile/site/2.2 \ | |
bd31bce6 MW |
391 | /usr/local/share/guile/site \ |
392 | /usr/local/share/guile \ | |
393 | ../srfi) | |
94906b75 MH |
394 | @end example |
395 | ||
396 | (Note: The line breaks, above, are for documentation purposes only, and | |
397 | not required in the actual example.) | |
398 | ||
399 | @item GUILE_WARN_DEPRECATED | |
400 | @vindex GUILE_WARN_DEPRECATED | |
401 | As Guile evolves, some features will be eliminated or replaced by newer | |
402 | features. To help users migrate their code as this evolution occurs, | |
403 | Guile will issue warning messages about code that uses features that | |
404 | have been marked for eventual elimination. @env{GUILE_WARN_DEPRECATED} | |
405 | can be set to ``no'' to tell Guile not to display these warning | |
406 | messages, or set to ``detailed'' to tell Guile to display more lengthy | |
407 | messages describing the warning. @xref{Deprecation}. | |
408 | ||
409 | @item HOME | |
410 | @vindex HOME | |
411 | Guile uses the environment variable @env{HOME}, the name of your home | |
412 | directory, to locate various files, such as @file{.guile} or | |
413 | @file{.guile_history}. | |
414 | ||
94906b75 MH |
415 | @end table |
416 | ||
417 | @c Local Variables: | |
418 | @c mode: texinfo | |
419 | @c TeX-master: "guile" | |
420 | @c End: |