-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
473 lines (357 loc) · 17 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
README file for the CHICKEN Scheme system
=========================================
(c) 2008-2012, The Chicken Team
(c) 2000-2007, Felix L. Winkelmann
version 4.7.0.6
1. Introduction
CHICKEN is a Scheme-to-C compiler supporting the language
features as defined in the 'Revised^5 Report on
Scheme'. Separate compilation is supported and full
tail-recursion and efficient first-class continuations are
available.
Some things that CHICKEN has to offer:
1. CHICKEN generates quite portable C code and compiled files
generated by it (including itself) should work without any
changes on DOS, Windows, most UNIX-like platforms, and with
minor changes on other systems.
2. The whole package is distributed under a BSD style license
and as such is free to use and modify as long as you agree
to its terms.
3. Linkage to C modules and C library functions is
straightforward. Compiled programs can easily be embedded
into existing C code.
4. Loads of extra libraries.
Note: Should you have any trouble in setting up and using
CHICKEN, please ask questions on the Chicken mailing list. You
can subscribe to the list from the Chicken homepage,
http://www.call-with-current-continuation.org)
2. Installation
Building CHICKEN requires GNU Make. Other "make" derivates are
not supported. If you are using a Windows system and do not
have GNU Make, download
http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip.
It contains a precompiled set of UNIX utilities, which among
other useful tools contains "make".
Configuration and customization of the build process is done by
either setting makefile variables on the "make" command line or
by editing the platform-specific makefile.
To build CHICKEN, first extract the archive ("tar xzf
chicken-<version>.tar.gz" on UNIX or use your favorite
extraction program on Windows), then change to the
chicken-<version> directory and invoke "make" like this:
make PLATFORM=<platform> PREFIX=<destination>
where "PLATFORM" specifies on what kind of system CHICKEN
shall be built and "PREFIX" specifies where the executables
and libraries shall be installed. Out-of-directory builds are
currently not supported, so you must be in the toplevel source
directory to invoke "make".
Enter "make" without any options to see a list of supported
platforms.
Note that parallel builds (using the "-j" make(1) option) are
*not* supported.
If you build CHICKEN directly from the development sources out
of the git repository, you will need a "chicken" executable to
generate the compiled C files from the Scheme library
sources. If you have a recent version of CHICKEN installed,
then pass "CHICKEN=<chicken-executable>" to the "make"
invocation to override this setting. "CHICKEN" defaults to
"$PREFIX/bin/chicken".
If you do not have a "chicken" binary installed, you will have
to obtain a "bootstrapping" compiler, which can either be
built from a release tarball (see below for instructions) or
by using a precompiled and statically linked compiler binary
from here:
http://code.call-cc.org/bootstrap/
If CHICKEN is built successfully, you can install it on your
system by entering
make PLATFORM=<platform> PREFIX=<destination> install
"PREFIX" defaults to "/usr/local". Note that the PREFIX is
compiled into several CHICKEN tools and must be the same
while building the system and during installation.
To install CHICKEN for a particular PREFIX on a different
location, set the "DESTDIR" variable in addition to "PREFIX":
It designates the directory where the files are installed
into.
You can further enable various optional features by adding
one or more of the following variables to the "make"
invocation:
DEBUGBUILD=1
Disable optimizations in compiled C code and enable
debug information.
STATICBUILD=1
Build only static versions of the runtime library, compiler
and interpreter. `chicken-install', `chicken-uninstall' and
`chicken-status' will not be generated, as it is mostly
useless unless compiled code can be loaded.
SYMBOLGC=1
Always enable garbage collection for unused symbols in the
symbol table by default. This will result in slightly slower
garbage collection, but minimizes the amount of garbage
retained at runtime (which might be important for long
running server applications). If you don't specify this
option you can still enable symbol GC at runtime by passing
the `-:w' runtime option when running the program.
EXTRA_CHICKEN_OPTIONS=...
Additional options that should be passed to `chicken' when
building the system.
C_COMPILER_OPTIMIZATION_OPTIONS=...
Override built-in C compiler optimization options. Available
for debug or release build.
PROGRAM_PREFIX=
A prefix to prepend to the names of all generated executables.
This allows having multiple CHICKEN versions in your PATH
(but note that they have to be installed at different locations).
PROGRAM_SUFFIX=
A suffix to be appended to the names of all generated executables.
HOSTSYSTEM=
A "<machine>-<platform>" name prefix to use for the C compiler to to
use to compile the runtime system and executables. Set this variable
if you want to compile CHICKEN for a different architecture than
the one on which you are building it.
TARGETSYSTEM=
Similar to "HOSTSYSTEM", but specifies the name
prefix to use for compiling code with the "csc" compiler
driver. This is required for creating a "cross chicken", a
specially built CHICKEN that invokes a cross C compiler to
build the final binaries. You will need a cross compiled
runtime system by building a version of CHICKEN with the
"HOST" option mentioned above. More information about this
process and the variables that you should set are provided
in the CHICKEN wiki at
<http://wiki.call-cc.org/cross-compilation>.
SRCDIR=
Specifies that CHICKEN should be built outside of its source
tree. The SRCDIR variable indicates the location of the
CHICKEN source tree. The executables and object files will
be generated in the current directory.
VARDIR=
If set, this directory overrides the location where
extensions along with their metadata are stored. Normally
this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".
When VARDIR is specified, extensions will be stored in
"<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.
CONFIG=
If you build CHICKEN often, passing all those make variables
can get annoying. An alternative is to create a configuration
file defining the required variables and passing
"CONFIG=<configfile>" to make(1).
Even simpler is editing the included "config.make"
and just invoke make(1) without any extra parameters.
C_COMPILER=
You can select an alternative compiler by setting this variable.
The default compiler is "gcc". CHICKEN can be built with the
LLVM version of gcc and with "clang", the LLVM-based C compiler,
just set C_COMPILER to "llvm-gcc" or "clang".
To remove CHICKEN from your file-system, enter (probably as
root):
make PLATFORM=<platform> PREFIX=<destination> uninstall
(If you gave DESTDIR during installation, you have to pass
the same setting to "make" when uninstalling)
In case you invoke "make" with different configuration parameters,
it is advisable to run
make PLATFORM=<platform> confclean
to remove old configuration files.
These files will be installed under the prefix given during
build and installation:
<PREFIX>
|-- bin
| |-- chicken
| |-- chicken-bug
| |-- chicken-install
| |-- chicken-profile
| |-- chicken-status
| |-- chicken-uninstall
| |-- libchicken.dll (Windows)
| |-- csc
| `-- csi
|-- include
| `-- chicken
| |-- chicken-config.h
| `-- chicken.h
|-- lib
| |-- chicken
| | `-- 6
| | |-- chicken.import.so
| | |-- csi.import.so
| | |-- data-structures.import.so
| | |-- extras.import.so
| | |-- files.import.so
| | |-- foreign.import.so
| | |-- irregex.import.so
| | |-- lolevel.import.so
| | |-- modules.db
| | |-- ports.import.so
| | |-- posix.import.so
| | |-- scheme.import.so
| | |-- setup-api.import.so
| | |-- setup-api.so
| | |-- setup-download.import.so
| | |-- setup-download.so
| | |-- srfi-1.import.so
| | |-- srfi-13.import.so
| | |-- srfi-14.import.so
| | |-- srfi-18.import.so
| | |-- srfi-4.import.so
| | |-- srfi-69.import.so
| | |-- tcp.import.so
| | |-- types.db
| | `-- utils.import.so
| |-- libchicken.a
| |-- libchicken.dll.a (Windows)
| |-- libchicken.so -> libchicken.so.6 (Unix)
| `-- libchicken.so.6 (Unix)
`-- share
|-- chicken
| |-- doc
| | |-- CHICKEN.icns (Macintosh)
| | |-- LICENSE
| | |-- README
| | |-- mac.r (Macintosh)
| | |-- manual-html
| | |-- chicken.png
| | `-- *.html
| `-- setup.defaults
`-- man
`-- man1
|-- chicken-bug.1
|-- chicken-install.1
|-- chicken-profile.1
|-- chicken-status.1
|-- chicken-uninstall.1
|-- chicken.1
|-- csc.1
`-- csi.1
3. Usage
Documentation can be found in the directory
PREFIX/share/chicken/doc in HTML format. The manual is
maintained in a wiki at http://wiki.call-cc.org. Go there to
read the most up to date documentation.
4. Extensions
A large number of extension libraries for CHICKEN are
available at http://wiki.call-cc.org/eggs. You can
automatically download, compile and install extensions with
the "chicken-install" program. See the CHICKEN User's Manual
for more information.
A selection of 3rd party libraries, together with source and
binary packages for tools helpful for development with CHICKEN
are also available at:
<http://www.call-with-current-continuation.org/tarballs/>.
5. Platform issues
FreeBSD/NetBSD/OpenBSD:
- *BSD system users *must* use GNU make ("gmake") - the makefiles
can not be processed by BSD make.
- On NetBSD it might be possible that compilation fails with a
"virtual memory exhausted error". Try the following:
% unlimit datasize
- Using external libraries on NetBSD may also be easier, if
you add the following definitions to `Makefile.bsd':
C_COMPILER_OPTIONS += -I/usr/pkg/lib
LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-R/usr/pkg/lib
Note that this may cause build-problems, if you already have
an existing CHICKEN installation in the /usr/pkg prefix.
Linux:
- Some old Linux distributions ship with a buggy version of
the GNU C compiler (2.96). If the system is configured for
kernel recompilation, then an alternative GCC version is
available under the name `kgcc' (GCC 2.96 can not recompile
the kernel). CHICKEN's configuration script should normally
be able to handle this problem, but you have to remember to
compile your translated Scheme files with `kgcc' instead of
`gcc'.
Solaris:
- By default, CHICKEN is build with the GNU C compiler (`gcc').
To use the SunPro C compiler (`cc') instead, pass
C_COMPILER=cc
to the "make" invocation.
- Older versions of Solaris have a bug in ld.so that causes
trouble with dynamic loading. Patching Solaris fixes the
problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
equivalent patch, 109147-16.
You can find out if you have these patches installed by
running:
% showrev -p | grep 106950 # solaris 7
% showrev -p | grep 109147 # solaris 8
Mac OS X:
- On 10.6 and 10.7, Chicken may incorrectly select a 32-bit build
environment when it should be building 64-bit, resulting in a
build error. This occurs when you have a 32-bit kernel and a
64-bit gcc (that is, on Core 2 Duo systems running 10.6 Desktop).
If this bites you, you'll get the following error or similar:
apply-hack.x86.S:35:suffix or operands invalid for `call'
As a workaround, manually force the build into 64-bit mode:
make PLATFORM=macosx ARCH=x86-64
- Chicken will normally select a 32-bit or 64-bit build
automatically when you use the normal build step:
make PLATFORM=macosx
Specifically, the defaults are:
10.4: 32-bit
10.5: 32-bit
10.6: 64-bit (32-bit on original Core Duo, circa early 2006)
10.7: 64-bit
On 10.5, you can optionally build in 64-bit mode on machines
released in late 2006 or later (i.e. with a Core 2 Duo or Xeon
CPU), by specifying ARCH=x86-64:
make PLATFORM=macosx ARCH=x86-64
- Universal binaries: On 10.4 and 10.5 only, Chicken and its eggs
can be built as universal binaries which will work on either
Intel or PowerPC. Most users will not want to do this.
For 10.4 universal build:
make PLATFORM=macosx ARCH=universal
For 10.5 universal build:
export MACOSX_DEPLOYMENT_TARGET=10.4
make C_COMPILER=gcc-4.0 PLATFORM=macosx ARCH=universal
For 10.6 and later, universal builds are not supported.
- On 10.3 and earlier, you must first install `dlcompat'
which can be found at http://distfiles.macports.org/dlcompat/.
Windows:
- On Windows, mingw32, <http://mingw.sourceforge.net/> and
Cygwin are supported (Microsoft Visual Studio is *NOT*).
Makefiles for mingw under MSYS and the Windows shell are
provided (`Makefile.mingw-msys' and `Makefile.mingw').
Please also read the notes below.
- When installing under the mingw-msys platform, PREFIX must be an
absolute path name (i.e. it must include the drive letter) and
must use forward slashes (no backward slashes).
- When installing under mingw, with a windows shell
("cmd.exe"), pass an absolute pathname (including the
drive letter) as PREFIX and use forward slashes.
- When installing under mingw without MSYS, make sure that the
MSYS tools (in case you have some of them, in particular the
sh.exe UNIX shell) are *NOT* visible in your PATH.
- Cygwin will not be able to find the chicken shared libraries
until Windows is rebooted.
- gcc 3.4 shows sometimes warnings of the form
easyffi.c: In function `f_11735':
easyffi.c:18697: warning: `noreturn' function does return
when compiling the system or compiled Scheme files. These
warnings are bogus and can be ignored.
6. Bootstrapping
To build a bootstrapping compiler yourself, obtain a recent
release tarball, unpack it, change into the extracted
directory and enter
make PLATFORM=<platform> CHICKEN=<path-to-existing-chicken> \
boot-chicken
This will produce a statically linked binary with the name
"chicken-boot[.exe]" that can be given as the value of the
"CHICKEN" argument when invoking make(1). Note that the path
to an existing `chicken' binary must be given to use it for
compiling the Scheme code of the runtime-system and compiler.
7. Emacs support
See http://wiki.call-cc.org/emacs for tips and links to emacs
extensions for Scheme and CHICKEN programming.
8. Compatibility notes
In CHICKEN 4, the macro system has been reimplemented
completely and provides module system, which has considerably
more flexibility and power, but will require the
re-implementation of macros in code that previously was used
with CHICKEN 3. Notably, `define-macro' is not available
anymore. See the manual on how to translate such macros to
low-level hygienic macros or ask on the CHICKEN mailing list.
9. What's next?
If you find any bugs, or want to report a problem, please consider
using the "chicken-bug" tool to create a detailed bug report.
If you have any more questions or problems (even the slightest
problems, or the most stupid questions), then please subscribe
to the "chicken-users"
(http://lists.nongnu.org/mailman/listinfo/chicken-users)
mailing list and ask for help. It will be answered.