-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
689 lines (517 loc) · 25.9 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
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
README file for the CHICKEN Scheme system
=========================================
(c) 2008-2015, The CHICKEN Team
(c) 2000-2007, Felix L. Winkelmann
version 4.9.1
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://code.call-cc.org/legacy-eggs/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.
2.1. Building from a release tarball
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 invoke "make" later with different configuration parameters,
it is advisable to run:
make PLATFORM=<platform> confclean
to remove old configuration files.
2.2. Building from git
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 are building in a checkout where you have built other
versions of chicken, you need to make sure that all traces of
the previous build are removed. "make clean" is insufficient,
and you should do the following:
make PLATFORM=<platform> spotless
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 "chicken".
If you do not have a "chicken" binary installed, you will have
to build from the closest release tarball to the git version
you are trying to build (significantly older or newer ones are
unlikely to work), and then use that chicken to build from
your git sources. You don't need to install the release
tarball chicken; simply unpack and build it in its own
directory with "make PLATFORM=<platform>", then use it to
build your git chicken like so:
LD_LIBRARY_PATH=<release dir> make PLATFORM=<platform> \
CHICKEN=<release dir>/chicken
The LD_LIBRARY_PATH is needed on Linux to allow chicken to
find libchicken; it may or may not be needed on your platform,
but probably won't do any harm.
2.3. Finishing the installation
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.
2.4. Verifying your installation is correct
You can check whether CHICKEN is functioning correctly by
running
make <vars> check
where <vars> are all the variables you used while building
CHICKEN.
This will run the test scripts, which show a lot of output.
The only thing that matters is the exit status at the end.
If it exits with status 0, everything is fine, if it exits
with a nonzero status, the failing test's output should be
the final lines before Make's "error; exit" output. If the
check fails on unmodified sources, please file a bugreport.
Currently "make check" only works if you have installed
CHICKEN.
2.5. Optional features
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 manual (see the "Cross development" chapter).
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".
LINKER=
Selects the linker to be used for creating executables and
dynamic libraries from compiled C code. This should normally
be the same as C_COMPILER.
PROFILE_OBJECTS=
This variable allows you to profile (parts of) CHICKEN itself.
Just pass in a whitespace-separated list of objects, without
the .scm-extension. (An "object" here is an individual
.scm-file which gets compiled to a .c-file)
To build with profiling support, run "make spotless" first.
Be warned that this is a highly experimental option and
profiling doesn't work for every component of CHICKEN.
2.6. Uninstalling CHICKEN
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)
2.7. What gets installed
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
| | `-- 7
| | |-- 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
| | |-- 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.dylib (Macintosh)
| |-- libchicken.so -> libchicken.so.6 (Unix)
| `-- libchicken.so.6 (Unix)
`-- share
|-- chicken
| |-- doc
| | |-- LICENSE
| | |-- README
| | |-- mac.r (Macintosh)
| | |-- CHICKEN.icns (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://code.call-cc.org/legacy-eggs/tarballs/>.
5. Platform issues
Android:
- The Android SDK and NDK are required. Make sure you have
set up a project and have a suitable NDK toolchain
available. You will have to override the make(1) variable
C_COMPILER to contain the correct compiler; see
docs/STANDALONE-TOOLCHAIN.html in your NDK root for notes
on how to call the correct compiler. You will also need to
override the ARCH variable to match the device you're
targeting. The build will produce a libchicken.so that
can then be integrated into your project as a prebuilt
shared library. See the android section on
http://wiki.call-cc.org/embedding for a complete example.
- It is possible to use eggs, by copying them into the right
place and probably renaming the files. This is somewhat
awkward and requires various hacks to make the
loading/linking of eggs work. It may be easier to build
the eggs you need manually and linking them statically to
your executable.
- By default debug-logging is enabled and written to the
Android log.
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
- When using -deploy on NetBSD, currently the kernel only
supports running the program through its absolute path,
otherwise you will get an error message stating:
execname not specified in AUX vector: No such file or directory
Deployed binaries can also be run without an explicit path,
through $PATH; only relative pathnames do not work.
- 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'.
- There have been reports where the library directory
"/usr/lib64" could not be found at build-time on a Fedora
12 system. If you build a 64-bit version of CHICKEN and
the library directory is set incorrectly, you can override
it by passing "LIBDIR=/usr/lib64" as an additional
argument when you invoke "make".
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:
- The build currently assumes the Xcode application path is
"/Applications/Xcode.app/", with the C compiler and build
tools being located in the "Contents/Developer/usr/bin"
and
"Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin"
subdirectories, respectively. To override these locations,
set XCODE_DEVELOPER and XCODE_TOOL_PATH on the make(3)
command line.
- 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/.
iOS:
- Make sure the "XCODE_PATH" setting is correct (see
Makefile.ios), it defaults to "/Applications/Xcode.app".
- The paths for the the various build tools changed between
Xcode 4 and 5. The makefile used for iOS builds of CHICKEN
assume Xcode 5 is used. If you are using Xcode 4, override
the XCODE_TOOLPATH and C_COMPILER make-variables providing
the correct paths, see Makefile.ios for suggestions.
- The iOS build is static (iOS doesn't support dynamic
loading of executable code). Only the runtime library
(libchicken.a) is of interest. To use it, integrate
libchicken.a in your Xcode project and use a normal MacOS
build to compile your Scheme sources into C files, adding
them to you project.
- Core library units must by accessed via "(declare (uses
...))" and "(import ...)", "require", "require-library",
"require-extension" and "use" will not work, due to the
reasons mentioned above.
- As dynamic loading is not supported, eggs can not be used
as usual, you will have to compile them manually and
integrate what you need into your project.
- If you want to build for the iPhone Simulator, override
the ARCH and XCODE_SDK variables accordingly, see also in
Makefile.ios for suggestions.
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. If you
are building the sources from git, use backslashes to
specify the path to `chicken' (the "CHICKEN" variable).
- 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.
- 64-bit Windows is supported, invoke mingw32-make with the
"ARCH=x86-64" argument (this is currently not detected
automatically). The build has been tested on Windows 7
with the SJLJ binary package from "MinGW-builds", which
can be found here:
http://sourceforge.net/projects/mingwbuilds/
- Cygwin will not be able to find the chicken shared libraries
until Windows is rebooted.
- During "make check" you may see these intermittent errors:
ld.exe: cannot open output file a.out: Permission denied
When this happens, the virusscanner is holding open
the file of the previous test while the compiler is
preparing the next test.
To work around this in Windows Defender (the default),
disable "realtime protection" under tools->options.
- 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.
AIX:
- CHICKEN is built with the GNU C compiler (`gcc'). IBM's XL
C compiler is not supported at this time.
- AIX users *must* use GNU make ("gmake") - the makefiles can not be
processed with IBM's version of make.
- Deployment doesn't work. See manual/Deployment for more details.
- The AIX linker may occasionally show warnings of the form:
ld: 0711-783 WARNING: TOC overflow. TOC size: 66656
Maximum size: 65536
Extra instructions are being generated for each reference to a TOC
symbol if the symbol is in the TOC overflow area.
Such messages indicate that lookups for some symbols in the
effected library/executable may be somewhat slower at runtime as an
auxiliary symbol table is needed to accommodate all of the symbols.
- The AIX assembler may show warnings of the form:
/tmp//ccycPGzK.s: line 527244: 1252-171 The displacement must be
greater than or equal to -32768 and less than or equal to 32767.
This is a known issue between the GNU toolchain and IBM's assembler:
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=4587
The problem arises because the PPC architecture cannot perform jumps
to addresses that differ more than what a 16-bit integer can
represent. Adding support for IBM's XL C compiler may resolve this
issue.
Instructing gcc to optimize the size of generated code (-Os)
mitigates this to some degree, but very large C files may still be
uncompilable. This is known to affect the html-tags egg.
Haiku:
- The default GCC compiler is too old to support the -fwrapv
option. You can either remove the flag from Makefile.haiku,
use a newer GCC, or supply your own C_COMPILER_OPTIONS on
the Make command line.
- The default Haiku BFS file system only supports timestamps
with a granularity of one second. This may cause trouble
with pregenerated release or development snapshot tarballs
due to the way files are pre-translated to C. You'll either
need to have CHICKEN installed, or touch the
build-version.c file before building.
6. Bootstrapping
To build a bootstrapping compiler yourself, get the most
recent release tarball from http://code.call-cc.org, unpack
it, build and install it. Then change to the directory
containing the git code and run:
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.