Fix and document decisions regarding /usr hierarchy split

Signed-off-by: David Oberhollenzer <goliath@infraroot.at>

3 files changed, 54 insertions, 8 deletions

diff --git a/00_setup.md b/00_setup.md
index 465c1d7..5a6e214 100644
--- a/00_setup.md
+++ b/00_setup.md
@@ -70,3 +70,49 @@ basically the `/` directory of the system we are going to build. For
 convenience, we will also store its absolute path in a shell variable:
 
     SYSROOT="$BUILDROOT/sysroot"
+
+
+### The Filesystem Hierarchy
+
+You might be familiar with the [Linux Filesyste Hiearchy Standard](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)
+which strives to standardize the root filesytem layout across GNU/Linux distros.
+
+This layout of course goes back to the [directory hierarchy on Unix Systems](https://en.wikipedia.org/wiki/Unix_directory_structure)
+which in turn hasn't been designed in any particular way, but evolved over the
+course of history.
+
+One issue that we will run into is that there are multiple possible places that
+libraries and program binaries could be installed to:
+ - `/bin`
+ - `/sbin`
+ - `/lib`
+ - `/usr/bin`
+ - `/usr/sbin`
+ - `/usr/lib`
+
+Yes, I know that there is an additional `/usr/local` sub-sub-hierarchy, but we'll
+ignore that once, since *nowadays** nobody outside the BSD world actually uses
+that.
+
+The split between `/` and `/usr` has historical reasons. The `/usr` directory
+used to be the home directory for the system users (e.g. `/usr/ken` was Ken
+Thompsons and `/usr/dmr` that of Dennis M. Ritchie) and was mounted from a
+separate disk during boot. At some point space on the primary disk grew tight
+and programs that weren't essential for system booting were moved from `/bin`
+to `/usr/bin` to free up some space. The home directories were later moved to
+an additional disk, mounted to `/home`. [So basically this split is a historic artifact](http://lists.busybox.net/pipermail/busybox/2010-December/074114.html).
+
+Anyway, for the system we are building, I will get rid of the pointless `/bin`
+and `/sbin` split, as well as the `/usr` sub-hiearchy split, but some programs
+are stubborn and use hard coded paths (remember the last time you
+used `#!/usr/bin/env` to make a script "portable"? You just replaced one
+portabillity problem with another one). So we will set up symlinks in `/usr`
+pointing back to `/bin` and `/lib`.
+
+Enough for the ranting, lets setup our directory hierarchy:
+
+    mkdir -p "$SYSROOT/bin" "$SYSROOT/lib"
+    mkdir -p "$SYSROOT/usr/share" "$SYSROOT/usr/include"
+
+    ln -s "../bin" "$SYSROOT/usr/bin"
+    ln -s "../lib" "$SYSROOT/usr/lib"
diff --git a/01_crosscc.md b/01_crosscc.md
index 74f2d07..348f571 100644
--- a/01_crosscc.md
+++ b/01_crosscc.md
@@ -495,13 +495,14 @@ Musl is quite easy to build but requires some special handling, because it
 doesn't use autotools. The configure script is actually a hand written shell
 script that tries to emulate some of the typical autotools handling:
 
-    CC="${TARGET}-gcc" $srcdir/configure --prefix=/usr --target="$TARGET"
+    CC="${TARGET}-gcc" $srcdir/configure --prefix=/ --includedir=/usr/include \
+                                         --target="$TARGET"
 
 We override the shell variable **CC** to point to the cross compiler that we
 just built. Remember, we added **$TCDIR/bin** to our **PATH**.
 
-We do the same thing for actually compiling musl and we explicitly set the
-**DESTDIR** variable for installing:
+We also set the compiler for actually compiling musl and we explicitly set
+the **DESTDIR** variable for installing:
 
     CC="${TARGET}-gcc" make
     make DESTDIR="$SYSROOT" install
@@ -511,7 +512,7 @@ We do the same thing for actually compiling musl and we explicitly set the
 The important part here, that later also applies for autotools based stuff, is
 that we don't set **--prefix** to the sysroot directory. We set the prefix so
 that the build system "thinks" it compiles the library to be installed
-in `/usr`, but then we install the compiled binaries and headers to the sysroot
+in `/`, but then we install the compiled binaries and headers to the sysroot
 directory.
 
 The `sysroot/usr/include` directory should now contain a bunch of standard
@@ -519,9 +520,9 @@ headers. Likewise, the `sysroot/usr/lib` directory should now contain a
 `libc.so`, a bunch of dummy libraries, and the startup object code provided
 by Musl.
 
-Despite the prefix we set, Musl installs a `sysroot/lib/ld-musl-armhf.so.1`
-symlink which points to `/usr/lib/libc.so`. Dynamically linked programs built
-with our toolchain will have `/lib/ld-musl-armhf.so.1` set as their loader.
+The prefix is set to `/` because we want the libraries to be installed
+to `/lib` instead of `/usr/lib`, but we still want the header files
+in `/usr/include`, so we explicitly specifiy the **--includedir**.
 
 ### Second pass GCC
 
diff --git a/02_kernel.md b/02_kernel.md
index 78a8cbc..5af1a5e 100644
--- a/02_kernel.md
+++ b/02_kernel.md
@@ -198,7 +198,6 @@ What is now left is to compile BusyBox.
 Before returning to the build root directory, I installed the resulting binary
 to the sysroot directory as `bbstatic`.
 
-    mkdir -p "$SYSROOT/bin"
     cp busybox "$SYSROOT/bin/bbstatic"
     cd "$BUILDROOT"