source: project/wiki/new-chapter1 @ 8741

Last change on this file since 8741 was 8741, checked in by svnwiki, 12 years ago

Changes applied for John Cowan (74.68.115.13) through svnwiki:

Oopsie. Fixed formatting.

File size: 21.3 KB
Line 
1== Getting started with Chicken
2
3TODO: this page is a revision and expansion of the existing Chapter 1
4of the Chicken manual. The goal is to give an overview of the whole
5system, and to give the new user some recipes for common use cases.
6I know this is somewhat verbose, and would be happy to eliminate
7unnecessary verbiage, but I do think the content shown here is
8worthwhile. Your mileage, of course, might vary :-) -- vincent
9
10''(This document describes version 3.0.0)'' TODO: the version number
11should be moved from here to the cover or index page. ''No, leave the Chicken version number on every manual page so that we know if a non-updated page exists. --John Cowan''
12
13'''Chicken is a compiler that translates Scheme source files into
14C''', which in turn can be fed to a C compiler to generate a
15standalone executable.  An interpreter is also available and can be
16used as a scripting environment or for testing programs before
17compilation.
18
19This chapter is designed to get you started with Chicken programming,
20describing what it is and what it will do for you, and covering basic
21use of the system. With almost everything discussed here, there is
22more to the story, which the remainder of the manual reveals. Here, we
23only cover enough to get you started. Nonetheless, someone who knows
24Scheme already should be able to use this chapter as the basis for
25writing and running small Chicken programs.
26
27=== Scheme
28
29Scheme is a member of the Lisp family of languages, of which Common
30Lisp and Emacs Lisp are the other two widely-known members. As with
31Lisp dialects, Scheme features
32
33* a wide variety of programming paradigms, including imperative, functional, and object-oriented
34* a very simple syntax, based upon nested parenthesization
35* the ability to extend the language in meaningful and useful ways
36
37In contrast to Common Lisp, Scheme is very minimal, and tries to
38include only those features absolutely necessary in programming. In
39contrast to Emacs Lisp, Scheme is not anchored into any one program
40(Emacs), and has a somewhat more modern language design.
41
42Scheme is defined in a document called ''The Revised^5 Report on the Algorithmic Language Scheme'', or ''R5RS'' for short. (Yes, it really has been revised five times, so an expanded version of its name would be ''The Revised Revised Revised Revised Revised Report''.)  A newer report, ''R6RS'', was
43released in 2007, but this report has attracted considerable
44controversy, and not all Scheme implementations will be made compliant
45with it. Chicken essentially complies with R5RS.
46
47Even though Scheme is consciously minimalist, it is recognized that a
48language must be more than a minimal core in order to be
49useful. Accordingly, the Scheme community uses a process known as
50`Scheme Requests For Implementation' (SRFI, pronounced `SUR-fee') to
51define new language features. A typical Scheme system therefore
52complies with one of the Scheme reports plus some or all of the
53accepted SRFIs.
54
55A good starting point for Scheme knowledge is
56[[http://www.schemers.org]]. There you will find the defining reports,
57FAQs, lists of useful books and other resources, and the SRFIs.
58
59The Chicken community is at present developing tutorials for
60programmers who are new to Scheme but experienced with Python, Ruby,
61or other languages. These can be found on the Chicken wiki.
62
63=== Chicken
64
65Chicken is an implementation of Scheme that has many advantages.
66
67<blockquote>
68Chicken Scheme combines an optimising compiler with a reasonably fast
69interpreter.  It supports almost all of R5RS and the important SRFIs.
70The compiler generates portable C code that supports tail recursion,
71first-class continuations, and lightweight threads, and the interface to
72and from C libraries is flexible, efficient, and easy to use.  There are
73hundreds of contributed Chicken libraries that make the programmer's
74task easier.  The interpreter allows interactive use, fast prototyping,
75debugging, and scripting.  The active and helpful Chicken community
76fixes bugs and provides support.  Extensive documentation is supplied.
77</blockquote>
78
79Chicken includes
80
81* a Scheme interpreter that supports almost all of  R5RS Scheme, with
82  only a few relatively minor omissions, and with many extensions
83* a compatible compiler whose target is C, thus making porting to new
84  machines and architectures relatively straightforward
85** the C support allows Scheme code to include `embedded' C code,
86  thus making it relatively easy to invoke host OS or library
87  functions
88* a framework for language extensions, library modules that broaden
89  the functionality of the system
90
91This package is distributed under the '''BSD license''' and as such is free
92to use and modify.
93
94Scheme cognoscenti will appreciate the method of compilation and the
95design of the runtime-system, which follow closely Henry Baker's
96[[http://home.pipeline.com/~hbaker1/CheneyMTA.html|CONS Should Not
97CONS Its Arguments, Part II: Cheney on the M.T.A.]] paper and expose a
98number of interesting properties.
99
100* Consing (creation of data on the heap) is relatively inexpensive,
101  because a generational garbage collection scheme is used, in which
102  short-lived data structures are reclaimed extremely quickly.
103
104* Moreover, {{call-with-current-continuation}} is practically for free
105  and Chicken does not suffer under any performance penalties if
106  first-class continuations are used in complex ways.
107
108The generated C code is fully tail-recursive.
109
110Some of the features supported by Chicken:
111
112* SRFIs 0, 1, 2, 4, 6-19, 23, 25-31, 37-40, 42, 43, 45, 47, 55, 57,
113  60-63, 66, 69, 72, 78, 85 and 95.
114* Lightweight threads based on first-class continuations
115* Pattern matching with Andrew Wright's {{match}} package
116* Record structures
117* Extended comment- and string-literal syntaxes
118* Libraries for regular expressions, string handling
119* UNIX system calls and extended data structures
120* Create interpreted or compiled shell scripts written in Scheme for
121  UNIX or Windows
122* Compiled C files can be easily distributed
123* Allows the creation of fully self-contained statically linked executables
124* On systems that support it, compiled code can be loaded dynamically
125
126Chicken has been used in many environments ranging from embedded
127systems through desktop machines to large-scale server deployments. 
128The number of language extensions, or '''eggs''', will soon reach 400,
129including
130
131* extended language features
132* development tools, such as documentation generators, debugging, and
133  automated testing libraries
134* interfaces to other languages such as Java, Python, and Objective-C
135* interfaces to database systems, GUIs, and other large-scale
136  libraries,
137* network applications, such as servers and clients for ftp,
138  smtp/pop3, irc, and http 
139* web servers and related tools, including URL parsing, HTML
140  generation, AJAX, and HTTP session management
141* data formats, including XML, JSON, and Unicode support
142
143Chicken is supported by SWIG (Simplified Wrapper and Interface
144Generator), a tool that produces quick-and-dirty interface modules
145for C libraries ([[http://www.swig.org]]).
146
147This chapter provides you with an overview of the entire system, with
148enough information to get started writing and running small Scheme
149programs. Subsequent chapters cover
150
151* [[Basic mode of operation]]: Compiling Scheme files.
152
153* [[Using the compiler]]: Explains how to use Chicken to compile
154  programs and execute them.
155
156* [[Using the interpreter]]: Invocation and usage of {{csi}}, the
157  Chicken interpreter
158
159* [[Supported language]]: The language implemented by Chicken
160  (deviations from the standard and extensions).
161
162* [[Interface to external functions and variables]]: Accessing C and
163  C++ code and data.
164
165* [[chicken-setup]]: Packaging and installing extension libraries.
166
167* [[Data representation]]: How Scheme data is internally represented.
168
169* [[Bugs and limitations]]: Yes, there are some.
170
171* [[FAQ]]: A list of Frequently Asked Questions about Chicken (and
172  their answers!).
173
174* [[Acknowledgements]]: A list of some of the people that have
175  contributed to make Chicken what it is.
176
177* [[Bibliography]]: Links to documents that may be of interest.
178
179=== Installing Chicken
180
181Chicken is available in binary form for Windows and Linux/x86
182systems, and in source form for all other platforms. Refer to the
183{{README}} file in the distribution for instructions on installing it
184on your system.
185
186Because it compiles to C, Chicken requires that a C compiler be
187installed on your system. (If you're not writing embedded C code, you
188can pretty much ignore the C compiler once you have installed it.)
189
190* On a Linux system, the GNU Compiler Collection ({{gcc}}) should be installed as part of the basic operating system.
191* On Macintosh OS X, you will need the XCode tools, which are shipped on the OS X DVD with recent versions of the operating system.  ''What about Fink or such?''
192* On Windows, you have four choices.
193** Cygwin ([[http://sources.redhat.com/cygwin]]) provides a relatively full-featured Unix environment for Windows.
194** The GNU Compiler Collection has been ported to Windows, in the MinGW system ([[http://mingw.sourceforge.net]]). Unlike Cygwin,  executables produced with MinGW do not need the Cygwin DLLs in order to run.
195*** TODO: explain mingw build here
196*** TODO: explain mingw-msys build here
197** Microsoft Visual Studio will soon be supported, including the Express edition, which is a non-free but no-cost compiler suite available from Microsoft   ([[http://www.microsoft.com/express/vc]]). Chicken supports command-line building using the Microsoft C/C++ compiler.  Visual Studio users will want to install the Unix Utilities, available at  [[http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip]], in order to get suitable versions of {{make}}, {tar}}, {{gzip}}, and similar commands.
198
199TODO: what's the least we can possibly say about PATH,
200CHICKEN_INCLUDE_PATH, DYLD_LIBRARY_PATH, etc?  ''The least we can say at this point is nothing at all.  Let's do that.''
201
202=== Development environments
203
204The simplest development environment is a text editor and terminal
205window (Windows: Command Prompt, OSX: Terminal, Linux/Unix: xterm). If
206you install the {{readline}} egg (TODO: insert xref), you have all the
207benefits of command history and reentry, Emacs or vi-compatible line
208editing, and customization.
209
210You will need a text editor that knows Scheme; it's just too painful
211with editors that don't do parenthesis matching and proper
212indentation. Some editors allow you to execute Scheme code directly in
213the editor. This makes programming very interactive: you can type in a
214function and then try it right away. This feature is very highly
215recommended.
216
217As programmers have very specific tastes about editors, the editors
218listed here are shown in alphabetic order. We aren't about to tell you
219which editor to use, and there may be editors not shown here that
220might satisfy your needs.
221
222* Emacs ([[http://www.gnu.org/software/emacs]]) is available for Linux/Unix, Macintosh, and Windows systems; CHICKEN provides Emacs support out of the box, with the {{hen.el}} Emacs Lisp file. Consult the ``Emacs Guide for Chicken Users'' (TODO: this document doesn't exist yet) for information on setting up and using Emacs with Chicken.
223
224* Epsilon ([[http://www.lugaru.com]]) is a commercial text editor whose design was   inspired by Emacs. Although Scheme support isn't provided,  a Lisp mode is available on Lugaru's FTP site, and could with some work be made to duplicate the Emacs support.
225
226* {{vim}} ([[http://www.vim.org]]) is a descendant of the venerable {{vi}} editor first included with Berkeley versions of Unix.  TODO: say more about using vim with Chicken, all I know about vi is that you can get out by typing :q! .
227
228TODO: other editors? Slick? Multi-Edit? Visual Studio? Eclipse? TextMate?  Please fill in anything you know about. Has somebody done a SchemeScript for Chicken?
229
230=== Using the interpreter
231
232In the rest of this chapter, we'll assume that you are using a
233terminal window.
234
235To invoke the interpreter, you use the {{csi}} command.
236
237 $ csi
238 CHICKEN
239 (c)2000-2007 Felix L. Winkelmann
240 (c)2008 The Chicken Team
241 Version 3.0.1 - macosx-unix-gnu-x86    [ manyargs dload ptables applyhook ]
242 SVN rev. 8489  compiled 2008-02-15 on argyre.local (Darwin)
243 #;1>
244
245This brings up a brief banner, and then the prompt. You can use this
246pretty much like any other Scheme system, e.g.,
247
248 #;1> (define (twice f) (lambda (x) (f (f x))))
249 #;2> ((twice (lambda (n) (* n 10))) 3)
250 300
251
252Suppose  we have already created a file {{fact.scm}} containing a
253function definition.
254
255 (define (fact n)
256   (if (= n 0)
257       1
258       (* n (fact (- n 1)))))
259
260We can now load this file and try out the function.
261
262 #;3> (load "fact.scm")
263 ; loading fact.scm ...
264 #;4> (fact 3)
265 6
266
267The '''read-eval-print loop''' ('''REPL''') is the component of the
268Scheme system that ''reads'' a Scheme expression, ''eval''uates it,
269and ''prints'' out the result. The REPL's prompt can be customized
270(TODO: xref),
271but the default prompt, showing the number of the form, is quite
272convenient.
273
274The REPL also supports debugging commands:
275input lines beginning with a {{,}} (comma) are treated as special
276commands. (TODO: insert cross-reference to full list) We can
277'''trace''' {{fact}} to see how it works.
278
279 #;5> ,tr fact
280 #;5> (fact 3)
281 |(fact 3)
282 | (fact 2)
283 |  (fact 1)
284 |   (fact 0)
285 |   fact -> 1
286 |  fact -> 1
287 | fact -> 2
288 |fact -> 6
289 6
290
291The command number didn't increment, because the {{tr}} command isn't
292actually a Scheme ''form''.
293
294==== Scripts
295
296You can use the interpreter to run a Scheme program from the command
297line. Here we create a program that does a quick search-and-replace on
298an input file; the arguments are a regular expression and a
299replacement string.
300
301 $ cat quickrep.dat
302 xyzabcghi
303 abxawxcgh
304 foonly
305 $ csi -ss quickrep.scm <quickrep.dat 'a.*c' A
306 xyzAghi
307 Agh
308 foonly
309
310The {{-ss}} option sets several options that work smoothly together to
311execute a script. You can make the command directly executable from
312the shell by inserting a `shebang line' at the beginning of the
313program (TODO: insert xref).
314
315The program itself uses one of the libraries included with Chicken,
316the regular expression library, {{regex}}.
317
318 (use regex)
319 (define (process-line line re rplc)
320   (string-substitute re rplc line 'all))
321 (define (quickrep re rplc)
322   (let ((line (read-line)))
323     (if (not (eof-object? line))
324         (begin
325           (display (process-line line re rplc))
326           (newline)
327           (quickrep re rplc)))))
328 ;;; Does a lousy job of error checking!
329 (define (main args)
330   (quickrep (regexp (car args)) (cadr args)))
331
332The {{-ss}} option arranges to call a procedure named {{main}}, with
333the command line arguments, packed in a list, as its arguments. (There
334are a number of ways this program could be made more idiomatic Chicken
335Scheme, see the rest of the manual for details.)
336
337=== The compiler
338
339There are several reasons you might want to compile your code.
340
341* Compiled code executes substantially more quickly than interpreted
342  code.
343* You might want to deploy an application onto machines where the
344  users aren't expected to have Chicken installed: compiled
345  applications can be self-contained.
346
347The Chicken compiler is provided as the command {{chicken}}, but in
348almost all cases, you will want to use the {{csc}} command
349instead. {{csc}} is a convenient driver that automates compiling
350Scheme programs into C, compiling C code into object code, and linking
351the results into an executable file. (Note: in a Windows environment
352with Visual Studio, you may find that {{csc}} refers to Microsoft's
353C\# compiler. There are a number of ways of sorting this out, of which
354the simplest is to make a Windows batch file named {{cshc.bat}} which
355invokes the Chicken compiler, and organize your {{PATH}} accordingly.)
356
357Compiled code can be intermixed with interpreted code on systems that
358support dynamic loading, which includes modern versions of *BSD,
359Linux, Mac OS X, Solaris, and Windows.
360
361We can compile our factorial function, producing a file named
362{{fact.so}} (`shared object' in Linux-ese, the same file type is used
363in OS X and Windows).
364
365 chicken$ csc -dynamic fact.scm
366 chicken$ csi -quiet
367 #;1> (load "fact.so")
368 ; loading fact.so ...
369 #;2> (fact 6)
370 720
371
372On any system, we can just compile a program directly into an
373executable. Here's a program that tells you whether its argument is a
374palindrome.
375
376 (define (palindrome? x)
377   (define (check left right)
378     (if (>= left right)
379         #t
380         (and (char=? (string-ref x left) (string-ref x right))
381              (check (add1 left) (sub1 right)))))
382   (check 0 (sub1 (string-length x))))
383 (let ((arg (car (command-line-arguments))))
384   (display
385    (string-append arg
386                   (if (palindrome? arg)
387                       " is a palindrome\n"
388                       " isn't a palindrome\n"))))
389 
390We can compile this program using {{csc}}, creating an executable
391named {{palindrome}}.
392
393 $ csc -o palindrome palindrome.scm
394 $ ./palindrome level
395 level is a palindrome
396 $ ./palindrome liver
397 liver isn't a palindrome
398
399Chicken supports separate compilation, using some extensions to
400Scheme. Let's divide our palindrome program into a library module
401({{pal-proc.scm}}) and a client module ({{pal-user.scm}}).
402
403Here's the external library. We {{declare}} that {{pal-proc}} is a
404``unit'', which is the basis of separately-compiled modules in
405Chicken. (Units deal with separate compilation, but don't involve
406separated namespaces; namespaced module systems are available as
407eggs.)
408
409 ;;; Library pal-proc.scm
410 (declare (unit pal-proc))
411 (define (palindrome? x)
412   (define (check left right)
413     (if (>= left right)
414         #t
415         (and (char=? (string-ref x left) (string-ref x right))
416              (check (add1 left) (sub1 right)))))
417   (check 0 (sub1 (string-length x))))
418
419Next we have some  client code that `uses' this separately-compiled
420module. 
421
422 ;;; Client pal-user.scm
423 (declare (uses pal-proc))
424 (let ((arg (car (command-line-arguments))))
425   (display
426    (string-append arg
427                   (if (palindrome? arg)
428                       " is a palindrome\n"
429                       " isn't a palindrome\n"))))
430
431Now we can compile and link everything together. (We show the compile
432and link operations separately, but they can of course be combined
433into one command.)
434
435 $ csc -c pal-proc.scm
436 $ csc -c pal-user.scm
437 $ csc -o pal-separate pal-proc.o pal-user.o
438 $ ./pal-separate level
439 level is a palindrome
440
441=== Installing an egg
442
443Installing eggs is quite straightforward on systems that support
444dynamic loading (again, that would include *BSD, Linux, Mac OS X,
445Solaris, and Windows).  The command {{chicken-setup}} will fetch an
446egg from the master Chicken repository, and install it on your local
447system.
448
449In this example, we install the {{uri}} egg, for parsing Uniform
450Resource Identifiers. The installation produces a lot of output, which
451we have edited for space reasons.
452
453 $ chicken-setup uri
454
455 The extension uri does not exist.
456 Do you want to download it ? (yes/no/abort) [yes] yes
457 downloading uri.egg from (www.call-with-current-continuation.org eggs/3 80)
458   gzip -d -c ../uri.egg | tar xf -
459 .  /Users/vmanis/local/bin/csc -feature compiling-extension
460      -s -O2 -d1 uri.scm -o uri.so -check-imports -emit-exports uri.exports
461 ... (lots of stuff elided)
462 .  rm -fr /Users/vmanis/project/chicken/uri.egg
463
464First, {{chicken-setup}} asks us if we want to download the egg. It
465then uncompresses the egg, compiles the code, and installs the egg in
466the local Chicken repository.
467
468Now we can use our new egg.
469
470 #;1> (use uri)
471 ; loading /Users/vmanis/local/lib/chicken/3/uri.so ...
472 ; loading /Users/vmanis/local/lib/chicken/3/coerce-support.so ...
473 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-list-support.so ...
474 ; loading /Users/vmanis/local/lib/chicken/3/synch-support.so ...
475 ; loading /Users/vmanis/local/lib/chicken/3/lookup-table.so ...
476 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-control-support.so ...
477 #;2> (uri-host (uri "http://www.foobar.org/blah"))
478 "www.foobar.org"
479
480=== Accessing C libraries
481
482Because Chicken compiles to C, and because a foreign function
483interface is built into the compiler, interfacing to a C library is
484quite straightforward. This means that nearly any facility available
485on the host system is accessible from Chicken, with more or less
486work.
487
488Let's create a simple C library, to demonstrate how this
489works. Here we have a function that will compute and return the '''n'''th
490Fibonacci number. (This isn't a particularly good use of C here,
491because we could write this function just as easily in Scheme, but a
492real example would take far too much space here.)
493
494 int fib(int n) {
495   int prev = 0, curr = 1;
496   int next;
497   int i;
498   for (i = 0; i < n; i++) {
499     next = prev + curr;
500     prev = curr;
501     curr = next;
502   }
503   return curr;
504 }
505
506Now we can call this function from Chicken.
507
508 #>
509   extern fib(int n);
510 <#
511 (define xfib (foreign-lambda int "fib" int))
512 (do ((i 0 (+ i 1))) ((> i 10))
513   (printf "~A " (xfib i)))
514 (newline)
515
516The syntax {{#>...<#}} allows you to include literal C (typically
517external declarations) in your Chicken code. We access {{fib}} by
518defining a {{foreign-lambda}} for it, in this case saying that the
519function takes one integer argument (the {{int}} after the function
520name), and that it returns an integer result. Now we can invoke
521{{xfib}} as though it were an ordinary Scheme function.
522
523 $ gcc -c fib.c
524 $ csc -o fib-user fib.o fib-user.scm
525 $ ./fib-user
526 0 1 1 2 3 5 8 13 21 34 55
527
528Those who are interfacing to substantial C libraries should consider using the
529easyffi egg, or SWIG.
Note: See TracBrowser for help on using the repository browser.