2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011, 2013
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
10 Guile is an implementation of the Scheme programming language. Scheme
11 (@url{http://schemers.org/}) is an elegant and conceptually simple
12 dialect of Lisp, originated by Guy Steele and Gerald Sussman, and since
13 evolved by the series of reports known as RnRS (the
22 Unlike, for example, Python or Perl, Scheme has no benevolent
23 dictator. There are many Scheme implementations, with different
24 characteristics and with communities and academic activities around
25 them, and the language develops as a result of the interplay between
26 these. Guile's particular characteristics are that
30 it is easy to combine with other code written in C
32 it has a historical and continuing connection with the GNU Project
34 it emphasizes interactive and incremental programming
36 it actually supports several languages, not just Scheme.
40 The next few sections explain what we mean by these points. The sections after
41 that cover how you can obtain and install Guile, and the typographical
42 conventions that we use in this manual.
47 * Guile and the GNU Project::
48 * Interactive Programming::
49 * Supporting Multiple Languages::
50 * Obtaining and Installing Guile::
51 * Organisation of this Manual::
52 * Typographical Conventions::
55 @node Guile and Scheme
56 @section Guile and Scheme
58 Guile implements Scheme as described in the
65 Report on the Algorithmic Language Scheme (usually known as
66 @acronym{R5RS}), providing clean and general data and control
67 structures. Guile goes beyond the rather austere language presented
68 in @acronym{R5RS}, extending it with a module system, full access to
69 @acronym{POSIX} system calls, networking support, multiple threads,
70 dynamic linking, a foreign function call interface, powerful string
71 processing, and many other features needed for programming in the real
74 The Scheme community has recently agreed and published R6RS, the
75 latest installment in the RnRS series. R6RS significantly expands the
76 core Scheme language, and standardises many non-core functions that
77 implementations---including Guile---have previously done in
78 different ways. Guile has been updated to incorporate some of the
79 features of R6RS, and to adjust some existing features to conform to
80 the R6RS specification, but it is by no means a complete R6RS
81 implementation. @xref{R6RS Support}.
83 Between R5RS and R6RS, the SRFI process (@url{http://srfi.schemers.org/})
84 standardised interfaces for many practical needs, such as multithreaded
85 programming and multidimensional arrays. Guile supports many SRFIs, as
86 documented in detail in @ref{SRFI Support}.
88 In summary, so far as relationship to the Scheme standards is
89 concerned, Guile is an R5RS implementation with many extensions, some
90 of which conform to SRFIs or to the relevant parts of R6RS.
92 @node Combining with C
93 @section Combining with C Code
95 Like a shell, Guile can run interactively---reading expressions from the user,
96 evaluating them, and displaying the results---or as a script interpreter,
97 reading and executing Scheme code from a file. Guile also provides an object
98 library, @dfn{libguile}, that allows other applications to easily incorporate a
99 complete Scheme interpreter. An application can then use Guile as an extension
100 language, a clean and powerful configuration language, or as multi-purpose
101 ``glue'', connecting primitives provided by the application. It is easy to call
102 Scheme code from C code and vice versa, giving the application designer full
103 control of how and when to invoke the interpreter. Applications can add new
104 functions, data types, control structures, and even syntax to Guile, creating a
105 domain-specific language tailored to the task at hand, but based on a robust
108 This kind of combination is helped by four aspects of Guile's design
109 and history. First is that Guile has always been targeted as an
110 extension language. Hence its C API has always been of great
111 importance, and has been developed accordingly. Second and third are
112 rather technical points---that Guile uses conservative garbage
113 collection, and that it implements the Scheme concept of continuations
114 by copying and reinstating the C stack---but whose practical
115 consequence is that most existing C code can be glued into Guile as
116 is, without needing modifications to cope with strange Scheme
117 execution flows. Last is the module system, which helps extensions to
118 coexist without stepping on each others' toes.
120 Guile's module system allows one to break up a large program into
121 manageable sections with well-defined interfaces between them.
122 Modules may contain a mixture of interpreted and compiled code; Guile
123 can use either static or dynamic linking to incorporate compiled code.
124 Modules also encourage developers to package up useful collections of
125 routines for general distribution; as of this writing, one can find
126 Emacs interfaces, database access routines, compilers, @acronym{GUI}
127 toolkit interfaces, and @acronym{HTTP} client functions, among others.
129 @node Guile and the GNU Project
130 @section Guile and the GNU Project
132 Guile was conceived by the GNU Project following the fantastic success
133 of Emacs Lisp as an extension language within Emacs. Just as Emacs
134 Lisp allowed complete and unanticipated applications to be written
135 within the Emacs environment, the idea was that Guile should do the
136 same for other GNU Project applications. This remains true today.
138 The idea of extensibility is closely related to the GNU project's
139 primary goal, that of promoting software freedom. Software freedom
140 means that people receiving a software package can modify or enhance
141 it to their own desires, including in ways that may not have occurred
142 at all to the software's original developers. For programs written in
143 a compiled language like C, this freedom covers modifying and
144 rebuilding the C code; but if the program also provides an extension
145 language, that is usually a much friendlier and lower-barrier-of-entry
146 way for the user to start making their own changes.
148 Guile is now used by GNU project applications such as AutoGen, Lilypond, Denemo,
149 Mailutils, TeXmacs and Gnucash, and we hope that there will be many more in
152 @node Interactive Programming
153 @section Interactive Programming
155 Non-free software has no interest in its users being able to see how it works.
156 They are supposed to just accept it, or to report problems and hope that the
157 source code owners will choose to work on them.
159 Free software aims to work reliably just as much as non-free software does, but
160 it should also empower its users by making its workings available. This is
161 useful for many reasons, including education, auditing and enhancements, as well
162 as for debugging problems.
164 The ideal free software system achieves this by making it easy for interested
165 users to see the source code for a feature that they are using, and to follow
166 through that source code step-by-step, as it runs. In Emacs, good examples of
167 this are the source code hyperlinks in the help system, and @code{edebug}.
168 Then, for bonus points and maximising the ability for the user to experiment
169 quickly with code changes, the system should allow parts of the source code to
170 be modified and reloaded into the running program, to take immediate effect.
172 Guile is designed for this kind of interactive programming, and this
173 distinguishes it from many Scheme implementations that instead prioritise
174 running a fixed Scheme program as fast as possible---because there are
175 tradeoffs between performance and the ability to modify parts of an already
176 running program. There are faster Schemes than Guile, but Guile is a GNU
177 project and so prioritises the GNU vision of programming freedom and
180 @node Supporting Multiple Languages
181 @section Supporting Multiple Languages
183 Since the 2.0 release, Guile's architecture supports compiling any language to
184 its core virtual machine bytecode, and Scheme is just one of the supported
185 languages. Other supported languages are Emacs Lisp, ECMAScript (commonly known
186 as Javascript) and Brainfuck, and work is under discussion for Lua, Ruby and
189 This means that users can program applications which use Guile in the language
190 of their choice, rather than having the tastes of the application's author
193 @node Obtaining and Installing Guile
194 @section Obtaining and Installing Guile
196 Guile can be obtained from the main GNU archive site
197 @url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named
198 guile-@var{version}.tar.gz. The current version is @value{VERSION}, so the
199 file you should grab is:
201 @url{ftp://ftp.gnu.org/gnu/guile/guile-@value{VERSION}.tar.gz}
203 To unbundle Guile use the instruction
206 zcat guile-@value{VERSION}.tar.gz | tar xvf -
210 which will create a directory called @file{guile-@value{VERSION}} with
211 all the sources. You can look at the file @file{INSTALL} for detailed
212 instructions on how to build and install Guile, but you should be able
216 cd guile-@value{VERSION}
222 This will install the Guile executable @file{guile}, the Guile library
223 @file{libguile} and various associated header files and support libraries. It
224 will also install the Guile reference manual.
226 @c [[include instructions for getting R5RS]]
228 Since this manual frequently refers to the Scheme ``standard'', also
229 known as R5RS, or the
231 ``Revised$^5$ Report on the Algorithmic Language Scheme'',
234 ``Revised^5 Report on the Algorithmic Language Scheme'',
236 we have included the report in the Guile distribution; see
237 @ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
239 This will also be installed in your info directory.
241 @node Organisation of this Manual
242 @section Organisation of this Manual
244 The rest of this manual is organised into the following chapters.
247 @item Chapter 2: Hello Guile!
248 A whirlwind tour shows how Guile can be used interactively and as
249 a script interpreter, how to link Guile into your own applications,
250 and how to write modules of interpreted and compiled code for use with
251 Guile. Everything introduced here is documented again and in full by
252 the later parts of the manual.
254 @item Chapter 3: Hello Scheme!
255 For readers new to Scheme, this chapter provides an introduction to the basic
256 ideas of the Scheme language. This material would apply to any Scheme
257 implementation and so does not make reference to anything Guile-specific.
259 @item Chapter 4: Programming in Scheme
260 Provides an overview of programming in Scheme with Guile. It covers how to
261 invoke the @code{guile} program from the command-line and how to write scripts
262 in Scheme. It also introduces the extensions that Guile offers beyond standard
265 @item Chapter 5: Programming in C
266 Provides an overview of how to use Guile in a C program. It
267 discusses the fundamental concepts that you need to understand to
268 access the features of Guile, such as dynamic types and the garbage
269 collector. It explains in a tutorial like manner how to define new
270 data types and functions for the use by Scheme programs.
272 @item Chapter 6: Guile API Reference
273 This part of the manual documents the Guile @acronym{API} in
274 functionality-based groups with the Scheme and C interfaces presented
277 @item Chapter 7: Guile Modules
278 Describes some important modules, distributed as part of the Guile
279 distribution, that extend the functionality provided by the Guile
282 @item Chapter 8: GOOPS
283 Describes GOOPS, an object oriented extension to Guile that provides
284 classes, multiple inheritance and generic functions.
288 @node Typographical Conventions
289 @section Typographical Conventions
291 In examples and procedure descriptions and all other places where the
292 evaluation of Scheme expression is shown, we use some notation for
293 denoting the output and evaluation results of expressions.
295 The symbol @samp{@result{}} is used to tell which value is returned by
303 Some procedures produce some output besides returning a value. This
304 is denoted by the symbol @samp{@print{}}.
307 (begin (display 1) (newline) 'hooray)
312 As you can see, this code prints @samp{1} (denoted by
313 @samp{@print{}}), and returns @code{hooray} (denoted by
318 @c TeX-master: "guile.texi"