Issue 9
0. Introduction
Welcome to issue 9 of the Chicken Gazette, brought to you by the letter k and the procedure call/cc.
1. The Hatching Farm
First off, this week's egg news.
- http-session: fix a bug in session ID generation for long-lived processes, due to a timer overflow in current-milliseconds;
- estraier: performance improvement and regex dependency dropped;
- wiki-parse: deleted, as it was unused and had diverged too far from upstream to be maintained;
- chickadee: added a wrapper program which simplifies installing and running a server;
- shell: a thin wrapper around a turtle;
- salmonella: now checks that eggs are documented and executes egg tests; also something you can find on a turtle
To take advantage of the new salmonella egg testing, a proper exit code was added to tests/run.scm in many eggs, reflecting whether a test failure occurred.
Additionally, explicit dependencies on the new regex egg were added to yet more eggs for compatibility with 4.6.2 and later.
And now a public service announcement. Egg authors, now hear this. When your egg installs both library files via install-extension and also an executable via install-program, you need to use different IDs for each. By convention, the library files should use the name of the egg (such as chicken-doc) and the executable should use this same name with something appended, such as chicken-doc-cmd. This prevents the uninstaller from losing track of files. Specifically, the .setup-info files created by chicken-install to track extension metadata will clobber each other if the IDs are identical.
2. Yolklore
Chicken core development was relatively active this week. Dare I say excitingly so? Yes, I dare it.
Peter Bex committed a patch to the irregex-bugfixes branch that fixes ticket 411, correcting an issue introduced in 4.6.2. It makes submatch accessors return #f instead of throwing an error when the submatch is in range but non-matching. For example, this no longer errors out:
(string-search-positions "(foo)|(bar)|(baz)" "bar") ;=> ((0 3) (#f #f) (0 3) (#f #f))
The new blob literal syntax mentioned in the last issue was changed from #{HEX ...} to #${HEX ...} after concerns were voiced about the loss of valuable ASCII real-estate. The use of $ to mean hex is of course well-known to assembly-language programmers of a certain age.
integer64 and unsigned-integer64 are now supported as FFI return values, including in let-location, fixing ticket 413.
When fed a non-link argument, read-symbolic-link in Unit posix now returns that argument when told to resolve symlinks recursively. Previously it threw an error.
delete-directory in Unit posix now accepts an optional argument telling it to delete recursively.
Optional per-slot SRFI-17 setters have been added to define-record.
And there were a few types.db fixes, as occur from time to time. types.db is a database of procedure signatures for the core, and is used by the scrutinizer to check procedure argument types at compile-time.
3. Chicken Talk
In which I summarize our last week of mail.
Enwin Thun wrote in with a problem installing eggs after upgrading to Ubuntu Maverick. The cause is that the Chicken infrastructure migrated to new servers between 4.5.0 and 4.6.0, but Maverick is still on 4.5.0 which points to the old servers. The solution is to provide the -l option to chicken-install to override the remote repository location or, preferably, to change its configuration file. The changes are detailed at the infrastructure migration page.
Discussion is ongoing about the proper procedure to install datafiles for eggs, as well as the proper place for compliance with the Filesystem Hierarchy Standard and BSD's hier(7). The only eggs known to the author to be affected are slatex, chicken-doc and chickadee, but egg authors are advised to keep an eye on this breaking issue.
On a related note, Kon Lovett recommended using setup-api's create-directory/parents instead of posix's create-directory when making new directories in .setup scripts, because the former respects chicken-install -s (the s is for sudo). That was news to me.
Alan Post asked how to access mmapped memory as a string and, having received a couple ideas from your illustrious developers, graciously wrote them up on the wiki.
Felix informed us that a "wish-list" page has been added to the wiki, as a place where users can describe their most earnest desires and fever-dreams. About Chicken.
Finally, Mario Goulart let us know that the salmonella egg tester has been updated to check if eggs are documented and to run egg tests. Authors are urged to update their test scripts for salmonella compliance.
4. Omelette Recipes
My momma always said "write what you know," so today you'll be learning about chicken-doc.
chicken-doc is, perhaps surprisingly, a documentation system for Chicken. Its primary goal is to provide access to documentation from the command-line and REPL.
Now, Chicken doesn't provide introspection in the form of docstrings, nor are docs installed alongside the eggs. Instead, the core and eggs are thoroughly documented on the wiki so that everyone can contribute. So, chicken-doc's approach is to process a copy of the wiki documentation and make it available to you offline via a nice interface. And, since you have access to all documentation at once -- instead of just the eggs you have installed -- you can quickly explore everything the community has to offer.
Install
First, install chicken-doc.
$ chicken-install -s chicken-doc
The nicest way to work with chicken-doc is to check out a copy of the wiki from Subversion, then use chicken-doc-admin to prepare it for use. But the quickest way to get started is to download today's pre-baked chicken-doc repository, a 1.4MB gzipped tarball:
$ cd `csi -p '(chicken-home)'` && curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx
The repository goes inside your Chicken install directory and you may need sudo to write to it. Alternatively, you could put the repository anywhere you want like this:
export CHICKEN_DOC_REPOSITORY=/path/to/my/cdoc/repo/dir
The command-line
Now you can ask for docs on any identifier:
$ chicken-doc + path: (scheme +) -- procedure: (+ z[1] ...) -- procedure: (* z[1] ...) These procedures return the sum or product of their arguments.
You can ask for docs on any documented egg or unit:
$ chicken-doc atom path: (atom) == atom Read and write Atom 1.0 feeds. [... rest of doc elided ...]
The identifier you ask for might be duplicately named:
$ chicken-doc file-open Found 2 matches: (9p file-open) (file-open connection path mode) (posix file-open) (file-open FILENAME FLAGS [MODE])
in which case you can disambiguate it:
$ chicken-doc posix file-open -- procedure: (file-open FILENAME FLAGS [MODE]) Opens the file specified with the string `FILENAME` and open-flags `FLAGS` using the C function `open(2)`. On success a file-descriptor for the opened file is returned.
You can ask for the contents of any egg or unit (a list of identifiers):
$ chicken-doc -c posix _exit (_exit [CODE]) block-device? (block-device? FILE) change-directory (change-directory NAME) [...]
And you can do a regular-expression match across the entire identifier space:
$ chicken-doc -m call- (scheme call-with-output-file) (call-with-output-file string proc) (ports call-with-output-string) (call-with-output-string PROC) (sql-de-lite call-with-database) (call-with-database filename proc) (library get-call-chain) (get-call-chain [START [THREAD]]) [...]
$ chicken-doc -m o.O
(glut glut:PostWindowOverlayRedisplay)
(glut:PostWindowOverlayRedisplay INTEGER)
The REPL
Just (use chicken-doc) from the REPL, and you gain three toplevel commands: ,doc, ,toc, and ,wtf.
,doc shows docs on its argument, like calling chicken-doc with no options:
#;> ,doc + path: (scheme +) -- procedure: (+ z[1] ...) #;> ,doc file-open Found 2 matches: (9p file-open) (file-open connection path mode) (posix file-open) (file-open FILENAME FLAGS [MODE]) #;> ,doc (posix file-open) ;; use parentheses to disambiguate
,toc shows egg or unit contents, like chicken-doc -c:
#;> ,toc posix _exit (_exit [CODE]) block-device? (block-device? FILE) change-directory (change-directory NAME)
,wtf ("where to find") matches identifiers, like chicken-doc -m:
#;> ,wtf call- (scheme call-with-output-file) (call-with-output-file string proc) (ports call-with-output-string) (call-with-output-string PROC) [...]
Emacs integration is possible as well, and is covered in the egg documentation.
chickadee
chickadee is a web-based interface to chicken-doc. That sounds rather roundabout, doesn't it? Why not just use the wiki? Why not, indeed. Well, chickadee has some features you might find useful:
- fast, incremental identifier search
- convenient contents sidebar
- easy installation and use offline
- documentation server for your own projects
- a local preview of wiki doc changes
- a sort of lisp-machine chic
You can use the primary chickadee server at http://3e8.org/chickadee, or you can run your own copy after setting up a chicken-doc repository:
$ chicken-install -s chickadee $ chickadee serve # start on http://localhost:8080 $ chickadee serve --port 8081 # start on http://localhost:8081
The look and feel of the server is customizable through CSS and Javascript but some layout is still hardcoded, particularly the front page.
chicken-doc-admin
So this is the way to use chicken-doc as nature intended: checkout the wiki and then process it with chicken-doc-admin. First, grab a copy of the wiki and initialize an empty chicken-doc repository:
$ chicken-install -s chicken-doc-admin
$ sudo chicken-doc-admin -i
$ svn co --username anonymous --password "" \
http://code.call-cc.org/svn/chicken-eggs/wiki
Then add the Chicken 4 man and egg pages to your database:
$ sudo chicken-doc-admin -m wiki/man/4 49 man pages processed, 49 updated $ sudo chicken-doc-admin -e wiki/eggref/4 347 eggs processed, 347 updated
Now you can use chicken-doc as before. Later, you can update your checkout and rerun the processor:
$ svn up wiki/eggref/4 $ sudo chicken-doc-admin -e wiki/eggref/4 347 eggs processed, 28 updated
chicken-doc-admin updates only the nodes that have changed since last run. So if you make some local changes, you can easily preview them without checking in:
$ emacs wiki/eggref/4/atom $ sudo chicken-doc-admin -e wiki/eggref/4 347 eggs processed, 1 updated
chicken-doc-admin has more options than you could possibly dream of (as long as you can count no higher than ten); check out the documentation for details.
5. Chick'n Chunks
This is a recurring Gazette feature which appears at least once every nine issues, and dispenses Chicken wisdom in tasty, bite-sized morsels.
- Use the -S option to csc to turn on the scrutinizer and get free static type checking on calls to core procedures. Drop everything and use it right now.
- The -local option to csc may give a speed boost to performance-critical code that is exported from your modules; code generation is improved by letting the compiler assume these globals can't be changed. It's like a less blocky version of -block. It's especially good with a dollop of -inline, and is now automatically set at -O3 and higher.
- Use csc -J instead of csc -j module to save a little typing in your extensions.
6. About the Chicken Gazette
The Gazette is produced weekly by a volunteer from the Chicken community. The latest issue can be found at http://gazette.call-cc.org or you can follow it in your feed reader at http://gazette.call-cc.org/feed.atom. If you'd like to write an issue, check out the instructions and come and find us in #chicken on Freenode!