Skip to content

Commit

Permalink
add more Windows instructions, misc tweaks in BUILDING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@lucaspimentel
lucaspimentel committed Jan 10, 2025
1 parent 3ed8d57 commit 49b945c
Showing 1 changed file with 84 additions and 54 deletions.
138 changes: 84 additions & 54 deletions BUILDING.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

# Building

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

## Development environment quick check

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.
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:

```bash
$ ./setup.sh
```
ℹ️ Checking required JVM:
✅ JAVA_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
✅ JAVA_8_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
Expand Down Expand Up @@ -48,7 +46,10 @@ Requirements to build the full project:

### Install the required JDKs

**On MacOS:**
Download and install Eclipse Temurin JDK versions 8, 11, 17 and 21, and GraalVM.

<details>
<summary>macOS</summary>

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

* 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/).
<details>
<summary>Linux</summary>

* 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/).
* 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).
* 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.
```shell
Expand All @@ -88,20 +92,43 @@ export JAVA_HOME=$JAVA_8_HOME
```
* Restart your shell after applying the changes if you appended the commands to your shell configuration file.

**On Windows:**
</details>

<details>
<summary>Windows</summary>

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.

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.

* 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/).
```
winget install --id EclipseAdoptium.Temurin.8.JDK
winget install --id EclipseAdoptium.Temurin.11.JDK
winget install --id EclipseAdoptium.Temurin.17.JDK
winget install --id EclipseAdoptium.Temurin.21.JDK
```

To install the JDKs manually:
* Download SDKs manually from [Eclipse Temurin releases](https://adoptium.net/temurin/releases/) and GraalVM from [Oracle downloads](https://www.graalvm.org/downloads/).
* 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).
* Add the required environment variables.
* Open the *Start Menu*, type `environment variable`, and use the *Edit environment variable for your account* entry to open the *System Properties*.
* Add new entries to the table.
* `JAVA_8_HOME` to the JDK 8 installation folder, usually `C:\Program Files\Eclipse Adoptium\jdk-<current version of Java 8>-hotspot\bin`
* `JAVA_11_HOME`, `JAVA_21_HOME`, and `JAVA_21_HOME` similarly to their respective installation `bin` folders
* `JAVA_GRAALVM17_HOME` to the GraalVM installation folder, usually `C:\Program Files\Java\<current version of graalvm>\bin`

### Install git
To add the required environment variables manually from PowerShell, run this command for each SDK version:
```pwsh
[Environment]::SetEnvironmentVariable("JAVA_8_HOME", "C:\Program Files\Eclipse Adoptium\jdk-<version>-hotspot", [EnvironmentVariableTarget]::User)
```

To add the required environment variables manually using the UI:
* Open the *Start Menu*, type `environment variable`, and use the *Edit environment variable for your account* entry to open the *System Properties*.
* Add new entries to the table:
* `JAVA_8_HOME` to the JDK 8 installation folder, usually `C:\Program Files\Eclipse Adoptium\jdk-<current version of Java 8>-hotspot\bin`
* `JAVA_11_HOME`, `JAVA_17_HOME`, and `JAVA_21_HOME` similarly to their respective installation `bin` folders
* `JAVA_GRAALVM17_HOME` to the GraalVM installation folder, usually `C:\Program Files\Java\<current version of graalvm>\bin`

**On MacOS:**
</details>

### Install `git`

**On macOS:**

You can trigger the installation by running any `git` command from the terminal, e.g. `git --version`.
If not installed, the terminal will prompt you to install it.
Expand All @@ -112,64 +139,67 @@ Run `apt-get install git`.

**On Windows:**

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

### Install Docker Desktop

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/).

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

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

# On Windows
cd dd-trace-java
copy .githooks/pre-commit .git/hooks/
```
**On Linux:**

> [!TIP]
> 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.
Download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/linux/

> [!NOTE]
> The git hooks will check that your code is properly formatted before commiting.
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
**On Windows:**

Run `winget install --id Docker.DockerDesktop`.

Alternatively, download and install Docker Desktop from the offical website: https://docs.docker.com/desktop/setup/install/windows-install/

### Clone the repository and set up git

* Get a copy of the project by cloning the repository using git in your workspace:
```bash
git clone --recurse-submodules [email protected]:DataDog/dd-trace-java.git
```
* There is a pre-commit hook setup to verify formatting before committing. It can be activated with the following command:
```bash
# On bash-like shells shells or PowerShell
cd dd-trace-java
cp .githooks/pre-commit .git/hooks/
```

> [!TIP]
> 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.
> [!NOTE]
> The git hooks will check that your code is properly formatted before commiting.
> This is done both to avoid future merge conflict and ensure uniformity inside the code base.
* Configure git to automatically update submodules.
```bash
git config --local submodule.recurse true
```
```bash
git config --local submodule.recurse true
```
> [!NOTE]
> Git does not automatically update submodules when switching branches.
> Without this configuration, you will need to remember to add `--recurse-submodules` to `git checkout` when switching to old branches.
> [!NOTE]
> Git does not automatically update submodules when switching branches.
> Without this configuration, you will need to remember to add `--recurse-submodules` to `git checkout` when switching to old branches.
> [!TIP]
> This will keep the submodule in `dd-java-agent/agent-jmxfetch/integrations-core` up-to-date.
> 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).
> [!TIP]
> This will keep the submodule in `dd-java-agent/agent-jmxfetch/integrations-core` up-to-date.
> 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).
> [!NOTE]
> Both git configurations (hooks and submodule) will only be applied to this project and won't apply globally in your setup.

### Check your development environment

You can confirm that your development environment is properly set up using the [quick check](#development-environment-quick-check) `setup.sh` script.

> [!NOTE]
> The `setup.sh` script is only available for MacOS and Linux.
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.

### Build the project

Expand Down

0 comments on commit 49b945c

Please sign in to comment.