source: project/wiki/new-chapter1 @ 9170

Last change on this file since 9170 was 9170, checked in by ecloud, 12 years ago

Changes applied for ecloud (167.236.0.62) through svnwiki:

added info about SciTE

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