[PATCH v4] README: Update build instructions - linux-morello-ltp - op-lists.linaro.org

1 Dec 2022

Clean-up the instructions for building LTP syscall testcases, as those
have become bit stale. Also add some additional details on the required
setup.
Signed-off-by: Beata Michalska beata.michalska@arm.com
---
 changes available at:
 https://git.morello-project.org/Bea/morello-linux-ltp/-/tree/morello/readme_...
v4:
 - re-fitting the 'Building' section title into one line
 - re-phrasing the description for OUTPUT_DIR and renaming that one into
   LTP_INSTALL
v3:
 - switching to 'plain aarch64' instead using aarch64
v2:
 - increasing readability (hopefully)
 - added info on aarch64 build
 - dropped -pthread option as this one is not required when building with Musl
   (@thanks to Yury)
README.rst | 75 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 50 insertions(+), 25 deletions(-)

diff --git a/README.rst b/README.rst
index 342901f4d..4aebadd35 100644
--- a/README.rst
+++ b/README.rst
@@ -18,8 +18,8 @@ https://op-lists.linaro.org/mailman3/lists/linux-morello-ltp.op-lists.linaro...
        pure-capability kernel-user ABI (PCuABI)
        (see `Morello Linux ABI specifications https://git.morello-project.org/morello/kernel/linux/-/wikis/home`_)
-Building (cross-compiling) & running relevant tests (purecap mode)
--------------------------------------------------------------------
+Building & running relevant tests (purecap and plain aarch64 mode)
+------------------------------------------------------------------
Dependencies/requirements: (additional to what's required to build base LTP):
@@ -29,7 +29,7 @@ Dependencies/requirements: (additional to what's required to build base LTP):
Binary releases: https://git.morello-project.org/morello/llvm-project-releases
-    - **morello/baremetal-release-1.4** + **morello/linux-aarch64-release-1.4** for Morello
+    - **morello/baremetal-release-1.x*** + **morello/linux-aarch64-release-1.x*** for Morello
       purecap crt objects
@@ -37,6 +37,8 @@ Dependencies/requirements: (additional to what's required to build base LTP):
- Kernel uAPI header files: https://git.morello-project.org/morello/morello-linux-headers
+* All based on the same release/tag version.
+
 Building Musl:
 --------------
@@ -44,16 +46,27 @@ Assumptions:
.. code-block::
-   clang - Morello Clang (see Dependencies) configured for current environment
+   clang                - Morello Clang (see Dependencies) configured for current environment
+
+
+.. code-block::
+
+   TRIPLE               - Target architecture:
+                                - morello+c64 (purecap): aarch64-linux-musl_purecap
+                                - plain aarch64:         aarch64-linux-gnu
+
+   MORELLO_SUPPORT      - Enabling support for Morello
+                                - morello+c64 (purecap): --enable-morello
+                                - plain aarch64:         --disable-morello
.. code-block::
CC=clang ./configure \
     --disable-shared \
-    --enable-morello \
+    ${MORELLO_SUPPORT} \
     --disable-libshim \
-    --target=aarch64-linux-musl_purecap \
+    --target=${TRIPLE} \
     --prefix=${INSTALL_PATH}
@@ -72,27 +85,31 @@ Assumptions:
 .. code-block::
clang            - Morello Clang (see Dependencies) configured for current environment
-    KHDR_DIR         - kernel uAPI headers
-    MUSL	     - Musl build (see above)
-    MORELLO_CRT_OBJS - as per https://git.morello-project.org/morello/llvm-project-releases/-/tree/morello...
-                       -> $(clang -print-resource-dir)/lib/aarch64-unknown-linux-musl_purecap
-
+    TRIPLE           - target architecture:
+                                - morello+c64 (purecap): aarch64-linux-musl_purecap
+                                - plain aarch64:         aarch64-linux-gnu
+                       (needs to match *TRIPLE* specified for Musl build)
+    KHDR_DIR         - kernel uAPI headers (see Dependencies or alternatively headers
+                       installed for Morello Linux kernel through make headers_install)
+    MUSL             - installed Musl libc for Morello (see section above: `Building Musl`);
+                       this will serve as a location for --sysroot option
+                       (note this must match chosen configuration - see
+                       *TRIPLE* & *MORELLO_SUPPORT* in `Building Musl`)
+    LTP_BUILD        - out-of-tree build path (created by LTP's build.sh script if needed)
+    LTP_INSTALL      - destination path where LTP tests are to be installed
+    TARGETS          - build targets, currently only pan and testcases/kernel/syscalls
+                       are supported, it can be further narrowed down for specific syscall
+                       testcases:
+                       TARGETS="pan testcases/kernel/syscalls/${syscall}"
+    TARGET_FEATURE   - morello+c64 (purecap) only: -march=morello+c64
.. code-block::
-    CLANG_RES_DIR=$(clang -print-resource-dir)
+    CFLAGS="--target=${TRIPLE} ${TARGET_FEATURE} --sysroot=${MUSL} \
+            -isystem ${KHDR_DIR}/usr/include -g -Wall"
-    CFLAGS_COMMON="--target=aarch64-linux-gnu -integrated-as -g -static -nostdinc -pthread \
-    -isystem $KHDR_DIR/usr/include"
-
-    CFLAGS_PURECAP="$CFLAGS_COMMON -march=morello+c64 -mabi=purecap \
-    -isystem $CLANG_RES_DIR/include -isystem $MUSL/include -Wall"
-
-    LDFLAGS_COMMON="--target=aarch64-linux-gnu -fuse-ld=lld -static -nostdlib"
-
-    LDFLAGS_PURECAP="$LDFLAGS_COMMON $MUSL/lib/crt1.o $MUSL/lib/crti.o \
-    $MORELLO_CRT_OBJS/clang_rt.crtbegin.o $MORELLO_CRT_OBJS/libclang_rt.builtins.a \
-    $MORELLO_CRT_OBJS/clang_rt.crtend.o $MUSL/lib/crtn.o -L$MUSL/lib/ -lc -L$LTP_BUILD/lib"
+    LDFLAGS="--target=${TRIPLE} -rtlib=compiler-rt --sysroot=${MUSL} \
+             -fuse-ld=lld -static -L${LTP_BUILD}/lib"
export CC=clang
     export HOST_CFLAGS="-O2 -Wall"
@@ -101,9 +118,17 @@ Assumptions:
MAKE_OPTS="TST_NEWER_64_SYSCALL=no TST_COMPAT_16_SYSCALL=no" \
     TARGETS="pan testcases/kernel/syscalls" BUILD_DIR="$LTP_BUILD" \
-    CFLAGS="$CFLAGS_PURECAP" LDFLAGS="$LDFLAGS_PURECAP" \
-    ./build.sh -t cross -o out -ip "${OUTPUT_DIR}/opt/ltp"
+    CFLAGS="$CFLAGS" LDFLAGS="$LDFLAGS" \
+    ./build.sh -t cross -o out -ip "${LTP_INSTALL}"
+
+This can be split into separate steps for ``configure``, ``build`` and ``install`` by
+specifying additional parameter to ``build.sh`` detailing each step:
+
+.. code-block::
+        -r configure   - run configure only
+        -r build       - run build only
+        -r install     - run install only
Running tests:
 --------------
-- 
2.38.1


    