diff --git a/BUILDING.md b/BUILDING.md index b07e1b2b201..4332ec13b5e 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,19 +1,33 @@ - # Building This documentation provides information for developers to set up their environment and build their project from sources. -* [Development environment quick check](#development-environment-quick-check) -* [Environment requirements quick check](#environment-requirements-quick-check) -* [Development environment set up](#development-environment-set-up) -* [Project build](#project-build) +* [Development environment](#development-environment) + * [Quick check](#quick-check) + * [Requirements](#requirements) + * [Install the required JDKs](#install-the-required-jdks) + * [Install git](#install-git) + * [Install Docker Desktop](#install-docker-desktop) +* [Clone the repository and set up git](#clone-the-repository-and-set-up-git) +* [Building the project](#building-the-project) + +## Development environment + +### Quick check + +To check that your development environment is properly set up to build the project, from the project root run on macOS or Linux: +```shell +./setup.sh +``` -## Development environment quick check +or on Windows: +```pwsh +.\setup.ps1 +``` -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. +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. @@ -31,116 +45,174 @@ $ ./setup.sh ✅ The Docker server is running. ``` -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. +If there is any issue with your output, check the requirements above and use the following guide to install and configure the required tools. -## Environment requirements quick check +### Requirements Requirements to build the full project: * The JDK versions 8, 11, 17 and 21 must be installed. -* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME` and `JAVA_GRAALVM17_HOME` must point to their respective JDK location. -* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`). +* The `JAVA_8_HOME`, `JAVA_11_HOME`, `JAVA_17_HOME`, `JAVA_21_HOME`, and `JAVA_GRAALVM17_HOME` must point to their respective JDK location. +* The JDK 8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`). * The `JAVA_HOME` environment variable may be unset. If set, it must point to the JDK 8 location (same as `JAVA_8_HOME`). * The `git` command line must be installed. * A container runtime environment must be available to run all tests (e.g. Docker Desktop). -## Development environment set up - ### Install the required JDKs -**On MacOS:** +Download and install Eclipse Temurin JDK versions 8, 11, 17 and 21, and GraalVM 17. -* Install the required JDKs using `brew`. -`brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17` -* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/). -`sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-` +#### macOS + +* Install the required JDKs using `brew`: + ```shell + brew install --cask zulu@8 zulu@11 zulu@17 zulu@21 graalvm/tap/graalvm-ce-java17 + ``` +* Fix the GraalVM installation by [removing the quarantine flag](https://www.graalvm.org/latest/docs/getting-started/macos/): + ``` + sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm- + ``` * 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 -export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home -export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home -export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home -export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home -export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-/Contents/Home -export JAVA_HOME=$JAVA_8_HOME -``` + ```shell + export JAVA_8_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home + export JAVA_11_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home + export JAVA_17_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home + export JAVA_21_HOME=/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home + export JAVA_GRAALVM17_HOME=/Library/Java/JavaVirtualMachines/graalvm-/Contents/Home + export JAVA_HOME=$JAVA_8_HOME + ``` * Restart your shell after applying the changes if you appended the commands to your shell configuration file. -> [!NOTE] -> ARM users: there is no Oracle JDK v8 for ARM. +> [!NOTE] +> ARM users: there is no Oracle JDK v8 for ARM. > 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. > [Amazon Corretto](https://aws.amazon.com/corretto/) builds have also been proven to work. > [!NOTE] -> MacOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path. +> macOS users: remember that `/usr/libexec/java_home` may control which JDK is in your path. -**On Linux:** +#### Linux -* 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/). +* 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/). * 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 -export JAVA_8_HOME=//jdk8u -export JAVA_11_HOME=//jdk-11. -export JAVA_17_HOME=//jdk-17. -export JAVA_21_HOME=//jdk-21. -export JAVA_GRAALVM17_HOME=//graalvm-jdk-17./Contents/Home -export JAVA_HOME=$JAVA_8_HOME -``` +* 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 + export JAVA_8_HOME=//jdk8u + export JAVA_11_HOME=//jdk-11. + export JAVA_17_HOME=//jdk-17. + export JAVA_21_HOME=//jdk-21. + export JAVA_GRAALVM17_HOME=//graalvm-jdk-17./Contents/Home + 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:** +#### Windows + +* Download and install JDK 8, 11, 17, and 21 [Eclipse Temurin releases](https://adoptium.net/temurin/releases/). + +
+ Alternatively, install JDKs using winget or scoop. (click here to expand) + + ```pwsh + 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 + ``` -* 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/). -* 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--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\\bin` + ```pwsh + scoop bucket add java + scoop install temurin8-jdk + scoop install temurin11-jdk + scoop install temurin17-jdk + scoop install temurin21-jdk + ``` + +
+ +* To add the required environment variables, run the following PowerShell commands for each SDK version, replacing the paths with the correct version installed: + ```pwsh + [Environment]::SetEnvironmentVariable("JAVA_8_HOME", "C:\Program Files\Eclipse Adoptium\jdk-8.0.432.6-hotspot", [EnvironmentVariableTarget]::User) + [Environment]::SetEnvironmentVariable("JAVA_11_HOME", "C:\Program Files\Eclipse Adoptium\jdk-11.0.25.9-hotspot", [EnvironmentVariableTarget]::User) + [Environment]::SetEnvironmentVariable("JAVA_17_HOME", "C:\Program Files\Eclipse Adoptium\jdk-17.0.12.7-hotspot", [EnvironmentVariableTarget]::User) + [Environment]::SetEnvironmentVariable("JAVA_21_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot", [EnvironmentVariableTarget]::User) + + # JAVA_HOME = JAVA_8_HOME + [Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-8.0.432.6-hotspot", [EnvironmentVariableTarget]::User) + ``` ### Install git -**On MacOS:** +#### 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. -**On Linux:** +#### Linux -Run `apt-get install git`. +```shell +apt-get install git +``` -**On Windows:** +#### Windows -Download and install [the installer](https://git-scm.com/download/win) from the official website. +Download and install the installer from [the official website](https://git-scm.com/download/win). -### Install Docker Desktop +
+Alternatively, install git using winget or scoop. (click here to expand) -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/). +```pwsh +winget install --id git.git +``` + +```pwsh +scoop install git +``` + +
+ +### Install Docker Desktop > [!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 +#### macOS -* Get a copy of the project. - * In your workspace, clone the repository using git. -```bash -git clone --recurse-submodules git@github.com: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/ - -# On Windows -cd dd-trace-java -copy .githooks/pre-comit .git/hooks/ +Download and install Docker Desktop from the offical website:
+https://docs.docker.com/desktop/setup/install/mac-install/ + +#### Linux + +Download and install Docker Desktop from the offical website:
+https://docs.docker.com/desktop/setup/install/linux/ + +#### Windows + +Download and install Docker Desktop from the offical website:
+https://docs.docker.com/desktop/setup/install/windows-install/ + +
+Alternatively, install Docker Desktop using winget. (click here to expand) + +```pwsh +winget install --id Docker.DockerDesktop ``` +
+ +## Clone the repository and set up git + +* Get a copy of the project by cloning the repository using git in your workspace: + ```shell + git clone --recurse-submodules git@github.com: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: + ```shell + 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. @@ -149,9 +221,9 @@ copy .githooks/pre-comit .git/hooks/ > 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 -``` + ```shell + git config --local submodule.recurse true + ``` > [!NOTE] > Git does not automatically update submodules when switching branches. @@ -164,26 +236,17 @@ git config --local submodule.recurse true > [!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. - -### Build the project +## Building the project 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). -## Project build - To build the project without running tests, run: -```bash +```shell ./gradlew clean assemble ``` To build the entire project with tests (this can take a very long time), run: -```bash +```shell ./gradlew clean build ``` @@ -193,7 +256,7 @@ To build the entire project with tests (this can take a very long time), run: > 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. To build the JVM agent artifact only, run: -```bash +```shell ./gradlew :dd-java-agent:shadowJar ``` diff --git a/setup.ps1 b/setup.ps1 new file mode 100644 index 00000000000..2e0b0d06ab8 --- /dev/null +++ b/setup.ps1 @@ -0,0 +1,137 @@ +<# + .DESCRIPTION + This script checks the development environment for required tools and configurations. +#> + +# Enable error handling +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +# Check for required JDKs +function TestJvm { + param ($JavaHomeName, $ExpectedJavaVersion) + + if (-not (Test-Path "env:$JavaHomeName")) { + Write-Host "❌ $JavaHomeName is not set. Please set $JavaHomeName to refer to a JDK $ExpectedJavaVersion installation." -ForegroundColor Red + exit 1 + } + else { + $javaHome = Get-Item "env:$JavaHomeName" | Select-Object -ExpandProperty Value + + try { + # try to handle differences between PowerShell 7 and Windows PowerShell 5 + $ErrorActionPreference = 'Continue' + $javaVersionOutput = & "$javaHome\bin\java.exe" -version 2>&1 + } + catch { + Write-Host "❌ Error running `"$javaHome\bin\java.exe -version`". Please check that $JavaHomeName is set to a JDK $ExpectedJavaVersion installation." + exit 1 + } + finally { + $ErrorActionPreference = 'Stop' + } + + if ($javaVersionOutput[0] -notmatch "version `"$ExpectedJavaVersion") { + Write-Host "❌ $JavaHomeName is set to $javaHome, but it does not refer to a JDK $ExpectedJavaVersion installation." -ForegroundColor Red + exit 1 + } + else { + Write-Host "✅ $JavaHomeName is set to $javaHome." + } + } +} + +Write-Host 'ℹ️ Checking required JVM:' +if (Test-Path 'env:JAVA_HOME') { + TestJvm 'JAVA_HOME' '1.8' +} + +TestJvm 'JAVA_8_HOME' '1.8' +TestJvm 'JAVA_11_HOME' '11' +TestJvm 'JAVA_17_HOME' '17' +TestJvm 'JAVA_21_HOME' '21' +# GraalVM cannot currently be installed due to license change in October 2024 for GraalVM 17.0.13 and later. +# TestJvm 'JAVA_GRAALVM17_HOME' '17' + +# Check for required commands (e.g., git, docker) +function TestCommand { + param ($command) + + if (Get-Command $command -ErrorAction SilentlyContinue) { + Write-Host "✅ The $command command line is installed." + } + else { + Write-Host "❌ The $command command line is missing. Please install $command." -ForegroundColor Red + exit 1 + } +} + +function Get-FileHashMD5 { + param ($file) + return (Get-FileHash -Path $file -Algorithm MD5).Hash +} + +function TestHook { + param ($hookName) + + $hookChecksum = Get-FileHashMD5 ".githooks/$hookName" + $hooksPath = (git config core.hooksPath) -or '.git/hooks' + + if ((Test-Path ".git/hooks/$hookName") -and (Get-FileHashMD5 ".git/hooks/$hookName" -eq $hookChecksum)) { + Write-Host "✅ $hookName hook is installed in repository." + } + elseif ((Test-Path "$hooksPath/$hookName") -and (Get-FileHashMD5 "$hooksPath/$hookName" -eq $hookChecksum)) { + Write-Host "✅ $hookName hook is installed in git hooks path." + } + else { + Write-Host "🟨 $hookName hook was not found (optional but recommended)." + } +} + +function TestGitConfig { + param ($configName, $expectedValue) + + $actualValue = git config $configName + + if ($actualValue -eq $expectedValue) { + Write-Host "✅ git config $configName is set to $expectedValue." + } + elseif (-not $actualValue) { + Write-Host "❌ git config $configName is not set. Please set it to $expectedValue." -ForegroundColor Red + } + else { + Write-Host "🟨 git config $configName is set to $actualValue (expected: $expectedValue)." + } +} + +Write-Host 'ℹ️ Checking git configuration:' +TestCommand 'git' +TestHook 'pre-commit' +TestGitConfig 'submodule.recurse' 'true' + +# Check Docker environment +function TestDockerServer { + try { + # try to handle differences between PowerShell 7 and Windows PowerShell 5 + $ErrorActionPreference = 'Continue' + docker info *> $null + + if ($LASTEXITCODE -eq 0) { + Write-Host "✅ The Docker server is running." + } + else { + Write-Host "🟨 The Docker server is not running. Please start it to run all tests." + } + } + catch { + Write-Host "❌ Error running `"docker info *> $null`"." + exit 1 + } + finally { + $ErrorActionPreference = 'Stop' + } +} + +Write-Host 'ℹ️ Checking Docker environment:' +TestCommand 'docker' +TestDockerServer