Skip to content

Commit 140b9b4

Browse files
lucaspimentellucaspimentel
committed
more changes in BUILDING.md
1 parent 8800182 commit 140b9b4

File tree

1 file changed

+112
-92
lines changed

1 file changed

+112
-92
lines changed

‎BUILDING.md‎

Lines changed: 112 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,42 @@
1-
# Building
1+
# Building <!-- omit from toc -->
22

33
This documentation provides information for developers to set up their environment and build their project from sources.
44

5-
* [Development environment quick check](#development-environment-quick-check)
6-
* [Environment requirements quick check](#environment-requirements-quick-check)
7-
* [Development environment set up](#development-environment-set-up)
8-
* [Project build](#project-build)
5+
* [Development environment](#development-environment)
6+
* [Requirements](#requirements)
7+
* [Quick check](#quick-check)
8+
* [Install the required JDKs](#install-the-required-jdks)
9+
* [Install git](#install-git)
10+
* [Install Docker Desktop](#install-docker-desktop)
11+
* [Clone the repository and set up git](#clone-the-repository-and-set-up-git)
12+
* [Building the project](#building-the-project)
913

10-
## Development environment quick check
14+
## Development environment
1115

12-
To check that your development environment is properly set up to build the project, run `./setup.sh` on macOS or Linux (or `.\setup.ps1` on Windows) from the project root. Your output should look something like the following:
16+
### Requirements
17+
18+
Requirements to build the full project:
19+
20+
* The JDK versions 8, 11, 17 and 21 must be installed.
21+
* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME` and `JAVA_GRAALVM17_HOME` must point to their respective JDK location.
22+
* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
23+
* The `JAVA_HOME` environment variable may be unset. If set, it must point to the JDK 8 location (same as `JAVA_8_HOME`).
24+
* The `git` command line must be installed.
25+
* A container runtime environment must be available to run all tests (e.g. Docker Desktop).
26+
27+
### Quick check
28+
29+
To check that your development environment is properly set up to build the project, from the project root run on macOS or Linux:
30+
```shell
31+
./setup.sh
32+
```
33+
34+
or on Windows:
35+
```pwsh
36+
.\setup.ps1
37+
```
38+
39+
Your output should look something like the following:
1340

1441
```
1542
ℹ️ Checking required JVM:
@@ -29,41 +56,32 @@ To check that your development environment is properly set up to build the proje
2956
✅ The Docker server is running.
3057
```
3158

32-
If there is any issue with your output, you can check the requirements and/or follow the guide below to install and configure the required tools.
59+
If there is any issue with your output, check the requirements above and use the following guide to install and configure the required tools.
3360

34-
## Environment requirements quick check
35-
36-
Requirements to build the full project:
37-
38-
* The JDK versions 8, 11, 17 and 21 must be installed.
39-
* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME` and `JAVA_GRAALVM17_HOME` must point to their respective JDK location.
40-
* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
41-
* The `JAVA_HOME` environment variable may be unset. If set, it must point to the JDK 8 location (same as `JAVA_8_HOME`).
42-
* The `git` command line must be installed.
43-
* A container runtime environment must be available to run all tests (e.g. Docker Desktop).
44-
45-
## Development environment set up
4661

4762
### Install the required JDKs
4863

4964
Download and install Eclipse Temurin JDK versions 8, 11, 17 and 21, and GraalVM.
5065

51-
<details>
52-
<summary>macOS</summary>
66+
#### macOS
5367

54-
* Install the required JDKs using `brew`.
55-
`brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17`
56-
* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/).
57-
`sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>`
68+
* Install the required JDKs using `brew`:
69+
```shell
70+
brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17
71+
```
72+
* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/):
73+
```
74+
sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>
75+
```
5876
* Add the required environment variables to your shell using the `export` command. You can permanently install the environment variables by appending the `export` commands into your shell configuration file `~/.zshrc` or `.bashrc` or other.
59-
```shell
60-
export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
61-
export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home
62-
export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
63-
export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home
64-
export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>/Contents/Home
65-
export JAVA_HOME=$JAVA_8_HOME
66-
```
77+
```shell
78+
export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
79+
export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home
80+
export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
81+
export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home
82+
export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>/Contents/Home
83+
export JAVA_HOME=$JAVA_8_HOME
84+
```
6785
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.
6886

6987
> [!NOTE]
@@ -72,34 +90,34 @@ export JAVA_HOME=$JAVA_8_HOME
7290
> [Amazon Corretto](https://aws.amazon.com/corretto/) builds have also been proven to work.
7391
7492
> [!NOTE]
75-
> MacOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path.
76-
77-
</details>
93+
> macOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path.
7894
79-
<details>
80-
<summary>Linux</summary>
95+
#### Linux
8196

8297
* Download and extract JDK 8, 11, 17, and 21 from [Eclipse Temurin releases](https://adoptium.net/temurin/releases/) and GraalVM from [Oracle downloads](https://www.graalvm.org/downloads/).
8398
* Install the GraalVM native image requirements for native builds by following [the GraalVM official documentation](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites).
8499
* Add the required environment variables to your shell using the `export` command. You can permanently install the environment variables by appending the `export` commands into your shell configuration file `~/.zshrc` or `~/.bashrc` or other.
85-
```shell
86-
export JAVA_8_HOME=/<path to extracted archive>/jdk8u<current version of JDK 8>
87-
export JAVA_11_HOME=/<path to extracted archive>/jdk-11.<current version of JDK 11>
88-
export JAVA_17_HOME=/<path to extracted archive>/jdk-17.<current version of JDK 17>
89-
export JAVA_21_HOME=/<path to extracted archive>/jdk-21.<current version of JDK 21>
90-
export JAVA_GRAALVM17_HOME=/<path to extracted archive>/graalvm-jdk-17.<current version of graalvm>/Contents/Home
91-
export JAVA_HOME=$JAVA_8_HOME
92-
```
100+
```shell
101+
export JAVA_8_HOME=/<path to extracted archive>/jdk8u<current version of JDK 8>
102+
export JAVA_11_HOME=/<path to extracted archive>/jdk-11.<current version of JDK 11>
103+
export JAVA_17_HOME=/<path to extracted archive>/jdk-17.<current version of JDK 17>
104+
export JAVA_21_HOME=/<path to extracted archive>/jdk-21.<current version of JDK 21>
105+
export JAVA_GRAALVM17_HOME=/<path to extracted archive>/graalvm-jdk-17.<current version of graalvm>/Contents/Home
106+
export JAVA_HOME=$JAVA_8_HOME
107+
```
93108
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.
94109

95-
</details>
96-
97-
<details>
98-
<summary>Windows</summary>
110+
#### Windows
99111

100112
Use the `install-jdks-windows.ps1` script to download and install Eclipse Temurin JDK versions 8, 11, 17, and 21, and set the required environment variables.
101113

102-
To install the JDKs manually using `winget`, use the following commands. After the JDKs are installed, you can still use `install-jdks-windows.ps1` to add the environment variables.
114+
> [!NOTE]
115+
> This scripts currently does _not_ install GraalVM.
116+
117+
<details>
118+
<summary>Manual installation</summary>
119+
120+
* To install the JDKs manually, download the installers from [Eclipse Temurin releases](https://adoptium.net/temurin/releases/) and GraalVM from [Oracle downloads](https://www.graalvm.org/downloads/), or use `winget`:
103121

104122
```
105123
winget install --id EclipseAdoptium.Temurin.8.JDK
@@ -108,68 +126,76 @@ winget install --id EclipseAdoptium.Temurin.17.JDK
108126
winget install --id EclipseAdoptium.Temurin.21.JDK
109127
```
110128

111-
To install the JDKs manually:
112-
* Download SDKs manually from [Eclipse Temurin releases](https://adoptium.net/temurin/releases/) and GraalVM from [Oracle downloads](https://www.graalvm.org/downloads/).
113129
* Install the GraalVM native image requirements for native builds by following [the GraalVM official documentation](https://www.graalvm.org/latest/docs/getting-started/windows/#prerequisites-for-native-image-on-windows).
114130

115-
To add the required environment variables manually from PowerShell, run this command for each SDK version:
116-
```pwsh
117-
[Environment]::SetEnvironmentVariable("JAVA_8_HOME", "C:\Program Files\Eclipse Adoptium\jdk-<version>-hotspot", [EnvironmentVariableTarget]::User)
118-
```
131+
* To add the required environment variables, run this PowerShell command for each SDK version:
132+
```pwsh
133+
[Environment]::SetEnvironmentVariable("JAVA_<version>_HOME", "C:\Program Files\Eclipse Adoptium\<path>", [EnvironmentVariableTarget]::User)
134+
```
119135

120-
To add the required environment variables manually using the UI:
121-
* Open the *Start Menu*, type `environment variable`, and use the *Edit environment variable for your account* entry to open the *System Properties*.
122-
* Add new entries to the table:
123-
* `JAVA_8_HOME` to the JDK 8 installation folder, usually `C:\Program Files\Eclipse Adoptium\jdk-<current version of Java 8>-hotspot\bin`
124-
* `JAVA_11_HOME`, `JAVA_17_HOME`, and `JAVA_21_HOME` similarly to their respective installation `bin` folders
125-
* `JAVA_GRAALVM17_HOME` to the GraalVM installation folder, usually `C:\Program Files\Java\<current version of graalvm>\bin`
136+
For example:
137+
```pwsh
138+
[Environment]::SetEnvironmentVariable("JAVA_8_HOME", "C:\Program Files\Eclipse Adoptium\jdk-8.0.432.6-hotspot", [EnvironmentVariableTarget]::User)
139+
```
126140

127141
</details>
128142

129-
### Install `git`
143+
### Install git
130144

131-
**On macOS:**
145+
#### macOS
132146

133147
You can trigger the installation by running any `git` command from the terminal, e.g. `git --version`.
134148
If not installed, the terminal will prompt you to install it.
135149

136-
**On Linux:**
150+
#### Linux
151+
152+
```shell
153+
apt-get install git
154+
```
137155

138-
Run `apt-get install git`.
156+
#### Windows
139157

140-
**On Windows:**
158+
```pwsh
159+
winget install --id git.git
160+
```
141161

142-
Run `winget install --id git.git`. Alternatively, download and install the installer from [the official website](https://git-scm.com/download/win).
162+
Alternatively, download and install the installer from [the official website](https://git-scm.com/download/win).
143163

144164
### Install Docker Desktop
145165

146166
> [!NOTE]
147167
> Docker Desktop is the recommended container runtime environment, but you can use any other environment to run testcontainers tests.
148168
> Check [the testcontainers container runtime requirements](https://java.testcontainers.org/supported_docker_environment/) for more details.
149169
150-
**On macOS:**
170+
#### macOS
171+
172+
Download and install Docker Desktop from the offical website:<br/>
173+
https://docs.docker.com/desktop/setup/install/mac-install/
151174

152-
Download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/mac-install/
175+
#### Linux
153176

154-
**On Linux:**
177+
Download and install Docker Desktop from the offical website:<br/>
178+
https://docs.docker.com/desktop/setup/install/linux/
155179

156-
Download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/linux/
180+
#### Windows
157181

158-
**On Windows:**
182+
Use `winget` to install Docker Desktop:
159183

160-
Run `winget install --id Docker.DockerDesktop`.
184+
```pwsh
185+
winget install --id Docker.DockerDesktop
186+
```
161187

162-
Alternatively, download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/windows-install/
188+
Alternatively, download and install Docker Desktop from the offical website:<br/>
189+
https://docs.docker.com/desktop/setup/install/windows-install/
163190

164-
### Clone the repository and set up git
191+
## Clone the repository and set up git
165192

166193
* Get a copy of the project by cloning the repository using git in your workspace:
167-
```bash
194+
```shell
168195
git clone --recurse-submodules [email protected]:DataDog/dd-trace-java.git
169196
```
170197
* There is a pre-commit hook setup to verify formatting before committing. It can be activated with the following command:
171-
```bash
172-
# On bash-like shells shells or PowerShell
198+
```shell
173199
cd dd-trace-java
174200
cp .githooks/pre-commit .git/hooks/
175201
```
@@ -182,7 +208,7 @@ Alternatively, download and install Docker Desktop from the offical website: htt
182208
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
183209
184210
* Configure git to automatically update submodules.
185-
```bash
211+
```shell
186212
git config --local submodule.recurse true
187213
```
188214
@@ -197,23 +223,17 @@ Alternatively, download and install Docker Desktop from the offical website: htt
197223
> [!NOTE]
198224
> Both git configurations (hooks and submodule) will only be applied to this project and won't apply globally in your setup.
199225

200-
### Check your development environment
201-
202-
You can confirm that your development environment is properly set up using the [quick check](#development-environment-quick-check) `setup.sh` script on macOS or Linux or `setup.ps1` on Windows.
203-
204-
### Build the project
226+
## Building the project
205227

206228
After everything is properly set up, you can move on to the next section to start a build or check [the contribution guidelines](CONTRIBUTING.md).
207229

208-
## Project build
209-
210230
To build the project without running tests, run:
211-
```bash
231+
```shell
212232
./gradlew clean assemble
213233
```
214234

215235
To build the entire project with tests (this can take a very long time), run:
216-
```bash
236+
```shell
217237
./gradlew clean build
218238
```
219239

@@ -223,7 +243,7 @@ To build the entire project with tests (this can take a very long time), run:
223243
> It is recommended to only run the tests related to your changes locally and leave running the whole test suite to the continuous integration platform.
224244

225245
To build the JVM agent artifact only, run:
226-
```bash
246+
```shell
227247
./gradlew :dd-java-agent:shadowJar
228248
```
229249

0 commit comments

Comments
 (0)