Skip to content

Commit 1083178

Browse files
lucaspimentelPerfectSlayer
lucaspimentel
and
PerfectSlayer
authored
[docs] improve setup of dev env on Windows (#8180)
* add PowerShell scripts for Windows * fix typo and remove trailing whitespace in BUILDING.md * add more Windows instructions, misc tweaks in BUILDING.md * more changes in BUILDING.md * use explicit value for JAVA_HOME instead of "%JAVA_8_HOME%" * Update install-jdks-windows.ps1 * move JDK install powershell script * update BUILDING.md * add comments about GraalVM license * add script descriptions * add comment to explain "omit from toc" * move "Quick check" up * remove Windows install script for now * rewrite Windows sections to focus on manual installation * remove toc comments * more updates to Windows instructions * fix formatting * simplify collapsible sections * tweak the "click here" text * add GraalVM version Co-authored-by: Bruce Bujon <[email protected]> * add GraalVM version Co-authored-by: Bruce Bujon <[email protected]> --------- Co-authored-by: Bruce Bujon <[email protected]>
1 parent 9ec7fde commit 1083178

File tree

2 files changed

+290
-90
lines changed

2 files changed

+290
-90
lines changed

‎BUILDING.md

+153-90
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,33 @@
1-
21
# Building
32

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

6-
* [Development environment quick check](#development-environment-quick-check)
7-
* [Environment requirements quick check](#environment-requirements-quick-check)
8-
* [Development environment set up](#development-environment-set-up)
9-
* [Project build](#project-build)
5+
* [Development environment](#development-environment)
6+
* [Quick check](#quick-check)
7+
* [Requirements](#requirements)
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)
13+
14+
## Development environment
15+
16+
### Quick check
17+
18+
To check that your development environment is properly set up to build the project, from the project root run on macOS or Linux:
19+
```shell
20+
./setup.sh
21+
```
1022

11-
## Development environment quick check
23+
or on Windows:
24+
```pwsh
25+
.\setup.ps1
26+
```
1227

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.
28+
Your output should look something like the following:
1429

15-
```bash
16-
$ ./setup.sh
30+
```
1731
ℹ️ Checking required JVM:
1832
✅ JAVA_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
1933
✅ JAVA_8_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
@@ -31,116 +45,174 @@ $ ./setup.sh
3145
✅ The Docker server is running.
3246
```
3347

34-
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.
48+
If there is any issue with your output, check the requirements above and use the following guide to install and configure the required tools.
3549

36-
## Environment requirements quick check
50+
### Requirements
3751

3852
Requirements to build the full project:
3953

4054
* The JDK versions 8, 11, 17 and 21 must be installed.
41-
* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME` and `JAVA_GRAALVM17_HOME` must point to their respective JDK location.
42-
* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
55+
* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME`, and `JAVA_GRAALVM17_HOME` must point to their respective JDK location.
56+
* The JDK 8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
4357
* The `JAVA_HOME` environment variable may be unset. If set, it must point to the JDK 8 location (same as `JAVA_8_HOME`).
4458
* The `git` command line must be installed.
4559
* A container runtime environment must be available to run all tests (e.g. Docker Desktop).
4660

47-
## Development environment set up
48-
4961
### Install the required JDKs
5062

51-
**On MacOS:**
63+
Download and install Eclipse Temurin JDK versions 8, 11, 17 and 21, and GraalVM 17.
5264

53-
* Install the required JDKs using `brew`.
54-
`brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17`
55-
* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/).
56-
`sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>`
65+
#### macOS
66+
67+
* Install the required JDKs using `brew`:
68+
```shell
69+
brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17
70+
```
71+
* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/):
72+
```
73+
sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>
74+
```
5775
* 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.
58-
```shell
59-
export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
60-
export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home
61-
export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
62-
export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home
63-
export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>/Contents/Home
64-
export JAVA_HOME=$JAVA_8_HOME
65-
```
76+
```shell
77+
export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
78+
export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home
79+
export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
80+
export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home
81+
export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-<current version of graalvm>/Contents/Home
82+
export JAVA_HOME=$JAVA_8_HOME
83+
```
6684
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.
6785

68-
> [!NOTE]
69-
> ARM users: there is no Oracle JDK v8 for ARM.
86+
> [!NOTE]
87+
> ARM users: there is no Oracle JDK v8 for ARM.
7088
> It's recommended to use [Azul's Zulu](https://www.azul.com/downloads/?version=java-8-lts&architecture=arm-64-bit&package=jdk#zulu) builds of Java 8.
7189
> [Amazon Corretto](https://aws.amazon.com/corretto/) builds have also been proven to work.
7290
7391
> [!NOTE]
74-
> MacOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path.
92+
> macOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path.
7593
76-
**On Linux:**
94+
#### Linux
7795

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/).
96+
* Download and extract JDK 8, 11, 17, and 21 from [Eclipse Temurin releases](https://adoptium.net/temurin/releases/) and GraalVM 17 from [Oracle downloads](https://www.graalvm.org/downloads/).
7997
* 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).
80-
* 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.
81-
```shell
82-
export JAVA_8_HOME=/<path to extracted archive>/jdk8u<current version of JDK 8>
83-
export JAVA_11_HOME=/<path to extracted archive>/jdk-11.<current version of JDK 11>
84-
export JAVA_17_HOME=/<path to extracted archive>/jdk-17.<current version of JDK 17>
85-
export JAVA_21_HOME=/<path to extracted archive>/jdk-21.<current version of JDK 21>
86-
export JAVA_GRAALVM17_HOME=/<path to extracted archive>/graalvm-jdk-17.<current version of graalvm>/Contents/Home
87-
export JAVA_HOME=$JAVA_8_HOME
88-
```
98+
* 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.
99+
```shell
100+
export JAVA_8_HOME=/<path to extracted archive>/jdk8u<current version of JDK 8>
101+
export JAVA_11_HOME=/<path to extracted archive>/jdk-11.<current version of JDK 11>
102+
export JAVA_17_HOME=/<path to extracted archive>/jdk-17.<current version of JDK 17>
103+
export JAVA_21_HOME=/<path to extracted archive>/jdk-21.<current version of JDK 21>
104+
export JAVA_GRAALVM17_HOME=/<path to extracted archive>/graalvm-jdk-17.<current version of graalvm>/Contents/Home
105+
export JAVA_HOME=$JAVA_8_HOME
106+
```
89107
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.
90108

91-
**On Windows:**
109+
#### Windows
110+
111+
* Download and install JDK 8, 11, 17, and 21 [Eclipse Temurin releases](https://adoptium.net/temurin/releases/).
112+
113+
<details>
114+
<summary>Alternatively, install JDKs using winget or scoop. (click here to expand)</summary>
115+
116+
```pwsh
117+
winget install --id EclipseAdoptium.Temurin.8.JDK
118+
winget install --id EclipseAdoptium.Temurin.11.JDK
119+
winget install --id EclipseAdoptium.Temurin.17.JDK
120+
winget install --id EclipseAdoptium.Temurin.21.JDK
121+
```
92122
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/).
94-
* 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`
123+
```pwsh
124+
scoop bucket add java
125+
scoop install temurin8-jdk
126+
scoop install temurin11-jdk
127+
scoop install temurin17-jdk
128+
scoop install temurin21-jdk
129+
```
130+
131+
</details>
132+
133+
* To add the required environment variables, run the following PowerShell commands for each SDK version, replacing the paths with the correct version installed:
134+
```pwsh
135+
[Environment]::SetEnvironmentVariable("JAVA_8_HOME", "C:\Program Files\Eclipse Adoptium\jdk-8.0.432.6-hotspot", [EnvironmentVariableTarget]::User)
136+
[Environment]::SetEnvironmentVariable("JAVA_11_HOME", "C:\Program Files\Eclipse Adoptium\jdk-11.0.25.9-hotspot", [EnvironmentVariableTarget]::User)
137+
[Environment]::SetEnvironmentVariable("JAVA_17_HOME", "C:\Program Files\Eclipse Adoptium\jdk-17.0.12.7-hotspot", [EnvironmentVariableTarget]::User)
138+
[Environment]::SetEnvironmentVariable("JAVA_21_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot", [EnvironmentVariableTarget]::User)
139+
140+
# JAVA_HOME = JAVA_8_HOME
141+
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-8.0.432.6-hotspot", [EnvironmentVariableTarget]::User)
142+
```
101143

102144
### Install git
103145

104-
**On MacOS:**
146+
#### macOS
105147

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

109-
**On Linux:**
151+
#### Linux
110152

111-
Run `apt-get install git`.
153+
```shell
154+
apt-get install git
155+
```
112156

113-
**On Windows:**
157+
#### Windows
114158

115-
Download and install [the installer](https://git-scm.com/download/win) from the official website.
159+
Download and install the installer from [the official website](https://git-scm.com/download/win).
116160

117-
### Install Docker Desktop
161+
<details>
162+
<summary>Alternatively, install git using winget or scoop. (click here to expand)</summary>
118163

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/).
164+
```pwsh
165+
winget install --id git.git
166+
```
167+
168+
```pwsh
169+
scoop install git
170+
```
171+
172+
</details>
173+
174+
### Install Docker Desktop
120175

121176
> [!NOTE]
122177
> Docker Desktop is the recommended container runtime environment, but you can use any other environment to run testcontainers tests.
123178
> Check [the testcontainers container runtime requirements](https://java.testcontainers.org/supported_docker_environment/) for more details.
124179
125-
### Clone the repository and set up git
180+
#### macOS
126181

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/
138-
139-
# On Windows
140-
cd dd-trace-java
141-
copy .githooks/pre-comit .git/hooks/
182+
Download and install Docker Desktop from the offical website:<br/>
183+
https://docs.docker.com/desktop/setup/install/mac-install/
184+
185+
#### Linux
186+
187+
Download and install Docker Desktop from the offical website:<br/>
188+
https://docs.docker.com/desktop/setup/install/linux/
189+
190+
#### Windows
191+
192+
Download and install Docker Desktop from the offical website:<br/>
193+
https://docs.docker.com/desktop/setup/install/windows-install/
194+
195+
<details>
196+
<summary>Alternatively, install Docker Desktop using winget. (click here to expand)</summary>
197+
198+
```pwsh
199+
winget install --id Docker.DockerDesktop
142200
```
143201

202+
</details>
203+
204+
## Clone the repository and set up git
205+
206+
* Get a copy of the project by cloning the repository using git in your workspace:
207+
```shell
208+
git clone --recurse-submodules [email protected]:DataDog/dd-trace-java.git
209+
```
210+
* There is a pre-commit hook setup to verify formatting before committing. It can be activated with the following command:
211+
```shell
212+
cd dd-trace-java
213+
cp .githooks/pre-commit .git/hooks/
214+
```
215+
144216
> [!TIP]
145217
> 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.
146218
@@ -149,9 +221,9 @@ copy .githooks/pre-comit .git/hooks/
149221
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
150222
151223
* Configure git to automatically update submodules.
152-
```bash
153-
git config --local submodule.recurse true
154-
```
224+
```shell
225+
git config --local submodule.recurse true
226+
```
155227
156228
> [!NOTE]
157229
> Git does not automatically update submodules when switching branches.
@@ -164,26 +236,17 @@ git config --local submodule.recurse true
164236
> [!NOTE]
165237
> Both git configurations (hooks and submodule) will only be applied to this project and won't apply globally in your setup.
166238

167-
### Check your development environment
168-
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.
173-
174-
### Build the project
239+
## Building the project
175240

176241
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).
177242

178-
## Project build
179-
180243
To build the project without running tests, run:
181-
```bash
244+
```shell
182245
./gradlew clean assemble
183246
```
184247

185248
To build the entire project with tests (this can take a very long time), run:
186-
```bash
249+
```shell
187250
./gradlew clean build
188251
```
189252

@@ -193,7 +256,7 @@ To build the entire project with tests (this can take a very long time), run:
193256
> 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.
194257

195258
To build the JVM agent artifact only, run:
196-
```bash
259+
```shell
197260
./gradlew :dd-java-agent:shadowJar
198261
```
199262

0 commit comments

Comments
 (0)