/usr/share/doc/chicken-bin/manual-html/Getting started.html is in chicken-bin 4.12.0-0.3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | <!doctype html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="manual.css" type="text/css" /></head>
<title>Chicken » Getting started</title>
<meta name="viewport" content="initial-scale=1" /></html>
<body>
<div id="body">
<div id="main"><h2 id="sec:Getting_started_"><a href="#sec:Getting_started_">Getting started </a></h2><p>CHICKEN is a compiler that translates Scheme source files into C, which in turn can be fed to a C compiler to generate a standalone executable. An interpreter is also available and can be used as a scripting environment or for testing programs before compilation.</p><p>This chapter is designed to get you started with CHICKEN programming, describing what it is and what it will do for you, and covering basic use of the system. With almost everything discussed here, there is more to the story, which the remainder of the manual reveals. Here, we only cover enough to get you started. Nonetheless, someone who knows Scheme already should be able to use this chapter as the basis for writing and running small CHICKEN programs.</p><h3 id="sec:Scheme"><a href="#sec:Scheme">Scheme</a></h3><p>Scheme is a member of the Lisp family of languages, of which Common Lisp and Emacs Lisp are the other two widely-known members. As with Lisp dialects, Scheme features</p><ul><li>a wide variety of programming paradigms, including imperative, functional, and object-oriented</li>
<li>a very simple syntax, based upon nested parenthesization </li>
<li>the ability to extend the language in meaningful and useful ways</li>
</ul>
<p>In contrast to Common Lisp, Scheme is very minimal, and tries to include only those features absolutely necessary in programming. In contrast to Emacs Lisp, Scheme is not anchored into a single program (Emacs), and has a more modern language design.</p><p>Scheme is defined in a document called <i>The Revised^5 Report on the Algorithmic Language Scheme</i>, or <i>R5RS</i> for short. (Yes, it really has been revised five times, so an expanded version of its name would be <i>The Revised Revised Revised Revised Revised Report</i>.) A newer report, <i>R6RS</i>, was released in 2007, but this report has attracted considerable controversy, and not all Scheme implementations will be made compliant with it. CHICKEN essentially complies with R5RS.</p><p>Even though Scheme is consciously minimalist, it is recognized that a language must be more than a minimal core in order to be useful. Accordingly, the Scheme community uses a process known as `Scheme Requests For Implementation' (SRFI, pronounced `SUR-fee') to define new language features. A typical Scheme system therefore complies with one of the Scheme reports plus some or all of the accepted SRFIs.</p><p>A good starting point for Scheme knowledge is <a href="http://www.schemers.org">http://www.schemers.org</a>. There you will find the defining reports, FAQs, lists of useful books and other resources, and the SRFIs.</p><p>The CHICKEN community is at present developing tutorials for programmers who are new to Scheme but experienced with Python, Ruby, or other languages. These can be found on the CHICKEN wiki.</p><h3 id="sec:CHICKEN"><a href="#sec:CHICKEN">CHICKEN</a></h3><p>CHICKEN is an implementation of Scheme that has many advantages.</p><p>CHICKEN Scheme combines an optimising compiler with a reasonably fast interpreter. It supports almost all of R5RS and the important SRFIs. The compiler generates portable C code that supports tail recursion, first-class continuations, and lightweight threads, and the interface to and from C libraries is flexible, efficient, and easy to use. There are hundreds of contributed CHICKEN libraries that make the programmer's task easier. The interpreter allows interactive use, fast prototyping, debugging, and scripting. The active and helpful CHICKEN community fixes bugs and provides support. Extensive documentation is supplied.</p><p>CHICKEN was developed by Felix L. Winkelmann over the period from 2000 through 2007. In early 2008, Felix asked the community to take over the responsibility of developing and maintaining the system, though he still takes a strong interest in it, and participates actively.</p><p>CHICKEN includes</p><ul><li>a Scheme interpreter that supports almost all of R5RS Scheme, with only a few relatively minor omissions, and with many extensions</li>
<li>a compatible compiler whose target is C, thus making porting to new machines and architectures relatively straightforward<ul><li>the C support allows Scheme code to include `embedded' C code, thus making it relatively easy to invoke host OS or library functions</li>
</ul>
</li>
<li>a framework for language extensions, library modules that broaden the functionality of the system</li>
</ul>
<p>This package is distributed under the <b>BSD license</b> and as such is free to use and modify.</p><p>Scheme cognoscenti will appreciate the method of compilation and the design of the runtime-system, which follow closely Henry Baker's <a href="http://home.pipeline.com/~hbaker1/CheneyMTA.html">CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A.</a> paper and expose a number of interesting properties.</p><ul><li>Consing (creation of data on the heap) is relatively inexpensive, because a generational garbage collection scheme is used, in which short-lived data structures are reclaimed extremely quickly.</li>
<li>Moreover, <tt>call-with-current-continuation</tt> is practically for free and CHICKEN does not suffer under any performance penalties if first-class continuations are used in complex ways.</li>
</ul>
<p>The generated C code is fully tail-recursive.</p><p>Some of the features supported by CHICKEN:</p><ul><li>SRFIs 0, 1, 2, 4, 6, 8-18, 23, 26, 28, 30, 31, 39, 46, 55, 61, 62, 69, 85, 88 and 98.</li>
<li>Lightweight threads based on first-class continuations</li>
<li>Record structures</li>
<li>Extended comment- and string-literal syntaxes</li>
<li>Libraries for regular expressions, string handling</li>
<li>UNIX system calls and extended data structures</li>
<li>Create interpreted or compiled shell scripts written in Scheme for UNIX or Windows</li>
<li>Compiled C files can be easily distributed</li>
<li>Allows the creation of fully self-contained statically linked executables</li>
<li>On systems that support it, compiled code can be loaded dynamically</li>
<li>Built-in support for cross-compilation and deployment</li>
</ul>
<p>CHICKEN has been used in many environments ranging from embedded systems through desktop machines to large-scale server deployments. The number of language extensions, or <b>eggs</b>, is constantly growing.</p><ul><li>extended language features</li>
<li>development tools, such as documentation generators, debugging, and automated testing libraries</li>
<li>interfaces to other languages such as Java, Python, and Objective-C</li>
<li>interfaces to database systems, GUIs, and other large-scale libraries,</li>
<li>network applications, such as servers and clients for ftp, smtp/pop3, irc, and http</li>
<li>web servers and related tools, including URL parsing, HTML generation, AJAX, and HTTP session management</li>
<li>data formats, including XML, JSON, and Unicode support</li>
</ul>
<p>This chapter provides you with an overview of the entire system, with enough information to get started writing and running small Scheme programs.</p><h3 id="sec:CHICKEN_repositories.2c_websites.2c_and_community"><a href="#sec:CHICKEN_repositories.2c_websites.2c_and_community">CHICKEN repositories, websites, and community</a></h3><p>The master CHICKEN website is <a href="http://www.call-cc.org">http://www.call-cc.org</a>. Here you can find basic information about CHICKEN, downloads, and pointers to other key resources.</p><p>The CHICKEN wiki (<a href="http://wiki.call-cc.org">http://wiki.call-cc.org</a>) contains the most current version of the User's manual, along with various tutorials and other useful documents. The list of eggs is at <a href="http://wiki.call-cc.org/egg-index">http://wiki.call-cc.org/egg-index</a>.</p><p>A very useful search facility for questions about CHICKEN is found at <a href="http://api.call-cc.org">http://api.call-cc.org</a>. The CHICKEN issue tracker is at <a href="http://bugs.call-cc.org">http://bugs.call-cc.org</a>.</p><p>The CHICKEN community has two major mailing lists. If you are a CHICKEN user, <tt>chicken-users</tt> (<a href="http://lists.nongnu.org/mailman/listinfo/chicken-users">http://lists.nongnu.org/mailman/listinfo/chicken-users</a>) will be of interest. The crew working on the CHICKEN system itself uses the very low-volume <tt>chicken-hackers</tt> list (<a href="http://lists.nongnu.org/mailman/listinfo/chicken-hackers">http://lists.nongnu.org/mailman/listinfo/chicken-hackers</a>) for communication. For other topic-specific mailing lists (e.g., announcements, security) and discussion groups, see <a href="http://wiki.call-cc.org/discussion-groups">http://wiki.call-cc.org/discussion-groups</a>.</p><p>There is also an IRC channel (<tt>#chicken</tt>) on <a href="http://freenode.net">Freenode</a>.</p><h3 id="sec:Installing_CHICKEN"><a href="#sec:Installing_CHICKEN">Installing CHICKEN</a></h3><p>CHICKEN is available as C sources. Refer to the <tt>README</tt> file in the distribution for instructions on installing it on your system.</p><p>Because it compiles to C, CHICKEN requires that a C compiler be installed on your system. (If you're not writing embedded C code, you can pretty much ignore the C compiler once you have installed it.)</p><ul><li>On a Linux system, a C toolchain (e.g., GCC, clang) should be installed as part of the basic operating system, or should be available through the package management system (e.g., APT, Synaptic, RPM, or Yum, depending upon your Linux distribution).</li>
<li>On Macintosh OS X, you will need the XCode tools, which were shipped on the OS X DVD with older versions of the operating system, and are installable from the App Store with recent versions of the operating system.</li>
<li>On Windows, you have three choices:<ul><li>Cygwin (<a href="http://sourceware.org/cygwin/">http://sourceware.org/cygwin/</a>) provides a relatively full-featured Unix environment for Windows. CHICKEN works substantially the same in Cygwin and Unix.</li>
<li>The GNU Compiler Collection has been ported to Windows, in the MinGW system (<a href="http://mingw.sourceforge.net">http://mingw.sourceforge.net</a>). Unlike Cygwin, executables produced with MinGW do not need the Cygwin DLLs in order to run. MSYS is a companion package to MinGW; it provides a minimum Unix-style development/build environment, again ported from free software.<ul><li>You can build CHICKEN either with MinGW alone or with MinGW plus MSYS. Both approaches produce a CHICKEN built against the mingw headers and libraries. The only difference is the environment where you actually run make. <tt>Makefile.mingw</tt> is can be used in <tt>cmd.exe</tt> with the version of make that comes with mingw. <tt>Makefile.mingw-msys</tt> uses unix commands such as <tt>cp</tt> and <tt>rm</tt>. The end product is the same.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>Refer to the <tt>README</tt> file for the version you're installing for more information on the installation process.</p><p>Alternatively, third party packages in binary format are available. See <a href="http://wiki.call-cc.org/platforms">http://wiki.call-cc.org/platforms</a> for information about how to obtain them.</p><h3 id="sec:Development_environments"><a href="#sec:Development_environments">Development environments</a></h3><p>The simplest development environment is a text editor and terminal window (Windows: Command Prompt, OSX: Terminal, Linux/Unix: xterm) for using the interpreter and/or calling the compiler. If you install one of the line editing extensions (e.g., <a href="http://wiki.call-cc.org/egg/readline">readline</a>, <a href="http://wiki.call-cc.org/egg/parley">parley</a>, <a href="http://wiki.call-cc.org/egg/linenoise">linenoise</a>, you have some useful command line editing features in the interpreter (e.g., Emacs or vi-compatible line editing, customization).</p><p>You will need a text editor that knows Scheme; it's just too painful with editors that don't do parenthesis matching and proper indentation. Some editors allow you to execute Scheme code directly in the editor. This makes programming very interactive: you can type in a function and then try it right away. This feature is very highly recommended.</p><p>As programmers have very specific tastes about editors, the editors listed here are shown in alphabetic order. We aren't about to tell you which editor to use, and there may be editors not shown here that might satisfy your needs. We would be very interested in reports of other editors that have been used with CHICKEN, especially those that support interactive evaluation of forms during editing. Pointers to these (and to any editor customization files appropriate) should be put on the CHICKEN wiki, and will likely be added to future editions of this manual. (We have had a request for editors that support proportional fonts, in particular.)</p><ul><li>Emacs (<a href="http://www.gnu.org/software/emacs">http://www.gnu.org/software/emacs</a>) is an extensible, customizable, self-documenting editor available for Linux/Unix, Macintosh, and Windows systems; See <a href="http://wiki.call-cc.org/emacs">http://wiki.call-cc.org/emacs</a> for more information about the available options.</li>
<li>SciTE (<a href="http://scintilla.sourceforge.net/SciTE.html">http://scintilla.sourceforge.net/SciTE.html</a>), 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, column 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. The syntax highlighting can be configured to use different fonts for different types of syntax, including proportional fonts.</li>
<li>Vim (<a href="http://www.vim.org">http://www.vim.org</a>) 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. See <a href="http://wiki.call-cc.org/Vim">/Vim</a> for a few tips on using Vim with CHICKEN.</li>
</ul>
<p>In the rest of this chapter, we'll assume that you are using an editor of your choice and a regular terminal window for executing your CHICKEN code.</p><h3 id="sec:The_Read-Eval-Print_loop"><a href="#sec:The_Read-Eval-Print_loop">The Read-Eval-Print loop</a></h3><p>To invoke the CHICKEN interpreter, you use the <tt>csi</tt> command.</p><pre>$ csi
CHICKEN
(c) 2008-2016, The CHICKEN Team
(c) 2000-2007, Felix L. Winkelmann
Version 4.11.0 (rev ce980c4)
linux-unix-gnu-x86-64 [ 64bit manyargs dload ptables ]
compiled 2016-05-28 on yves.more-magic.net (Linux)
#;1></pre><p>This brings up a brief banner, and then the prompt. You can use this pretty much like any other Scheme system, e.g.,</p><pre>#;1> (define (twice f) (lambda (x) (f (f x))))
#;2> ((twice (lambda (n) (* n 10))) 3)
300</pre><p>Suppose we have already created a file <tt>fact.scm</tt> containing a function definition.</p><pre>(define (fact n)
(if (= n 0)
1
(* n (fact (- n 1)))))</pre><p>We can now load this file and try out the function.</p><pre>#;3> (load "fact.scm")
; loading fact.scm ...
#;4> (fact 3)
6</pre><p>The <b>read-eval-print loop</b> (<b>REPL</b>) is the component of the Scheme system that <i>reads</i> a Scheme expression, <i>eval</i>uates it, and <i>prints</i> out the result. The REPL's prompt can be customized (see the <a href="Using%20the%20interpreter.html">Using the interpreter</a>) but the default prompt, showing the number of the form, is quite convenient.</p><p>The REPL also supports debugging commands: input lines beginning with a <tt>,</tt> (comma) are treated as special commands. (See the <a href="Using%20the%20interpreter.html#sec:Toplevel_commands">full list</a>.)</p><h4 id="sec:Scripts"><a href="#sec:Scripts">Scripts</a></h4><p>You can use the interpreter to run a Scheme program from the command line. For the following example we create a program that does a quick search-and-replace on an input file; the arguments are a regular expression and a replacement string. First create a file to hold the "data" called <i>quickrep.dat</i> with your favorite editor holding these lines:</p><pre>xyzabcghi
abxawxcgh
foonly </pre><p>Next create the scheme code in a file called <i>quickrep.scm</i> with the following little program:</p>
<pre class="highlight colorize">
<span class="paren1">(<span class="default">use irregex</span>)</span> <span class="comment">; irregex, the regular expression library, is one of the
</span> <span class="comment">; libraries included with CHICKEN.
</span>
<span class="paren1">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren2">(<span class="default">process-line line re rplc</span>)</span>
<span class="paren2">(<span class="default">irregex-replace/all re line rplc</span>)</span></span>)</span>
<span class="paren1">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren2">(<span class="default">quickrep re rplc</span>)</span>
<span class="paren2">(<span class="default"><i><span class="symbol">let</span></i> <span class="paren3">(<span class="default"><span class="paren4">(<span class="default">line <span class="paren5">(<span class="default">read-line</span>)</span></span>)</span></span>)</span>
<span class="paren3">(<span class="default"><i><span class="symbol">if</span></i> <span class="paren4">(<span class="default">not <span class="paren5">(<span class="default">eof-object? line</span>)</span></span>)</span>
<span class="paren4">(<span class="default">begin
<span class="paren5">(<span class="default">display <span class="paren6">(<span class="default">process-line line re rplc</span>)</span></span>)</span>
<span class="paren5">(<span class="default">newline</span>)</span>
<span class="paren5">(<span class="default">quickrep re rplc</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span>
<span class="comment">;;; Does a lousy job of error checking!
</span><span class="paren1">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren2">(<span class="default">main args</span>)</span>
<span class="paren2">(<span class="default">quickrep <span class="paren3">(<span class="default">irregex <span class="paren4">(<span class="default">car args</span>)</span></span>)</span> <span class="paren3">(<span class="default">cadr args</span>)</span></span>)</span></span>)</span></pre><p>To run it enter this in your shell:</p><pre>$ csi -ss quickrep.scm <quickrep.dat 'a.*c' A
xyzAghi
Agh
foonly </pre><p>The <tt>-ss</tt> option sets several options that work smoothly together to execute a script. You can make the command directly executable from the shell by inserting a <a href="Using%20the%20interpreter.html#sec:Writing_Scheme_scripts">shebang line</a> at the beginning of the program.</p><p>The <tt>-ss</tt> option arranges to call a procedure named <tt>main</tt>, with the command line arguments, packed in a list, as its arguments. (There are a number of ways this program could be made more idiomatic CHICKEN Scheme, see the rest of the manual for details.)</p><h3 id="sec:The_compiler_"><a href="#sec:The_compiler_">The compiler </a></h3><p>There are several reasons you might want to compile your code.</p><ul><li>Compiled code executes substantially faster than interpreted code.</li>
<li>You might want to deploy an application onto machines where the users aren't expected to have CHICKEN installed: compiled applications can be self-contained.</li>
</ul>
<p>The CHICKEN compiler is provided as the command <tt>chicken</tt>, but in almost all cases, you will want to use the <tt>csc</tt> command instead. <tt>csc</tt> is a convenient driver that automates compiling Scheme programs into C, compiling C code into object code, and linking the results into an executable file. (Note: in a Windows environment with Visual Studio, you may find that <tt>csc</tt> refers to Microsoft's C# compiler. There are a number of ways of sorting this out, of which the simplest is to rename one of the two tools, and/or to organize your <tt>PATH</tt> according to the task at hand.)</p><p>Compiled code can be intermixed with interpreted code on systems that support dynamic loading, which includes modern versions of *BSD, Linux, Mac OS X, Solaris, and Windows.</p><p>We can compile our factorial function, producing a file named <tt>fact.so</tt> (<i>shared object</i> in Linux-ese, the same file type is used in OS X and Windows, rather than <tt>dylib</tt> or <tt>dll</tt>, respectively).</p><pre>chicken$ csc -dynamic fact.scm
chicken$ csi -quiet
#;1> (load "fact.so")
; loading fact.so ...
#;2> (fact 6)
720</pre><p>On any system, we can just compile a program directly into an executable. Here's a program that tells you whether its argument is a palindrome.</p>
<pre class="highlight colorize"><span class="paren1">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren2">(<span class="default">palindrome? x</span>)</span>
<span class="paren2">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren3">(<span class="default">check left right</span>)</span>
<span class="paren3">(<span class="default"><i><span class="symbol">if</span></i> <span class="paren4">(<span class="default">>= left right</span>)</span>
#t
<span class="paren4">(<span class="default">and <span class="paren5">(<span class="default">char=? <span class="paren6">(<span class="default">string-ref x left</span>)</span> <span class="paren6">(<span class="default">string-ref x right</span>)</span></span>)</span>
<span class="paren5">(<span class="default">check <span class="paren6">(<span class="default">add1 left</span>)</span> <span class="paren6">(<span class="default">sub1 right</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span>
<span class="paren2">(<span class="default">check 0 <span class="paren3">(<span class="default">sub1 <span class="paren4">(<span class="default">string-length x</span>)</span></span>)</span></span>)</span></span>)</span>
<span class="paren1">(<span class="default"><i><span class="symbol">let</span></i> <span class="paren2">(<span class="default"><span class="paren3">(<span class="default">arg <span class="paren4">(<span class="default">car <span class="paren5">(<span class="default">command-line-arguments</span>)</span></span>)</span></span>)</span></span>)</span>
<span class="paren2">(<span class="default">display
<span class="paren3">(<span class="default">string-append arg
<span class="paren4">(<span class="default"><i><span class="symbol">if</span></i> <span class="paren5">(<span class="default">palindrome? arg</span>)</span>
<span class="string">" is a palindrome</span><span class="string">\n</span><span class="string">"</span>
<span class="string">" isn't a palindrome</span><span class="string">\n</span><span class="string">"</span></span>)</span></span>)</span></span>)</span></span>)</span></pre><p>We can compile this program using <tt>csc</tt>, creating an executable named <tt>palindrome</tt>.</p><pre>$ csc -o palindrome palindrome.scm
$ ./palindrome level
level is a palindrome
$ ./palindrome liver
liver isn't a palindrome</pre><p>CHICKEN supports separate compilation, using some extensions to Scheme. Let's divide our palindrome program into a library module (<tt>pal-proc.scm</tt>) and a client module (<tt>pal-user.scm</tt>).</p><p>Here's the external library. We <tt>declare</tt> that <tt>pal-proc</tt> is a <i>unit</i>, which is the basis of separately-compiled modules in CHICKEN. (Units deal with separate compilation, but don't necessarily involve separated namespaces; namespaces can be implemented by <a href="Modules.html">modules</a>.)</p>
<pre class="highlight colorize"><span class="comment">;;; Library pal-proc.scm
</span><span class="paren1">(<span class="default">declare <span class="paren2">(<span class="default">unit pal-proc</span>)</span></span>)</span>
<span class="paren1">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren2">(<span class="default">palindrome? x</span>)</span>
<span class="paren2">(<span class="default"><i><span class="symbol">define</span></i> <span class="paren3">(<span class="default">check left right</span>)</span>
<span class="paren3">(<span class="default"><i><span class="symbol">if</span></i> <span class="paren4">(<span class="default">>= left right</span>)</span>
#t
<span class="paren4">(<span class="default">and <span class="paren5">(<span class="default">char=? <span class="paren6">(<span class="default">string-ref x left</span>)</span> <span class="paren6">(<span class="default">string-ref x right</span>)</span></span>)</span>
<span class="paren5">(<span class="default">check <span class="paren6">(<span class="default">add1 left</span>)</span> <span class="paren6">(<span class="default">sub1 right</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span>
<span class="paren2">(<span class="default">check 0 <span class="paren3">(<span class="default">sub1 <span class="paren4">(<span class="default">string-length x</span>)</span></span>)</span></span>)</span></span>)</span></pre><p>Next we have some client code that <i>uses</i> this separately-compiled module.</p>
<pre class="highlight colorize"><span class="comment">;;; Client pal-user.scm
</span><span class="paren1">(<span class="default">declare <span class="paren2">(<span class="default">uses pal-proc</span>)</span></span>)</span>
<span class="paren1">(<span class="default"><i><span class="symbol">let</span></i> <span class="paren2">(<span class="default"><span class="paren3">(<span class="default">arg <span class="paren4">(<span class="default">car <span class="paren5">(<span class="default">command-line-arguments</span>)</span></span>)</span></span>)</span></span>)</span>
<span class="paren2">(<span class="default">display
<span class="paren3">(<span class="default">string-append arg
<span class="paren4">(<span class="default"><i><span class="symbol">if</span></i> <span class="paren5">(<span class="default">palindrome? arg</span>)</span>
<span class="string">" is a palindrome</span><span class="string">\n</span><span class="string">"</span>
<span class="string">" isn't a palindrome</span><span class="string">\n</span><span class="string">"</span></span>)</span></span>)</span></span>)</span></span>)</span></pre><p>Now we can compile and link everything together. (We show the compile and link operations separately, but they can of course be combined into one command.)</p><pre>$ csc -c pal-proc.scm
$ csc -c pal-user.scm
$ csc -o pal-separate pal-proc.o pal-user.o
$ ./pal-separate level
level is a palindrome</pre><h3 id="sec:Installing_an_egg"><a href="#sec:Installing_an_egg">Installing an egg</a></h3><p>Installing eggs is quite straightforward on systems that support dynamic loading (again, that would include *BSD, Linux, Mac OS X, Solaris, and Windows). The command <tt>chicken-install</tt> will fetch an egg from the master CHICKEN repository, and install it on your local system.</p><p>In this example, we install the <tt>uri-common</tt> egg, for parsing Uniform Resource Identifiers. The installation produces a lot of output, which we have edited for space.</p><pre>$ chicken-install uri-common
retrieving ...
resolving alias `kitten-technologies' to: http://chicken.kitten-technologies.co.uk/henrietta.cgi
connecting to host "chicken.kitten-technologies.co.uk", port 80 ...
requesting "/henrietta.cgi?name=uri-common&mode=default" ...
reading response ...
[...]
/usr/bin/csc -feature compiling-extension -setup-mode -s -O2 uri-common.scm -j uri-common
/usr/bin/csc -feature compiling-extension -setup-mode -s -O2 uri-common.import.scm
cp -r uri-common.so /usr/lib/chicken/5/uri-common.so
chmod a+r /usr/lib/chicken/5/uri-common.so
cp -r uri-common.import.so /usr/lib/chicken/5/uri-common.import.so
chmod a+r /usr/lib/chicken/5/uri-common.import.so
chmod a+r /usr/lib/chicken/5/uri-common.setup-info</pre><p><tt>chicken-install</tt> connects to a mirror of the egg repository and retrieves the egg contents. If the egg has any uninstalled dependencies, it recursively installs them. Then it builds the egg code and installs the resulting extension into the local CHICKEN repository.</p><p>Now we can use our new egg.</p><pre>#;1> (use uri-common)
; loading /usr/lib/chicken/5/uri-common.import.so ...
; [... other loaded files omitted for clarity ...]
#;2> (uri-host (uri-reference "http://www.foobar.org/blah"))
"www.foobar.org"</pre><h3 id="sec:Accessing_C_libraries_"><a href="#sec:Accessing_C_libraries_">Accessing C libraries </a></h3><p>Because CHICKEN compiles to C, and because a foreign function interface is built into the compiler, interfacing to a C library is quite straightforward. This means that nearly any facility available on the host system is accessible from CHICKEN, with more or less work.</p><p>Let's create a simple C library, to demonstrate how this works. Here we have a function that will compute and return the <b>n</b>th Fibonacci number. (This isn't a particularly good use of C here, because we could write this function just as easily in Scheme, but a real example would take far too much space here.)</p><pre>/* fib.c */
int fib(int n) {
int prev = 0, curr = 1;
int next;
int i;
for (i = 0; i < n; i++) {
next = prev + curr;
prev = curr;
curr = next;
}
return curr;
} </pre><p>Now we can call this function from CHICKEN.</p><pre>;;; fib-user.scm
#>
extern int fib(int n);
<#
(define xfib (foreign-lambda int "fib" int))
(do ((i 0 (+ i 1))) ((> i 10))
(printf "~A " (xfib i)))
(newline)</pre><p>The syntax <tt>#>...<#</tt> allows you to include literal C (typically external declarations) in your CHICKEN code. We access <tt>fib</tt> by defining a <tt>foreign-lambda</tt> for it, in this case saying that the function takes one integer argument (the <tt>int</tt> after the function name), and that it returns an integer result (the <tt>int</tt> before.) Now we can invoke <tt>xfib</tt> as though it were an ordinary Scheme function.</p><pre>$ gcc -c fib.c
$ csc -o fib-user fib.o fib-user.scm
$ ./fib-user
0 1 1 2 3 5 8 13 21 34 55 </pre><p>Those who are interfacing to substantial C libraries should consider using the <a href="http://wiki.call-cc.org/egg/bind">bind egg</a>.</p><hr /><p>Back to <a href="The%20User%27s%20Manual.html">The User's Manual</a></p><p>Next: <a href="Basic%20mode%20of%20operation.html">Basic mode of operation</a></p></div></div></body>
|