////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////

[#requirements]
== Requirements

* JDK 17+
* A modern Linux, OSX, or Windows host

[#building]
== Building the sources

You can build and verify the sources as follows:

[source,bash]
----
./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:

[source,bash]
----
./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]
=== 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:

[source,bash]
----
printf '127.0.0.1 %s\n::1 %s\n' `hostname` `hostname` | sudo tee -a /etc/hosts
----

[#java8-tests]
=== Java 8 tests

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

[#toolchains]
. 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
[source,xml]
----
<?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>
----

. Run Maven tests with the `java8-tests` profile:
+
[source,bash]
----
./mvnw verify -Pjava8-tests,!java8-incompat-fixes
----

[#docker]
=== 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.

[#website]
== Building the website

You can build the website as follows:

[source,bash]
----
./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]
== Development

You can follow below steps for casual development needs:

. Make sure you installed everything:
+
[source,bash]
----
./mvnw install -DskipTests
----

. After making a change to, say, `log4j-core`, install your changes:
+
[source,bash]
----
./mvnw install -pl :log4j-core -DskipTests
----

. Run all tests associated with `log4j-core`:
+
[source,bash]
----
./mvnw test -pl :log4j-core-test
----

. Run a particular test:
+
[source,bash]
----
./mvnw test -pl :log4j-core-test -Dtest=FooBarTest
----

. Make sure all build checks (Spotless, Spotbugs, BND, RAT, etc.) succeed:
+
[source,bash]
----
./mvnw verify -DskipTests -pl :log4j-core,:log4j-core-test
----

[#development-ide-debug]
=== Debugging `./mvnw test` with IDE

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

. Run `./mvnw test -pl :log4j-core-test -Dtest=FooBarTest -Dmaven.surefire.debug`
. Use _"Run > Attach to process"_ in IntelliJ IDEA

[#development-ci]
=== 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:

[source,bash]
----
CI=true ./mvnw ...
----

[#development-faq-idea-plugin-not-found]
=== 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"_.

[#development-api-compatibility]
=== Fixing API compatibility check failures

Log4j uses the
https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-baseline-maven-plugin[BND Baseline Maven Plugin]
to enforce its
https://semver.org/[semantic versioning policy].
Following the
https://bnd.bndtools.org/chapters/170-versioning.html#best-practices[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:

[source]
----
  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`):

[#development-api-compatibility-micro]
`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.
+
[source,java]
----
@Version("2.3.5")
package org.apache.logging.foo.bar;
----

[#development-api-compatibility-minor]
`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
https://logging.apache.org/log4j/tools/log4j-changelog.html#changelog-entry-file[changelog entry]
of type `added`, `changed` or `deprecated` to your PR.
* As in the
<<development-api-compatibility-micro,`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.
--

[#development-api-compatibility-major]
`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.
