Some more docs.

1 files changed, 89 insertions, 17 deletions

diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
index 32302bfab..206eab750 100755
--- a/scripts/bootstrap.sh
+++ b/scripts/bootstrap.sh
@@ -5,7 +5,7 @@
 # Purpose  : Bootstraps Adélie from source for any architecture.
 # Authors  : Zach van Rijn <me@zv.io>
 # License  : MIT
-# Revision : 20221206
+# Revision : 20221207
 #===============================================================
 
 #===============================================================
@@ -27,13 +27,7 @@
 # binaries can run natively on the build machine. We know and do
 # appreciate there are different opinions on how to approach the
 # bootstrap process. This meets our needs and hopefully offers a
-# different perspective.
-#
-# This process takes up a lot of TIME and SPACE, and this cannot
-# be improved by throwing hardware at it. This is primarily due
-# to the tradeoff of not requiring root privileges at any point,
-# and the decision to emulate a native environment instead of to
-# force explicit cross-compilation at each step in the process.
+# different perspective on how to simplify cross compilation.
 #
 # (*) See the "requirements" section for mitigations/discussion.
 #
@@ -68,6 +62,15 @@
 #
 # TL;DR: You must be able to run the mcmtools bootstrap script.
 #
+# Cross builds take up a lot of TIME and SPACE, and this cannot
+# be improved by throwing hardware at it. This is primarily due
+# to the tradeoff of not requiring root privileges at any point,
+# and the decision to emulate a native environment instead of to
+# force explicit cross-compilation at each step in the process.
+#
+# If you wish to bootstrap to the same target CPU architecture,
+# or a compatible mode (e.g. i686 on x86_64), it will be faster.
+#
 # mcmtools is a hard dependency for our bootstrap process now:
 #
 #     https://git.zv.io/toolchains/bootstrap
@@ -84,6 +87,38 @@
 # To do this, you'd essentially comment out the first stages or
 # copy the results of the first stages elsewhere and continue.
 #
+# There are a few different sequences, depending on your needs.
+# In this diagram, indentation refers to an output product, and
+# moving down vertically refers to an input step.
+#
+#   * CPU A --> CPU B (slow; no access to CPU B hardware)
+#         --> Bootstrap 1 (Cross Libc + Partial Cross CPU B)
+#             --> CPU A + CPU B Mixed Rootfs
+#             --> Partial Emulation
+#             --> Bootstrap 2 (Full Cross CPU B)
+#                 --> CPU B Host Rootfs
+#                 --> Full Emulation
+#                 --> Adélie Bootstrap
+#                     --> Adélie Rootfs for CPU B
+#
+#   * CPU A --> CPU B (faster;  access to CPU B hardware)
+#         --> Bootstrap 1 (Cross Libc + Partial Cross CPU B)
+#             --> CPU A + CPU B Mixed Rootfs
+#             --> Partial Emulation
+#             --> Bootstrap 2 (Full Cross CPU B)
+#                 --> CPU B Host Rootfs
+#                 --> Copy to Native CPU B Hardware
+#                 --> Adélie Bootstrap
+#                     --> Adélie Rootfs for CPU B
+#
+#   * CPU A --> CPU A (fastest)
+#         --> Bootstrap 1 (Cross Libc)
+#             --> CPU A Mixed Rootfs
+#             --> Bootstrap 2 (Remove Contamination)
+#                 --> CPU A Host Rootfs
+#                 --> Adélie Bootstrap
+#                     --> Adélie Rootfs for CPU A
+#
 # Other requirements that you should be aware of, estimated:
 #
 #   * As many CPU cores as you can throw at it;
@@ -347,17 +382,18 @@ if ! test -d "${MTOOLS}/sys/emus/bin"; then # FIXME: no hard code
         cp "${MTOOLS}"/tmp/musl-cross-make/config.mak          \
         "${MTOOLS}"/config.mak                                 \
         ;
-    #rm -fr "${MTOOLS}"/tmp; # save 10 GB (FIXME: make safe)
+
+    # cleaning
+    cd "${MTOOLS}";
+    rm -fr tmp; # save 10 GB
 
     # is any of this actually needed?
-    (
-        cd "${MTOOLS}"/sys;
-        mkdir -p dev;
-        mkdir -p proc;
-        mkdir -p sys;
-        rm -fr usr;
-        ln -s . usr;
-    )
+    cd "${MTOOLS}"/sys;
+    mkdir -p dev;
+    mkdir -p proc;
+    mkdir -p sys;
+    rm -fr usr;
+    ln -s . usr;
 
     ## emulators
     #
@@ -457,6 +493,22 @@ ${MTOOLS}/sys/emus/bin/proot                                   \
 
 
 #---------------------------------------------------------------
+# rootfs: build
+
+##
+# Create a tarball of the build rootfs. The image creator could
+# use this as input if the target architecture matches.
+#
+cd "${BASE}";
+if ! test -f rootfs-${BUILDS}.tgz; then
+    tar -C "${BASE}"/mcmtools/sys                              \
+        -pczf rootfs-${BUILDS}.tgz                             \
+        .                                                      \
+        ;
+fi
+
+
+#---------------------------------------------------------------
 # mcmtools (host)
 
 ##
@@ -538,8 +590,24 @@ ${MTOOLS}/sys/emus/bin/proot                                   \
 
 
 #---------------------------------------------------------------
+# rootfs: host
+
+##
+# Create a tarball of the host rootfs. This is a safety measure.
+#
+cd "${BASE}";
+if ! test -f rootfs-${TARGET}.tgz; then
+    tar -C "${BASE}"/mcmtools-${TARGET}/sys                    \
+        -pczf rootfs-${TARGET}.tgz                             \
+        .                                                      \
+        ;
+fi
+
+
+#---------------------------------------------------------------
 # finalize pre-adelie rootfs
 
+exit 0;
 (
     cd "${BASE}"/mcmtools-${TARGET}/sys;
 
@@ -554,6 +622,10 @@ EOF
 
     # handle git backend issue
     # git config --global http.sslCAInfo ...
+
+grep -rl /old/path . | cut -d: -f1 | while read k; do
+        perl -pi -e 's@/old/path@/new/path@g' ${k};
+    done
 )