rust174: add a description of how I/we build bootstrap kits with pkgsrc.

[Havard Eidnes <he%NetBSD.org@localhost>]

Module Name:	pkgsrc-wip
Committed By:	Havard Eidnes <he%NetBSD.org@localhost>
Pushed By:	he
Date:		Sat Dec 2 12:55:15 2023 +0000
Changeset:	0937a3e92453f580e03fb4e89c553b5b2d135b8b

Added Files:
	rust174/HOWTO-BOOTSTRAP

Log Message:
rust174: add a description of how I/we build bootstrap kits with pkgsrc.

To see a diff of this commit:
https://wip.pkgsrc.org/cgi-bin/gitweb.cgi?p=pkgsrc-wip.git;a=commitdiff;h=0937a3e92453f580e03fb4e89c553b5b2d135b8b

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

diffstat:
 rust174/HOWTO-BOOTSTRAP | 85 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diffs:
diff --git a/rust174/HOWTO-BOOTSTRAP b/rust174/HOWTO-BOOTSTRAP
new file mode 100644
index 0000000000..81133db2ec
--- /dev/null
+++ b/rust174/HOWTO-BOOTSTRAP
@@ -0,0 +1,85 @@
+How to build a rust bootstrap kit using pkgsrc
+----------------------------------------------
+
+A rust bootstrap kit is simply a pre-compiled binary of rust and
+the rust standard library, and contains the "rust" and "rust-std"
+build results, found in
+
+   work/rustc-<version>/build/dist/
+as
+   rust-<version>-<target>.tar.xz
+and
+   rust-std-<version>-<target>.tar.xz
+
+These result files are produced when the "dist" build target is
+used, ref. BUILD_TARGET.   For a normal native build of the rust
+pkgsrc package, the default BUILD_TARGET is "build", not "dist".
+
+There are two possible ways to produce a bootstrap kit:
+
+1) a native build.  This requires minimum preparation, except
+   possibly for setting rust.BUILD_TARGET to "dist" via e.g.
+   /etc/mk.conf.  Note that on NetBSD, using the "BUILD_TARGET" ==
+   "dist" results in the "rust-cargo-static" option being set, ref.
+   options.mk.  This is so that the resulting bootstrap kits are
+   built with mostly-static linking, reducing the run-time dependencies
+   of the bootstrap kits.
+
+2) a cross-build.  This requires a bit of preparation:
+
+   For each target you want to cross-build rust for, you need
+     - the cross toolchain resulting from "build.sh tools" for
+       the intended target
+     - an OS distribution extracted, including the comp.tgz
+       set so that the target's include files can be used
+     - for 32-bit ports, the "libatomic" package needs to be
+       available.  I'm sure there's a clever and long-winded
+       use of pkg_install which can be used to effect this;
+       I on my hand have always just extracted the tgz file
+       and done the minimal cleanup of the "cruft" files
+       which are part of the package meta-data.
+     - Pick a root directory for the target, e.g. /u/i386.
+       Below this directory place the "tools" containing
+       the cross-compiler in a "tools" sub-directory.
+       Similarly, the extracted OS distribution in the "dest"
+       sub-directory.
+
+   There are two methods available for doing the cross-compile:
+
+   a) Using the "cross.mk" file.  For an i386 build against i586, the
+      following settings should be active:
+
+CROSS_ROOT=            /u/i386
+MAKE_ENV+=             CROSS_ROOT=${CROSS_ROOT}
+GNU_CROSS_TARGET=      i486--netbsdelf
+MAKE_ENV+=             GNU_CROSS_TARGET=${GNU_CROSS_TARGET}
+TARGET=                i586-unknown-netbsd
+SCRIPTS=               ${WRKDIR}/scripts
+CONFIGURE_ARGS+=       --host=${TARGET}
+CONFIGURE_ARGS+=       --target=${TARGET}
+CONFIGURE_ARGS+=       --set=target.${TARGET}.cc=${SCRIPTS}/gcc-wrap
+CONFIGURE_ARGS+=       --set=target.${TARGET}.cxx=${SCRIPTS}/c++-wrap
+CONFIGURE_ARGS+=       --set=target.${TARGET}.linker=${SCRIPTS}/gcc-wrap
+CONFIGURE_ARGS+=       --set=target.${TARGET}.ar=${CROSS_ROOT}/tools/bin/${GNU_CROSS_TARGET}-ar
+
+      Then doing a "make" will cross-build rust, including the LLVM
+      embedded in the rust distribution, ref. the defaulting of that
+      option when TARGET is defined ref. options.mk.
+
+      Note that when TARGET is set, the default build target for
+      the rust makefile becomes "dist", so there's no need to set
+      rust.BUILD_TARGET for cross-builds.
+
+   b) Using the "do-cross.mk" Makefile.  This will attempt to
+      cross-build rust for all the targets listed in the SHORT_TARGETS
+      variable in that file.  Overriding the root directories for
+      the various targets can be done by making your own "local-roots.mk"
+      file, ref. "do-cross.mk".
+
+      This will create a "dist" subdirectory in the rust pkgsrc
+      directory, and the bootstrap kits for each architecture, plus
+      the library source kit will be placed in this directory.
+
+The bootstrap kits can then be placed in /usr/pkgsrc/distfiles, and
+be used by the "next" rust version, where you can use "make makesum"
+to compute the updated checksums for the bootstrap kits.