Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
4b4b1e0b | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011 |
2da09c3f MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
3d9af0c9 NJ |
7 | @node Introduction |
8 | @chapter Introduction | |
9 | ||
10 | Guile is an implementation of the Scheme programming language. Scheme | |
4b4b1e0b AW |
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 | |
95c2df5c NJ |
14 | @tex |
15 | Revised$^n$ | |
16 | @end tex | |
17 | @ifnottex | |
18 | Revised^n | |
19 | @end ifnottex | |
84d86e74 | 20 | Reports on Scheme). |
3d9af0c9 | 21 | |
f0c56cad | 22 | Unlike, for example, Python or Perl, Scheme has no benevolent |
3d9af0c9 NJ |
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 | |
84d86e74 | 27 | |
3d9af0c9 NJ |
28 | @itemize |
29 | @item | |
30 | it is easy to combine with other code written in C | |
31 | @item | |
32 | it has a historical and continuing connection with the GNU Project | |
33 | @item | |
34 | it emphasizes interactive and incremental programming | |
35 | @item | |
36 | it actually supports several languages, not just Scheme. | |
37 | @end itemize | |
84d86e74 | 38 | |
3d9af0c9 | 39 | @noindent |
45a272c5 | 40 | The next few sections explain what we mean by these points. The sections after |
46733b42 NJ |
41 | that cover how you can obtain and install Guile, and the typographical |
42 | conventions that we use in this manual. | |
3229f68b MV |
43 | |
44 | @menu | |
ebb6158f NJ |
45 | * Guile and Scheme:: |
46 | * Combining with C:: | |
3ce5e130 NJ |
47 | * Guile and the GNU Project:: |
48 | * Interactive Programming:: | |
49 | * Supporting Multiple Languages:: | |
3229f68b | 50 | * Obtaining and Installing Guile:: |
79bd99b3 | 51 | * Organisation of this Manual:: |
65de7494 | 52 | * Typographical Conventions:: |
3229f68b MV |
53 | @end menu |
54 | ||
ebb6158f NJ |
55 | @node Guile and Scheme |
56 | @section Guile and Scheme | |
38a93523 | 57 | |
ebb6158f | 58 | Guile implements Scheme as described in the |
38a93523 NJ |
59 | @tex |
60 | Revised$^5$ | |
61 | @end tex | |
801892e7 | 62 | @ifnottex |
38a93523 | 63 | Revised^5 |
801892e7 | 64 | @end ifnottex |
ebb6158f NJ |
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 | |
72 | world. | |
73 | ||
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 | |
f0c56cad | 77 | implementations---including Guile---have previously done in |
ebb6158f NJ |
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 | |
845cbcfe | 81 | implementation. @xref{R6RS Support}. |
ebb6158f | 82 | |
0a864beb NJ |
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}. | |
ebb6158f NJ |
87 | |
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. | |
91 | ||
92 | @node Combining with C | |
0a864beb NJ |
93 | @section Combining with C Code |
94 | ||
f0c56cad LC |
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, | |
0a864beb NJ |
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 | |
106 | language design. | |
38a93523 | 107 | |
c6c8e7e0 NJ |
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 | |
f0c56cad | 112 | rather technical points---that Guile uses conservative garbage |
c6c8e7e0 | 113 | collection, and that it implements the Scheme concept of continuations |
f0c56cad | 114 | by copying and reinstating the C stack---but whose practical |
c6c8e7e0 NJ |
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. | |
119 | ||
38a93523 | 120 | Guile's module system allows one to break up a large program into |
01b30204 MV |
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. | |
38a93523 | 128 | |
3ce5e130 NJ |
129 | @node Guile and the GNU Project |
130 | @section Guile and the GNU Project | |
131 | ||
0a864beb NJ |
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. | |
137 | ||
5bcaf46b NJ |
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. | |
147 | ||
0a864beb NJ |
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 | |
150 | future. | |
151 | ||
3ce5e130 NJ |
152 | @node Interactive Programming |
153 | @section Interactive Programming | |
154 | ||
0a864beb NJ |
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. | |
158 | ||
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. | |
163 | ||
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. | |
171 | ||
1d84577c NJ |
172 | Guile is designed for this kind of interactive programming, and this |
173 | distinguishes it from many Scheme implementations that instead prioritise | |
f0c56cad | 174 | running a fixed Scheme program as fast as possible---because there are |
1d84577c NJ |
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 | |
178 | experimentation. | |
0a864beb | 179 | |
3ce5e130 NJ |
180 | @node Supporting Multiple Languages |
181 | @section Supporting Multiple Languages | |
182 | ||
0a864beb NJ |
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 | |
187 | Python. | |
188 | ||
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 | |
38a93523 NJ |
191 | imposed on them. |
192 | ||
3229f68b MV |
193 | @node Obtaining and Installing Guile |
194 | @section Obtaining and Installing Guile | |
195 | ||
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 | |
0a864beb | 198 | guile-@var{version}.tar.gz. The current version is @value{VERSION}, so the |
3229f68b MV |
199 | file you should grab is: |
200 | ||
3c4ecddd | 201 | @url{ftp://ftp.gnu.org/gnu/guile/guile-@value{VERSION}.tar.gz} |
3229f68b MV |
202 | |
203 | To unbundle Guile use the instruction | |
204 | ||
205 | @example | |
206 | zcat guile-@value{VERSION}.tar.gz | tar xvf - | |
207 | @end example | |
208 | ||
31c73458 | 209 | @noindent |
3229f68b MV |
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 | |
213 | to just do | |
214 | ||
215 | @example | |
216 | cd guile-@value{VERSION} | |
217 | ./configure | |
218 | make | |
219 | make install | |
220 | @end example | |
221 | ||
222 | This will install the Guile executable @file{guile}, the Guile library | |
0a864beb NJ |
223 | @file{libguile} and various associated header files and support libraries. It |
224 | will also install the Guile reference manual. | |
3229f68b MV |
225 | |
226 | @c [[include instructions for getting R5RS]] | |
227 | ||
228 | Since this manual frequently refers to the Scheme ``standard'', also | |
229 | known as R5RS, or the | |
31c73458 | 230 | @tex |
3229f68b | 231 | ``Revised$^5$ Report on the Algorithmic Language Scheme'', |
31c73458 | 232 | @end tex |
3229f68b MV |
233 | @ifnottex |
234 | ``Revised^5 Report on the Algorithmic Language Scheme'', | |
235 | @end ifnottex | |
31c73458 NJ |
236 | we have included the report in the Guile distribution; see |
237 | @ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic | |
3229f68b MV |
238 | Language Scheme}. |
239 | This will also be installed in your info directory. | |
9401323e | 240 | |
79bd99b3 NJ |
241 | @node Organisation of this Manual |
242 | @section Organisation of this Manual | |
243 | ||
244 | The rest of this manual is organised into the following chapters. | |
245 | ||
246 | @table @strong | |
d93c0bc4 NJ |
247 | @item Chapter 2: Hello Guile! |
248 | A whirlwind tour shows how Guile can be used interactively and as | |
79bd99b3 NJ |
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 | |
d93c0bc4 NJ |
252 | the later parts of the manual. |
253 | ||
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. | |
258 | ||
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 | |
263 | Scheme. | |
264 | ||
265 | @item Chapter 5: Programming in C | |
266 | Provides an overview of how to use Guile in a C program. It | |
79bd99b3 NJ |
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. | |
271 | ||
d93c0bc4 | 272 | @item Chapter 6: Guile API Reference |
79bd99b3 NJ |
273 | This part of the manual documents the Guile @acronym{API} in |
274 | functionality-based groups with the Scheme and C interfaces presented | |
275 | side by side. | |
276 | ||
d93c0bc4 | 277 | @item Chapter 7: Guile Modules |
79bd99b3 NJ |
278 | Describes some important modules, distributed as part of the Guile |
279 | distribution, that extend the functionality provided by the Guile | |
280 | Scheme core. | |
281 | ||
d93c0bc4 | 282 | @item Chapter 8: GOOPS |
79bd99b3 NJ |
283 | Describes GOOPS, an object oriented extension to Guile that provides |
284 | classes, multiple inheritance and generic functions. | |
285 | ||
286 | @end table | |
287 | ||
65de7494 NJ |
288 | @node Typographical Conventions |
289 | @section Typographical Conventions | |
290 | ||
291 | We use some conventions in this manual. | |
292 | ||
293 | @itemize @bullet | |
294 | ||
295 | @item | |
296 | For some procedures, notably type predicates, we use ``iff'' to mean | |
297 | ``if and only if''. The construct is usually something like: `Return | |
298 | @var{val} iff @var{condition}', where @var{val} is usually | |
299 | ``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that | |
300 | @var{val} is returned if @var{condition} holds, and that @samp{#f} is | |
301 | returned otherwise. To clarify: @var{val} will @strong{only} be | |
302 | returned when @var{condition} is true. | |
303 | @cindex iff | |
304 | ||
305 | @item | |
306 | In examples and procedure descriptions and all other places where the | |
307 | evaluation of Scheme expression is shown, we use some notation for | |
308 | denoting the output and evaluation results of expressions. | |
309 | ||
310 | The symbol @samp{@result{}} is used to tell which value is returned by | |
311 | an evaluation: | |
312 | ||
313 | @lisp | |
314 | (+ 1 2) | |
315 | @result{} 3 | |
316 | @end lisp | |
317 | ||
318 | Some procedures produce some output besides returning a value. This | |
319 | is denoted by the symbol @samp{@print{}}. | |
320 | ||
321 | @lisp | |
322 | (begin (display 1) (newline) 'hooray) | |
323 | @print{} 1 | |
324 | @result{} hooray | |
325 | @end lisp | |
326 | ||
327 | As you can see, this code prints @samp{1} (denoted by | |
328 | @samp{@print{}}), and returns @code{hooray} (denoted by | |
de3ba527 | 329 | @samp{@result{}}). |
65de7494 NJ |
330 | |
331 | @c Add other conventions here. | |
332 | ||
333 | @end itemize | |
334 | ||
38a93523 NJ |
335 | |
336 | @c Local Variables: | |
337 | @c TeX-master: "guile.texi" | |
338 | @c End: |