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 * [How we minimize buffer transfers](hat-minimizing-buffer-transfers.md)
18
19 ---
20
21 # Building HAT with Script
22
23 We initially used maven and cmake to build hat. If you feel more comfortable
24 with maven consider [building with maven and cmake](hat-01-03-building-hat-with-maven.md)
25 but it is possible that maven support will be removed if the `Script` approach takes off.
26
27 ## Dependencies
28
29 Before we start to build HAT we will need `cmake` and `jextract` installed.
30
31 You can download jextract from [here](https://jdk.java.net/jextract/)
32
33 Use `sudo apt` on Linux or `brew install`.
34
35 ```bash
36 sudo apt install cmake
37
38 ```
39
40 ```bash
41 brew install cmake
42 ```
43
44
45 You will also need a Babylon JDK built (the one we built [here](hat-01-02-building-babylon.md))
46
47
48 ## Setting your PATH variable
49
50 To build HAT we will need `JAVA_HOME` to point to our prebuilt babylon jdk
51
52 I suggest you also create a `JEXTRACT_HOME` var to point to the location where you placed JEXTRACT)
53
54 In my case
55 ```
56 export JEXTRACT_HOME=/Users/me/jextract-22
57 ```
58
59 Make sure also that `cmake` in in your PATH
60
61 ## ./env.bash
62
63 Thankfully just sourcing the top level `env.bash` script should then be able to set up your PATH for you.
64
65 It should detect the arch type (AARCH64 or X86_46) and
66 select the correct relative parent dir for your BABYLON_JDK and inject that dir in your PATH.
67
68 It should also add jextract to your PATH (based on the value you set above for JEXTRACT_HOME)
69
70
71
72 ```bash
73 cd hat
74 export JEXTRACT_HOME=/Users/me/jextract-22
75 . ./env.bash
76 echo ${JAVA_HOME}
77 /Users/me/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
78 echo ${PATH}
79 /Users/me/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/Users/me/jextract-22/bin:/usr/local/bin:......
80 ```
81
82 ## Building using bld
83
84 To build hat artifacts (hat jar + backends and examples)
85 ```bash
86 java @hat/bld
87 ```
88
89 This places build artifacts in the `build` and `stages` dirs
90
91 ```bash
92 cd hat
93 . ./env.bash
94 java @hat/bld
95 ls build
96 hat-1.0.jar hat-example-heal-1.0.jar libptx_backend.dylib
97 hat-backend-ffi-cuda-1.0.jar hat-example-mandel-1.0.jar libspirv_backend.dylib
98 hat-backend-ffi-mock-1.0.jar hat-example-squares-1.0.jar mock_info
99 hat-backend-ffi-opencl-1.0.jar hat-example-view-1.0.jar opencl_info
100 hat-backend-ffi-ptx-1.0.jar hat-example-violajones-1.0.jar ptx_info
101 hat-backend-ffi-spirv-1.0.jar libmock_backend.dylib spirv_info
102 hat-example-experiments-1.0.jar libopencl_backend.dylib
103 ls stage
104 opencl_jextracted opengl_jextracted
105 ```
106
107 `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)
108
109 We have another script called `sanity` which will check all .md/.java/.cpp/.h for tabs, lines that end with whitespace
110 or files without appropriate licence headers
111
112 This is run using
113
114 ```
115 java @hat/sanity
116 ```
117
118
119 ## Running an example
120
121 To run a HAT example we can run from the artifacts in `build` dir
122
123 ```bash
124 ${JAVA_HOME}/bin/java \
125 --add-modules jdk.incubator.code --enable-preview --enable-native-access=ALL-UNNAMED \
126 --class-path build/hat-1.0.jar:build/hat-example-mandel-1.0.jar:build/hat-backend-ffi-opencl-1.0.jar \
127 --add-exports=java.base/jdk.internal=ALL-UNNAMED \
128 -Djava.library.path=build\
129 mandel.Main
130 ```
131
132 The `hat/run.java` script can also be used which simply needs the backend
133 name `ffi-opencl|ffi-java|ffi-cuda|ffi-ptx|ffi-mock` and the package name `mandel`
134
135 ```bash
136 java @hat/run ffi-opencl mandel
137 ```
138
139 If you pass `headless` as the first arg
140
141 ```bash
142 java @hat/run headless opencl mandel
143 ```
144
145 This sets `-Dheadless=true` and passes '--headless' to the example. Some examples can use this to avoid launching UI.
146
147
148 # More Bld info
149 `hat/Script.java` is an evolving set of static methods and types required (so far.. ;) )
150 to be able to build HAT, hat backends and examples via the `bld` script
151
152 We rely on java's ability to launch java source directly (without needing to javac first)
153
154 * [JEP 458: Launch Multi-File Source-Code Program](https://openjdk.org/jeps/458)
155 * [JEP 330: Launch Single-File Source-Code Programs](https://openjdk.org/jeps/330)
156
157 The `hat/bld.java` script (really java source) can be run like this
158
159 ```bash
160 java --add-modules jdk.incubator.code --enable-preview --source 25 bld
161 ```
162
163 In our case the magic is under the `hat`subdir
164
165 We also have a handy `hat/XXXX` which allows us to avoid specifying common args `--enable-preview --source 25` eash time we launch a script
166
167 ```
168 hat
169 ├── hat
170 | ├── Script.java
171 | ├── sanity (the args for sanity.java) "--enable-preview --source 25 sanity"
172 | |-- sanity.java (the script)
173 | ├── run (the args for sanity.java) "--enable-preview --source 25 hatrun"
174 | |-- run.java (the script)
175 | ├── bld (the args for bld.java) "--enable-preview --source 25 bld"
176 | ├── bld.java (the script)
177
178 ```
179
180 For example
181 ```bash
182 java @hat/bld
183 ```
184
185 Is just a shortcut for
186 ```bash
187 java --enable-preview --source 25 hat/bld.java
188 ```