@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2006, 2010
+@c Copyright (C) 2006, 2010, 2011, 2012, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
support for languages other than Scheme.
@menu
+* Init File::
* Readline::
* Value History::
* REPL Commands::
@end menu
+@node Init File
+@subsection The Init File, @file{~/.guile}
+
+@cindex .guile
+When run interactively, Guile will load a local initialization file from
+@file{~/.guile}. This file should contain Scheme expressions for
+evaluation.
+
+This facility lets the user customize their interactive Guile
+environment, pulling in extra modules or parameterizing the REPL
+implementation.
+
+To run Guile without loading the init file, use the @code{-q}
+command-line option.
+
+
@node Readline
@subsection Readline
@end lisp
It's a good idea to put these two lines (without the
-@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file. Guile
-reads this file when it starts up interactively, so anything in this
-file has the same effect as if you type it in by hand at the
-@code{scheme@@(guile-user)>} prompt.
+@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file.
+@xref{Init File}, for more on @file{.guile}.
@node Value History
@end lisp
@deffn {Scheme Procedure} value-history-enabled?
-Return true iff value history is enabled.
+Return true if value history is enabled, or false otherwise.
@end deffn
@deffn {Scheme Procedure} enable-value-history!
Change modules / Show current module.
@end deffn
-@deffn {REPL Command} import [module ...]
+@deffn {REPL Command} import module @dots{}
Import modules / List those imported.
@end deffn
Load a file in the current module.
@end deffn
+@deffn {REPL Command} reload [module]
+Reload the given module, or the current module if none was given.
+@end deffn
+
@deffn {REPL Command} binding
List current bindings.
@end deffn
+@deffn {REPL Command} in module expression
+@deffnx {REPL Command} in module command arg @dots{}
+Evaluate an expression, or alternatively, execute another meta-command
+in the context of a module. For example, @samp{,in (foo bar) ,binding}
+will show the bindings in the module @code{(foo bar)}.
+@end deffn
+
@node Language Commands
@subsubsection Language Commands
Compile a file.
@end deffn
+@deffn {REPL Command} expand exp
+Expand any macros in a form.
+@end deffn
+
+@deffn {REPL Command} optimize exp
+Run the optimizer on a piece of code and print the result.
+@end deffn
+
@deffn {REPL Command} disassemble exp
Disassemble a compiled procedure.
@end deffn
Profile execution.
@end deffn
-@deffn {REPL Command} trace exp
+@deffn {REPL Command} trace exp [#:width w] [#:max-indent i]
Trace execution.
+
+By default, the trace will limit its width to the width of your
+terminal, or @var{width} if specified. Nested procedure invocations
+will be printed farther to the right, though if the width of the
+indentation passes the @var{max-indent}, the indentation is abbreviated.
@end deffn
@node Debug Commands
@deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
Print a backtrace.
-Print a backtrace of all stack frames, or innermost @var{COUNT} frames.
+Print a backtrace of all stack frames, or innermost @var{count} frames.
If @var{count} is negative, the last @var{count} frames will be shown.
@end deffn
@xref{Stack Layout}, for more information on VM stack frames.
@end deffn
+@deffn {REPL Command} width [cols]
+Sets the number of display columns in the output of @code{,backtrace}
+and @code{,locals} to @var{cols}. If @var{cols} is not given, the width
+of the terminal is used.
+@end deffn
+
The next 3 commands work at any REPL.
@deffn {REPL Command} break proc
@node Inspect Commands
@subsubsection Inspect Commands
-@deffn {REPL Command} inspect EXP
+@deffn {REPL Command} inspect exp
Inspect the result(s) of evaluating @var{exp}.
@end deffn
-@deffn {REPL Command} pretty-print EXP
+@deffn {REPL Command} pretty-print exp
Pretty-print the result(s) of evaluating @var{exp}.
@end deffn
Display statistics.
@end deffn
-@deffn {REPL Command} option [key value]
-List/show/set options.
+@deffn {REPL Command} option [name] [exp]
+With no arguments, lists all options. With one argument, shows the
+current value of the @var{name} option. With two arguments, sets the
+@var{name} option to the result of evaluating the Scheme expression
+@var{exp}.
@end deffn
@deffn {REPL Command} quit
Quit this session.
@end deffn
+Current REPL options include:
+
+@table @code
+@item compile-options
+The options used when compiling expressions entered at the REPL.
+@xref{Compilation}, for more on compilation options.
+@item interp
+Whether to interpret or compile expressions given at the REPL, if such a
+choice is available. Off by default (indicating compilation).
+@item prompt
+A customized REPL prompt. @code{#f} by default, indicating the default
+prompt.
+@item print
+A procedure of two arguments used to print the result of evaluating each
+expression. The arguments are the current REPL and the value to print.
+By default, @code{#f}, to use the default procedure.
+@item value-history
+Whether value history is on or not. @xref{Value History}.
+@item on-error
+What to do when an error happens. By default, @code{debug}, meaning to
+enter the debugger. Other values include @code{backtrace}, to show a
+backtrace without entering the debugger, or @code{report}, to simply
+show a short error printout.
+@end table
+
+Default values for REPL options may be set using
+@code{repl-default-option-set!} from @code{(system repl common)}:
+
+@deffn {Scheme Procedure} repl-default-option-set! key value
+Set the default value of a REPL option. This function is particularly
+useful in a user's init file. @xref{Init File}.
+@end deffn
+
@node Error Handling
@subsection Error Handling
truth, regardless.) Paredit is the bee's knees.
@cindex Geiser
-The second is José Antonio Ortega Ruiz's
+The second is
+@iftex
+Jos@'e
+@end iftex
+@ifnottex
+José
+@end ifnottex
+Antonio Ortega Ruiz's
@uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
@code{scheme-mode} with tight integration to running Guile processes via
a @code{comint-mode} REPL buffer.
information.
+@node Using Guile Tools
+@section Using Guile Tools
+
+@cindex guild
+@cindex guile-tools
+@cindex wizards
+Guile also comes with a growing number of command-line utilities: a
+compiler, a disassembler, some module inspectors, and in the future, a
+system to install Guile packages from the internet. These tools may be
+invoked using the @code{guild} program.
+
+@example
+$ guild compile -o foo.go foo.scm
+wrote `foo.go'
+@end example
+
+This program used to be called @code{guile-tools} up to
+Guile version 2.0.1, and for backward
+compatibility it still may be called as such. However we changed the
+name to @code{guild}, not only because it is pleasantly shorter and
+easier to read, but also because this tool will serve to bind Guile
+wizards together, by allowing hackers to share code with each other
+using a CPAN-like system.
+
+@xref{Compilation}, for more on @code{guild compile}.
+
+A complete list of guild scripts can be had by invoking @code{guild
+list}, or simply @code{guild}.
+
+
+@node Installing Site Packages
+@section Installing Site Packages
+
+@cindex site
+@cindex site path
+@cindex load path
+@findex %site-dir
+@findex %site-ccache-dir
+
+At some point, you will probably want to share your code with other
+people. To do so effectively, it is important to follow a set of common
+conventions, to make it easy for the user to install and use your
+package.
+
+The first thing to do is to install your Scheme files where Guile can
+find them. When Guile goes to find a Scheme file, it will search a
+@dfn{load path} to find the file: first in Guile's own path, then in
+paths for @dfn{site packages}. A site package is any Scheme code that
+is installed and not part of Guile itself. @xref{Load Paths}, for more
+on load paths.
+
+There are several site paths, for historical reasons, but the one that
+should generally be used can be obtained by invoking the
+@code{%site-dir} procedure. @xref{Build Config}. If Guile
+@value{EFFECTIVE-VERSION} is installed on your system in @code{/usr/},
+then @code{(%site-dir)} will be
+@code{/usr/share/guile/site/@value{EFFECTIVE-VERSION}}. Scheme files
+should be installed there.
+
+If you do not install compiled @code{.go} files, Guile will compile your
+modules and programs when they are first used, and cache them in the
+user's home directory. @xref{Compilation}, for more on
+auto-compilation. However, it is better to compile the files before
+they are installed, and to just copy the files to a place that Guile can
+find them.
+
+As with Scheme files, Guile searches a path to find compiled @code{.go}
+files, the @code{%load-compiled-path}. By default, this path has two
+entries: a path for Guile's files, and a path for site packages. You
+should install your @code{.go} files into the latter directory, whose
+value is returned by invoking the @code{%site-ccache-dir} procedure. As
+in the previous example, if Guile @value{EFFECTIVE-VERSION} is installed
+on your system in @code{/usr/}, then @code{(%site-ccache-dir)} site
+packages will be
+@code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}.
+
+Note that a @code{.go} file will only be loaded in preference to a
+@code{.scm} file if it is newer. For that reason, you should install
+your Scheme files first, and your compiled files second. @code{Load
+Paths}, for more on the loading process.
+
+Finally, although this section is only about Scheme, sometimes you need
+to install C extensions too. Shared libraries should be installed in
+the @dfn{extensions dir}. This value can be had from the build config
+(@pxref{Build Config}). Again, if Guile @value{EFFECTIVE-VERSION} is
+installed on your system in @code{/usr/}, then the extensions dir will
+be @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/extensions}.
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
HCoop / bpt / guile.git / blobdiff