Notes on chicken.h file
Disclaimer
This page is a modest primer for reading the chicken.h header file. By no means it is intended to be a comprehensive guide for understanding chicken source. Please consider reading Internals for a more in-depth understanding of how CHICKEN works. Feel free to make suggestions to Arthur or edit this page directly.
Purpose
As stated at its beginning, chicken.h is a general headerfile for compiler generated executables.
Coding conventions
All of the functions start with C_ to avoid namespace collisions. All the below prefixes and suffixes go after it.
- _a_
- "allocating" - accepts a pointer at which it will store the object and change it.
- _u_
- "unsafe" - macros and functions don't do any typechecking and will happily dereference invalid objects.
- _nn_
- "not null" - the macro just fetches the pointer, so it can only be used in case the value isn't #f.
- _ub_
- "unboxed" - a plain data structure which isn't wrapped as a Scheme object. This isn't used at the moment (we used to have boxing/unboxing support but it was broken so it was removed).
- _i_
- "inline" - it doesn't accept a continuation but just returns.
- _o_
- "overflow-detecting" - it's not used much.
- _2_
- diadic version of a multi-arg procedure.
- p
- p at the end of function names generally means predicate as in Common Lisp.We can see a bunch of examples from line 1163 to 1198. Ex.: C_truep(x) would be in Scheme equivalent to true? in (define (true? x) (if x #t #f)). All predicates return Scheme values, but C_truep is an exception: it returns a C "boolean", ie 1 if the value is non-#f and 0 if it is #f.
External configuration
On line 62 chicken-config.h file is included. We can see that Makefiles fill this file with many options that will be used by chicken.h, according to the machine/platform/system environment. For comparison, see how Makefile.linux and Makefile.mingw-msys differ regarding to their options (lines 61 and 82 respectively).