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