Skip to content

Commit 58cddb6

Browse files
PerfectSlayerPerfectSlayer
authored
Merge pull request #6942 from DataDog/bbujon/documentation
Improve environment setup documentation
2 parents 0f6ccb0 + 1abb783 commit 58cddb6

File tree

4 files changed

+238
-85
lines changed

4 files changed

+238
-85
lines changed

‎BUILDING.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
2+
# Building
3+
4+
## Development environment quick check
5+
6+
You can quickly check that your development environment is properly set up to build the project running `./setup.sh` from the project root:
7+
8+
```bash
9+
$ ./setup.sh
10+
ℹ️ Checking required JVM:
11+
✅ JAVA_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
12+
✅ JAVA_8_HOME is set to /Users/datadog/.sdkman/candidates/java/8.0.402-zulu.
13+
✅ JAVA_11_HOME is set to /Users/datadog/.sdkman/candidates/java/11.0.22-zulu.
14+
✅ JAVA_17_HOME is set to /Users/datadog/.sdkman/candidates/java/17.0.10-zulu.
15+
✅ JAVA_21_HOME is set to /Users/datadog/.sdkman/candidates/java/21.0.2-zulu.
16+
✅ JAVA_GRAALVM17_HOME is set to /Users/datadog/.sdkman/candidates/java/17.0.9-graalce.
17+
ℹ️ Checking git configuration:
18+
✅ The git command line is installed.
19+
✅ pre-commit hook is installed in repository.
20+
✅ git config submodule.recurse is set to true.
21+
ℹ️ Checking shell configuration:
22+
✅ File descriptor limit is set to 12800.
23+
✅ The docker command line is installed.
24+
✅ The Docker server is running.
25+
```
26+
27+
If the script finds any issue, you can follow the requirements below to install and configure the required tools and [the code contribution guidelines](CONTRIBUTING.md#code-contributions).
28+
29+
## Building requirements
30+
31+
To build the full project:
32+
33+
* JDK version 8 must be installed.
34+
* JDK version 11 must be installed.
35+
* JDK version 17 must be installed.
36+
* JDK version 21 must be installed.
37+
* `JAVA_8_HOME` must point to the JDK-8 location.
38+
* `JAVA_11_HOME` must point to the JDK-11 location.
39+
* `JAVA_17_HOME` must point to the JDK-17 location.
40+
* `JAVA_21_HOME` must point to the JDK-21 location.
41+
* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
42+
* `JAVA_HOME` may be unset. If set, it must point to JDK-8 (same as `JAVA_8_HOME`).
43+
* git command line must be installed.
44+
* A container runtime environment must be available to run all tests (usually Docker Desktop).
45+
46+
> [!NOTE]
47+
> MacOS users, remember that `/usr/libexec/java_home` may control which JDK is in your path.
48+
49+
> [!NOTE]
50+
> ARM users, there is no Oracle JDK v8 for ARM.
51+
> You might want 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.
52+
> On macOS, they can be installed using `brew tap homebrew/cask-versions && brew install --cask zulu8`.
53+
> [Amazon Corretto](https://aws.amazon.com/corretto/) builds have also been proven to work.
54+
55+
## Building commands
56+
57+
To build the project without running tests run:
58+
59+
```bash
60+
./gradlew clean assemble
61+
```
62+
63+
To build the entire project with tests (this can take a very long time) run:
64+
65+
```bash
66+
./gradlew clean build
67+
```

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,75 @@
11
# Contributing
22

3+
## Contributions are welcomed
4+
35
Pull requests for bug fixes are welcome, but before submitting new features or changes to current
4-
functionality [open an issue](https://github.com/DataDog/dd-trace-java/issues/new)
5-
and discuss your ideas or propose the changes you wish to make. After a resolution is reached a PR can be submitted for
6+
functionality, please [open an issue](https://github.com/DataDog/dd-trace-java/issues/new)
7+
and discuss your ideas or propose the changes you wish to make first. After a resolution is reached a PR can be submitted for
68
review.
79

810
When opening a pull request, please open it as
911
a [draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to not auto assign reviewers before you feel
1012
the pull request is in a reviewable state.
1113

12-
## Requirements
13-
14-
To build the full project:
15-
16-
* JDK version 8 must be installed.
17-
* JDK version 11 must be installed.
18-
* JDK version 17 must be installed.
19-
* JDK version 21 must be installed.
20-
* `JAVA_8_HOME` must point to the JDK-8 location.
21-
* `JAVA_11_HOME` must point to the JDK-11 location.
22-
* `JAVA_17_HOME` must point to the JDK-17 location.
23-
* `JAVA_21_HOME` must point to the JDK-21 location.
24-
* The JDK-8 `bin` directory must be the only JDK on the PATH (e.g. `$JAVA_8_HOME/bin`).
25-
* `JAVA_HOME` may be unset. If set, it must point to JDK-8 (same as `JAVA_8_HOME`).
14+
## Adding instrumentations
2615

27-
MacOS users, remember that `/usr/libexec/java_home` may control which JDK is in your path.
16+
Check [Adding a New Instrumentation](docs/add_new_instrumentation.md) for instructions on adding a new instrumentation.
2817

29-
In contrast to the [IntelliJ IDEA set up](#intellij-idea) the default JVM to build and run tests from the command line
30-
should be Java 8.
18+
Check [How Instrumentations Work](docs/how_instrumentations_work.md) for a deep dive into how instrumentations work.
3119

32-
There is no Oracle JDK v8 for ARM. ARM users might want to
33-
use [Azul's Zulu](https://www.azul.com/downloads/?version=java-8-lts&architecture=arm-64-bit&package=jdk#zulu)
34-
builds of Java 8. On macOS, they can be installed
35-
using `brew tap homebrew/cask-versions && brew install --cask zulu8`. [Amazon Corretto](https://aws.amazon.com/corretto/)
36-
builds have also been proven to work.
20+
## Code contributions
3721

38-
# Building
22+
### Development environment quick check
3923

40-
To build the project without running tests run:
24+
Prior contributing to the project, you can quickly check your development environment using the `./setup.sh` command line, and fix any issue found using the [Building documentation](BUILDING.md).
4125

42-
```bash
43-
./gradlew clean assemble
44-
```
45-
46-
To build the entire project with tests (this can take a very long time) run:
47-
48-
```bash
49-
./gradlew clean build
50-
```
26+
### Automatic code formatting
5127

52-
# Adding Instrumentations
53-
54-
See [Adding a New Instrumentation](./docs/add_new_instrumentation.md) for instructions on adding a new instrumentation.
55-
56-
See [How Instrumentations Work](./docs/how_instrumentations_work.md) for a deep dive into how instrumentations work.
57-
58-
# Automatic code formatting
59-
60-
This project includes a `.editorconfig` file for basic editor settings. This file is supported by most common text
61-
editors.
28+
This project includes a `.editorconfig` file for basic editor settings.
29+
This file is supported by most common text editors.
6230

6331
We have automatic code formatting enabled in Gradle configuration using [Spotless](https://github.com/diffplug/spotless)
6432
[Gradle plugin](https://github.com/diffplug/spotless/tree/master/plugin-gradle).
6533
Main goal is to avoid extensive reformatting caused by different IDEs having different opinion about how things should
66-
be formatted by establishing single 'point of truth'.
34+
be formatted by establishing single _point of truth_.
6735

68-
To reformat all the files that need reformatting.
36+
To reformat all the files that need reformatting:
6937

7038
```bash
7139
./gradlew spotlessApply
7240
```
7341

74-
To run formatting verify task only.
42+
To run formatting verify task only:
7543

7644
```bash
7745
./gradlew spotlessCheck
7846
```
7947

80-
## Pre-commit hook
48+
#### IntelliJ IDEA
49+
50+
For IntelliJ IDEA, we suggest the following settings and plugin:
51+
52+
In contrast to the [IntelliJ IDEA set up](CONTRIBUTING.md#intellij-idea) the default JVM to build and run tests from the command line should be Java 8.
53+
* Use Java 8 to build and run tests:
54+
`Project Structure` > `Project` > `SDK` > Use a JDK 1.8
55+
* Configure import formatting:
56+
`Editor` > `Code Style` > `Java/Groovy` > `Imports`
57+
* `Class count to use import with '*'`: `9999` (some number sufficiently large that is unlikely to matter)
58+
* `Names count to use static import with '*'`: `9999`
59+
* With java use the following import layout (groovy should still use the default) to ensure consistency with
60+
google-java-format:
61+
![import layout](https://user-images.githubusercontent.com/734411/43430811-28442636-94ae-11e8-86f1-f270ddcba023.png)
62+
* [Google Java Format](https://plugins.jetbrains.com/plugin/8527-google-java-format) plugin
63+
64+
### Git pre-commit hook
8165

8266
There is a pre-commit hook setup to verify formatting before committing. It can be activated with this command:
8367

8468
```bash
8569
git config core.hooksPath .githooks
8670
```
8771

88-
## Git submodule setup
72+
### Git submodule setup
8973

9074
Git does not automatically update submodules when switching branches.
9175

@@ -98,41 +82,28 @@ git config --local submodule.recurse true
9882

9983
This will keep the submodule in `dd-java-agent/agent-jmxfetch/integrations-core` up to date.
10084

101-
## Intellij IDEA
102-
103-
Compiler settings:
104-
105-
* OpenJDK 11 must be installed to build the entire project. Under `SDKs` it must have the name `11`.
106-
* Under `Build, Execution, Deployment > Compiler > Java Compiler` disable `Use '--release' option for cross-compilation`
10785

108-
Suggested plugins and settings:
86+
### Troubleshooting
10987

110-
* Editor > Code Style > Java/Groovy > Imports
111-
* Class count to use import with '*': `9999` (some number sufficiently large that is unlikely to matter)
112-
* Names count to use static import with '*': `9999`
113-
* With java use the following import layout (groovy should still use the default) to ensure consistency with
114-
google-java-format:
115-
![import layout](https://user-images.githubusercontent.com/734411/43430811-28442636-94ae-11e8-86f1-f270ddcba023.png)
116-
* [Google Java Format](https://plugins.jetbrains.com/plugin/8527-google-java-format)
88+
* Gradle fails with a "too many open files" error.
89+
* You can check the `ulimit` for open files in your current shell by doing `ulimit -n` and raise it by
90+
calling `ulimit -n <new number>`
11791

118-
## Troubleshooting
92+
<details>
93+
<summary>More past issues</summary>
11994

120-
* When Gradle is building the project, the
95+
* When Gradle is building the project, the
12196
error `Could not find netty-transport-native-epoll-4.1.43.Final-linux-x86_64.jar` is shown.
12297
* Execute `rm -rf ~/.m2/repository/io/netty/netty-transport*` in a Terminal and re-build again.
12398

124-
* IntelliJ 2021.3
125-
complains `Failed to find KotlinGradleProjectData for GradleSourceSetData` https://youtrack.jetbrains.com/issue/KTIJ-20173
99+
* IntelliJ 2021.3 complains `Failed to find KotlinGradleProjectData for GradleSourceSetData` https://youtrack.jetbrains.com/issue/KTIJ-20173
126100
* Switch to `IntelliJ IDEA CE 2021.2.3`
127101

128102
* IntelliJ Gradle fails to import the project with `JAVA_11_HOME must be set to build Java 11 code`
129103
* A workaround is to run IntelliJ from terminal with `JAVA_11_HOME`
130104
* In order to verify what's visible from IntelliJ use `Add Configuration` bar and go
131105
to `Add New` -> `Gradle` -> `Environmental Variables`
132-
133-
* Gradle fails with a "too many open files" error.
134-
* You can check the `ulimit` for open files in your current shell by doing `ulimit -n` and raise it by
135-
calling `ulimit -n <new number>`
106+
</details>
136107

137108
## Running tests on another JVM
138109

@@ -146,18 +117,15 @@ To run tests on a different JVM than the one used for doing the build, you need
146117

147118
Please note that the JDK name needs to end with the JDK version, e.g. `11`, `ZULU15`, `ORACLE8`, `GRAALVM17`, etc.
148119

149-
## The APM Test Agent
120+
## The APM test agent
150121

151-
The APM test agent emulates the APM endpoints of the Datadog Agent. The Test Agent container runs alongside Java tracer
152-
Instrumentation Tests in CI, handling all traces during test runs and performing a number of `Trace Checks`. Trace
153-
Check results are returned within the `Get APM Test Agent Trace Check Results` step for all instrumentation test jobs.
154-
155-
For more information on Trace Checks, see:
156-
https://github.com/DataDog/dd-apm-test-agent#trace-invariant-checks
122+
The APM test agent emulates the APM endpoints of the Datadog Agent.
123+
The APM Test Agent container runs alongside Java tracer Instrumentation Tests in CI,
124+
handling all traces during test runs and performing a number of `Trace Checks`.
125+
Trace Check results are returned within the `Get APM Test Agent Trace Check Results` step for all instrumentation test jobs.
126+
Check [trace invariant checks](https://github.com/DataDog/dd-apm-test-agent#trace-invariant-checks) for more informations.
157127

158128
The APM Test Agent also emits helpful logging, including logging received traces' headers, spans, errors encountered,
159-
ands information on trace checks being performed. Logs can be viewed in CircleCI within the Test-Agent container step
160-
for all instrumentation test suites, ie: `z_test_8_inst` job
161-
162-
Read more about the APM Test Agent:
163-
https://github.com/datadog/dd-apm-test-agent#readme
129+
ands information on trace checks being performed.
130+
Logs can be viewed in CircleCI within the Test-Agent container step for all instrumentation test suites, ie: `z_test_8_inst` job.
131+
Read more about [the APM Test Agent](https://github.com/datadog/dd-apm-test-agent#readme).

‎gradle/spotless.gradle‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,16 @@ spotless {
5959
}
6060
}
6161

62+
format 'markdown', {
63+
toggleOffOn()
64+
target '*.md', '.github/**/*.md', 'src/**/*.md', 'application/**/*.md'
65+
indentWithSpaces()
66+
endWithNewline()
67+
}
68+
6269
format 'misc', {
6370
toggleOffOn()
64-
target '.gitignore', '*.md', '.github/**/*.md', 'src/**/*.md', 'application/**/*.md', '*.sh', 'tooling/*.sh', '.circleci/*.sh'
71+
target '.gitignore', '*.sh', 'tooling/*.sh', '.circleci/*.sh'
6572
indentWithSpaces()
6673
trimTrailingWhitespace()
6774
endWithNewline()

0 commit comments

Comments
 (0)