source: project/wiki/Getting started @ 13812

Last change on this file since 13812 was 13812, checked in by felix winkelmann, 11 years ago

added a few bits of confirmed working platforms

File size: 24.6 KB
Line 
1== Getting started
2
3Chicken is a compiler that translates Scheme source files into
4C, which in turn can be fed to a C compiler to generate a
5standalone executable.  An interpreter is also available and can be
6used as a scripting environment or for testing programs before
7compilation.
8
9This chapter is designed to get you started with Chicken programming,
10describing what it is and what it will do for you, and covering basic
11use of the system. With almost everything discussed here, there is
12more to the story, which the remainder of the manual reveals. Here, we
13only cover enough to get you started. Nonetheless, someone who knows
14Scheme already should be able to use this chapter as the basis for
15writing and running small Chicken programs.
16
17=== Scheme
18
19Scheme is a member of the Lisp family of languages, of which Common
20Lisp and Emacs Lisp are the other two widely-known members. As with
21Lisp dialects, Scheme features
22
23* a wide variety of programming paradigms, including imperative, functional, and object-oriented
24* a very simple syntax, based upon nested parenthesization
25* the ability to extend the language in meaningful and useful ways
26
27In contrast to Common Lisp, Scheme is very minimal, and tries to
28include only those features absolutely necessary in programming. In
29contrast to Emacs Lisp, Scheme is not anchored into any one program
30(Emacs), and has a somewhat more modern language design.
31
32Scheme is defined in a document called ''The Revised^5 Report on the
33Algorithmic Language Scheme'', or ''R5RS'' for short. (Yes, it really
34has been revised five times, so an expanded version of its name would
35be ''The Revised Revised Revised Revised Revised Report''.)  A newer
36report, ''R6RS'', was
37released in 2007, but this report has attracted considerable
38controversy, and not all Scheme implementations will be made compliant
39with it. Chicken essentially complies with R5RS.
40
41Even though Scheme is consciously minimalist, it is recognized that a
42language must be more than a minimal core in order to be
43useful. Accordingly, the Scheme community uses a process known as
44`Scheme Requests For Implementation' (SRFI, pronounced `SUR-fee') to
45define new language features. A typical Scheme system therefore
46complies with one of the Scheme reports plus some or all of the
47accepted SRFIs.
48
49A good starting point for Scheme knowledge is
50[[http://www.schemers.org]]. There you will find the defining reports,
51FAQs, lists of useful books and other resources, and the SRFIs.
52
53The Chicken community is at present developing tutorials for
54programmers who are new to Scheme but experienced with Python, Ruby,
55or other languages. These can be found on the Chicken wiki.
56
57=== Chicken
58
59Chicken is an implementation of Scheme that has many advantages.
60
61<blockquote>
62Chicken Scheme combines an optimising compiler with a reasonably fast
63interpreter.  It supports almost all of R5RS and the important SRFIs.
64The compiler generates portable C code that supports tail recursion,
65first-class continuations, and lightweight threads, and the interface to
66and from C libraries is flexible, efficient, and easy to use.  There are
67hundreds of contributed Chicken libraries that make the programmer's
68task easier.  The interpreter allows interactive use, fast prototyping,
69debugging, and scripting.  The active and helpful Chicken community
70fixes bugs and provides support.  Extensive documentation is supplied.
71</blockquote>
72
73Chicken was developed by Felix L. Winkelmann over the period from 2000
74through 2007. In early 2008, Felix
75asked the community to take over the responsibility of developing and
76maintaining the system, though he still takes a strong interest in it,
77and participates actively.
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=== Chicken repositories, websites, and community
180
181At present, the URLs for Chicken information and download are somewhat
182confusing. It is envisaged that everything will eventually be
183accessible via the
184domain {{chicken-scheme.org}}, but this hasn't been completely done.
185
186At present, the master Chicken website is
187[[http://www.call-with-current-continuation.org]]. Here you can find
188basic information about Chicken, downloads, and pointers to other key
189resources.
190
191The Chicken wiki ([[http://chicken.wiki.br]]) contains the most
192current version of the User's manual, along with various tutorials and
193other useful documents. The list of eggs is at
194[[http://chicken.wiki.br/Eggs%20Unlimited]].
195
196A very useful search facility for questions about Chicken is found at
197[[http://www.callcc.org]]. The Chicken issue tracker is at
198[[http://trac.callcc.org]].
199
200The Chicken community has two major mailing lists. If you are a
201Chicken user, {{Chicken-Users}}
202([[http://lists.nongnu.org/mailman/listinfo/chicken-users]]) will be
203of interest. The crew working on the Chicken system itself uses the
204very low-volume {{Chicken-Hackers}} list
205([[http://lists.nongnu.org/mailman/listinfo/chicken-hackers]]) for
206communication. 
207
208=== Installing Chicken
209
210Chicken is available in binary form for Windows and Linux/x86
211systems, and in source form for all other platforms. Refer to the
212{{README}} file in the distribution for instructions on installing it
213on your system.
214
215Because it compiles to C, Chicken requires that a C compiler be
216installed on your system. (If you're not writing embedded C code, you
217can pretty much ignore the C compiler once you have installed it.)
218
219* On a Linux system, the GNU Compiler Collection ({{gcc}}) should be
220  installed as part of the basic operating system, or should be
221  available through the package management system (e.g., APT,
222  Synaptic, RPM, or Yum, depending upon your Linux distribution).
223* On Macintosh OS X, you will need the XCode tools, which are shipped
224  on the OS X DVD with recent versions of the operating system.
225* On Windows, you have three choices.
226** Cygwin ([[http://sources.redhat.com/cygwin]]) provides a relatively
227  full-featured Unix environment for Windows.  Chicken works
228  substantially the same in Cygwin and Unix.
229** The GNU Compiler Collection has been ported to Windows, in the
230  MinGW system ([[http://mingw.sourceforge.net]]). Unlike Cygwin,
231  executables produced with MinGW do not need the Cygwin DLLs in order
232  to run.   MSys is a companion package to MinGW; it provides a minimum
233  Unix-style development/build environment, again ported from free
234  software.
235*** You can build Chicken either with MinGW alone or with MinGW plus
236  MSys. Both approaches produce a Chicken built against the mingw headers
237  and import libraries.
238  The only difference is the environment where you actually run make.
239  {{Makefile.mingw}} is can be used in {{cmd.exe}} with the version of make
240  that comes with mingw.  {{Makefile.mingw-msys}}
241  uses unix commands such as {{cp}} and {{rm}}.  The end product is the
242  same.
243** Microsoft Visual Studio will soon be supported, including the
244  Express edition, which is a non-free but no-cost compiler suite
245  available from Microsoft
246  ([[http://www.microsoft.com/express/vc]]). Chicken supports
247  command-line building using the command-line C/C++ compiler.
248*** Visual
249  Studio users will want to install the Unix Utilities, available at
250  [[http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip]],
251  in order to get suitable versions of {{make}}, {{tar}}, {{gzip}}, and
252  similar commands. 
253
254Refer to the {{README}} file for the version you're installing for
255more information on the installation process.
256
257=== Development environments
258
259The simplest development environment is a text editor and terminal
260window (Windows: Command Prompt, OSX: Terminal, Linux/Unix: xterm) for
261using the interpreter and/or calling the compiler. If you
262[[/egg/readline|install the {{readline}} egg]], you
263have all the benefits of command history in the interpreter, Emacs or
264vi-compatible line editing, and customization.
265
266You will need a text editor that knows Scheme; it's just too painful
267with editors that don't do parenthesis matching and proper
268indentation. Some editors allow you to execute Scheme code directly in
269the editor. This makes programming very interactive: you can type in a
270function and then try it right away. This feature is very highly
271recommended.
272
273As programmers have very specific tastes about editors, the editors
274listed here are shown in alphabetic order. We aren't about to tell you
275which editor to use, and there may be editors not shown here that
276might satisfy your needs. We would be very interested in reports of
277other editors that have been used with Chicken, especially those that
278support interactive evaluation of forms during editing. Pointers to
279these (and to any editor customization files appropriate) should be
280put on the Chicken wiki, and will likely be added to future editions
281of this manual. (We have had a request for editors that support
282proportional fonts, in particular.)
283
284* Emacs ([[http://www.gnu.org/software/emacs]]) is an
285extensible, customizable, self-documenting editor available for
286Linux/Unix, Macintosh, and Windows systems; CHICKEN provides Emacs
287support out of the box, with the {{hen.el}} Emacs Lisp file. Consult
288the `Emacs Guide for Chicken Users' (which will be available on the
289Chicken Wiki soon) for information on setting up and using Emacs with
290Chicken. 
291
292* Epsilon ([[http://www.lugaru.com]]) is a commercial (proprietary) text
293editor whose design was inspired by Emacs. Although Scheme support
294isn't provided, a Lisp mode is available on Lugaru's FTP site, and
295could with some work be made to duplicate the Emacs support. 
296
297* SciTE ([[http://scintilla.sourceforge.net/SciTE.html]]),
298unlike Emacs or Vim, follows typical graphical UI design conventions
299and control-key mappings, and for simple tasks is as familiar and
300easy to use as Notepad, KEdit, TeachText etc.  However it has many
301programming features such as multiple open files, syntax
302highlighting for a large number of languages (including Lisps),
303matching of brackets, ability to fold sections of code based on the
304matched brackets, column selections, comment/uncomment, and the
305ability to run commands in the same directory as the current file
306(such as make, grep, etc.)  SciTE is written with the GTK toolkit
307and is portable to any GTK platform, including Windows, Linux and
308MacOS.  It uses the Scintilla text-editing component, which lends
309itself well to embedding within other IDEs and graphical toolkits.
310It does not have any other Scheme-specific features, but being
311open-source and modular, features like auto-formatting of
312S-expressions could be added.  The syntax highlighting can be
313configured to use different fonts for different types of syntax,
314including proportional fonts.
315
316* Vim ([[http://www.vim.org]]) is a highly configurable text
317editor built to enable efficient and fast text editing. It is an
318improved version of the vi editor distributed with most UNIX
319systems. Vim comes with generic Lisp (and therefore Scheme) editing
320capabilities out of the
321box. A few tips on using Vim with Chicken can be found at
322[[http://cybertiggyr.com/gene/15-vim/]].
323
324In the rest of this chapter, we'll assume that you are using an editor
325of your choice and a regular terminal window for executing your
326Chicken code.
327
328=== The Read-Eval-Print loop
329
330To invoke the Chicken interpreter, you use the {{csi}} command.
331
332 $ csi
333 CHICKEN
334 (c)2008 The Chicken Team
335 (c)2000-2007 Felix L. Winkelmann
336 Version 3.1.2 - macosx-unix-gnu-x86    [ manyargs dload ptables applyhook ]
337 SVN rev. 10185 compiled 2008-03-27 on argyre.local (Darwin)
338 #;1>
339
340This brings up a brief banner, and then the prompt. You can use this
341pretty much like any other Scheme system, e.g.,
342
343 #;1> (define (twice f) (lambda (x) (f (f x))))
344 #;2> ((twice (lambda (n) (* n 10))) 3)
345 300
346
347Suppose  we have already created a file {{fact.scm}} containing a
348function definition.
349
350 (define (fact n)
351   (if (= n 0)
352       1
353       (* n (fact (- n 1)))))
354
355We can now load this file and try out the function.
356
357 #;3> (load "fact.scm")
358 ; loading fact.scm ...
359 #;4> (fact 3)
360 6
361
362The '''read-eval-print loop''' ('''REPL''') is the component of the
363Scheme system that ''reads'' a Scheme expression, ''eval''uates it,
364and ''prints'' out the result. The REPL's prompt can be customized
365(see the [[http:Using%20the%20interpreter|`Using the Interpreter']])
366but the default prompt, showing the number of the form, is quite
367convenient.
368
369The REPL also supports debugging commands:
370input lines beginning with a {{,}} (comma) are treated as special
371commands. (See the [[Using the interpreter#Toplevel commands|full list]].) We can
372'''trace''' {{fact}} to see how it works.
373
374 #;5> ,tr fact
375 #;5> (fact 3)
376 |(fact 3)
377 | (fact 2)
378 |  (fact 1)
379 |   (fact 0)
380 |   fact -> 1
381 |  fact -> 1
382 | fact -> 2
383 |fact -> 6
384 6
385
386The command number didn't increment, because the {{tr}} command isn't
387actually a Scheme ''form''.
388
389==== Scripts
390
391You can use the interpreter to run a Scheme program from the command
392line. Here we create a program that does a quick search-and-replace on
393an input file; the arguments are a regular expression and a
394replacement string.
395
396 $ cat quickrep.dat
397 xyzabcghi
398 abxawxcgh
399 foonly
400 $ csi -ss quickrep.scm <quickrep.dat 'a.*c' A
401 xyzAghi
402 Agh
403 foonly
404
405The {{-ss}} option sets several options that work smoothly together to
406execute a script. You can make the command directly executable from
407the shell by inserting a `[[Using the interpreter#Writing Scheme scripts|shebang line]]' at the beginning of the
408program.
409
410{{regex}}, the regular expression library, is one of the libraries
411included with Chicken.
412
413 (use regex)
414 (define (process-line line re rplc)
415   (string-substitute re rplc line 'all))
416 (define (quickrep re rplc)
417   (let ((line (read-line)))
418     (if (not (eof-object? line))
419         (begin
420           (display (process-line line re rplc))
421           (newline)
422           (quickrep re rplc)))))
423 ;;; Does a lousy job of error checking!
424 (define (main args)
425   (quickrep (regexp (car args)) (cadr args)))
426
427The {{-ss}} option arranges to call a procedure named {{main}}, with
428the command line arguments, packed in a list, as its arguments. (There
429are a number of ways this program could be made more idiomatic Chicken
430Scheme, see the rest of the manual for details.)
431
432=== The compiler
433
434There are several reasons you might want to compile your code.
435
436* Compiled code executes substantially faster than interpreted
437  code.
438* You might want to deploy an application onto machines where the
439  users aren't expected to have Chicken installed: compiled
440  applications can be self-contained.
441
442The Chicken compiler is provided as the command {{chicken}}, but in
443almost all cases, you will want to use the {{csc}} command
444instead. {{csc}} is a convenient driver that automates compiling
445Scheme programs into C, compiling C code into object code, and linking
446the results into an executable file. (Note: in a Windows environment
447with Visual Studio, you may find that {{csc}} refers to Microsoft's
448C# compiler. There are a number of ways of sorting this out, of which
449the simplest is to rename one of the two tools, and/or to
450organize your {{PATH}} according to the task at hand.)
451
452Compiled code can be intermixed with interpreted code on systems that
453support dynamic loading, which includes modern versions of *BSD,
454Linux, Mac OS X, Solaris, and Windows.
455
456We can compile our factorial function, producing a file named
457{{fact.so}} (`shared object' in Linux-ese, the same file type is used
458in OS X and Windows, rather than {{dylib}} or {{dll}}, respectively).
459
460 chicken$ csc -dynamic fact.scm
461 chicken$ csi -quiet
462 #;1> (load "fact.so")
463 ; loading fact.so ...
464 #;2> (fact 6)
465 720
466
467On any system, we can just compile a program directly into an
468executable. Here's a program that tells you whether its argument is a
469palindrome.
470
471 (define (palindrome? x)
472   (define (check left right)
473     (if (>= left right)
474         #t
475         (and (char=? (string-ref x left) (string-ref x right))
476              (check (add1 left) (sub1 right)))))
477   (check 0 (sub1 (string-length x))))
478 (let ((arg (car (command-line-arguments))))
479   (display
480    (string-append arg
481                   (if (palindrome? arg)
482                       " is a palindrome\n"
483                       " isn't a palindrome\n"))))
484 
485We can compile this program using {{csc}}, creating an executable
486named {{palindrome}}.
487
488 $ csc -o palindrome palindrome.scm
489 $ ./palindrome level
490 level is a palindrome
491 $ ./palindrome liver
492 liver isn't a palindrome
493
494Chicken supports separate compilation, using some extensions to
495Scheme. Let's divide our palindrome program into a library module
496({{pal-proc.scm}}) and a client module ({{pal-user.scm}}).
497
498Here's the external library. We {{declare}} that {{pal-proc}} is a
499`unit', which is the basis of separately-compiled modules in
500Chicken. (Units deal with separate compilation, but don't involve
501separated namespaces; namespaced module systems are available as
502eggs.)
503
504 ;;; Library pal-proc.scm
505 (declare (unit pal-proc))
506 (define (palindrome? x)
507   (define (check left right)
508     (if (>= left right)
509         #t
510         (and (char=? (string-ref x left) (string-ref x right))
511              (check (add1 left) (sub1 right)))))
512   (check 0 (sub1 (string-length x))))
513
514Next we have some  client code that `uses' this separately-compiled
515module. 
516
517 ;;; Client pal-user.scm
518 (declare (uses pal-proc))
519 (let ((arg (car (command-line-arguments))))
520   (display
521    (string-append arg
522                   (if (palindrome? arg)
523                       " is a palindrome\n"
524                       " isn't a palindrome\n"))))
525
526Now we can compile and link everything together. (We show the compile
527and link operations separately, but they can of course be combined
528into one command.)
529
530 $ csc -c pal-proc.scm
531 $ csc -c pal-user.scm
532 $ csc -o pal-separate pal-proc.o pal-user.o
533 $ ./pal-separate level
534 level is a palindrome
535
536=== Installing an egg
537
538Installing eggs is quite straightforward on systems that support
539dynamic loading (again, that would include *BSD, Linux, Mac OS X,
540Solaris, and Windows).  The command {{chicken-setup}} will fetch an
541egg from the master Chicken repository, and install it on your local
542system.
543
544In this example, we install the {{uri}} egg, for parsing Uniform
545Resource Identifiers. The installation produces a lot of output, which
546we have edited for space reasons.
547
548 $ chicken-setup uri
549
550 The extension uri does not exist.
551 Do you want to download it ? (yes/no/abort) [yes] yes
552 downloading uri.egg from (www.call-with-current-continuation.org eggs/3 80)
553   gzip -d -c ../uri.egg | tar xf -
554 .  /Users/vmanis/local/bin/csc -feature compiling-extension
555      -s -O2 -d1 uri.scm -o uri.so -check-imports -emit-exports uri.exports
556 ... (lots of stuff elided)
557 .  rm -fr /Users/vmanis/project/chicken/uri.egg
558
559First, {{chicken-setup}} asks us if we want to download the egg. It
560then uncompresses the egg, compiles the code, and installs the egg in
561the local Chicken repository.
562
563Now we can use our new egg.
564
565 #;1> (use uri)
566 ; loading /Users/vmanis/local/lib/chicken/3/uri.so ...
567 ; loading /Users/vmanis/local/lib/chicken/3/coerce-support.so ...
568 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-list-support.so ...
569 ; loading /Users/vmanis/local/lib/chicken/3/synch-support.so ...
570 ; loading /Users/vmanis/local/lib/chicken/3/lookup-table.so ...
571 ; loading /Users/vmanis/local/lib/chicken/3/misc-extn-control-support.so ...
572 #;2> (uri-host (uri "http://www.foobar.org/blah"))
573 "www.foobar.org"
574
575=== Accessing C libraries
576
577Because Chicken compiles to C, and because a foreign function
578interface is built into the compiler, interfacing to a C library is
579quite straightforward. This means that nearly any facility available
580on the host system is accessible from Chicken, with more or less
581work.
582
583Let's create a simple C library, to demonstrate how this
584works. Here we have a function that will compute and return the '''n'''th
585Fibonacci number. (This isn't a particularly good use of C here,
586because we could write this function just as easily in Scheme, but a
587real example would take far too much space here.)
588
589 int fib(int n) {
590   int prev = 0, curr = 1;
591   int next;
592   int i;
593   for (i = 0; i < n; i++) {
594     next = prev + curr;
595     prev = curr;
596     curr = next;
597   }
598   return curr;
599 }
600
601Now we can call this function from Chicken.
602
603 #>
604   extern int fib(int n);
605 <#
606 (define xfib (foreign-lambda int "fib" int))
607 (do ((i 0 (+ i 1))) ((> i 10))
608   (printf "~A " (xfib i)))
609 (newline)
610
611The syntax {{#>...<#}} allows you to include literal C (typically
612external declarations) in your Chicken code. We access {{fib}} by
613defining a {{foreign-lambda}} for it, in this case saying that the
614function takes one integer argument (the {{int}} after the function
615name), and that it returns an integer result (the {{int}} before.) Now we can invoke
616{{xfib}} as though it were an ordinary Scheme function.
617
618 $ gcc -c fib.c
619 $ csc -o fib-user fib.o fib-user.scm
620 $ ./fib-user
621 0 1 1 2 3 5 8 13 21 34 55
622
623Those who are interfacing to substantial C libraries should consider
624using the [[easyffi]] egg.
625
626---
627
628Back to [[The User's Manual]]
629
630Next: [[Basic mode of operation]]
Note: See TracBrowser for help on using the repository browser.