1 # HAT Project
2
3 This is a fairly large project with Java and native (C/C++) artifacts.
4
5 To use HAT you will need to clone and build the `babylon` (JDK23+Babylon) project or of course your fork of the babylon project (say `babylon-myfork`)
6
7 [github.com/openjdk/babylon](https://github.com/openjdk/babylon)
8
9 The HAT project is in the 'hat' subdir of the babylon project.
10
11 We will walk through the initial steps to clone and build babylon and then focus on the steps for building HAT.
12
13 If you follow these steps, you should not have to change any of the maven or cmake build files.
14
15 We suggest starting with a 'github' dir and a dir where we will need to install jdk22
16
17 ```
18 export GITHUB=${HOME}/github
19 mkdir -p ${GITHUB}
20 mkdir -p ${HOME}/java
21 ```
22
23 We need an existing jdk22 build to build babylon. These steps are slightly different for Mac OSX and Ubuntu
24
25 ### Ubuntu
26
27 ```
28 cd ${HOME}/java
29 wget https://download.java.net/java/GA/jdk22.0.1/c7ec1332f7bb44aeba2eb341ae18aca4/8/GPL/openjdk-22.0.1_linux-x64_bin.tar.gz
30 export BOOT_JDK=${HOME}/java/jdk-22.0.1.jdk
31 ```
32
33 ### Mac OSX Aarch64
34 ```
35 cd ${HOME}/java
36 wget https://download.java.net/java/GA/jdk22.0.1/c7ec1332f7bb44aeba2eb341ae18aca4/8/GPL/openjdk-22.0.1_linux-x64_bin.tar.gz
37 export BOOT_JDK=${HOME}/java/jdk-22.0.1.jdk/Contents/Home
38 ```
39
40 From now on the Mac and Ubuntu steps are the same.
41
42 If you have your own fork of the babylon repo use it rather that babylon.git below.
43
44 ```
45 cd ${GITHUB}
46 git clone https://github.com/openjdk/babylon.git
47 cd ${GITHUB}/babylon
48 bash configure --with-boot-jdk=${BOOT_JDK}
49 make clean
50 make images
51 ```
52 If you have never built JDK before you may find that the 'configure' step will suggest packages to install.
53
54 I usually just take the suggestions and try running `bash configure` again.
55
56 Eventually you will have a successful babylon build.
57
58 You now should have
59
60 ```
61 github
62 ├── babylon (or babylon-my-fork)
63 │ ├── build
64 │ │ └── XXXX-server-release
65 │ │ ├── jdk
66 │ │ └── ...
67 │ ├── hat
68 │ │ ├── README.md
69
70 ```
71 Where XXXX is either linux-x64 or macosx-aarch64 and contains your build of babylon JDK.
72
73 ## Building HAT
74
75 HAT uses maven and cmake.
76
77 Maven controls the build but delegates to cmake to build the native code for the various backends.
78
79 To build HAT we need to ensure that `JAVA_HOME` is set up to point to the babylon build (that we just created) and that `${JAVA_HOME}/bin` is in your PATH.
80
81 The `env.bash` shell script can be sourced (dot included) in your shell to set up these vars.
82
83 It should detect the arch type and select the correct relative parent dir and inject that dir in your PATH.
84
85 ```bash
86 cd hat
87 . ./env.bash
88 echo ${JAVA_HOME}
89 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk
90 echo ${PATH}
91 /Users/ME/github/babylon/hat/../build/macosx-aarch64-server-release/jdk/bin:/usr/local/bin:......
92 ```
93
94 Now we should be able to use maven to build, it will do its magic and place all jars and libs in `maven-build` dir
95
96 ```
97 cd hat
98 . ./env.bash
99 mvn clean compile jar:jar install
100 ls maven-build
101 hat-1.0.jar hat-example-heal-1.0.jar libptx_backend.dylib
102 hat-backend-cuda-1.0.jar hat-example-mandel-1.0.jar libspirv_backend.dylib
103 hat-backend-mock-1.0.jar hat-example-squares-1.0.jar mock_info
104 hat-backend-opencl-1.0.jar hat-example-view-1.0.jar opencl_info
105 hat-backend-ptx-1.0.jar hat-example-violajones-1.0.jar ptx_info
106 hat-backend-spirv-1.0.jar libmock_backend.dylib spirv_info
107 hat-example-experiments-1.0.jar libopencl_backend.dylib
108 ```
109
110 To run an example
111 ```
112 ${JAVA_HOME}/bin/java \
113 --enable-preview --enable-native-access=ALL-UNNAMED \
114 --class-path maven-build/hat-1.0.jar:maven-build/hat-example-mandel-1.0.jar:maven-build/hat-backend-opencl-1.0.jar \
115 --add-exports=java.base/jdk.internal=ALL-UNNAMED \
116 -Djava.library.path=maven-build\
117 mandel.MandelCompute
118 ```
119
120 The `hatrun.bash` script simplifies this somewhat
121
122 ```
123 bash hatrun.bash opencl mandel MandelCompute
124 ```
125
126 ### Intellij and Clion
127 We can use JetBrains' `intelliJ` and `clion` but care must be taken as these tools
128 do not play well together, specifically we cannot have `Clion` and `Intellij`
129 project artifacts rooted under each other or in the same dir.
130
131 The `intellij` subdir houses the various `*.iml` module files and the project `.idea` so
132 just open that dir as an intellij project
133
134 Thankfully `clion` uses cmake. So we can reuse the same `hat/backends/CMakeLists.txt` that
135 maven uses to build the backends.
136
137 ### Initial Project Layout
138
139 ```
140 ${BABYLON_JDK}
141 └── hat
142 ├── maven-build (created by the build)
143 │
144 ├── intellij
145 │ ├── .idea
146 │ │ ├── compiler.xml
147 │ │ ├── misc.xml
148 │ │ ├── modules.xml
149 │ │ ├── uiDesigner.xml
150 │ │ ├── vcs.xml
151 │ │ └── workspace.xml
152 │ │
153 │ ├── hat.iml
154 │ ├── backend_(spirv|mock|cuda|ptx|opencl).iml
155 │ └── (mandel|violajones|experiments|heal|view).iml
156 │
157 ├── hat
158 │ ├── pom.xml
159 │ └── src
160 │ ├── src/main/java
161 │ └── src/main/resources
162 │
163 ├── backends
164 │ ├── pom.xml
165 │ ├── CMakeLists.txt
166 │ └── (opencl|cuda|ptx|mock|shared)
167 │ ├── pom.xml
168 │ ├── CMakeLists.txt
169 │ ├── cpp
170 │ ├── include
171 │ ├── src/main/java
172 │ └── src/main/resources
173 └── examples
174 ├── pom.xml
175 └── (mandel|violajones|squares|heal|view|experiments)
176 ├── pom.xml
177 ├── src/main/java
178 └── src/main/resources
179 ```
180 As you will note the `intellij` dir is somewhat self contained. the various `*.iml`
181 files refer to the source dirs using relative paths.