Skip to content

Commit edab42a

Browse files
lucaspimentellucaspimentel
committed
add more Windows instructions, misc tweaks in BUILDING.md
1 parent 3ed8d57 commit edab42a

File tree

1 file changed

+83
-53
lines changed

1 file changed

+83
-53
lines changed

‎BUILDING.md‎

Lines changed: 83 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
# Building
32

43
This documentation provides information for developers to set up their environment and build their project from sources.
@@ -10,10 +9,9 @@ This documentation provides information for developers to set up their environme
109

1110
## Development environment quick check
1211

13-
To check that your development environment is properly set up to build the project, run `./setup.sh` from the project root. Your output should look something like the following.
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:
1413

15-
```bash
16-
$ ./setup.sh
14+
```
1715
ℹ️ Checking required JVM:
1816
✅ JAVA_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
1917
✅ JAVA_8_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
@@ -48,7 +46,10 @@ Requirements to build the full project:
4846

4947
### Install the required JDKs
5048

51-
**On MacOS:**
49+
Download and install Eclipse Temurin JDK versions 8, 11, 17 and 21, and GraalVM.
50+
51+
<details open>
52+
<summary>macOS<summary>
5253

5354
* Install the required JDKs using `brew`.
5455
`brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17`
@@ -73,9 +74,12 @@ export JAVA_HOME=$JAVA_8_HOME
7374
> [!NOTE]
7475
> MacOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path.
7576
76-
**On Linux:**
77+
</details>
78+
79+
<details>
80+
<summary>Linux<summary>
7781

78-
* 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/).
82+
* 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/).
7983
* 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).
8084
* 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.
8185
```shell
@@ -88,18 +92,41 @@ export JAVA_HOME=$JAVA_8_HOME
8892
```
8993
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.
9094

91-
**On Windows:**
95+
</details>
96+
97+
<details>
98+
<summary>Windows<summary>
99+
100+
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.
92101

93-
* Download and install 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/).
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.
103+
104+
```
105+
winget install --id EclipseAdoptium.Temurin.8.JDK
106+
winget install --id EclipseAdoptium.Temurin.11.JDK
107+
winget install --id EclipseAdoptium.Temurin.17.JDK
108+
winget install --id EclipseAdoptium.Temurin.21.JDK
109+
```
110+
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/).
94113
* 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).
95-
* Add the required environment variables.
96-
* Open the *Start Menu*, type `environment variable`, and use the *Edit environment variable for your account* entry to open the *System Properties*.
97-
* Add new entries to the table.
98-
* `JAVA_8_HOME` to the JDK 8 installation folder, usually `C:\Program Files\Eclipse Adoptium\jdk-<current version of Java 8>-hotspot\bin`
99-
* `JAVA_11_HOME`, `JAVA_21_HOME`, and `JAVA_21_HOME` similarly to their respective installation `bin` folders
100-
* `JAVA_GRAALVM17_HOME` to the GraalVM installation folder, usually `C:\Program Files\Java\<current version of graalvm>\bin`
101114

102-
### Install git
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+
```
119+
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`
126+
127+
</details>
128+
129+
### Install `git`
103130

104131
**On MacOS:**
105132

@@ -112,64 +139,67 @@ Run `apt-get install git`.
112139

113140
**On Windows:**
114141

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

117144
### Install Docker Desktop
118145

119-
Download and install Docker Desktop from the offical website for [MacOS](https://docs.docker.com/desktop/install/mac-install/), [Linux](https://docs.docker.com/desktop/install/linux-install/) or [Windows](https://docs.docker.com/desktop/install/windows-install/).
120-
121146
> [!NOTE]
122147
> Docker Desktop is the recommended container runtime environment, but you can use any other environment to run testcontainers tests.
123148
> Check [the testcontainers container runtime requirements](https://java.testcontainers.org/supported_docker_environment/) for more details.
124149
125-
### Clone the repository and set up git
150+
**On macOS:**
126151

127-
* Get a copy of the project.
128-
* In your workspace, clone the repository using git.
129-
```bash
130-
git clone --recurse-submodules [email protected]:DataDog/dd-trace-java.git
131-
```
132-
* Install the project git hooks.
133-
* There is a pre-commit hook setup to verify formatting before committing. It can be activated with the following command.
134-
```bash
135-
# On MacOS and Linux
136-
cd dd-trace-java
137-
cp .githooks/pre-commit .git/hooks/
152+
Download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/mac-install/
138153

139-
# On Windows
140-
cd dd-trace-java
141-
copy .githooks/pre-commit .git/hooks/
142-
```
154+
**On Linux:**
143155

144-
> [!TIP]
145-
> You can alternatively use the `core.hooksPath` configuration to point to the `.githooks` folder using `git config --local core.hooksPath .githooks` if you don't already have a hooks path defined system-wide.
156+
Download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/linux/
146157

147-
> [!NOTE]
148-
> The git hooks will check that your code is properly formatted before commiting.
149-
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
158+
**On Windows:**
159+
160+
Run `winget install --id Docker.DockerDesktop`.
161+
162+
Alternatively, download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/windows-install/
163+
164+
### Clone the repository and set up git
165+
166+
* Get a copy of the project by cloning the repository using git in your workspace:
167+
```bash
168+
git clone --recurse-submodules [email protected]:DataDog/dd-trace-java.git
169+
```
170+
* 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
173+
cd dd-trace-java
174+
cp .githooks/pre-commit .git/hooks/
175+
```
176+
177+
> [!TIP]
178+
> You can alternatively use the `core.hooksPath` configuration to point to the `.githooks` folder using `git config --local core.hooksPath .githooks` if you don't already have a hooks path defined system-wide.
179+
180+
> [!NOTE]
181+
> The git hooks will check that your code is properly formatted before commiting.
182+
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
150183
151184
* Configure git to automatically update submodules.
152-
```bash
153-
git config --local submodule.recurse true
154-
```
185+
```bash
186+
git config --local submodule.recurse true
187+
```
155188
156-
> [!NOTE]
157-
> Git does not automatically update submodules when switching branches.
158-
> Without this configuration, you will need to remember to add `--recurse-submodules` to `git checkout` when switching to old branches.
189+
> [!NOTE]
190+
> Git does not automatically update submodules when switching branches.
191+
> Without this configuration, you will need to remember to add `--recurse-submodules` to `git checkout` when switching to old branches.
159192
160-
> [!TIP]
161-
> This will keep the submodule in `dd-java-agent/agent-jmxfetch/integrations-core` up-to-date.
162-
> There is also an automated check when opening a pull request if you are trying to submit a module version change (usually an outdated version).
193+
> [!TIP]
194+
> This will keep the submodule in `dd-java-agent/agent-jmxfetch/integrations-core` up-to-date.
195+
> There is also an automated check when opening a pull request if you are trying to submit a module version change (usually an outdated version).
163196
164197
> [!NOTE]
165198
> Both git configurations (hooks and submodule) will only be applied to this project and won't apply globally in your setup.
166199

167200
### Check your development environment
168201

169-
You can confirm that your development environment is properly set up using the [quick check](#development-environment-quick-check) `setup.sh` script.
170-
171-
> [!NOTE]
172-
> The `setup.sh` script is only available for MacOS and Linux.
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.
173203

174204
### Build the project
175205

0 commit comments

Comments
 (0)