source: project/wiki/notes-on-chicken.h @ 36676

Last change on this file since 36676 was 31463, checked in by arthurmaciel, 5 years ago
File size: 2.9 KB
1== Notes on {{chicken.h}} file
5=== Disclaimer
7This page is a modest primer for reading the [[;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD|{{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 [[/users/arthurmaciel|Arthur]] or edit this page directly.
9=== Purpose
11As stated at its beginning, [[;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD|{{chicken.h}}]] is a general headerfile for compiler generated executables.
13=== Coding conventions
15All of the functions start with {{C_}} to avoid namespace collisions. All the bellow prefixes and suffixes go after it.
17; _a_ : "allocating" - accepts a pointer at which it will store the object and change it.
18; _u_ : "unsafe" - macros and functions don't do any typechecking and will happily dereference invalid objects.
19; _nn_ : "not null" - the macro just fetches the pointer, so it can only be used in case the value isn't #f.
20; _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).
21; _i_ : "inline" - it doesn't accept a continuation but just returns.
22; _o_ : "overflow-detecting" - it's not used much.
23; _2_ : diadic version of a multi-arg procedure.
24; p : {{p}} at the end of function names generally means {{predicate}} as in [[|Common Lisp]].We can see a bunch of examples from line [[;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD#l1163|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}}.
26=== External configuration
28On line [[;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD#l62|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 [[;a=blob;f=Makefile.linux;h=010b560eea074dae1da63627e6c83f09b1733263;hb=HEAD|{{Makefile.linux}}]] and [[;a=blob;f=Makefile.mingw-msys;h=2af2dc17b5794df796782dd787baed474d897364;hb=HEAD|{{Makefile.mingw-msys}}]] differ regarding to their options (lines 61 and 82 respectively).
Note: See TracBrowser for help on using the repository browser.