~ chicken-core (chicken-5) a1d5b460807249ab85a0d4a6d1c9af3af282fcff
commit a1d5b460807249ab85a0d4a6d1c9af3af282fcff
Author: felix <felix@call-with-current-continuation.org>
AuthorDate: Thu Jun 10 01:24:16 2010 +0200
Commit: felix <felix@call-with-current-continuation.org>
CommitDate: Thu Jun 10 01:24:16 2010 +0200
updated docs
diff --git a/manual/Cross development b/manual/Cross development
index 3920fb0f..24376bef 100644
--- a/manual/Cross development
+++ b/manual/Cross development
@@ -37,6 +37,7 @@ make ARCH= \
PLATFORM=linux
HOSTSYSTEM=arm-none-linux-gnueabi \
DESTDIR=$HOME/target \
+ TARGET_FEATURES="-no-feature x86 -feature arm" \
libs install-dev
}}
@@ -62,6 +63,16 @@ If your cross compiler does not follow this convention, pass {{C_COMPILER}} and
* {{DESTDIR}} holds the directory where the compiled library files will temporarily
installeds 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
+the following will do the right thing when cross-compiled:
+
+<enscript hightlight=scheme>
+(cond-expand
+ (x86 <do this ...>)
+ ...)
+</enscript>
+
* If you obtained the sources from a source-code repository and not
from an official release tarball, you will need a {{chicken}}
executable to compile the Scheme sources of the runtime system. In
@@ -90,7 +101,7 @@ You should now have these files on {{~/target}}:
You should now transfer {{libchicken.so}} to the target system, and place
it in {{/usr}}.
-==== Building the "cross CHICKEN"
+==== Building the "cross chicken"
Next, we will build another chicken, one that uses the cross C compiler to
generate target-specific code that uses the target-specific runtime library
@@ -109,7 +120,7 @@ make PLATFORM=linux \
install
}}
-* {{PREFIX}} gives the place where the "cross CHICKEN" should be installed
+* {{PREFIX}} gives the place where the "cross chicken" should be installed
into. It is recommended not to install into a standard location (like {{/usr/local}}
or {{$HOME}}) - some files will conflict with a normal CHICKEN installation.
@@ -127,7 +138,7 @@ system into.
* Make sure to use the same version of the CHICKEN sources for the target and
the cross build.
-* If you build the cross CHICKEN from repository sources, the same note
+* If you build the cross chicken from repository sources, the same note
about the {{CHICKEN}} variable applies as given above.
In {{~/cross-chicken}}, you should find the following:
@@ -192,43 +203,14 @@ Is it an ARM binary?
Yes, looks good.
-==== Compiling simple extensions
-
-Invoking the cross {{arm-chicken-install}} for simple extensions that
-only provide runtime code is quite straightforward. The only
-difference is that we don't want the extension to be installed in the
-extension repository of the cross CHICKEN: the generated binary is
-(usually) not executable on the build platform, and should
-additionally be moved into the repository path of the native
-CHICKEN. For this to work, we pass the {{-prefix}} option to
-{{chicken-install}}:
-
- % ~/cross-chicken/arm-chicken-install -prefix $HOME/target/usr defstruct
-
-=== Compiling "host" extensions
-
-''Host'' extensions are extensions that have to execute on the build
-platform, like for example compiled macro extension packages. You also
-have to install all extensions that you intend to use on the target
-system for your cross CHICKEN as well, since compile-time information
-must be executable on the host (i.e. syntax definitions).
+==== Compiling extensions
-Use the {{-host}} option to {{arm-chicken-install}} to force
-building and installing an extension for the cross CHICKEN (and not
-the native target):
-
- % ~/cross-chicken/arm-chicken-install -host matchable
-
-Now {{matchable}} is installed for the cross CHICKEN:
-
- % ~/cross-chicken/arm-chicken-status -host
- matchable
-
-Next, build and install it for the target:
-
- $ ~/cross-chicken/arm-chicken-install matchable
- % ~/cross-chicken/arm-chicken-status
- matchable
+By default, the tools that CHICKEN provides to install, list and uninstall
+extensions will operate on both the host and the target repository.
+So running {{arm-chicken-install}} will compile and install the extension
+for the host system and for the cross-target. To selectively install, uninstall
+or list extensions for either the host or the target system use the
+{{-host}} and {{-target}} options for the tools.
=== "Target-only" extensions
@@ -247,20 +229,12 @@ cp target-only-extension.import.scm ~/cross-chicken/lib/chicken/5
=== Final notes
-Cross-development is a tricky process - it often involves countless
+Cross-development is a very tricky process - it often involves countless
manual steps and it is very easy to forget an important detail or mix
-up target and host systems. CHICKEN attempts to make this easier but
-the process still is rather low-level. Also, full 100% platform neutrality
-is hard to achieve - for example the ''features'' that you can test
-with {{feature?}} and {{cond-expand}} represent the host system, not
-the target system, so code like this will not work as intended,
-when cross compiled:
-
-<enscript highlite=scheme>
-(cond-expand
- (x86 (do-something))
- ...)
-</enscript>
+up target and host systems. Also, full 100% platform neutrality is
+hard to achieve. CHICKEN tries very hard to make this transparent, but
+at the price of considerable complexity in the code that manages
+extensions.
----
diff --git a/manual/Extensions b/manual/Extensions
index 1fd0db65..1bb76280 100644
--- a/manual/Extensions
+++ b/manual/Extensions
@@ -562,7 +562,8 @@ Available options:
; {{-r -retrieve}} : only retrieve egg into current directory, don't install
; {{-n -no-install}} : do not install, just build (implies {{-keep}})
; {{-p -prefix PREFIX}} : change installation prefix to {{PREFIX}}
-; {{-host}} : when cross-compiling, compile extension for host
+; {{-host}} : when cross-compiling, compile extension for host only
+; {{-target}} : when cross-compiling, compile extension for target only
; {{-test}} : run included test-cases, if available
; {{-username USER}} : set username for transports that require this
; {{-password PASS}} : set password for transports that require this
@@ -579,7 +580,8 @@ Available options:
; {{-v -version}} : show version and exit
; {{-force}} : don't ask, delete whatever matches
; {{-s -sudo}} : use {{sudo(1)}} for deleting files
-; {{-host}} : when cross-compiling, remove extensions for host system (the default for cross-compiling is to remove the extensions of the target system).
+; {{-host}} : when cross-compiling, remove extensions for host system only
+; {{-target}} : when cross-compiling, remove extensions for target system only
=== chicken-status reference
@@ -587,7 +589,8 @@ Available options:
; {{-h -help}} : show usage information and exit
; {{-v -version}} : show version and exit
; {{-f -files}} : list installed files
-; {{-host}} : when cross-compiling, show extensions for host system (the default for cross-compiling is to show the extensions of the target system).
+; {{-host}} : when cross-compiling, show extensions for host system only
+; {{-target}} : when cross-compiling, show extensions for target system only
=== Security
Trap