update cross-build info for Racket CS

pkgs/racket-doc/scribblings/inside/appendix.scrbl

@@ -1,5 +1,6 @@
 #lang scribble/base
-@(require "utils.rkt")
+@(require "utils.rkt"
+          scribble/bnf)
 
 @title[#:style '(grouper toc) #:tag "appendix"]{Appendices}
 
@@ -30,44 +31,51 @@ build modes that are more suitable for developing Racket itself; see
 
 @section[#:tag "ios-cross-compilation"]{Cross-compiling Racket Sources for iOS}
 
-Everything in this section can be adapted to other cross-compilation
+See @secref[#:doc raco-doc "cross-system"] for general information on
-targets, but iOS is used to give concrete examples.
+using Racket in cross-build mode. Everything in this section can be
+adapted to other cross-compilation targets, but iOS is used to make
+the examples concrete.
 
-After cross-compiling Racket CS for iOS according to the documentation
+After cross-compiling Racket CS for iOS according to the source
-in the source distribution's @filepath{src/README.txt} file, you can
+distribution's @filepath{src/README.txt} file, you can use that build
-use that build of Racket in conjunction with the host build it was
+@nonterm{ios-racket-dir} in conjunction with the host build it was
 compiled by to cross-compile Racket modules for iOS by passing the
 following set of flags to the host executable:
 
 @verbatim[#:indent 2]{
-racket \
+racket  \
-  --compile-any \
+  --compile-any  \
-  --compiled 'compiled_host:tarm64osx' \
+  --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled:  \
-  --cross \
+  --cross  \
-  --cross-compiler tarm64osx /path/to/ios/racket/lib \
+  --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib  \
-  --config /path/to/ios/racket/etc \
+  --config @nonterm{ios-racket-dir}/etc  \
-  --collects /path/to/ios/racket/collects
+  --collects @nonterm{ios-racket-dir}/collects
 }
 
-The above command runs the host Racket REPL with support for
+The above command runs the host Racket REPL with support for writing
-outputting compiled code for both the host machine and for the
+compiled code for both the host machine and for the @tt{tarm64osx}
-@tt{tarm64osx} target.  The second path to @exec{--compiled} may be
+target. The first path to @DFlag{compiled} (before the @litchar{:})
-any relative path, but @filepath{tarm64osx} is what the cross build
+can be any absolute path, and @filepath{.zo} files for the host
-uses to set up its installation so it is convenient to re-use it.
+platform will be written there; specifying the path
+@filepath{@nonterm{ios-racket-dir}/src/build/cs/c/compiled} is meant
+to reuse the directory that was created during cross-compilation
+installation. The second path to @DFlag{compiled} (after @litchar{:})
+is empty, which causes target-platform @filepath{.zo} files to be
+written in the usual @filepath{compiled} subdirectory.
 
-Furthermore, you can instruct the host Racket to run library code by
+Instruct the host Racket to run library code by
-passing the @exec{-l} flag.  For example, you can setup the target
+passing the @Flag{l} flag.  For example, you can setup the target
 Racket's installation with the following command:
 
 @verbatim[#:indent 2]{
-racket \
+racket  \
-  --compile-any \
+  --compile-any  \
-  --compiled 'compiled_host:tarm64osx' \
+  --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled:  \
-  --cross \
+  --cross  \
-  --cross-compiler tarm64osx /path/to/ios/racket/lib \
+  --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib  \
-  --config /path/to/ios/racket/etc \
+  --config @nonterm{ios-racket-dir}/etc  \
-  --collects /path/to/ios/racket/collects \
+  --collects @nonterm{ios-racket-dir}/collects  \
-  -l- \
+  -l-  \
   raco setup
 }
 
@@ -77,14 +85,14 @@ use with @cppi{racket_embedded_load_file} (after installing
 with:
 
 @verbatim[#:indent 2]{
-racket \
+racket  \
-  --compile-any \
+  --compile-any  \
-  --compiled 'compiled_host:tarm64osx' \
+  --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled:  \
-  --cross \
+  --cross  \
-  --cross-compiler tarm64osx /path/to/ios/racket/lib \
+  --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib  \
-  --config /path/to/ios/racket/etc \
+  --config @nonterm{ios-racket-dir}/etc  \
-  --collects /path/to/ios/racket/collects \
+  --collects @nonterm{ios-racket-dir}/collects  \
-  -l- \
+  -l-  \
   raco ctool --mods application.zo src/application.rkt
 }
 

pkgs/racket-doc/scribblings/raco/setup.scrbl

@@ -2163,8 +2163,9 @@ does not match the running Racket's information, then the
 @racketmodname[setup/cross-system] module infers that Racket is being
 run in cross-installation mode.
 
-For example, if an in-place Racket installation for a different
+For example, if an in-place Racket @tech[#:doc guide-doc]{BC}
-platform resides at @nonterm{cross-dir}, then
+installation for a different platform resides at @nonterm{cross-dir},
+then running Racket BC as
 
 @commandline{racket -C -G @nonterm{cross-dir}/etc -X @nonterm{cross-dir}/collects -l- raco pkg}
 
@@ -2176,6 +2177,53 @@ libraries need to run to perform the requested @exec{raco pkg} action
 (e.g., when installing built packages), or as long as the current
 platform's installation already includes those libraries.
 
+For Racket @tech[#:doc guide-doc]{CS}, cross compilation is more
+complicated, because Racket CS @filepath{.zo} files are
+platform-specific:
+
+@itemlist[
+
+ @item{A target installation @nonterm{cross-dir} is needed that
+       includes cross-compilation support for the host platform as
+       plug-in within the installation's
+       @filepath{@nonterm{cross-dir}/lib} directory. That installation
+       might be created by compiling from source on the host platform.
+       Only Racket CS can use a CS cross-compilation plug-in.
+
+       When running @exec{racket} in cross mode, use the
+       @DFlag{cross-compiler} flag to specify the target machine and
+       path to the @filepath{@nonterm{cross-dir}/lib} directory.}
+
+ @item{A flag combination @Flag{MCR} with argument
+       @filepath{@nonterm{absolute-zo-dir}:} is needed to enable
+       @filepath{.zo} file creation for both the host platform (which
+       uses the directory before a @litchar{:}) and the target
+       platform (which uses the normal compiled-file subdirectory when
+       the path after the @litchar{:} is empty).
+
+       The @nonterm{absolute-zo-dir} can be any absolute path. It
+       generally should be populated by running @exec{raco setup} in
+       cross mode before commands like @exec{raco pkg}.}
+
+]
+
+For example, the @exec{raco pkg} example for Racket CS is
+
+@verbatim[#:indent 2]{
+  racket --cross-compiler @nonterm{target-machine} @nonterm{cross-dir}/lib \
+    -MCR @nonterm{absolute-zo-dir}: \
+    -G @nonterm{cross-dir}/etc -X @nonterm{cross-dir}/collects -l- raco pkg
+}
+
+The @nonterm{target-machine} provided to @DFlag{cross-compiler} should
+be the same as the @racketidfont{target-machine} entry in
+@filepath{@nonterm{cross-dir}/lib/systemd.rktd}.
+
+The @Flag{C} flag is shorthand for @DFlag{cross}, @Flag{M} is short
+for @DFlag{compile-any}, @Flag{R} is short for @DFlag{compiled},
+@Flag{G} is short for @DFlag{config}, @Flag{X} is short for
+@DFlag{collects}, and @Flag{MCR} is short for @exec{@Flag{M} @Flag{C}
+@Flag{R}}.
 
 @history[#:added "6.3"]
 

racket/src/README.txt

@@ -218,7 +218,7 @@ Detailed instructions:
     libraries can find the installation directories. At this stage, in
     case you are packaging an installation instead of installing
     directly, you can redirect the installation by setting the
-    "DESTDIR" environment variable to an absolute path for the
+    "DESTDIR" makefile variable to an absolute path for the
     packaging area. For example, `make DESTDIR=/tmp/racket-build
     install` places the installation into "/tmp/racket-build" instead
     of the location originally specified with `--prefix`. The
@@ -309,9 +309,6 @@ but note the following:
    Mac-style directory structure on top of an existing Unix-style
    directory structure.)
 
- * On Mac OS 10.6 and later, to build Racket in 32-bit mode, use
-   `--disable-mac64`.
-
 
 ========================================================================
  Compiling for Windows
@@ -397,12 +394,13 @@ the [comp] of your choice and the [platform] used to compile.
  Cross-compiling for iOS
 ========================================================================
 
-To compile the Racket runtime system as a Framework for iOS, use (all
+To compile the Racket BC runtime system as a Framework for iOS, use
-on one line) for BC
+(all on one line)
 
   configure --host=[arch]-apple-darwin
             --enable-ios="[sdk]"
             --enable-racket=racket
+            --enable-bcdefault
 
 where [arch] is one of
 

racket/src/cs/c/Makefile.in

@@ -478,7 +478,7 @@ do-setup-install:
 	@RUN_RACKET@ $(SELF_ROOT_CONFIG) $(SETUP_ARGS)
 
 do-setup-install-cross:
-	@RUN_RACKET@ $(SELF_ROOT_CONFIG) -C -M -R 'compiled_host:$(TARGET_MACH)' --cross-compiler $(TARGET_MACH) "$(DESTDIR)$(libpltdir)" $(SETUP_ARGS)
+	@RUN_RACKET@ $(SELF_ROOT_CONFIG) -C -M -R `pwd`/compiled: --cross-compiler $(TARGET_MACH) "$(DESTDIR)$(libpltdir)" $(SETUP_ARGS)
 
 no-setup-install:
 	echo done