From a5ec53f1578d6a3f329e11c915f4a8969acaedcd Mon Sep 17 00:00:00 2001
From: Oliver Smith <ollieparanoid@postmarketos.org>
Date: Thu, 3 Sep 2020 18:35:18 +0200
Subject: [PATCH] cross/crossdirect: add more comments and license (MR 1545)

Make it easier to wrap one's head around the code and make the license
explicit. It was implicit already by the LICENSE file of this repository.
---
 cross/crossdirect/APKBUILD      |  4 ++--
 cross/crossdirect/crossdirect.c | 39 ++++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/cross/crossdirect/APKBUILD b/cross/crossdirect/APKBUILD
index b4c42dfe5..39c1bc9e8 100644
--- a/cross/crossdirect/APKBUILD
+++ b/cross/crossdirect/APKBUILD
@@ -17,7 +17,7 @@
 
 pkgname=crossdirect
 pkgver=4
-pkgrel=1
+pkgrel=2
 pkgdesc="Wrappers to launch native cross compilers in foreign chroots"
 url="https://postmarketOS.org"
 arch="all"
@@ -77,6 +77,6 @@ package() {
 		install -Dm755 "$srcdir/rustc-$_arch" "$_bindir/rustc"
 	done
 }
-sha512sums="20b963322820de038257304c1eefa85767b78e242eda7459f06d70a1cfae5540a445aa7d5587024bf4d88a4bee28120ef9f5c2d24a648e71b542b9618318deb2  crossdirect.c
+sha512sums="53d2910a9079e1b8a7fef2992eb98ef9e1a70054fa9eb8a00e1c2f2d0b5b0de6fe8f2b8e8f7806396f76b0e97ccbf9169b36215b20f60792c6758f936681730a  crossdirect.c
 6be16ba88720e628a3ecc8fa53f8e7a21d2af268b0509745d989139874d6b94b640bfcff09575eaa19073810be6ef91169c1f83e94f5cf8e6819f2670d9408de  rustc.sh
 ea9bf8db3810d03d0a7395057f3d6e57f7127d87c55deaedc171c255288f5f3cc6fbcc680a5a1b92786cf573875d5dc22521173799fe2639acc97d0715ff905b  rust-qemu-linker.sh"
diff --git a/cross/crossdirect/crossdirect.c b/cross/crossdirect/crossdirect.c
index 46672b4bb..a55e70db3 100644
--- a/cross/crossdirect/crossdirect.c
+++ b/cross/crossdirect/crossdirect.c
@@ -1,4 +1,34 @@
-// HOSTSPEC is defined at compile time, see APKBUILD
+/* Copyright 2020 Zhuowei Zhang, Oliver Smith
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * This program gets built to a set of wrapper executables, which launch native
+ * cross compilers inside foreign arch chroots. Speeds up cross compilation a
+ * lot, compared to using just qemu user mode emulation or using the previous
+ * distcc-based methods.
+ *
+ * How this program gets called:
+ * - pmbootstrap creates one native arch chroot and one foreign arch chroot.
+ * - The native chroot gets mounted as /native in the foreign chroot.
+ * - When calling "abuild", pmbootstrap sets PATH to:
+ *   /native/usr/lib/crossdirect/<ARCH>:$PATH
+ * - That crossdirect directory contains a crossdirect-<ARCH> binary built with
+ *   the matching HOSTSPEC (e.g. crossdirect-aarch64 binary with HOSTSPEC
+ *   aarch64-alpine-linux-musl). This binary is symlinked to:
+ *	- <HOSTSPEC>-c++
+ *	- <HOSTSPEC>-cc
+ *	- <HOSTSPEC>-clang
+ *	- <HOSTSPEC>-clang++
+ *	- <HOSTSPEC>-cpp
+ *	- <HOSTSPEC>-g++
+ *	- <HOSTSPEC>-gcc
+ *	- c++
+ *	- cc
+ *	- clang
+ *	- clang++
+ *	- cpp
+ *	- g++
+ *	- gcc
+ */
 
 #include <errno.h>
 #include <libgen.h>
@@ -52,20 +82,26 @@ int main(int argc, char **argv)
 		}
 	}
 
+	// prepend the HOSTSPEC to GCC binaries
 	if (isClang || startsWithHostSpec) {
 		snprintf(newExecutable, sizeof(newExecutable), NATIVE_BIN_DIR "/%s", executableName);
 	} else {
 		snprintf(newExecutable, sizeof(newExecutable), NATIVE_BIN_DIR "/" HOSTSPEC "-%s", executableName);
 	}
 
+	// prepare new arguments for GCC / clang
 	char **newArgsPtr = newargv;
 	*newArgsPtr++ = newExecutable;
 	if (isClang) {
+		// clang does not use a HOSTSPEC prefix for the cross compiler
+		// binary, but instead have a -target argument
 		*newArgsPtr++ = "-target";
 		*newArgsPtr++ = HOSTSPEC;
 	}
 	*newArgsPtr++ = "--sysroot=/";
 
+	// add all arguments passed to this executable to GCC / clang and set
+	// the last arg in newargv to NULL to mark its end
 	memcpy(newArgsPtr, argv + 1, sizeof(char *) * (argc - 1));
 	newArgsPtr += (argc - 1);
 	*newArgsPtr = NULL;
@@ -85,6 +121,7 @@ int main(int argc, char **argv)
 		}
 	}
 
+	// finally exec GCC / clang
 	if (execve(newExecutable, newargv, env) == -1) {
 		fprintf(stderr, "ERROR: crossdirect: failed to execute %s: %s\n", newExecutable, strerror(errno));
 		fprintf(stderr, "Maybe the target arch is missing in the ccache-cross-symlinks package?\n");