Skip to content

Latest commit

 

History

History
263 lines (198 loc) · 10.7 KB

BUILDING.md

File metadata and controls

263 lines (198 loc) · 10.7 KB

Building

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

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:

./setup.sh

or on Windows:

.\setup.ps1

Your output should look something like the following:

ℹ️ 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.
✅ JAVA_11_HOME is set to /Users/datadog/.sdkman/candidates/java/11.0.22-zulu.
✅ JAVA_17_HOME is set to /Users/datadog/.sdkman/candidates/java/17.0.10-zulu.
✅ JAVA_21_HOME is set to /Users/datadog/.sdkman/candidates/java/21.0.2-zulu.
✅ JAVA_GRAALVM17_HOME is set to /Users/datadog/.sdkman/candidates/java/17.0.9-graalce.
ℹ️ Checking git configuration:
✅ The git command line is installed.
✅ pre-commit hook is installed in repository.
✅ git config submodule.recurse is set to true.
✅ All git submodules are initialized.
ℹ️ Checking Docker environment:
✅ The docker command line is installed.
✅ The Docker server is running.

If there is any issue with your output, check the requirements above and use the following guide to install and configure the required tools.

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

Install the required JDKs

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

macOS

  • 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: 
    sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-<current version of 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. 
    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-<current version of 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. It's recommended to use Azul's Zulu builds of Java 8. Amazon 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.

Linux

  • Download and extract JDK 8, 11, 17, and 21 from Eclipse Temurin releases and GraalVM 17 from Oracle downloads.
  • Install the GraalVM native image requirements for native builds by following the GraalVM official documentation.
  • 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. 
    export JAVA_8_HOME=/<path to extracted archive>/jdk8u<current version of JDK 8>
export JAVA_11_HOME=/<path to extracted archive>/jdk-11.<current version of JDK 11>
export JAVA_17_HOME=/<path to extracted archive>/jdk-17.<current version of JDK 17>
export JAVA_21_HOME=/<path to extracted archive>/jdk-21.<current version of JDK 21>
export JAVA_GRAALVM17_HOME=/<path to extracted archive>/graalvm-jdk-17.<current version of 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.

Windows

  • Download and install JDK 8, 11, 17, and 21 Eclipse Temurin releases.

    Alternatively, install JDKs using winget or scoop. (click here to expand) 
    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
    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:

    [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

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.

Linux

apt-get install git

Windows

Download and install the installer from the official website.

Alternatively, install git using winget or scoop. (click here to expand) 
winget install --id git.git
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 for more details.

macOS

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

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.

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.

To build the project without running tests, run:

./gradlew clean assemble

To build the entire project with tests (this can take a very long time), run:

./gradlew clean build

Note

Running the complete test suite on a local development environment can be challenging. It may take a very long time, and you might encounter a few flaky tests along the way. 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:

./gradlew :dd-java-agent:shadowJar

After building the project, you can find the built JVM agent artifact in the dd-java-agent/build/libs folder.