4.2 Invoking Guile ================== Many features of Guile depend on and can be changed by information that the user provides either before or when Guile is started. Below is a description of what information to provide and how to provide it. 4.2.1 Command-line Options -------------------------- 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 *note Scripting Examples::. `-s SCRIPT ARG...' By default, Guile will read a file named on the command line as a script. However, it is possible to name a file using a leading hyphen, for example, `-myfile.scm'. In this case, the file name must be preceded by `-s' to tell Guile that a (script) file is being named. Any command-line arguments ARG... following SCRIPT become the script's arguments; the `command-line' function returns a list of strings of the form `(SCRIPT ARG...)'. Scripts are read and evaluated as Scheme source code just as the `load' function would. After loading SCRIPT, Guile exits. `-c EXPR ARG...' Evaluate EXPR as Scheme code, and then exit. Any command-line arguments ARG... following EXPR become command-line arguments; the `command-line' function returns a list of strings of the form `(GUILE ARG...)', where GUILE is the path of the Guile executable. `-- ARG...' Run interactively, prompting the user for expressions and evaluating them. Any command-line arguments ARG... following the `--' become command-line arguments for the interactive session; the `command-line' function returns a list of strings of the form `(GUILE ARG...)', where GUILE is the path of the Guile executable. `-L DIRECTORY' Add 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 `GUILE_LOAD_PATH' environment variable. Paths added here are _not_ in effect during execution of the user's `.guile' file. `-x EXTENSION' Add EXTENSION to the front of Guile's load extension list (*note `%load-extensions': Loading.). The specified extensions are tried in the order given on the command line, and before the default load extensions. Extensions added here are _not_ in effect during execution of the user's `.guile' file. `-l FILE' Load Scheme source code from FILE, and continue processing the command line. `-e FUNCTION' Make FUNCTION the "entry point" of the script. After loading the script file (with `-s') or evaluating the expression (with `-c'), apply FUNCTION to a list containing the program name and the command-line arguments--the list provided by the `command-line' function. A `-e' switch can appear anywhere in the argument list, but Guile always invokes the FUNCTION as the _last_ action it performs. This is weird, but because of the way script invocation works under POSIX, the `-s' option must always come last in the list. The FUNCTION is most often a simple symbol that names a function that is defined in the script. It can also be of the form `(@ MODULE-NAME SYMBOL)', and in that case, the symbol is looked up in the module named MODULE-NAME. For compatibility with some versions of Guile 1.4, you can also use the form `(symbol ...)' (that is, a list of only symbols that doesn't start with `@'), which is equivalent to `(@ (symbol ...) main)', or `(symbol ...) symbol' (that is, a list of only symbols followed by a symbol), which is equivalent to `(@ (symbol ...) symbol)'. We recommend to use the equivalent forms directly since they correspond to the `(@ ...)' read syntax that can be used in normal code. See *note Using Guile Modules:: and *note Scripting Examples::. `-ds' Treat a final `-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 `-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 *note Scripting Examples::. `\' Read more command-line arguments, starting from the second line of the script file. *Note The Meta Switch::. `--use-srfi=LIST' The option `--use-srfi' expects a comma-separated list of numbers, each representing a SRFI module 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 `cond-expand' when this option is used. Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13 ('string library') before the GUILE interpreter is started: guile --use-srfi=8,13 `--debug' 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. *Note VM Hooks::, for more information. By default, the debugging VM engine is only used when entering an interactive session. When executing a script with `-s' or `-c', the normal, faster VM is used by default. `--no-debug' Do not use the debugging VM engine, even when entering an interactive session. `-q' Do not load the initialization file, `.guile'. This option only has an effect when running interactively; running scripts does not load the `.guile' file. *Note Init File::. `--listen[=P]' While this program runs, listen on a local port or a path for REPL clients. If 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 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 `nc localhost 37146' and get a Guile prompt. Alternately you can fire up Emacs and connect to the process; see *note 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. Do not use `--listen' on multi-user machines. Of course, if you do not pass `--listen' to Guile, no port will be opened. That said, `--listen' is great for interactive debugging and development. `--auto-compile' Compile source files automatically (default behavior). `--no-auto-compile' Disable automatic source file compilation. `-h, --help' Display help on invoking Guile, and then exit. `-v, --version' Display the current version of Guile, and then exit. 4.2.2 Environment Variables --------------------------- The "environment" is a feature of the operating system; it consists of a collection of variables with names and values. Each variable is called an "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, *note 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 is how to tell Guile to provide detailed warning messages about deprecated features by setting `GUILE_WARN_DEPRECATED' using Bash: $ export GUILE_WARN_DEPRECATED="detailed" $ guile Or, detailed warnings can be turned on for a single invocation using: $ env GUILE_WARN_DEPRECATED="detailed" guile If you wish to retrieve or change the value of the shell environment variables that affect the run-time behavior of Guile from within a running instance of Guile, see *note Runtime Environment::. Here are the environment variables that affect the run-time behavior of Guile: `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 `GUILE_AUTO_COMPILE' is set to zero (0), then Scheme files are not compiled automatically. If a compiled `.go' file corresponding to a `.scm' file is not found or is not newer than the `.scm' file, the `.scm' file will be compiled on the fly, and the resulting `.go' file stored away. An advisory note will be printed on the console. Note that this mechanism depends on the timestamp of the `.go' file being newer than that of the `.scm' file; if the `.scm' or `.go' files are moved after installation, care should be taken to preserve their original timestamps. Auto-compiled files will be stored in the directory `$XDG_CACHE_HOME/guile/ccache', where `XDG_CACHE_HOME' defaults to the directory `$HOME/.cache'. This directory will be created if it does not already exist. To inhibit automatic compilation, set the `GUILE_AUTO_COMPILE' environment variable to zero (0), or pass `--no-auto-compile' on the Guile command line. `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 `$HOME/.guile_history'. `GUILE_LOAD_COMPILED_PATH' This variable may be used to augment the path that is searched for compiled Scheme files (`.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 `%load-compiled-path'. Here is an example using the Bash shell that adds the current directory, `.', and the relative directory `../my-library' to `%load-compiled-path': $ export GUILE_LOAD_COMPILED_PATH=".:../my-library" $ guile -c '(display %load-compiled-path) (newline)' (. ../my-library /usr/local/lib/guile/2.0/ccache) `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 `%load-path'. Here is an example using the Bash shell that adds the current directory and the parent of the current directory to `%load-path': $ 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) (Note: The line breaks, above, are for documentation purposes only, and not required in the actual example.) `GUILE_WARN_DEPRECATED' As Guile evolves, some features will be eliminated or replaced by newer features. To help users migrate their code as this evolution occurs, Guile will issue warning messages about code that uses features that have been marked for eventual elimination. `GUILE_WARN_DEPRECATED' can be set to "no" to tell Guile not to display these warning messages, or set to "detailed" to tell Guile to display more lengthy messages describing the warning. *Note Deprecation::. `HOME' Guile uses the environment variable `HOME', the name of your home directory, to locate various files, such as `.guile' or `.guile_history'. `LTDL_LIBRARY_PATH' Guile now adds its install prefix to the `LTDL_LIBRARY_PATH'. Users may now install Guile in non-standard directories and run `/path/to/bin/guile', without having also to set `LTDL_LIBRARY_PATH' to include `/path/to/lib'.