1 # Building HAT
2
3 ----
4 * [Contents](hat-00.md)
5 * Build Babylon and HAT
6 * [Quick Install](hat-01-quick-install.md)
7 * [Building Babylon with jtreg](hat-01-02-building-babylon.md)
8 * [Building HAT with jtreg](hat-01-03-building-hat.md)
9 * [Enabling the NVIDIA CUDA Backend](hat-01-05-building-hat-for-cuda.md)
10 * [Testing Framework](hat-02-testing-framework.md)
11 * [Running Examples](hat-03-examples.md)
12 * [HAT Programming Model](hat-03-programming-model.md)
13 * Interface Mapping
14 * [Interface Mapping Overview](hat-04-01-interface-mapping.md)
15 * [Cascade Interface Mapping](hat-04-02-cascade-interface-mapping.md)
16 * Development
17 * [Project Layout](hat-01-01-project-layout.md)
18 * Implementation Details
19 * [Walkthrough Of Accelerator.compute()](hat-accelerator-compute.md)
20 * [How we minimize buffer transfers](hat-minimizing-buffer-transfers.md)
21 * [Running HAT with Docker on NVIDIA GPUs](hat-07-docker-build-nvidia.md)
22 ---
23
24 # Building HAT
25
26 We can build HAT using maven and cmake.
27
28 Maven controls the build but delegates to cmake for native artifacts (such as various backends).
29
30 Note: You should not edit the pom.xml files, these are autogenerated (using mkpoms) and your changes will get overwritten.
31
32
33 ## Setting environment variables JAVA_HOME and PATH
34
35 To build HAT we need to ensure that `JAVA_HOME` is set
36 to point to our babylon jdk (the one we built [here](hat-01-02-building-babylon.md))
37
38 It will simplify our tasks going forward if we add `${JAVA_HOME}/bin` to our PATH (before any other JAVA installs).
39
40 The `env.bash` shell script can be sourced (dot included) in your shell to set JAVA_HOME and PATH
41
42 It should detect the arch type (AARCH64 or X86_46) and select the correct relative parent dir and inject that dir in your PATH.
43
44 You will need jextract for your platform, and the jextract/bin dir should also be in your path.
45
46
47 ```bash
48 cd hat
49 . ./env.bash
50 export PATH=${PATH}:/path/to/my/jextract/bin
51 echo ${JAVA_HOME}
52 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
53 echo ${PATH}
54 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/usr/local/bin:......
55 ```
56
57 ## Root level maven pom.xml properties
58
59 If you followed the instructions for building babylon your `pom.xml`
60 properties should look like this, and should not need changing
61
62 ```xml
63 <project>
64 <!-- yada -->
65 <properties>
66 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
67 <hat.build>${env.PWD}/build</hat.build>
68 </properties>
69 <!-- yada -->
70 </project>
71 ```
72 ## Sanity checking your env and root pom.xml
73
74 After sourcing `env.bash` or making changes to `pom.xml` we can
75 sanity check our setup by running
76
77 ```bash
78 cd hat
79 java @bldr/sanity
80 ```
81
82 ## Building with maven
83
84 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.
85
86 ```bash
87 cd hat
88 . ./env.bash
89 mvn clean compile package install
90 ls build
91 hat-1.0.jar hat-example-heal-1.0.jar libptx_backend.dylib
92 hat-backend-ffi-cuda-1.0.jar hat-example-mandel-1.0.jar libspirv_backend.dylib
93 hat-backend-ffi-mock-1.0.jar hat-example-squares-1.0.jar mock_info
94 hat-backend-ffi-opencl-1.0.jar hat-example-view-1.0.jar opencl_info
95 hat-backend-ffi-ptx-1.0.jar hat-example-violajones-1.0.jar ptx_info
96 hat-backend-ffi-spirv-1.0.jar libmock_backend.dylib spirv_info
97 hat-example-experiments-1.0.jar libopencl_backend.dylib
98 ```
99
100 The provided `maven-build.bash` script contains the minimal maven commandline
101
102 ```bash
103 bash maven-build.bash
104 ```
105
106 ## Running an example
107
108 To run an example we use the maven artifacts in `build`
109
110 ```bash
111 ${JAVA_HOME}/bin/java \
112 --enable-preview --enable-native-access=ALL-UNNAMED \
113 --class-path build/hat-1.0.jar:build/hat-example-mandel-1.0.jar:build/hat-backend-ffi-opencl-1.0.jar \
114 --add-exports=java.base/jdk.internal=ALL-UNNAMED \
115 -Djava.library.path=build\
116 mandel.Main
117 ```
118
119 The provided `hat/run` java launch script simplifies this somewhat, we just need to pass the backend name `ffi-opencl` and the package name `mandel`
120 (all examples are assumed to be in `packagename/Main.java`
121
122 ```bash
123 java @hat/run ffi-opencl mandel
124 ```