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.
