diff --git a/pkgs/racket-doc/scribblings/inside/appendix.scrbl b/pkgs/racket-doc/scribblings/inside/appendix.scrbl index b10142ebac..1ac2ac22e2 100644 --- a/pkgs/racket-doc/scribblings/inside/appendix.scrbl +++ b/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 -targets, but iOS is used to give concrete examples. +See @secref[#:doc raco-doc "cross-system"] for general information on +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 -in the source distribution's @filepath{src/README.txt} file, you can -use that build of Racket in conjunction with the host build it was +After cross-compiling Racket CS for iOS according to the source +distribution's @filepath{src/README.txt} file, you can use that build +@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 \ - --compile-any \ - --compiled 'compiled_host:tarm64osx' \ - --cross \ - --cross-compiler tarm64osx /path/to/ios/racket/lib \ - --config /path/to/ios/racket/etc \ - --collects /path/to/ios/racket/collects +racket \ + --compile-any \ + --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled: \ + --cross \ + --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib \ + --config @nonterm{ios-racket-dir}/etc \ + --collects @nonterm{ios-racket-dir}/collects } -The above command runs the host Racket REPL with support for -outputting compiled code for both the host machine and for the -@tt{tarm64osx} target. The second path to @exec{--compiled} may be -any relative path, but @filepath{tarm64osx} is what the cross build -uses to set up its installation so it is convenient to re-use it. +The above command runs the host Racket REPL with support for writing +compiled code for both the host machine and for the @tt{tarm64osx} +target. The first path to @DFlag{compiled} (before the @litchar{:}) +can be any absolute path, and @filepath{.zo} files for the host +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 -passing the @exec{-l} flag. For example, you can setup the target +Instruct the host Racket to run library code by +passing the @Flag{l} flag. For example, you can setup the target Racket's installation with the following command: @verbatim[#:indent 2]{ -racket \ - --compile-any \ - --compiled 'compiled_host:tarm64osx' \ - --cross \ - --cross-compiler tarm64osx /path/to/ios/racket/lib \ - --config /path/to/ios/racket/etc \ - --collects /path/to/ios/racket/collects \ - -l- \ +racket \ + --compile-any \ + --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled: \ + --cross \ + --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib \ + --config @nonterm{ios-racket-dir}/etc \ + --collects @nonterm{ios-racket-dir}/collects \ + -l- \ raco setup } @@ -77,14 +85,14 @@ use with @cppi{racket_embedded_load_file} (after installing with: @verbatim[#:indent 2]{ -racket \ - --compile-any \ - --compiled 'compiled_host:tarm64osx' \ - --cross \ - --cross-compiler tarm64osx /path/to/ios/racket/lib \ - --config /path/to/ios/racket/etc \ - --collects /path/to/ios/racket/collects \ - -l- \ +racket \ + --compile-any \ + --compiled @nonterm{ios-racket-dir}/src/build/cs/c/compiled: \ + --cross \ + --cross-compiler tarm64osx @nonterm{ios-racket-dir}/lib \ + --config @nonterm{ios-racket-dir}/etc \ + --collects @nonterm{ios-racket-dir}/collects \ + -l- \ raco ctool --mods application.zo src/application.rkt } diff --git a/pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-doc/scribblings/raco/setup.scrbl index a8161d12e6..d0032868f5 100644 --- a/pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/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 -platform resides at @nonterm{cross-dir}, then +For example, if an in-place Racket @tech[#:doc guide-doc]{BC} +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"] diff --git a/racket/src/README.txt b/racket/src/README.txt index d40607d961..3b2580f430 100644 --- a/racket/src/README.txt +++ b/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 -on one line) for BC +To compile the Racket BC runtime system as a Framework for iOS, use +(all on one line) configure --host=[arch]-apple-darwin --enable-ios="[sdk]" --enable-racket=racket + --enable-bcdefault where [arch] is one of diff --git a/racket/src/cs/c/Makefile.in b/racket/src/cs/c/Makefile.in index 8707b31ab6..258a437c1a 100644 --- a/racket/src/cs/c/Makefile.in +++ b/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