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