1 # Building HAT
2
3 ----
4
5 * [Contents](hat-00.md)
6 * House Keeping
7 * [Project Layout](hat-01-01-project-layout.md)
8 * [Building Babylon](hat-01-02-building-babylon.md)
9 * [Building HAT](hat-01-03-building-hat.md)
10 * Programming Model
11 * [Programming Model](hat-03-programming-model.md)
12 * Interface Mapping
13 * [Interface Mapping Overview](hat-04-01-interface-mapping.md)
14 * [Cascade Interface Mapping](hat-04-02-cascade-interface-mapping.md)
15 * Implementation Detail
16 * [Walkthrough Of Accelerator.compute()](hat-accelerator-compute.md)
17
18 ---
19
20 # Building HAT with Bldr
21
22 We initially used maven and cmake to build hat. If you feel more comfortable
23 with maven consider [building with maven and cmake](hat-01-03-building-hat-with-maven.md)
24 but it is possible that maven support will be removed if the `Bldr` approach takes off.
25
26 We might even have `Bldr` create the maven artifacts....
27
28 ## Setting environment variables JAVA_HOME and PATH
29
30 To build HAT we need to ensure that `JAVA_HOME` is set
31 to point to our babylon jdk (the one we built [here](hat-01-02-building-babylon.md))
32
33 It simplifes our tasks going forward if we
34 add `${JAVA_HOME}/bin` to our PATH (before any other JAVA installs).
35
36 Thankfully just sourcing the top level `env.bash` script will perform these tasks
37
38 It should detect the arch type (AARCH64 or X86_46) and
39 select the correct relative parent dir and inject that dir in your PATH.
40
41 ```bash
42 cd hat
43 . ./env.bash
44 echo ${JAVA_HOME}
45 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
46 echo ${PATH}
47 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/usr/local/bin:......
48 ```
49
50 # Introducing Bldr
51 `Bldr` is an evolving set of static methods and types required (so far.. ;) )
52 to be able to build HAT, hat backends and examples.
53
54 We rely on the ability to launch java source directly (without needing to javac first)
55
56 * [JEP 458: Launch Multi-File Source-Code Program](https://openjdk.org/jeps/458)
57 * [JEP 330: Launch Single-File Source-Code Programs](https://openjdk.org/jeps/330)
58
59 The `bld` script (really java source) can be run like this
60
61 ```bash
62 java --add-modules jdk.incubator.code --enable-preview --source 24 bld
63 ```
64
65 In our case the magic is under the `hat/bldr`subdir
66
67 ```
68 bldr
69 ├── Bldr.java (symlink) -> src/main/java/bldr/Bldr.java
70 ├── args (text) "--enable-preview --source 24"
71 └── src
72 └── main
73 └── java
74 └── bldr
75 └── Bldr.java
76 ```
77
78 We also have a handy `bldr/args` which allows us to avoid specifying commmon args `--enable-preview --source 24` which are always needed
79
80 ```bash
81 java @bldr/args bld
82 ```
83
84 This `bld` script builds HAT, all the backends and examples and places buildable artifacts in `build` dir
85
86 ```bash
87 cd hat
88 . ./env.bash
89 java @bld/args bld
90 ls build
91 hat-1.0.jar hat-example-heal-1.0.jar libptx_backend.dylib
92 hat-backend-cuda-1.0.jar hat-example-mandel-1.0.jar libspirv_backend.dylib
93 hat-backend-mock-1.0.jar hat-example-squares-1.0.jar mock_info
94 hat-backend-opencl-1.0.jar hat-example-view-1.0.jar opencl_info
95 hat-backend-ptx-1.0.jar hat-example-violajones-1.0.jar ptx_info
96 hat-backend-spirv-1.0.jar libmock_backend.dylib spirv_info
97 hat-example-experiments-1.0.jar libopencl_backend.dylib
98 ```
99
100 `bld` relies on cmake to build native code for backends, so if cmake finds OpenCL libs/headers, you will see libopencl_backend (.so or .dylib) in the build dir, if cmake finds CUDA you will see libcuda_backend(.so or .dylib)
101
102 We have another script called `sanity` which will check all .md/.java/.cpp/.h for tabs, lines that end with whitespace
103 or files without appropriate licence headers
104
105 This is run using
106
107 ```
108 java @bldr/args sanity
109 ```
110
111
112 ## Running an example
113
114 To run a HAT example we can run from the artifacts in `build` dir
115
116 ```bash
117 ${JAVA_HOME}/bin/java \
118 --add-modules jdk.incubator.code --enable-preview --enable-native-access=ALL-UNNAMED \
119 --class-path build/hat-1.0.jar:build/hat-example-mandel-1.0.jar:build/hat-backend-opencl-1.0.jar \
120 --add-exports=java.base/jdk.internal=ALL-UNNAMED \
121 -Djava.library.path=build\
122 mandel.Main
123 ```
124
125 The `hatrun` script can also be used which simply needs the backend
126 name `opencl|java|cuda|ptx|mock` and the package name `mandel`
127
128 ```bash
129 java @bldr/args hatrun opencl mandel
130 ```
131
132 If you pass `headless` as the first arg
133
134 ```bash
135 java @bldr/args hatrun headless opencl mandel
136 ```
137
138 This sets `-Dheadless=true` and passes '--headless' to the example. Some examples can use this to avoid launching UI.
139