Skip to content

Latest commit

 

History

History
230 lines (185 loc) · 7.17 KB

BUILDING.adoc

File metadata and controls

230 lines (185 loc) · 7.17 KB
Raw

Requirements

  • JDK 17+

  • A modern Linux, OSX, or Windows host

Building the sources

You can build and verify the sources as follows:

./mvnw verify

verify goal runs validation and test steps next to building (i.e., compiling) the sources. To speed up the build, you can skip verification:

./mvnw -DskipTests package

If you want to install generated artifacts to your local Maven repository, replace above verify and/or package goals with install.

DNS lookups in tests

Note that if your /etc/hosts file does not include an entry for your computer’s hostname, then many unit tests may execute slow due to DNS lookups to translate your hostname to an IP address in InetAddress.getLocalHost(). To remedy this, you can execute the following:

printf '127.0.0.1 %s\n::1 %s\n' `hostname` `hostname` | sudo tee -a /etc/hosts

Java 8 tests

You can run tests using the target JRE (i.e., JRE 8) as follows:

  1. Maven Toolchains is used to employ additional JDKs required for tests. You either need to have a user-level configuration in ~/.m2/toolchains.xml or explicitly provide one to the Maven: ./mvnw --global-toolchains /path/to/toolchains.xml.

    An example toolchains.xml containing a JDK 8 toolchain
    <?xml version="1.0" encoding="UTF8"?>
<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>1.8.0_372</version>
    </provides>
    <configuration>
      <jdkHome>/usr/lib/jvm/java-8-openjdk-amd64</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

  2. Run Maven tests with the java8-tests profile:

    ./mvnw verify -Pjava8-tests,!java8-incompat-fixes

Docker tests

Certain tests use Docker to spawn necessary external services. Docker tests are configured using the docker Maven profile, which is activated by default for the CI environment. You can locally enable this profile by passing a -P docker argument to your ./mvnw commands.

Building the website

You can build the website as follows:

./mvnw compile    # (1)
./mvnw site       # (2)

  1. Generate plugin descriptors that will be used to generate the plugin reference page. Descriptors are placed under target/plugin-descriptors.

  2. Generate the website to target/site

You can view the generated website with a browser by pointing it to target/site directory.

Development

You can follow below steps for casual development needs:

  1. Make sure you installed everything:

    ./mvnw install -DskipTests

  2. After making a change to, say, log4j-core, install your changes:

    ./mvnw install -pl :log4j-core -DskipTests

  3. Run all tests associated with log4j-core:

    ./mvnw test -pl :log4j-core-test

  4. Run a particular test:

    ./mvnw test -pl :log4j-core-test -Dtest=FooBarTest

  5. Make sure all build checks (Spotless, Spotbugs, BND, RAT, etc.) succeed:

    ./mvnw verify -DskipTests -pl :log4j-core,:log4j-core-test

Debugging ./mvnw test with IDE

You can connect your IDE to a ./mvnw test run by

  1. Run ./mvnw test -pl :log4j-core-test -Dtest=FooBarTest -Dmaven.surefire.debug

  2. Use "Run > Attach to process" in IntelliJ IDEA

Activating CI profiles

There are certain Maven profiles activated only for CI. As a consequence of this, you can observe certain CI failures that you can’t reproduce locally. To work around this, you can activate CI profiles by running Maven commands as follows:

CI=true ./mvnw ...

Compilation in IntelliJ IDEA fails with java: plug-in not found: ErrorProne

Try removing all "Override compiler parameters per-module" entries in "Settings > Build, Execution, Deployment > Compiler > Java Compiler".

Fixing API compatibility check failures

Log4j uses the BND Baseline Maven Plugin to enforce its semantic versioning policy. Following the OSGi versioning best practices, both Log4j artifacts and packages are versioned. If you modify Log4j’s public API, a BND Baseline error like the following will occur:

  Name                        Type     Delta      New    Old    Suggest  If Prov.
  org.apache.logging.foo      PACKAGE  UNCHANGED  2.1.0  2.1.0  ok       -
* org.apache.logging.foo.bar  PACKAGE  MINOR      2.3.4  2.3.4  2.4.0    -
  MINOR        PACKAGE    org.apache.logging.foo.bar
  ...

The solution of the error depends on the change kind (Delta):

MICRO

For patch level changes modify the package-info.java file of the org.apache.logging.foo.bar package and update the @Version annotation to the number suggested by BND: increment just the patch number.

@Version("2.3.5")
package org.apache.logging.foo.bar;
MINOR

Changes of type MINOR require more work:

  • Make sure that the current Log4j version is a minor upgrade over the last released version. If that is not the case (e.g., it is 2.34.5-SNAPSHOT) modify the <revision> property in the main POM file (e.g., change it to 2.35.0-SNAPSHOT).

  • Make sure to add a changelog entry of type added, changed or deprecated to your PR.

  • As in the MICRO case modify the package-info.java file of the package and update the @Version annotation to the next Log4j version (2.35.0 in the example) and not the minimal version number suggested by BND. The purpose of this policy is to have an alignment between package versions and the last Log4j version, where an API change occurred.

MAJOR

Changes of type MAJOR (i.e. breaking changes) are not accepted in the 2.x branch. If you believe it is not a breaking change (e.g., you removed a class documented as private), the development team will guide you on how to solve it.