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