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
21
22 HAT uses both maven and cmake.
23
24 Maven controls the build but delegates to cmake for native artifacts (such as various backends).
25
26
27 ## Setting environment variables JAVA_HOME and PATH
28
29 To build HAT we need to ensure that `JAVA_HOME` is set
30 to point to our babylon jdk (the one we built [here](hat-01-02-building-babylon.md))
31
32 It will simplify our tasks going forward if we add `${JAVA_HOME}/bin` to our PATH (before any other JAVA installs).
33
34 The `env.bash` shell script can be sourced (dot included) in your shell to set JAVA_HOME and PATH
35
36 It should detect the arch type (AARCH64 or X86_46) and select the correct relative parent dir and inject that dir in your PATH.
37
38 ```bash
39 cd hat
40 . ./env.bash
41 echo ${JAVA_HOME}
42 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
43 echo ${PATH}
44 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/usr/local/bin:......
45 ```
46
47 ## Root level maven pom.xml properties
48
49 If you followed the instructions for building babylon your `pom.xml`
50 properties should look like this, and should not need changing
51
52 ```xml
53 <project>
54 <!-- yada -->
55 <properties>
56 <babylon.repo.name>babylon</babylon.repo.name> <!--replace with your fork name -->
57 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
58 <maven.compiler.source>24</maven.compiler.source>
59 <maven.compiler.target>24</maven.compiler.target>
60 <github.dir>${env.HOME}/github</github.dir>
61 <beehive.spirv.toolkit.dir>${github.dir}/beehive-spirv-toolkit/</beehive.spirv.toolkit.dir>
62 <babylon.dir>${github.dir}/${babylon.repo.name}</babylon.dir>
63 <hat.dir>${babylon.dir}/hat</hat.dir>
64 <hat.target>${hat.dir}/build</hat.target>
65 </properties>
66 <!-- yada -->
67 </project>
68 ```
69 If say your github dir (the one containing babylon) is somewhere other than `${HOME}/github` then make sure that `github.dir` is
70 set accordingly.
71
72 ```xml
73 <properties>
74 <!-- ... -->
75 <github.dir>/full/path/to/github</github.dir>
76 <!-- ... -->
77 </properties>
78 ```
79
80 ## Sanity checking your env and root pom.xml
81
82 After sourcing `env.bash` or making changes to `pom.xml` we can
83 sanity check our setup by running
84
85 ```bash
86 cd hat
87 java sanity.java
88 ```
89
90 This will check that your `PATH` includes your babylon JDK's bin dir, and will parse the top level `pom.xml` to ensure that that
91 the properties are pointing to `sane` values.
92
93 ## Building with maven
94
95 Now we should be able to use maven to build, if successful maven will place all jars and libs in a newly created `build` dir in your top level hat dir.
96
97 ```bash
98 cd hat
99 . ./env.bash
100 mvn clean compile jar:jar install
101 ls build
102 hat-1.0.jar hat-example-heal-1.0.jar libptx_backend.dylib
103 hat-backend-cuda-1.0.jar hat-example-mandel-1.0.jar libspirv_backend.dylib
104 hat-backend-mock-1.0.jar hat-example-squares-1.0.jar mock_info
105 hat-backend-opencl-1.0.jar hat-example-view-1.0.jar opencl_info
106 hat-backend-ptx-1.0.jar hat-example-violajones-1.0.jar ptx_info
107 hat-backend-spirv-1.0.jar libmock_backend.dylib spirv_info
108 hat-example-experiments-1.0.jar libopencl_backend.dylib
109 ```
110
111 The provided `build.sh` script contains the minimal maven commandline
112
113 ```bash
114 bash build.sh
115 ```
116
117 ## Running an example
118
119 To run an example we should be able to use the maven artifacts in `build`
120
121 ```bash
122 ${JAVA_HOME}/bin/java \
123 --enable-preview --enable-native-access=ALL-UNNAMED \
124 --class-path build/hat-1.0.jar:build/hat-example-mandel-1.0.jar:build/hat-backend-opencl-1.0.jar \
125 --add-exports=java.base/jdk.internal=ALL-UNNAMED \
126 -Djava.library.path=build\
127 mandel.Main
128 ```
129
130 The provided `hatrun.bash` script simplifies this somewhat, we just need to pass the backend name `opencl` and the package name `mandel`
131 (all examples are assumed to be in `packagename/Main.java`
132
133 ```bash
134 bash hatrun.bash opencl mandel
135 ```