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
Line 
1== Notes on {{chicken.h}} file
2
3[[toc:]]
4
5=== Disclaimer
6
7This page is a modest primer for reading the [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;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.
8
9=== Purpose
10
11As stated at its beginning, [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD|{{chicken.h}}]] is a general headerfile for compiler generated executables.
12
13=== Coding conventions
14
15All of the functions start with {{C_}} to avoid namespace collisions. All the bellow prefixes and suffixes go after it.
16
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 [[http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html|Common Lisp]].We can see a bunch of examples from line [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;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}}.
25
26=== External configuration
27
28On line [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;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 [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;a=blob;f=Makefile.linux;h=010b560eea074dae1da63627e6c83f09b1733263;hb=HEAD|{{Makefile.linux}}]] and [[http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;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.