Skip to content

Latest commit

 

History

History
224 lines (165 loc) · 7.99 KB

BUILDING.md

File metadata and controls

224 lines (165 loc) · 7.99 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, run the following command from the project root 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 /Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home.
ℹ️ Checking other JVMs available for testing:
✅ Azul Zulu JDK 1.8.0_462-b08 from /Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home.
✅ Azul Zulu JDK 11.0.28+6-LTS from /Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home.
✅ Azul Zulu JDK 17.0.16+8-LTS from /Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home.
✅ Azul Zulu JDK 21.0.8+9-LTS from /Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home.
✅ Azul Zulu JDK 25+36-LTS from /Library/Java/JavaVirtualMachines/zulu-25.jdk/Contents/Home.
✅ GraalVM Community JDK 17.0.9+9-jvmci-23.0-b22 from /Library/Java/JavaVirtualMachines/graalvm-ce-java17-22.3.1/Contents/Home.
ℹ️ 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 below and use the following guide to install and configure the required tools.

Requirements

Requirements to build the full project:

  • JDK version is 21+,
  • The git command line is installed,
  • A container runtime environment is available to run all tests (e.g. Docker Desktop).

Install JDK

Java is required to run Gradle, the project build tool. Gradle will find any locally installed JDK and download any missing JDK versions needed for the project build and testing.

macOS

Install JDK 21 using brew:

brew install --cask zulu@21

Linux

Use your distribution package manager to install JDK 21:

apt install openjdk-21-jdk

Alternatively, manually download and install from Eclipse Temurin releases.

Add the JAVA_HOME environment variable to your shell using the export command. You can permanently set it by appending the export command to your shell configuration file such as ~/.zshrc, ~/.bashrc or similar.

export JAVA_HOME=/<path to extracted archive>/jdk-21.x.x

If you appended the commands to your shell configuration file, restart your shell after applying the changes.

Windows

Install JDK 21 using the Windows package manager winget:

winget install --id EclipseAdoptium.Temurin.21.JDK

Or manually download and install it from Eclipse Temurin releases.

Set the JAVA_HOME environment variable, replacing the path with your JDK 21 installation:

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21.x.x-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 install git

Windows

Download and install the installer from the official website, or install it using the Windows package manager winget:

winget install --id git.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 official website:
https://docs.docker.com/desktop/setup/install/mac-install/

Linux

Download and install Docker Desktop from the official website:
https://docs.docker.com/desktop/setup/install/linux/

Windows

Download and install Docker Desktop from the official 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 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: 
    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 committing. This is done both to avoid future merge conflicts and ensure uniformity across 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.

Configure Akka Token

Note

You can skip this step if you don’t need instrumentation for the akka-http-10.6 module. For background on why Akka now requires authentication, see this article.

To enable access to Akka artifacts hosted on Lightbend’s private repository, you’ll need to configure an authentication token.

  1. Obtain a repository token by visiting the Akka account page to generate a secure repository token.
  2. Create an environment variable named:
  ORG_GRADLE_PROJECT_akkaRepositoryToken=<your_token>

Building the project

After everything is properly set up, you can build the project 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.