BUILDING.adoc - logging-log4j2 - Git at Google

 ////
     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.
	////
	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.