Add env.bash error tracking and update build scripts and docs

Author: Gary Frost

hat/README.md

@@ -14,10 +14,6 @@ The HAT project is in the 'hat' subdir of the babylon project.
 
 ## Building HAT
 
-HAT uses both maven and cmake.
-
-Maven controls the build but delegates to cmake for native artifacts (such as various backends).
-
 [See](docs/hat-01-03-building-hat.md)
 
 

hat/bld

@@ -1,4 +1,4 @@
-#!/usr/bin/env java --enable-preview --source 24 --class-path bldr/classes
+//usr/bin/env java --enable-preview --source 24 --class-path bldr/bldr.jar "$0" "$@"; exit $?
 /*
  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
@@ -29,6 +29,7 @@ import static java.nio.file.Files.*; // so we can use isDirectory(path);
 
 void main(String[] args) throws IOException, InterruptedException, URISyntaxException {
    var hatDir = new Root();
+   List.of(args).forEach(arg->println(arg));
 
    withExpectedDirectory(hatDir.path(), "hat", hatProjectDir -> {
       var hatJavacOpts = new JavacBuilder().opts(

hat/bldr/.gitignore

@@ -1 +1,2 @@
 classes
+bldr.jar

hat/docs/hat-01-03-building-hat.md

@@ -30,11 +30,12 @@ We might even have `Bldr` create the maven artifacts....
 To build HAT we need to ensure that `JAVA_HOME` is set
 to point to our babylon jdk (the one we built [here](hat-01-02-building-babylon.md))
 
-It will simplify our tasks going forward if we
+It simplifes our tasks going forward if we
 add `${JAVA_HOME}/bin` to our PATH (before any other JAVA installs).
 
-The top level `env.bash` shell script can be sourced (dot included)
-into your shell to both set `JAVA_HOME` and update your `PATH`
+We also need to prebuild the `bldr/bldr.jar`
+
+Thankfully just sourcing the top level `env.bash` script will perform these tasks
 
 It should detect the arch type (AARCH64 or X86_46) and
 select the correct relative parent dir and inject that dir in your PATH.
@@ -46,12 +47,13 @@ echo ${JAVA_HOME}
 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
 echo ${PATH}
 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/usr/local/bin:......
+ls bldr/bldr.jar
+bldr/bldr.jar
 ```
 
 # Introducing Bldr
-`Bldr` is a minimal java build system which has all the capabilities needed so far
-to build existing HAT as well as it's examples and backends. It is just a set of
-static methods and helper classes wrapping javac/jar tooling.
+`Bldr` is an evolving set of static methods and types needed (so far.. ;) )
+to build HAT as well as the HAT examples and backends.
 
 `Bldr` itself is a java class in
 ```
@@ -63,60 +65,39 @@ bldr
                   └── Bldr.java
 ```
 
-We do need to compile this one class using javac one time, then we can use this in `bld` scripts to actually bld.
+The first run of  `env.bash` will compile and create build `bldr/bldr.jar`
 
 Assuming we have our babylon JDK build in our path (via `. env.bash`) we should do this every time we 'pull' HAT.
 
 ```shell
 mkdir bldr/classes
 javac --enable-preview -source 24 -d bldr/classes bldr/src/main/java/bldr/Bldr.java
+jar -cf bldr/bldr.jar -C bldr/classes bldr
 ```
-
-Now the `bldr/classes` dir contains all we need to create build scripts
-
-In HAT's root dir is a `#!` (Hash Bang) java launcher style script called `bld`
+In HAT's root dir is a `#!` (Hash Bang) java launcher style script called `bld` (and one called `sanity`)
 which uses tools exposed by the precompiled `Bldr` to compile, create jars, run jextract, download dependencies, tar/untar etc.
 
 As git does not allow us to check in scripts with execute permission, we need to `chmod +x` this `bld` file.
 
 ```bash
-chmod +x bld
+chmod +x bld sanity
 ```
 
-A simple example of `bld` script which just compiles core HAT source to `build/hat-1.0.jar` is shown.
-
-```java
-#!/usr/bin/env java --enable-preview --source 24 --class-path bldr/classes
-import module java.compiler;
-import static bldr.Bldr.*;
-void main(String[] args) throws IOException, InterruptedException {
-    var hatDir = Path.of(System.getProperty("user.dir"));
-    var target = path(hatDir, "build");// mkdir(rmdir(path(hatDir, "build")));
-
-    var hatJarResult = javacjar($ -> $
-            .opts(  "--source", "24",
-                    "--enable-preview",
-                    "--add-exports=java.base/jdk.internal=ALL-UNNAMED",
-                    "--add-exports=java.base/jdk.internal.vm.annotation=ALL-UNNAMED")
-            .jar(path(target, "hat-1.0.jar"))
-            .source_path(path(hatDir, "hat/src/main/java"))
-    );
-}
-```
 Note that the first line has the `#!` magic to allow this java code to be executed as if it
 were a script.  Whilst `bld` is indeed real java code,  we do not need to compile it. Instead we just execute using
 
 ```bash
 ./bld
 ```
 
-The real `bld` is more complicated, but not much more. It will will build hat-1.0.jar, along with all the backend jars hat-backend-?-1.0.jar,
+`bld` will build hat-1.0.jar, along with all the backend jars hat-backend-?-1.0.jar,
 all the example jars hat-example-?-1.0.jar and will try to build all native artifacts (.so/.dylib) it can.
+
 So if cmake finds OpenCL libs/headers, you will see libopencl_backend (.so or .dylib)
 
 On a CUDA machine you will see libcuda_backend(.so or .dylib)
 
-`bld` will also sanity check .java/.cpp/.h files to make sure we don't have any tabs, lines that with whitespace
+`sanity` will sanity check all  .md/.java/.cpp/.h files to make sure we don't have any tabs, lines that with whitespace
 or files without appropriate licence headers
 
 ```bash
@@ -152,4 +133,5 @@ name `opencl` and the package name `mandel`
 
 ```bash
 bash hatrun.bash opencl mandel
+bash hatrun.bash opencl heal
 ```

hat/env.bash

@@ -1,5 +1,4 @@
-#!/bin.bash
-cat >/dev/null<<LICENSE
+cat >/dev/null<<END_OF_LICENSE
 /*
  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
@@ -24,34 +23,96 @@ cat >/dev/null<<LICENSE
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
-LICENSE
+END_OF_LICENSE
 
-OS=$(uname -s )
-if [[ "$OS" == Linux ]]; then
-  export ostype=linux
-elif  [[ "$OS" == Darwin ]]; then
-  export ostype=macosx
-else
-  echo "could not determine ostype uname -s returned ${OS}"
-  exit 1
-fi
+# First lets check if this script was sourced into a bash compatible shell
 
-ARCH=$(uname -m)
-if [[ "$ARCH" == x86_64 ]]; then
-  export archtype=${ARCH}
-elif  [[ "$ARCH" == arm64 ]]; then
-  export archtype=aarch64
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then 
+   # We just bail if it was not sourced.. We want to set PATH and JAVA_HOME...
+   echo "You must source this file ..."
+   echo "Using either "
+   echo "    . ${0}"
+   echo "or"
+   echo "    source ${0}"
+   exit 1;  # this is ok because we were sourced 
 else
-  echo "could not determine aarchtype uname -m returned ${ARCH}"
-  exit 1
-fi
+  # Don't exit below here or you will trash the users shell ;)
 
-export JAVA_HOME=${PWD}/../build/${ostype}-${archtype}-server-release/jdk
-echo "exporting JAVA_HOME=${JAVA_HOME}"
-if echo ${PATH} | grep ${JAVA_HOME} >/dev/null ;then
-   echo 'path already contains ${JAVA_HOME}/bin'
-else
-   export SAFE_PATH=${PATH}
-   echo 'adding ${JAVA_HOME}/bin prefix to PATH,  SAFE_PATH contains previous value'
-   export PATH=${JAVA_HOME}/bin:${PATH}
+  OS=$(uname -s )
+  if [[ "$OS" == Linux ]]; then
+    export ostype=linux
+  elif  [[ "$OS" == Darwin ]]; then
+    export ostype=macosx
+  else
+    echo "Could not determine ostype uname -s returned ${OS}"
+  fi
+
+  ARCH=$(uname -m)
+  if [[ "$ARCH" == x86_64 ]]; then
+    export archtype=${ARCH}
+  elif  [[ "$ARCH" == arm64 ]]; then
+    export archtype=aarch64
+  else
+    echo "Could not determine aarchtype uname -m returned ${ARCH}"
+  fi
+
+  if [[ -z "${archtype}" || -z "${ostype}" ]]; then 
+     echo "Can't determine archtype and/or ostype"
+  else
+    # We expect the user to provide a value for BABYLON_JDK_HOME or we can locate one using ${PWD}/..
+
+    # below is a verbose version of 
+    # export BABYLON_JDK_HOME=${BABYLON_JDK_HOME:-$(realpath ${PWD}/..)}
+
+    if [[ -z "${BABYLON_JDK_HOME}" ]]; then 
+       echo "No user supplied BABYLON_JDK_HOME var, we will try \${PWD}/.. = $(realpath ${PWD}/..)"
+       export BABYLON_JDK_HOME=$(realpath ${PWD}/..)
+    else
+       echo "Using user supplied BABYLON_JDK_HOME ${BABYLON_JDK_HOME}"
+    fi
+
+
+    if [[ -d "${BABYLON_JDK_HOME}/build" ]]; then
+      echo "\${BABYLON_JDK_HOME}/build seems ok!"
+      export JAVA_HOME=${BABYLON_JDK_HOME}/build/${ostype}-${archtype}-server-release/jdk
+      echo "exporting JAVA_HOME=${JAVA_HOME}"
+      if echo ${PATH} | grep ${JAVA_HOME} >/dev/null ;then
+         echo "PATH already contains \${JAVA_HOME}/bin"
+      else
+         export SAFE_PATH=${PATH}
+         echo "Adding \${JAVA_HOME}/bin prefix to PATH, SAFE_PATH contains previous value"
+         export PATH=${JAVA_HOME}/bin:${PATH}
+      fi
+
+      # Our java source launcher based build system needs bldr.bldr.jar so we create it here if needed. 
+      if [[ -f bldr/bldr.jar ]]; then 
+         echo "Found prebuilt bldr.jar"
+      else
+         mkdir -p bldr/classes
+         echo "Bootrapping bldr.jar"
+         javac \
+           --enable-preview \
+           --source 24 \
+           -d bldr/classes \
+           --source-path bldr/src/main/java \
+           bldr/src/main/java/bldr/Bldr.java
+  
+         jar -cf bldr/bldr.jar -C bldr/classes bldr 
+      fi
+      echo "SUCCESS!"
+    else
+      echo "We expected either:-"
+      echo "    \${PWD} to be in a hat subdir of a compiled babylon jdk build" 
+      echo "or" 
+      echo "    BABYLON_JDK_HOME to be set, to a compiled babylon jdk build"
+      echo ""
+      echo "If you are in a hat subdir make sure babylon jdk is built ;)"
+      echo ""
+      echo "If you are in another dir try  "
+      echo "    BABYLON_JDK_HOME=<<YOUR_PREBULT_BABYLON>> . ${0}"
+      echo "or"
+      echo "    BABYLON_JDK_HOME=<<YOUR_PREBULT_BABYLON>> source ${0}"
+    fi
+  fi
 fi
+

hat/build.bash hat/maven-build.bash

@@ -25,5 +25,4 @@ cat >/dev/null<<LICENSE
  */
 LICENSE
 
-
 mvn clean compile jar:jar install

hat/mkbldr

@@ -1,4 +1,5 @@
-#!/usr/bin/env java --enable-preview --source 24 --class-path bldr/classes
+//usr/bin/env java --enable-preview --source 24 --class-path bldr/bldr.jar "$0" "$@"; exit $?
+
 /*
  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.