| //// |
| 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 |
| |
| To test the library against the target JRE (JRE 8), you need to configure a JDK 8 toolchains as explained below and run Maven with the `java8-tests` profile: |
| |
| [source,bash] |
| ---- |
| ./mvnw verify -Pjava8-tests |
| ---- |
| |
| [#toolchains] |
| === Configuring Maven 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`. |
| |
| [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> |
| ---- |
| |
| [#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: `./mvnw install -DskipTests` |
| . After making a change to, say, `log4j-core`, install your changes: `./mvnw install -pl :log4j-core -DskipTests` |
| . Run all tests associated with `log4j-core`: `./mvnw test -pl :log4j-core-test` |
| . Run a particular test: `./mvnw test -pl :log4j-core-test -Dtest=FooBarTest` |
| |
| 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-faq] |
| === F.A.Q |
| |
| [#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"_. |