source: project/wiki/chickenista-guide @ 30615

Last change on this file since 30615 was 30615, checked in by John Foerch, 7 years ago

link to modules documentation

File size: 21.1 KB
1== A guided tour through the CHICKEN scheme republic
5== What to expect from this tour
6This session will inform interested programmers about the
7infrastructure and motivations that drive the CHICKEN scheme
8republic and the people behind it.  The major goal is to get you
9ready for programming in scheme today, so you can implement your
10great idea for a program in a nice programming language.  After this
11talk you should be able to find your way on your own, know who you
12can ask for help and how to operate the tools that come with the
13CHICKEN scheme system.
15== Welcome to CHICKEN scheme
16The CHICKEN scheme republic consists of
17* A compiler that uses C as intermediate language and gcc to compile
18  native code.
19* An interpreter that provides a read, eval, print, loop (aka REPL)
20  for rapid prototyping and explorative programming.
21* A software package system that allows you to distribute and
22  package software easily: The egg system.
23* A wiki for gathering egg documentation, and general advice.
24* An API / Identifier search system called chickadee.
25* A test suite compiling all available eggs and CHICKEN core on
26 called salmonella.
27* A bugtracking system for all extensions and the core library.
28* Mailing lists and an IRC channel for asking real people
29* Code repositories for the core language and extensions
31== Installing CHICKEN scheme
32Depending on your operating system you may choose your
33distribution's package system to install CHICKEN or build it
34yourself from source. Please do use the latest release version. If
35your distribution's package is too old you can nag the package
36maintainer to update and build your own in the meantime.
38=== Building CHICKEN from a stable source
39The CHICKEN core system is held in a git repository at
40[[|]] The latest major
41release is 4.8.0. Please
42use this first. There are development snapshots up to 4.7.2 if you
43want to try or need new features not already in the latest release.
44The code website offers tarballs for each.
45The CHICKEN system requires GNU make as a build dependency as well
46as a recent C compiler. Compilation works on all major free OSes
47like GNU/Linux, *BSD, Haiku, as well as Mac OS X, Windows and
49So to install the 4.8.0 release on a linux box download the tarball:
50  $ wget
51  $ tar xfz chicken-4.8.0.tar.gz
52  $ cd chicken-4.8.0
53  $ make PLATFORM=linux
54  # make PLATFORM=linux install
55Other supported platforms are: bsd, cross-linux-mingw, cygwin,
56haiku, linux, macosx, mingw, mingw-msys, and solaris.
57This will build and install CHICKEN in the default prefix
58"/usr/local". If you want to use a custom path for your installation
59provide a PREFIX parameter to both make calls.
60  $ make PLATFORM=linux PREFIX=$HOME/chickens/4.8.0
61  $ make PLATFORM=linux PREFIX=$HOME/chickens/4.8.0 install
62Note that the PREFIX is used as part of search path for extensions
63by the loader and needs to be consistent for both parts.
65If you want to use clang instead of the default gcc as C compiler, make and make install chicken like this:
67  $ make PLATFORM=<your-platform> C_COMPILER=clang
68  # make PLATFORM=<your-platform> C_COMPILER=clang install
70=== Building CHICKEN from the stability branches
71The stability branch series is a fork of the Chicken Scheme core which backports certain useful bugfixes and minor features from the future to "stable" maintenance versions. You can install a stability from either source tarball or a git checkout.
72Please have a look at [[stability]] to get further information.
75=== Building a development snapshot or from git
76Development snapshots differ from release tarballs in one
77significant way: They do not include bootstrapping code and require
78a pre-installed CHICKEN to build. So you need to install the latest
79release first and add the additional steps when building the
81  $ make PLATFORM=linux boot-chicken
82  $ make PLATFORM=linux CHICKEN=./chicken-boot
83  $ make PLATFORM=linux install
84Of course you can also build this in a separate PREFIX path, the
85same rules apply.
87== Using CHICKEN
88After a successful installation you should have the following
89binaries in your path:
90* chicken: The CHICKEN compiler, called by csc
91* csc: The CHICKEN scheme compiler driver
92* csi: The CHICKEN scheme interpreter
93* chicken-install: For installing CHICKEN scheme eggs
94* chicken-status: shows the currently installed eggs
95* chicken-uninstall: gets rid of rotten eggs
96* chicken-profile: Shows statistics of instrumented CHICKEN code
97* chicken-bug: Generate bug report templates
99=== Using the interpreter
100Calling csi without arguments will start a REPL for you:
101  $ csi
103  (c)2008-2012 The Chicken Team
104  (c)2000-2007 Felix L. Winkelmann
105  Version 4.8.0
106  openbsd-unix-gnu-x86 [ manyargs dload ptables ]
107  compiled 2012-12-27 on (OpenBSD)
108  #;1> "hello world!"
109  "hello world!"
110  #;2> (+ 1 2)
111  3
112  #;3> (string-split #1)
113  ("hello" "world!")
114As you can see you can refer to results from an earlier command by
115using its history number prefixed with a pound sign (#). To leave
116the interpreter type ",q". To see a list of available special
117commands type ,?.
119=== Running interpreted scripts
120Another common use for csi is to be used as a interpreter for your
121CHICKEN scripts. Here is a small script that reverses all input:
122  #!/usr/local/bin/csi -s
123  ; This imports the nonstandard procedures read-all and string-reverse
124  (use utils srfi-13)
125  (display (string-reverse (read-all)))
126  (newline)
127When calling the script, it does reverse all input:
128  $ chmod +x ./rev.scm
129  $ echo -n hello world|./rev.scm
130  dlrow olleh
131  $
132Notice the -s parameters above. -s will exit the REPL for you when
133the script has been evaluated completely. For a complete list call
134"csi -h".
136=== Compiling your programs
137The real strength of CHICKEN is its compiler. Your code will run
138faster and some more advanced features like calling C functions of
139other libraries in your scheme code are available during
140compilation only.
141For everyday usage you will use the CHICKEN scheme compiler driver
142mostly. Suppose we want to compile our reverse script from above:
143  $ csc rev.scm
144  $ echo -n hello world|./rev
145  dlrow olleh
146  $
147csc will generate a binary that has the same name as your scheme
148file without the .scm extension. Note that this extension is not
149enforced by the compiler but has been used by most schemers in the
151The resulting binary will be dynamically linked to the CHICKEN
152runtime library. In a more complex example you may need to add
153additional libraries for the linker yourself, for example external
154libraries that you use, like SDL, libexif, etc.
155Building static binaries is still possible but officially not
156recommended anymore. For starters ignore static compilation.
157If you want to distribute your binary as a standalone application
158without the need of CHICKEN installed there is the possibility of
159putting all the eggs in one basket, by the use of the -deploy
160option (more on this below).
162=== More than just standard scheme: Extending R5RS with Units and Eggs
163The simple example above is of course not at all that simple. There
164is a lot of work going on under the hood. Reading everything from a
165port, then reversing this string. If you already know scheme and
166the scheme standard you might have noticed that these procedures
167are not part of R5RS, the scheme standard CHICKEN is based on.
168To meet the goal of being a practical scheme environment CHICKEN
169ships with extensions included in the core distribution. These
170extensions are called units for historical reasons and are covered
171by the CHICKEN Manual. They include these topics:
172* Unit library: Basic Scheme definitions
173* Unit eval: Evaluation
174* Unit expand: Modules and macros handling
175* Unit data-structures: Data structures
176* Unit ports: I/O ports
177* Unit files: File and pathname operations
178* Unit extras: Useful utility definitions
179* Unit irregex: Regular expressions
180* Unit srfi-1: List Library
181* Unit srfi-4: Homogeneous numeric vectors
182* Unit srfi-13: String library
183* Unit srfi-14: Character set library
184* Unit srfi-18: multithreading
185* Unit srfi-69: Hashtable Library
186* Unit posix: Unix-like services
187* Unit utils: Shell scripting and file operations
188* Unit tcp: Basic TCP-sockets
189* Unit lolevel: Low-level operations
191As those are so commonly used in scheme programming they are part of
192the core distribution. Extensions not shipped with the core system
193are called "eggs". Those can be installed with the chicken-install
194program. If we need a sha1-sum in our application for example we
195just install the "simple-sha1" egg:
197  $ chicken-install simple-sha1
198  retrieving...
199  [loads of output]
200  $
202This will need a working internet connection and download the
203extension and its scheme dependencies from or a
204mirror. After that the extension is compiled and placed in your
205PREFIX, ready to be used. To be able to use the procedures exported
206by an egg just place (use egg-name) in your program. If we now want
207to calculate a sha-1 has from all input read instead of reversing
208it, change or script like this:
210  #!/usr/local/bin/csi -ns
211  ; This imports the nonstandard procedures read-all
212  (use utils)
213  ; This makes the sha1 egg procedures available
214  (use simple-sha1)
215  (display (string->sha1sum (read-all)))
216  (newline)
218So let's see the sha1 hashsum for the string "hello world":
220  $ csc sha1.scm
221  $ echo -n "hello world" | ./sha1
222  2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
223  $
225As you can see it is quite easy to reuse other people's code by
226using their published extensions. How do I know which procedures
227simple-sha1 exports? I have checked the documentation.
229=== Finding your way: The documentation
231==== Manual
232CHICKEN scheme is documented in mainly two places, one offline and
233one online: The manual and the wiki. The manual is part of every
234release tarball and installs HTML versions of the wiki pages
235locally in $PREFIX/share/chicken/doc/manual/. Point your browser to
236the index.html file in this directory to get started.
237The manual is also available online in the CHICKEN wiki. The wiki
238resides at [[|]] with the
239manual being available
240at [[/manual|]]
241The manual covers the usage of the core binaries, the
242deviations and extensions to the R5RS standard and the
243documentation of the core units.
245==== Wiki and egg index
246The wiki also includes documentation for eggs. All eggs are
247supposed to host their api description there. Also there is a list
248of available eggs in the egg index at:
250Note that the wiki can be edited by anyone including
251yourself. Feel free to reword unclear passages or correct spelling
252errors as you encounter them. The wiki is backed by svn so do not
253be afraid of breaking anything.
254Since it is svn you can also do a checkout of the whole wiki and
255edit it locally in your favourite text editor:
256  $ svn co wiki
257  (user: anonymous, empty password)
259==== Chickadee
260The wiki's search function is currently not optimised for
261searching for suitable procedures. For identifier searches use the
262chickadee. Chickadee is reachable at [[|]] and
263supports identifier searching as well as regexp searching.
264Both chickadee and the wiki search the manual as well as egg
267==== Searching offline: chicken-doc
268The database for chickadee can be reused offline by installing the
269chicken-doc extension. To be able to use chicken-doc install it
270with chicken-install and download the database:
272  $ chicken-install chicken-doc
273  $ cd `csi -p '(chicken-home)'`
274  $ curl | sudo tar zx
276After this you can query chicken-doc for procedures as well as
277whole module documentation. Calling chicken-doc without arguments
278will list all possible options as well as usage examples.
279For our simple-sha1 example we can ask chicken-doc about anything
280that contains "sha1" in its name:
282  $ chicken-doc -m sha1
283  (sha1)                         sha1 egg
284  (sha1 sha1-binary-digest)      (sha1-binary-digest SOURCE)
285  (sha1 sha1-digest)             (sha1-digest SOURCE)
286  (sha1 sha1-primitive)          (sha1-primitive)
287  (simple-sha1 sha1sum)          (sha1sum filename)
288  (simple-sha1)                  simple-sha1 egg
289  (simple-sha1 string->sha1sum)  (string->sha1sum str)
291So there are two eggs for calculating sha1 hashes: sha1 and
292simple-sha1. Let's have a look at the egg documentation for the
293simple-sha1 egg as we only want to convert a string to a hash:
295  $ chicken-doc simple-sha1
296  [simple-sha1's egg page]
298we could have skipped this step and just asked for the description
299of string->sha1sum:
301  $ chicken-doc "string->sha1sum"
302  path: (simple-sha1 string->sha1sum)
303* - procedure: (string->sha1sum str)
304  Generates the SHA1 hash for the given string `str`.
305  $
307The latter tells us that string->sha1sum is part of the
308simple-sha1 egg (in the "path:" line) and it does what we need
309for our little script.
311=== The home of bugs: CHICKEN'S bug tracker
312CHICKEN scheme uses trac as its bug tracker. It can be
313reached at [[|]]. Currently
314filing a new ticket
315requires getting a trac account, which we will do happily upon
316request. Please follow the instructions on
318to get one.
320=== Getting help from humans
321Searched through the manual, wiki, bugs, and chickadee without
322finding an answer to your question? Then it might be time to ask a
323human. Chickenistas can be found online on IRC in #chicken on
324freenode or if you want to reach more people and have an archived
325form of your question you can post to one of the mailing
326lists. These are:
328* chicken-users: For all general questions about the usage of
329  CHICKEN scheme. If in doubt post to this list.
330* chicken-hackers: For all questions about the implementation of
331  scheme in CHICKEN
332* chicken-janitors: The bug tracking list which will post all
333  changes to the bug tracking system. Subscribe here if you are
334  interested in CHICKEN's bugs and the handling of those
336These lists are quite responsive as is the IRC channel. Provided
337the usual netiquette you will get an answer to your problem almost
340== Programming in CHICKEN
341Up to now you should be able to find your way around and write
342simple scripts. There are a couple of hints and tricks scattered
343throughout the CHICKEN village that try to make programming in
344CHICKEN scheme even more pleasant. The most requested things are
345collected here.
347=== Choosing an editor
348People in #chicken usually do not engage in the editor wars. Be it
349notepad, vim, nano or emacs you should choose the one that floats
350your boat. There are bindings for vim and emacs available that
351enable auto completion of identifiers, easy integration of the REPL
352and basic compilation support. As emacs is more popular among
353schemers the support here is a bit better but in the end it does not
354matter much. If you are coming from Common Lisp you might enjoy the
355SLIME egg that provides a SWANK backend for the famous Lisp mode.
356Another common caveat for new users is the missing line editing
357support for csi. Here you can either install bindings for readline,
358linenoise or parley to get line editing support. The installation
359procedures are covered in the documentation for those eggs.
361=== Building complex projects
362Once your application grows you will want to split up your code
363into separate, independent entities. The CHICKEN way to do so is to
364write [[|modules]]. Modules
365give you means to separate and manipulate namespaces and encourage
366encapsulation and controlled exposure of your code to the outside
369Compiling more than one file on the command line is a tedious
370task. To automate this you can either write a Makefile as with
371other projects or use the systems egg. The systems egg works as a
372simple build system, that allows you to recompile your code from
373inside the REPL as well as on the command line: Load a system
374definition and tell the system egg to recompile it and you can
375continue testing your program. A typical definition looks like
378  (define-system xyz
379       (file "z")
380       (scheme-file "y" includes: '("z"))
381       (compiled-scheme-file "x" depends: '("y")))
383You can then use this definition in csi like:
385  #;1> (use system posix)
386  #;2> (load "xyz.system")
387  #;3> (load-system xyz)
389Whenever you load the system changes to the defined files will be
390detected and recompilation initiated automatically. You can wrap
391this in a csi script for replacing a Makefile as well. This can be
392especially useful if you are using FFI code in your application
393which is only available in compiled code.
395=== Writing your own extensions
396If you have modules that may be used by others or you want to be
397able to deploy those with chicken-install you can wrap them into an
398egg. An egg can include 1 or more modules and executables. The
399current infrastructure (known as "the new system" amongst
400chicken-users) allows you to either include your egg in the svn egg
401tree (you will need to apply for an account, where "application"
402means just asking for it) or you can host it in a git, mercurial or
403fossil repository. If you choose the decentralised version you
404still need to get an entry into a centralised egg-location file for
405chicken-install being able to pick it up. Again, this is another
406matter of asking for it.
408Whatever you choose please consider your egg complete only if you
409provide documentation for it in the wiki. Otherwise people are
410unable to find information about it neither through chickadee nor
413An egg consists of your source files, a so called .meta file, a
414.setup script that handles the compilation of your source files
415and optionally a test directory including a test suite that will
416get run by salmonella, CHICKEN's test infrastructure.
418Let's suppose you want to write an mp3 decoder. A setup script for
419it may look like this:
421  ; These two instructions will produce a dynamically linkable object file
422  "" respectively.
423  (compile -s -O2 -d1 mpeg3.scm -j mpeg3)
424  (compile -s mpeg.import.scm -O2 -d0)
425  (install-extension
426  ; Name of your extension:
427  'mpeg3
428  ; Files to install for your extension:
429  '("" "")
430  ; Assoc list with properties for your extension:
431  '((version 1.2)))
433For the egg index as well as declaring dependencies for your egg
434the .meta file is used:
436  (
437  ; Your egg's license:
438  (license "BSD")
439  (category misc)
440  ; A list of eggs mpeg3 depends on.  If none, you can omit this
441  declaration
442  ; altogether. `depends' is an alias to `needs'.
443  ; Notice that you should NOT put CHICKEN units (e.g., srfi-1, srfi-13
444  ; and many others) in `needs' or in `depends'.
445  (needs sandbox syntax-case)
446  ; A list of eggs required for TESTING ONLY.  See the `Tests' section.
447  ; Just like `needs' and `depends', `test-depends' should NOT contain
448  ; CHICKEN units.
449  (test-depends test)
450  (author "Your Name Goes Here")
451  (synopsis "A basic description of the purpose of the egg."))
453Now to release the egg create a tag that matches the name of the
454version clause above ("1.12") and people are able to
455chicken-install your egg. All the details to this procedure is
456found at [[/eggs tutorial]].
458=== Deploy your application as a standalone bundle
459CHICKEN scheme supports the deployment of your application as a
460self-contained version without the need of CHICKEN installed on your
461target machine.
463To use this use the -deploy option of csc. To compile a single
464executable it is sufficient to add -deploy to the call. If you are
465using eggs in your application you need to use chicken-install with
466the -deploy option. As for our sha1 example this means that the
467following will result in a directory called sha1 containing
468everything you need to run this on another machine (provided it is
469the same OS and architecture):
471  $ csc -deploy sha1.scm
472  $ chicken-install -prefix $PWD/sha1 -deploy simple-sha1
473  $ ls -l sha1
474  total 6328
475  rwxr-xr-x  1 ckeen  ckeen  3124541 Aug 13 18:16
476  rwxr-xr-x  1 ckeen  ckeen    13074 Aug 13 18:16 sha1
477  rwxr-xr-x  1 ckeen  ckeen    12164 Aug 13 18:18
478  rw-r--r--  1 ckeen  ckeen       92 Aug 13 18:18 simple-sha1.setup-info
479  rwxr-xr-x  1 ckeen  ckeen    27647 Aug 13 18:18
481Please note that you need to install all extensions on your build
482system first. Installing directly from the egg repositories without
483this step will not work for deployment for reasons beyond the scope
484of this tour. Also this currently does not work on NetBSD; OpenBSD
485needs a trampoline script that sets LD\_LIBRARY\_PATH
487=== Using the test infrastructure
488Salmonella, located at [[|]], will compile your
489egg every day against the development branch of CHICKEN, giving you
490hints for API changes in CHICKEN and build problems. You can
491subscribe to RSS feeds of your eggs to get notifications if your
492egg suddenly fails to build.
494== Wrapping up
495Now we have reached the end of our tour through the CHICKEN
496landscape. There have been rough edges and lots of
497omissions for the sake of clarity and simplicity. I hope you got a
498good impression of the CHICKEN infrastructure and will try it out on
499your own during the workshop.
501== Thanks
502I want to thank the fine people from #chicken on Freenode IRC for
503their corrections and suggestions. Many corrections have been done by
504John Gabriele.
Note: See TracBrowser for help on using the repository browser.