source: project/wiki/chickenista-guide @ 36650

Last change on this file since 36650 was 31126, checked in by Mario Domenech Goulart, 6 years ago

Properly capitalize CHICKEN on the wiki directory (only first level).

I used the following shell script to change things:

while IFS= read -d $'\0' -r file ; do

sed -i 's/Chicken/CHICKEN/g' "$file"

done < <(find wiki -maxdepth 1 -type f -print0 )

Some files have been manually reverted after that, since some
substitutions don't apply:

  • friedly-chicken (repl banner)
  • survey2011 (Chicken in URI paths)
  • chickenista-guide (Chickenista)

I hope the link canonicalization thing will be on my side.

File size: 21.1 KB
Line 
1== A guided tour through the CHICKEN scheme republic
2
3[[toc:]]
4
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.
14
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  call-cc.org 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
30
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.
37
38=== Building CHICKEN from a stable source
39The CHICKEN core system is held in a git repository at
40[[http://code.call-cc.org|http://code.call-cc.org]] 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
48Solaris.
49So to install the 4.8.0 release on a linux box download the tarball:
50  $ wget http://code.call-cc.org/releases/4.8.0/chicken-4.8.0.tar.gz
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.
64
65If you want to use clang instead of the default gcc as C compiler, make and make install chicken like this:
66
67  $ make PLATFORM=<your-platform> C_COMPILER=clang
68  # make PLATFORM=<your-platform> C_COMPILER=clang install
69
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.
73
74
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
80snapshot:
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.
86
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
98
99=== Using the interpreter
100Calling csi without arguments will start a REPL for you:
101  $ csi
102  CHICKEN
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 necronomicon.my.domain (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 ,?.
118
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".
135
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
150past.
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).
161
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
190
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:
196
197  $ chicken-install simple-sha1
198  retrieving...
199  [loads of output]
200  $
201
202This will need a working internet connection and download the
203extension and its scheme dependencies from call-cc.org 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:
209
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)
217
218So let's see the sha1 hashsum for the string "hello world":
219
220  $ csc sha1.scm
221  $ echo -n "hello world" | ./sha1
222  2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
223  $
224
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.
228
229=== Finding your way: The documentation
230
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 [[http://wiki.call-cc.org|http://wiki.call-cc.org]] with the
239manual being available
240at [[/manual|http://wiki.call-cc.org/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.
244
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:
249[[/egg-index|http://wiki.call-cc.org/egg-index]]
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 https://code.call-cc.org/svn/wiki wiki
257  (user: anonymous, empty password)
258
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 [[http://api.call-cc.org|http://api.call-cc.org]] and
263supports identifier searching as well as regexp searching.
264Both chickadee and the wiki search the manual as well as egg
265documentation.
266
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:
271
272  $ chicken-install chicken-doc
273  $ cd `csi -p '(chicken-home)'`
274  $ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx
275
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:
281
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)
290
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:
294
295  $ chicken-doc simple-sha1
296  [simple-sha1's egg page]
297
298we could have skipped this step and just asked for the description
299of string->sha1sum:
300
301  $ chicken-doc "string->sha1sum"
302  path: (simple-sha1 string->sha1sum)
303 
304  -- procedure: (string->sha1sum str)
305 
306  Generates the SHA1 hash for the given string `str`.
307  $
308
309The latter tells us that string->sha1sum is part of the
310simple-sha1 egg (in the "path:" line) and it does what we need
311for our little script.
312
313=== The home of bugs: CHICKEN'S bug tracker
314CHICKEN scheme uses trac as its bug tracker. It can be
315reached at [[http://bugs.call-cc.org|http://bugs.call-cc.org]]. Currently
316filing a new ticket
317requires getting a trac account, which we will do happily upon
318request. Please follow the instructions on
319[[/contribute|http://wiki.call-cc.org/contribute]]
320to get one.
321
322=== Getting help from humans
323Searched through the manual, wiki, bugs, and chickadee without
324finding an answer to your question? Then it might be time to ask a
325human. Chickenistas can be found online on IRC in #chicken on
326freenode or if you want to reach more people and have an archived
327form of your question you can post to one of the mailing
328lists. These are:
329
330* chicken-users: For all general questions about the usage of
331  CHICKEN scheme. If in doubt post to this list.
332* chicken-hackers: For all questions about the implementation of
333  scheme in CHICKEN
334* chicken-janitors: The bug tracking list which will post all
335  changes to the bug tracking system. Subscribe here if you are
336  interested in CHICKEN's bugs and the handling of those
337
338These lists are quite responsive as is the IRC channel. Provided
339the usual netiquette you will get an answer to your problem almost
340instantly.
341
342== Programming in CHICKEN
343Up to now you should be able to find your way around and write
344simple scripts. There are a couple of hints and tricks scattered
345throughout the CHICKEN village that try to make programming in
346CHICKEN scheme even more pleasant. The most requested things are
347collected here.
348
349=== Choosing an editor
350People in #chicken usually do not engage in the editor wars. Be it
351notepad, vim, nano or emacs you should choose the one that floats
352your boat. There are bindings for vim and emacs available that
353enable auto completion of identifiers, easy integration of the REPL
354and basic compilation support. As emacs is more popular among
355schemers the support here is a bit better but in the end it does not
356matter much. If you are coming from Common Lisp you might enjoy the
357SLIME egg that provides a SWANK backend for the famous Lisp mode.
358Another common caveat for new users is the missing line editing
359support for csi. Here you can either install bindings for readline,
360linenoise or parley to get line editing support. The installation
361procedures are covered in the documentation for those eggs.
362
363=== Building complex projects
364Once your application grows you will want to split up your code
365into separate, independent entities. The CHICKEN way to do so is to
366write [[http://wiki.call-cc.org/man/4/Modules|modules]]. Modules
367give you means to separate and manipulate namespaces and encourage
368encapsulation and controlled exposure of your code to the outside
369world.
370
371Compiling more than one file on the command line is a tedious
372task. To automate this you can either write a Makefile as with
373other projects or use the systems egg. The systems egg works as a
374simple build system, that allows you to recompile your code from
375inside the REPL as well as on the command line: Load a system
376definition and tell the system egg to recompile it and you can
377continue testing your program. A typical definition looks like
378this:
379
380  (define-system xyz
381       (file "z")
382       (scheme-file "y" includes: '("z"))
383       (compiled-scheme-file "x" depends: '("y")))
384
385You can then use this definition in csi like:
386
387  #;1> (use system posix)
388  #;2> (load "xyz.system")
389  #;3> (load-system xyz)
390
391Whenever you load the system changes to the defined files will be
392detected and recompilation initiated automatically. You can wrap
393this in a csi script for replacing a Makefile as well. This can be
394especially useful if you are using FFI code in your application
395which is only available in compiled code.
396
397=== Writing your own extensions
398If you have modules that may be used by others or you want to be
399able to deploy those with chicken-install you can wrap them into an
400egg. An egg can include 1 or more modules and executables. The
401current infrastructure (known as "the new system" amongst
402chicken-users) allows you to either include your egg in the svn egg
403tree (you will need to apply for an account, where "application"
404means just asking for it) or you can host it in a git, mercurial or
405fossil repository. If you choose the decentralised version you
406still need to get an entry into a centralised egg-location file for
407chicken-install being able to pick it up. Again, this is another
408matter of asking for it.
409
410Whatever you choose please consider your egg complete only if you
411provide documentation for it in the wiki. Otherwise people are
412unable to find information about it neither through chickadee nor
413chicken-doc.
414
415An egg consists of your source files, a so called .meta file, a
416.setup script that handles the compilation of your source files
417and optionally a test directory including a test suite that will
418get run by salmonella, CHICKEN's test infrastructure.
419
420Let's suppose you want to write an mp3 decoder. A setup script for
421it may look like this:
422
423  ; These two instructions will produce a dynamically linkable object file
424  "mpeg3.so" respectively.
425  (compile -s -O2 -d1 mpeg3.scm -j mpeg3)
426  (compile -s mpeg.import.scm -O2 -d0)
427  (install-extension
428  ; Name of your extension:
429  'mpeg3
430  ; Files to install for your extension:
431  '("mpeg3.so" "mpeg3.import.so")
432  ; Assoc list with properties for your extension:
433  '((version 1.2)))
434
435For the egg index as well as declaring dependencies for your egg
436the .meta file is used:
437
438  (
439  ; Your egg's license:
440  (license "BSD")
441  (category misc)
442  ; A list of eggs mpeg3 depends on.  If none, you can omit this
443  declaration
444  ; altogether. `depends' is an alias to `needs'.
445  ; Notice that you should NOT put CHICKEN units (e.g., srfi-1, srfi-13
446  ; and many others) in `needs' or in `depends'.
447  (needs sandbox syntax-case)
448  ; A list of eggs required for TESTING ONLY.  See the `Tests' section.
449  ; Just like `needs' and `depends', `test-depends' should NOT contain
450  ; CHICKEN units.
451  (test-depends test)
452  (author "Your Name Goes Here")
453  (synopsis "A basic description of the purpose of the egg."))
454
455Now to release the egg create a tag that matches the name of the
456version clause above ("1.12") and people are able to
457chicken-install your egg. All the details to this procedure is
458found at [[/eggs tutorial]].
459
460=== Deploy your application as a standalone bundle
461CHICKEN scheme supports the deployment of your application as a
462self-contained version without the need of CHICKEN installed on your
463target machine.
464
465To use this use the -deploy option of csc. To compile a single
466executable it is sufficient to add -deploy to the call. If you are
467using eggs in your application you need to use chicken-install with
468the -deploy option. As for our sha1 example this means that the
469following will result in a directory called sha1 containing
470everything you need to run this on another machine (provided it is
471the same OS and architecture):
472
473  $ csc -deploy sha1.scm
474  $ chicken-install -prefix $PWD/sha1 -deploy simple-sha1
475  $ ls -l sha1
476  total 6328
477  rwxr-xr-x  1 ckeen  ckeen  3124541 Aug 13 18:16 libchicken.so.6
478  rwxr-xr-x  1 ckeen  ckeen    13074 Aug 13 18:16 sha1
479  rwxr-xr-x  1 ckeen  ckeen    12164 Aug 13 18:18 simple-sha1.import.so
480  rw-r--r--  1 ckeen  ckeen       92 Aug 13 18:18 simple-sha1.setup-info
481  rwxr-xr-x  1 ckeen  ckeen    27647 Aug 13 18:18 simple-sha1.so
482
483Please note that you need to install all extensions on your build
484system first. Installing directly from the egg repositories without
485this step will not work for deployment for reasons beyond the scope
486of this tour. Also this currently does not work on NetBSD; OpenBSD
487needs a trampoline script that sets LD\_LIBRARY\_PATH
488
489=== Using the test infrastructure
490Salmonella, located at [[http://tests.call-cc.org|http://tests.call-cc.org]], will compile your
491egg every day against the development branch of CHICKEN, giving you
492hints for API changes in CHICKEN and build problems. You can
493subscribe to RSS feeds of your eggs to get notifications if your
494egg suddenly fails to build.
495
496== Wrapping up
497Now we have reached the end of our tour through the CHICKEN
498landscape. There have been rough edges and lots of
499omissions for the sake of clarity and simplicity. I hope you got a
500good impression of the CHICKEN infrastructure and will try it out on
501your own during the workshop.
502
503== Thanks
504I want to thank the fine people from #chicken on Freenode IRC for
505their corrections and suggestions. Many corrections have been done by
506John Gabriele.
Note: See TracBrowser for help on using the repository browser.