userland: make libs work

Working for build, but now test-user-mode-in-tree is not using --in-tree,
TODO fix later on.

README.adoc

@@ -973,7 +973,7 @@ This is the most reproducible and controlled environment, and all examples work
 
 With this setup, we will use the host toolchain and execute executables directly on the host.
 
-No installation or toolchain build is reuqired, so you can just jump straight into it.
+No installation or toolchain build is required, so you can just jump straight into it.
 
 Build, run and example, and clean it in-tree with:
 
@@ -1002,13 +1002,22 @@ cd userland/c
 ./test
 ....
 
-You can install those libraries and do the build in one go with:
+As mentioned at <<user-mode-tests>>, tests under link:userland/libs[] require certain optional libraries to be installed, and are not built or tested by default.
+
+You can install those libraries with:
 
 ....
 cd linux-kernel-module-cheat
 ./build --download-dependencies userland-host
 ....
 
+and then build the examples and test with:
+
+....
+./build --package-all
+./test --package-all
+....
+
 Pass custom compiler options:
 
 ....
@@ -3536,7 +3545,7 @@ This script skips a manually configured list of tests, notably:
 * tests that take perceptible ammounts of time
 * known bugs we didn't have time to fix ;-)
 
-Tests under link:userland/libs/[] depend on certain libraries being available on the target, e.g. <<blas>> for link:userland/libs/blas[]. They are not run by default, but can be enabled with `--has-package` and `--has-all-packages`.
+Tests under link:userland/libs/[] depend on certain libraries being available on the target, e.g. <<blas>> for link:userland/libs/blas[]. They are not run by default, but can be enabled with `--package` and `--package-all`.
 
 The gem5 tests require building statically with build id `static`, see also: <<gem5-syscall-emulation-mode>>. TODO automate this better.
 
@@ -3695,7 +3704,7 @@ So programs that rely on those libraries might not compile as GCC can't find the
 For example, if we try to build <<blas>> statically:
 
 ....
-./build-userland --has-package openblas --static -- userland/libs/openblas/hello.c
+./build-userland --package openblas --static -- userland/libs/openblas/hello.c
 ....
 
 it fails with:
@@ -8302,7 +8311,7 @@ DRM / DRI is the new interface that supersedes `fbdev`:
 
 ....
 ./build-buildroot --config 'BR2_PACKAGE_LIBDRM=y'
-./build-userland --has-package libdrm -- userland/libs/libdrm/modeset.c
+./build-userland --package libdrm -- userland/libs/libdrm/modeset.c
 ./run --eval-after './libs/libdrm/modeset.out' --graphic
 ....
 
@@ -8314,7 +8323,7 @@ TODO not working for `aarch64`, it takes over the screen for a few seconds and t
 
 ....
 ./build-buildroot --config 'BR2_PACKAGE_LIBDRM=y'
-./build-userland --has-package libdrm
+./build-userland --package libdrm
 ./build-buildroot
 ./run --eval-after './libs/libdrm/modeset.out' --graphic
 ....
@@ -10061,7 +10070,7 @@ Buildroot supports it, which makes everything just trivial:
 
 ....
 ./build-buildroot --config 'BR2_PACKAGE_OPENBLAS=y'
-./build-userland --has-package openblas -- userland/libs/openblas/hello.c
+./build-userland --package openblas -- userland/libs/openblas/hello.c
 ./run --eval-after './libs/openblas/hello.out; echo $?'
 ....
 
@@ -10101,7 +10110,7 @@ Header only linear algebra library with a mainline Buildroot package:
 
 ....
 ./build-buildroot --config 'BR2_PACKAGE_EIGEN=y'
-./build-userland --has-package eigen -- userland/libs/eigen/hello.cpp
+./build-userland --package eigen -- userland/libs/eigen/hello.cpp
 ....
 
 Just create an array and print it:
@@ -13351,7 +13360,7 @@ We have link:https://buildroot.org/downloads/manual/manual.html#ccache[enabled c
 * absolute paths are used and GDB can find source files
 * but builds are not reused across separated LKMC directories
 
-=== Rebuild buildroot while running
+=== Rebuild Buildroot while running
 
 It is not possible to rebuild the root filesystem while running QEMU because QEMU holds the file qcow2 file:
 
@@ -13640,6 +13649,31 @@ We chose this awkward name so that our includes will have an `lkmc/` prefix.
 
 Another option would have been to name it as `includes/lkmc`, but that would make paths longer, and we might want to store source code in that directory as well in the future.
 
+===== Userland objects vs header-only
+
+When factoring out functionality across userland examples, there are two main options:
+
+* use header-only implementations
+* use separate C files and link to separate objects.
+
+The downsides of the header-only implementation are:
+
+* slower compilation time, especially for C++
+* cannot call C implementations from assembly files
+
+The advantages of header-only implementations are:
+
+* easier to use, just `#include` and you are done, no need to modify build metadata.
+
+As a result, we are currently using the following rule:
+
+* if something is only going to be used from C and not assembly, define it in a header which is easier to use
++
+The slower compilation should be OK as long as split functionality amongst different headers and only include the required ones.
++
+Also we don't have a choice in the case of C++ template, which must stay in headers.
+* if the functionality will be called from assembly, then we don't have a choice, and must add it to a separate source file and link against it.
+
 ==== buildroot_packages directory
 
 Source: link:buildroot_packages/[]