~ chicken-core (chicken-5) 2e85368d4635f9a61a97fdc62b9d0cafa07ffa80
commit 2e85368d4635f9a61a97fdc62b9d0cafa07ffa80
Author: Peter Bex <peter.bex@xs4all.nl>
AuthorDate: Sun Feb 16 11:50:24 2014 +0100
Commit: Peter Bex <peter.bex@xs4all.nl>
CommitDate: Sun Feb 16 11:50:24 2014 +0100
Update manual with changes from the wiki
diff --git a/manual/Accessing external objects b/manual/Accessing external objects
index 8c304e33..dcc95887 100644
--- a/manual/Accessing external objects
+++ b/manual/Accessing external objects
@@ -183,6 +183,8 @@ where {{N}} is the number of values to be returned, and {{X1, ...}} are the
results, which should be Scheme data objects. When returning multiple values, the
return-type should be omitted.
+Returning just a single value can still be done via the {{C_return(...)}} macro.
+
== Returning large objects or chunks of memory to Scheme
When you call a C function which needs to return quantities of data, several issues arise:
diff --git a/manual/Acknowledgements b/manual/Acknowledgements
index 6a7e71d2..cbf9d5f3 100644
--- a/manual/Acknowledgements
+++ b/manual/Acknowledgements
@@ -11,48 +11,49 @@ Brannon, Roy Bryant, Adam Buchbinder, Hans Bulfone, "Category 5",
Taylor Campbell, Naruto Canada, Mark Carter, Esteban U. Caamano
Castro, Semih Cemiloglu, Franklin Chen, Joo ChurlSoo, Thomas Chust,
Gian Paolo Ciceri, Fulvio Ciriaco, Paul Colby, Tobia Conforto, John
-Cowan, Grzegorz Chrupala, James Crippen, Evan Hanson, Tollef Fog Heen,
-Drew Hess, Alejandro Forero Cuervo, Peter Danenberg, Linh Dang, Brian
-Denheyer, Sean D'Epagnier, "dgym", "Don", Chris Double, "Brown
-Dragon", David Dreisigmeyer, Jarod Eells, Petter Egesund, Stephen
-Eilert, Steve Elkins, Daniel B. Faken, Erik Falor, Will Farr, Graham
-Fawcett, Marc Feeley, "Fizzie", Matthew Flatt, Kimura Fuyuki, Tony
-Garnock-Jones, Martin Gasbichler, Abdulaziz Ghuloum, Joey Gibson,
-Stephen C. Gilardi, Mario Domenech Goulart, Joshua Griffith, Johannes
-Groedem, Damian Gryski, Matt Gushee, Andreas Gustafsson, Sven
-Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo, Matthias Heiler, Karl
-M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans
-Hübner, Markus Hülsmann, Götz Isenmann, Paulo Jabardo, Wietse Jacobs,
-David Janssens, Christian Jäger, Matt Jones, Dale Jordan, Valentin
-Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel,
-Matthias Köppe, Krysztof Kowalczyk, Andre Kühne, Todd R. Kueny Sr,
-Goran Krampe, David Krentzlin, Ben Kurtz, Michele La Monaca, Micky
-Latowicki, Kristian Lein-Mathisen, John Lenz, Kirill Lisovsky, Jürgen
-Lorenz, Kon Lovett, Lam Luu, Vitaly Magerya, Leonardo Valeri Manera,
-Claude Marinier, Dennis Marti, Charles Martin, Bob McIsaac, "megane",
-Alain Mellan, Eric Merrit, Perry Metzger, Scott G. Miller, Mikael,
-Karel Miklav, Bruce Mitchener, Fadi Moukayed, Chris Moline, Eric
-E. Moore, Julian Morrison, Dan Muresan, David N. Murray, Timo Myyrä,
-"nicktick", Lars Nilsson, Ian Oversby, "o.t.", Gene Pavlovsky, Levi
-Pearson, Jeronimo Pellegrini, Nicolas Pelletier, Derrell Piper, Carlos
-Pita, Robin Lee Powell, Alan Post, "Pupeno", Davide Puricelli,
-"presto", Doug Quale, Imran Rafique, Eric Raible, Ivan Raikov, Santosh
-Rajan, Joel Reymont, "rivo", Chris Roberts, Eric Rochester, Paul
-Romanchenko, Andreas Rottman, David Rush, Lars Rustemeier, Daniel
-Sadilek, Otavio Salvador, Burton Samograd, "Sandro", "satori", Aleksej
-Saushev, Oskar Schirmer, Reed Sheridan, Ronald Schröder, Spencer
-Schumann, Ivan Shcheklein, Alex Shinn, Ivan Shmakov, "Shmul", Tony
-Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato,
-Iruata Souza, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels,
-Jason Songhurst, Clifford Stein, David Steiner, Sunnan, Zbigniew
-Szadkowski, Rick Taube, Nathan Thern, Mike Thomas, Minh Thu, Christian
-Tismer, Andre van Tonder, John Tobey, Henrik Tramberend, Vladimir
-Tsichevsky, Neil van Dyke, Sam Varner, Taylor Venable, Sander Vesik,
-Jaques Vidrine, Panagiotis Vossos, Shawn Wagner, Peter Wang, Ed
-Watkeys, Brad Watson, Thomas Weidner, Göran Weinholt, Matthew Welland,
-Drake Wilson, Jörg Wittenberger, Peter Wright, Mark Wutka, Adam Young,
-Richard Zidlicky, Houman Zolfaghari and Florian Zumbiehl for
-bug-fixes, tips and suggestions.
+Cowan, Grzegorz Chrupala, James Crippen, Evan Hanson, Adhi Hargo,
+Moritz Heidkamp, Tollef Fog Heen, Drew Hess, Alejandro Forero Cuervo,
+Peter Danenberg, Linh Dang, Brian Denheyer, Sean D'Epagnier, "dgym",
+"Don", Chris Double, "Brown Dragon", David Dreisigmeyer, Jarod Eells,
+Petter Egesund, Stephen Eilert, Steve Elkins, Daniel B. Faken, Erik
+Falor, Will Farr, Graham Fawcett, Marc Feeley, "Fizzie", Matthew
+Flatt, Kimura Fuyuki, Tony Garnock-Jones, Martin Gasbichler, Abdulaziz
+Ghuloum, Joey Gibson, Stephen C. Gilardi, Mario Domenech Goulart,
+Joshua Griffith, Johannes Groedem, Damian Gryski, Matt Gushee, Andreas
+Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo,
+Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman,
+Bruce Hoult, Hans Hübner, Markus Hülsmann, Götz Isenmann, Paulo
+Jabardo, Wietse Jacobs, David Janssens, Christian Jäger, Matt Jones,
+Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller, Christian
+Kellermann, Brad Kind, Ron Kneusel, Matthias Köppe, Krysztof
+Kowalczyk, Andre Kühne, Todd R. Kueny Sr, Goran Krampe, David
+Krentzlin, Ben Kurtz, Michele La Monaca, Micky Latowicki, Kristian
+Lein-Mathisen, John Lenz, Kirill Lisovsky, Jürgen Lorenz, Kon Lovett,
+Lam Luu, Vitaly Magerya, Leonardo Valeri Manera, Claude Marinier,
+Dennis Marti, Charles Martin, Bob McIsaac, "megane", Alain Mellan,
+Eric Merrit, Perry Metzger, Scott G. Miller, Mikael, Karel Miklav,
+Bruce Mitchener, Fadi Moukayed, Chris Moline, Eric E. Moore, Julian
+Morrison, Dan Muresan, David N. Murray, Timo Myyrä, "nicktick", Lars
+Nilsson, Ian Oversby, "o.t.", Gene Pavlovsky, Levi Pearson, Jeronimo
+Pellegrini, Nicolas Pelletier, Derrell Piper, Carlos Pita, Robin Lee
+Powell, Alan Post, "Pupeno", Davide Puricelli, "presto", Doug Quale,
+Imran Rafique, Eric Raible, Ivan Raikov, Santosh Rajan, Joel Reymont,
+"rivo", Chris Roberts, Eric Rochester, Paul Romanchenko, Andreas
+Rottman, David Rush, Lars Rustemeier, Daniel Sadilek, Otavio Salvador,
+Burton Samograd, "Sandro", "satori", Aleksej Saushev, Oskar Schirmer,
+Reed Sheridan, Ronald Schröder, Spencer Schumann, Ivan Shcheklein,
+Alex Shinn, Ivan Shmakov, "Shmul", Tony Sidaway, Jeffrey B. Siegal,
+Andrey Sidorenko, Michele Simionato, Iruata Souza, Volker Stolz, Jon
+Strait, Dorai Sitaram, Robert Skeels, Jason Songhurst, Clifford Stein,
+David Steiner, Sunnan, Zbigniew Szadkowski, Rick Taube, Nathan Thern,
+Mike Thomas, Minh Thu, Christian Tismer, Andre van Tonder, John Tobey,
+Henrik Tramberend, Vladimir Tsichevsky, James Ursetto, Neil van Dyke,
+Sam Varner, Taylor Venable, Sander Vesik, Jaques Vidrine, Panagiotis
+Vossos, Shawn Wagner, Peter Wang, Ed Watkeys, Brad Watson, Thomas
+Weidner, Göran Weinholt, Matthew Welland, Drake Wilson, Jörg
+Wittenberger, Peter Wright, Mark Wutka, Adam Young, Richard Zidlicky,
+Houman Zolfaghari and Florian Zumbiehl for bug-fixes, tips and
+suggestions.
Special thanks to Brandon van Every for contributing the (now defunct)
[[http://www.cmake.org|CMake]] support and for helping with Windows
diff --git a/manual/C interface b/manual/C interface
index 821f0541..c1605824 100644
--- a/manual/C interface
+++ b/manual/C interface
@@ -486,6 +486,8 @@ and can also be simulated by declaring a stack-allocated array of
[C macro] int C_SIZEOF_VECTOR (int length)
+Returns the size in words needed for allocation of vector with ''length'' elements.
+
===== C_SIZEOF_INTERNED_SYMBOL
[C macro] int C_SIZEOF_INTERNED_SYMBOL (int length)
diff --git a/manual/Cross development b/manual/Cross development
index 38a73154..9ce32dbc 100644
--- a/manual/Cross development
+++ b/manual/Cross development
@@ -37,15 +37,12 @@ repository, then build the libraries and necessary development files:
HOSTSYSTEM=arm-none-linux-gnueabi \
DESTDIR=$HOME/target \
TARGET_FEATURES="-no-feature x86 -feature arm" \
- libs install-dev
-
-This will build the CHICKEN libraries and install them in {{~/target}},
-which we use as a temporary place to store the target files. A few things
-to note:
+ install
-* {{ARCH}} is empty, since we don't want the build process to detect the
-architecture (since the target-architecture is likely to be different).
+This will build CHICKEN and install it in {{~/target}}, which we use
+as a temporary place to store the target files. A few things to note:
+* {{ARCH}} is empty, since we don't want the build process to detect the architecture (since the target-architecture is likely to be different) and there is no {{apply-hack.<ARCH>.S}} file corresponding to arm at the moment. If you know the right string to represent target architecture (see {{C_PLATFORM_TYPE}} in {{chicken.h}} for the supported options), you can set {{ARCH}} with that value. Notice, however, that the apply-hack is not supported for all those architectures (at the moment, only for {{ppc.darwin}}, {{ppc.sysv}}, {{x86}} and {{x86-64}}).
* {{PREFIX}} gives the prefix ''on the target system'', under which the
libraries will finally be installed. In this case it will be {{/usr/lib}}.
@@ -59,7 +56,7 @@ If your cross compiler does not follow this convention, pass {{C_COMPILER}} and
{{ar(1)}} tool, respectively.
* {{DESTDIR}} holds the directory where the compiled library files will temporarily
-installeds into.
+be installed into.
* {{TARGET_FEATURES}} contains extra options to be passed to the target-specific
Scheme translator; in this case we disable and enable features so that code like
@@ -75,24 +72,42 @@ the following will do the right thing when cross-compiled:
from an official release tarball, you will need a {{chicken}}
executable to compile the Scheme sources of the runtime system. In
this case pass yet another variable to the {{make(1)}} invocation:
-{{CHICKEN=<where the "chicken" executable is}}.
+{{CHICKEN=<where the "chicken" executable is>}}.
* You can also put all those variables into a file, say {{config.mk}}
and run {{make CONFIG=config.mk}}.
You should now have these files on {{~/target}}:
- `-- usr
- |-- include
- | |-- chicken-config.h
- | `-- chicken.h
- |-- lib
- | |-- chicken
- | | `-- 6
- | | `-- types.db
- | |-- libchicken.a
- | `-- libchicken.so
- `-- share
+ |-- bin
+ | |-- chicken
+ | |-- chicken-bug
+ | |-- chicken-install
+ | |-- chicken-profile
+ | |-- chicken-status
+ | |-- chicken-uninstall
+ | |-- csc
+ | `-- csi
+ |-- include
+ | |-- chicken-config.h
+ | `-- chicken.h
+ |-- lib
+ | |-- chicken
+ | | `-- 6
+ | | :
+ | |
+ | |-- libchicken.a
+ | |-- libchicken.so -> libchicken.so.6
+ | `-- libchicken.so.6
+ `-- share
+ |-- chicken
+ | |-- doc
+ : ; :
+ | |
+ | `-- setup.defaults
+ `-- man
+ `-- man1
+ :
You should now transfer {{libchicken.so}} to the target system, and place
it in {{/usr}}.
diff --git a/manual/Data representation b/manual/Data representation
index 3a6ba788..610546aa 100644
--- a/manual/Data representation
+++ b/manual/Data representation
@@ -43,9 +43,9 @@ The first word of the data block contains a header, which gives
information about the type of the object. The header is a
single machine word.
-The 24 lowest-order bits contain the length of the data object, which is either
-the number of bytes in a string or byte-vector, or the the number
-of elements for a vector or record type.
+The 24 lowest-order bits contain the length of the data object, which
+is either the number of bytes in a string or byte-vector, or the
+number of elements for a vector or record type.
The remaining bits are placed in the high-order end of the header.
The four highest-order bits are used for garbage
@@ -69,7 +69,7 @@ of the symbol.
'''strings''': byte-vector objects with type bits {{C_STRING_TYPE}}, currently 0010.
-'''pairs''': vector-like object with type bits {{C_PAIR_TYPE}}, currently 0011).
+'''pairs''': vector-like object with type bits {{C_PAIR_TYPE}}, currently 0011.
The car and the cdr are contained in the first and second slots,
respectively.
@@ -81,7 +81,7 @@ a flat closure representation is used).
'''flonums''': byte-vector objects with type bits
{{C_FLONUM_BITS}}, currently 0101. Slots one and two (or a single slot on
64 bit architectures) contain a 64-bit floating-point number, in the
-representation used by the host systems C compiler.
+representation used by the host system's C compiler.
'''ports''': special vector objects with type bits
{{C_PORT_TYPE}}, currently 0111. The first slot contains a pointer to a file-
diff --git a/manual/Deployment b/manual/Deployment
index fd3c88c2..4ee51115 100644
--- a/manual/Deployment
+++ b/manual/Deployment
@@ -177,14 +177,9 @@ linker will only load libraries from paths hardcoded at link time.
=== Deploying source code
An alternative to deploying binaries is deployment as compiled
-C sources. Usually, you just need to ship your application code,
-compiled to {{.c}} files and the {{chicken.h}} and {{runtime.c}}
-files from the CHICKEN sources. You will also need the {{.c}} files
-of any library units your program uses (at least {{library.c}} and
-{{build-version.c}}). Compiling everything and
-linking it together should work on most systems. Consult the
-CHICKEN makefiles for more information about optimization options,
-etc.
+C sources.
+
+See the corresponding section in [[Using the compiler]].
---
diff --git a/manual/Deviations from the standard b/manual/Deviations from the standard
index cd463164..3be8e714 100644
--- a/manual/Deviations from the standard
+++ b/manual/Deviations from the standard
@@ -108,7 +108,7 @@ the standard procedure {{number?}}. The procedures {{make-rectangular}}
and {{make-polar}} are not implemented. Fixnums are limited to
2^<nowiki><sup>30</sup></nowiki> (or 2^<nowiki><sup>62</sup></nowiki>
on 64-bit hardware). Support for the full numeric tower is available
-as a separate package.
+as a separate package (see the {{numbers}} package).
=== {{transcript-on}} and {{transcript-off}} are not implemented
diff --git a/manual/Extensions b/manual/Extensions
index 5e612c09..25dbd0bb 100644
--- a/manual/Extensions
+++ b/manual/Extensions
@@ -82,7 +82,7 @@ and put the extension code in it.
Extensions need two special files: an {{<extension name>.setup}}
file and an {{<extension name>.meta}} file (where {{<extension
name>}} is the name of your extension). The former indicates how
-the egg is to be copiled and the latter provides some information
+the egg is to be compiled and the latter provides some information
about the extension (author, license, dependencies etc). See the
[[/eggs tutorial|eggs tutorial]] for further information about
how to create extensions.
@@ -446,8 +446,7 @@ program to remove one or more extensions from the local repository:
The hello module was just a shared library, and not a module.
To create an extension that exports syntax see the chapter on
-[[http://wiki.call-cc.org/man/4/Modules%20and%20macros|Modules and
-macros]]. We will show a simple example here: a module {{my-lib}}
+[[Modules]]. We will show a simple example here: a module {{my-lib}}
that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):
<enscript highlight=scheme>
@@ -499,7 +498,7 @@ The setup file is:
(install-extension
'my-lib
- '("my-lib.o" "my-lib.so" "my-lib.import.so")
+ '("my-lib.so" "my-lib.import.so")
'((version 1.0)))
</enscript>
diff --git a/manual/Foreign type specifiers b/manual/Foreign type specifiers
index 090a1013..19351be9 100644
--- a/manual/Foreign type specifiers
+++ b/manual/Foreign type specifiers
@@ -115,6 +115,10 @@ maximum range of a fixnum. (Numbers between 2^62 and 2^64-1 have gaps.)
Either a fixnum or a flonum in the range of an (unsigned) machine ''long''.
Similar to {{integer32}} on 32-bit systems or {{integer64}} on 64-bit.
+<type>size_t</type>
+
+A direct mapping to C's {{size_t}}.
+
=== Floating-point
<type>float</type><br>
@@ -357,6 +361,7 @@ The foreign type {{TYPE}} with an additional {{const}} qualifier.
<tr><td>{{[unsigned-]integer32}}</td><td>{{[unsigned] int32_t}}</td></tr>
<tr><td>{{[unsigned-]integer64}}</td><td>{{[unsigned] int64_t}}</td></tr>
<tr><td>{{[unsigned-]long}}</td><td>{{[unsigned] long}}</td></tr>
+<tr><td>{{size_t}}</td><td>{{size_t}}</td></tr>
<tr><td>{{float}}</td><td>{{float}}</td></tr>
<tr><td>{{double}}</td><td>{{double}}</td></tr>
<tr><td>{{number}}</td><td>{{double}}</td></tr>
diff --git a/manual/Getting started b/manual/Getting started
index 157ac01a..00bd8c22 100644
--- a/manual/Getting started
+++ b/manual/Getting started
@@ -188,7 +188,7 @@ can pretty much ignore the C compiler once you have installed it.)
* On Macintosh OS X, you will need the XCode tools, which are shipped
on the OS X DVD with recent versions of the operating system.
* On Windows, you have three choices.
-** Cygwin ([[http://sources.redhat.com/cygwin]]) provides a relatively
+** Cygwin ([[http://sourceware.org/cygwin/]]) provides a relatively
full-featured Unix environment for Windows. CHICKEN works
substantially the same in Cygwin and Unix.
** The GNU Compiler Collection has been ported to Windows, in the
@@ -210,7 +210,7 @@ Refer to the {{README}} file for the version you're installing for
more information on the installation process.
Alternatively, third party packages in binary format are available.
-Se [[http://wiki.call-cc.org/platforms]] for information about how to
+See [[http://wiki.call-cc.org/platforms]] for information about how to
obtain them.
=== Development environments
@@ -273,9 +273,8 @@ including proportional fonts.
editor built to enable efficient and fast text editing. It is an
improved version of the vi editor distributed with most UNIX
systems. Vim comes with generic Lisp (and therefore Scheme) editing
-capabilities out of the
-box. A few tips on using Vim with CHICKEN can be found at
-[[http://cybertiggyr.com/gene/15-vim/]].
+capabilities out of the box. See [[http://wiki.call-cc.org/Vim]]
+for a few tips on using Vim with CHICKEN.
In the rest of this chapter, we'll assume that you are using an editor
of your choice and a regular terminal window for executing your
diff --git a/manual/Locations b/manual/Locations
index 5954638b..0ac54caa 100644
--- a/manual/Locations
+++ b/manual/Locations
@@ -71,7 +71,7 @@ returns more than one result value:
(print "i=" i ", f=" f) ) )
</enscript>
-See [[http://wiki.call-cc.org/location-and-c-string-star|location and c-string*]]
+See [[/location-and-c-string-star|location and c-string*]]
for a tip on returning a {{c-string*}} type.
{{location}} returns a value of type {{c-pointer}}, when given
diff --git a/manual/Modules b/manual/Modules
index f8a40a65..38bad00c 100644
--- a/manual/Modules
+++ b/manual/Modules
@@ -343,6 +343,14 @@ and used in an identical manner:
#;3> (greet "you")
Hello, you !
+If you are depending on external libraries inside your module, follow the general rule of {{(import chicken scheme) (use anything-else)}} like so:
+
+ (module test (hello greet)
+ (import chicken scheme)
+ (use posix)
+ (use srfi-4)
+ ...)
+
If you want to keep macro-definitions in a separate file, use import
libraries:
@@ -370,9 +378,9 @@ load it manually:
#;1> (import test)
#;2>
-Note that you must us import libraries if you compile code
+Note that you must use import libraries if you compile code
that depends on other modules. The compiler will not execute
-the modules that are refered to by compiled code, and thus
+the modules that are referred to by compiled code, and thus
the binding information and exported syntax of the former
must be available separately.
diff --git a/manual/Non-standard macros and special forms b/manual/Non-standard macros and special forms
index 23f69dd9..087c1f10 100644
--- a/manual/Non-standard macros and special forms
+++ b/manual/Non-standard macros and special forms
@@ -260,6 +260,7 @@ expression that evaluates to a parameter procedure.
<macro>(receive (NAME ...) VALUEEXP BODY ...)</macro><br>
<macro>(receive (NAME1 ... NAMEn . NAMEn+1) VALUEEXP BODY ...)</macro><br>
+<macro>(receive NAME VALUEEXP BODY ...)</macro><br>
<macro>(receive VALUEEXP)</macro>
[[http://srfi.schemers.org/srfi-8/srfi-8.html|SRFI-8]].
@@ -267,6 +268,7 @@ Syntactic sugar for {{call-with-values}}. Binds variables
to the result values of {{VALUEEXP}} and evaluates {{BODY ...}}.
{{(receive VALUEEXP)}} is equivalent to {{(receive _ VALUEEXP _)}}.
+This shortened form is not described by SRFI-8.
==== set!-values
diff --git a/manual/Non-standard read syntax b/manual/Non-standard read syntax
index 6fd2e97a..04707b99 100644
--- a/manual/Non-standard read syntax
+++ b/manual/Non-standard read syntax
@@ -88,7 +88,7 @@ is equivalent to
=== Multiline String Constant with Embedded Expressions
-<read>#<</read>
+<read>#<#</read>
#<#TAG
@@ -118,31 +118,25 @@ Abbreviation for {{(foreign-declare " ... ")}}.
=== String escape sequences
-String-literals may contain the following of the escape sequences:
+String-literals may contain the following escape sequences:
-<table>
+<table style="margin-top: 1em; max-width: 40em">
<tr><th>Escape sequence</th><th>Character</th></tr>
-<tr><td>\n</td><td>line feed / newline</td></tr>
-<tr><td>\t</td><td>tab</td></tr>
-<tr><td>\r</td><td>carriage return</td></tr>
-<tr><td>\b</td><td>backspace</td></tr>
-<tr><td>\a</td><td>bell</td></tr>
-<tr><td>\v</td><td>vertical tab</td></tr>
-<tr><td>\f</td><td>form feed</td></tr>
-<tr><td>\xXX</td><td>hexadecimal 8-bit character</td></tr>
-<tr><td>\uXXXX</td><td>hexadecimal 16-bit UNICODE character</td></tr>
-<tr><td>\UXXXXXXXX</td><td>hexadecimal 32-bit UNICODE character</td></tr>
-<tr><td>\OOO</td><td>octal 8-bit character</td></tr>
-<tr><td>\| \" \\ \'</td><td>represents escaped character</td></tr>
+<tr><td>{{\n}}</td><td>line feed / newline</td></tr>
+<tr><td>{{\t}}</td><td>tab</td></tr>
+<tr><td>{{\r}}</td><td>carriage return</td></tr>
+<tr><td>{{\b}}</td><td>backspace</td></tr>
+<tr><td>{{\a}}</td><td>bell</td></tr>
+<tr><td>{{\v}}</td><td>vertical tab</td></tr>
+<tr><td>{{\f}}</td><td>form feed</td></tr>
+<tr><td>{{\x}}''XX''</td><td>hexadecimal 8-bit character code</td></tr>
+<tr><td>{{\u}}''XXXX''</td><td>hexadecimal 16-bit Unicode character code</td></tr>
+<tr><td>{{\U}}''XXXXXXXX''</td><td>hexadecimal 32-bit Unicode character code</td></tr>
+<tr><td>{{\}}''OOO''</td><td>octal 8-bit character code</td></tr>
+<tr><td>{{\|}} {{\"}} {{\\}} {{\'}}</td><td>the escaped character</td></tr>
</table>
-=== Foreign Declare
-
- #> ... <#
-
-Abbreviation for {{foreign-declare " ... ")}}.
-
=== Sharp Prefixed Symbol
<read>#%</read>
diff --git a/manual/Unit data-structures b/manual/Unit data-structures
index c64432e1..803db577 100644
--- a/manual/Unit data-structures
+++ b/manual/Unit data-structures
@@ -266,7 +266,6 @@ for equality.
Time complexity: O (|V| + |E|)
<enscript highlight=scheme>
-(require 'tsort)
(topological-sort
'((shirt tie belt)
(tie jacket)
diff --git a/manual/Unit library b/manual/Unit library
index 1efb5bdf..936ec8e9 100644
--- a/manual/Unit library
+++ b/manual/Unit library
@@ -469,6 +469,8 @@ building the executing system, which is one of the following:
mingw32
gnu
intel
+ clang
+ sun
unknown
diff --git a/manual/Unit posix b/manual/Unit posix
index 1ede6c09..af889722 100644
--- a/manual/Unit posix
+++ b/manual/Unit posix
@@ -638,15 +638,18 @@ Returns the process group ID of the process specified by {{PID}}.
<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])</procedure>
-Creates a new child process and replaces the running process with it
-using the C library function {{execvp(3)}}. If the optional argument
-{{ARGUMENT-LIST}} is given, then it should contain a list of strings which
-are passed as arguments to the subprocess. If the optional argument
-{{ENVIRONMENT-LIST}} is supplied, then the library function {{execve(2)}}
-is used, and the environment passed in {{ENVIRONMENT-LIST}} (which should
-be of the form {{("<NAME>=<VALUE>" ...)}} is given
-to the invoked process. Note that {{execvp(3)}} respects the current setting
-of the {{PATH}} environment variable while {{execve(3)}} does not.
+Replaces the running process with a new process image from the program
+stored at {{PATHNAME}}, using the C library function {{execvp(3)}}.
+If the optional argument {{ARGUMENT-LIST}} is given, then it should
+contain a list of strings which are passed as arguments to the subprocess.
+If the optional argument {{ENVIRONMENT-LIST}} is supplied, then the library
+function {{execve(2)}} is used, and the environment passed in
+{{ENVIRONMENT-LIST}} (which should be of the form {{("<NAME>=<VALUE>" ...)}}
+is given to the invoked process. Note that {{execvp(3)}} respects the
+current setting of the {{PATH}} environment variable while {{execve(3)}} does not.
+
+This procedure never returns; it either replaces the process with a new one
+or it raises an exception in case something went wrong executing the program.
==== process-fork
@@ -709,6 +712,10 @@ and the process-id of the started sub-process. Blocking reads and writes
to or from the ports returned by {{process}} only block the current
thread, not other threads executing concurrently.
+Standard error for the subprocess is linked up to the current
+process's standard error (see {{process*}} if you want to reify
+its standard error into a separate port).
+
* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
is invoked as a subprocess.
* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
@@ -1155,7 +1162,7 @@ Returns the abbreviation for the local timezone as a string.
<procedure>(seconds->string [SECONDS])</procedure>
-Converts the local time represented in {{SECONDS}} into a string
+Converts the time represented in {{SECONDS}} into a local-time string
of the form {{"Tue May 21 13:46:22 1991"}}. {{SECONDS}} defaults to
the value of {{(current-seconds)}}.
diff --git a/manual/Unit srfi-18 b/manual/Unit srfi-18
index c35e32fd..dd33b99d 100644
--- a/manual/Unit srfi-18
+++ b/manual/Unit srfi-18
@@ -4,11 +4,18 @@
== Unit srfi-18
-A simple multithreading package, largely following the specification
+A multithreading package, largely following the specification
of [[http://srfi.schemers.org/srfi-18/srfi-18.html|SRFI-18]]. This
document contains the core of the SRFI-18 documentation as well as
information on Chicken deviations from the spec.
+The threads implemented in CHICKEN are so called "green" threads,
+based on first-class continuations. Native threads that map directly
+to the threads provided by the operating system are not supported.
+The advantage of this is that threads are very lightweight and
+somewhat larger degree of determinism. The disadvantage is that
+execution of Scheme code on multiple processor cores is not available.
+
SRFI-18 defines the following multithreading datatypes:
* Thread
diff --git a/manual/Using the compiler b/manual/Using the compiler
index 9807eaa6..cf123f7d 100644
--- a/manual/Using the compiler
+++ b/manual/Using the compiler
@@ -17,7 +17,7 @@ on the command line for a list of options.
csc FILENAME-OR-OPTION
{{FILENAME}} is the pathname of the source file that is to
-be compiled. A filename argument of {{-}} specifies that
+be compiled. A filename argument of {{-}} (a single dash) specifies that
the source text should be read from standard input.
==== Basic command-line options
@@ -278,11 +278,10 @@ This will produce the {{foo}} executable:
To run your newly compiled executable use:
- % foo
+ % ./foo
3628800
-If you get a {{foo: command not found}} error, you might want to try with {{./foo}} instead
-(or, in Unix machines, modify your {{PATH}} environment variable to include your current directory).
+
==== An example with multiple files
If multiple bodies of Scheme code are to be combined into a single
@@ -394,12 +393,13 @@ seen by {{user-preprocessor-pass}} but by {{user-pass}}.
It is relatively easy to create distributions of Scheme projects that
have been compiled to C. The runtime system of CHICKEN consists of only
-two handcoded C files ({{runtime.c}} and {{chicken.h}}), plus
+three handcoded C files ({{runtime.c}} and {{chicken.h}}), plus
the file {{chicken-config.h}}, which is generated by the build process. All
other modules of the runtime system and the extension libraries are just
-compiled Scheme code. The following example shows a minimal application, which
+compiled Scheme code.The following example shows a minimal application, which
should run without changes on the most frequent operating systems, like Windows,
-Linux or FreeBSD:
+Linux or FreeBSD (Static binaries are NOT supported on Mac OS X):
+
Let's take a simple example.
@@ -411,26 +411,33 @@ Let's take a simple example.
% csc -t hello.scm -optimize-level 3 -output-file hello.c
-Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}} and
-{{runtime.c}}, which contain the basic runtime system, plus the three
-basic library files {{library.c}}, {{eval.c}} and {{build-version.c}}
-which contain the same functionality as the library linked into a
-plain CHICKEN-compiled application, or which is available by default
-in the interpreter, {{csi}}:
+Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}},
+{{chicken-config.h}} and {{runtime.c}}, which contain the basic
+runtime system, plus the five basic library files {{library.c}},
+{{eval.c}}, {{expand.c}}, {{modules.c}} and {{build-version.c}}
+which contain the same functionality as the library linked into a
+plain CHICKEN-compiled application, or which is available by
+default in the interpreter, {{csi}}:
+
% cd /tmp
- %echo '(print "Hello World.")' > hello.scm
- % cp $CHICKEN_BUILD/runtime.c .
- % cp $CHICKEN_BUILD/library.c .
- % cp $CHICKEN_BUILD/eval.c .
- % cp $CHICKEN_BUILD/extras.c .
- % gcc -static -Os -fomit-frame-pointer runtime.c build-version.c library.c eval.c \
- hello.c -o hello -lm
+ % echo '(print "Hello World.")' > hello.scm
+ % cp $CHICKEN_BUILD/runtime.c .
+ % cp $CHICKEN_BUILD/library.c .
+ % cp $CHICKEN_BUILD/eval.c .
+ % cp $CHICKEN_BUILD/extras.c .
+ % cp $CHICKEN_BUILD/expand.c .
+ % cp $CHICKEN_BUILD/modules.c .
+ % cp $CHICKEN_BUILD/chicken.h .
+ % cp $CHICKEN_BUILD/chicken-config.h .
+ % cp $CHICKEN_BUILD/buildtag.h .
+ % gcc -static -Os -fomit-frame-pointer -DHAVE_CHICKEN_CONFIG_H runtime.c build-version.c \
+ library.c eval.c expand.c modules.c hello.c -o hello -lm
Now we have all files together, and can create an tarball containing all the files:
- % tar cf hello.tar Makefile hello.c runtime.c build-version.c library.c eval.c extras.c \
- chicken.h
+ % tar cf hello.tar hello.c runtime.c build-version.c library.c eval.c extras.c \
+ expand.c modules.c chicken.h chicken-config.h
% gzip hello.tar
This is naturally rather simplistic. Things like enabling dynamic loading, estimating
@@ -438,6 +445,10 @@ the optimal stack-size and selecting supported features of the host system would
more configuration- and build-time support. All this can be addressed using more
elaborate build-scripts, makefiles or by using autoconf/automake.
+The {{chicken-config.h}} file may contain wrong settings for your
+deployment target. Especially when the architecture is different.
+In that case you will have to adjust the values as needed.
+
Note also that the size of the application can still be reduced by removing
{{eval}} and compiling {{hello.scm}} with the {{-explicit-use}} option.
diff --git a/manual/Using the interpreter b/manual/Using the interpreter
index cec50aa7..0db4817b 100644
--- a/manual/Using the interpreter
+++ b/manual/Using the interpreter
@@ -128,7 +128,7 @@ executed as a script or normally loaded into the interpreter, say for debugging
<enscript highlight=scheme>
#!/bin/sh
#| demonstrates a slightly different way to run a script on UNIX systems
-exec csi -s "$@"
+exec csi -s "$0" "$@"
|#
(define (main args) ...)
@@ -141,6 +141,8 @@ exec csi -s "$@"
See also the documentation for the {{-ss}} option above.
+You can also have a look at [[/writing portable scripts]].
+
=== Toplevel commands
@@ -288,11 +290,11 @@ example:
On platforms that support it, it is possible to get auto-completion of
symbols, history (over different {{csi}} sessions) and a more
feature-full editor for the expressions you type using the
-[[http://wiki.call-cc.org/eggref/4/readline|readline]] egg by Tony
+[[/eggref/4/readline|readline]] egg by Tony
Garnock Jones. It is very useful for interactive use of csi. See the
egg's documentation on how to set it up. If readline is not available
on your system consider using the self-contained
-[[http://wiki.call-cc.org/eggref/4/linenoise|linenoise]] egg
+[[/eggref/4/linenoise|linenoise]] egg
instead. It should work on almost any system but is not as
feature-rich as readline (e.g. it lacks reverse-i-search and
auto-completion).
Trap