Improve build instructions

neighbourhoodie · Nov 29, 2023 · a31ea22 · a31ea22
1 parent 8a918f5
commit a31ea22
Show file tree

Hide file tree

Showing 9 changed files with 181 additions and 145 deletions.
diff --git a/BUILDING.adoc b/BUILDING.adoc
@@ -0,0 +1,126 @@
+////
+    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 11+
+* JDK 8 (optional)
+* 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 and manual
+
+You can build the website and manual as follows:
+
+[source,bash]
+----
+./mvnw site
+----
+
+And view it using a simple HTTP server, e.g., the one comes with the Python:
+
+[source,bash]
+----
+python3 -m http.server -d target/site
+----
+
+[#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
+
+. Add `-Dmaven.surefire.debug` to the `./mvnw test` command
+. 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"_.
diff --git a/BUILDING.md b/BUILDING.md
diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc
@@ -0,0 +1,18 @@
+////
+    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.
+////
+
+See https://www.apache.org/foundation/policies/conduct.html[the Apache Software Foundation's Code of Conduct].
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
diff --git a/RELEASE-NOTES.adoc b/RELEASE-NOTES.adoc
@@ -0,0 +1,18 @@
+////
+    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.
+////
+
+See https://logging.apache.org/log4j/2.x/release-notes.html[the Release Notes page].
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
diff --git a/SECURITY.adoc b/SECURITY.adoc
@@ -0,0 +1,18 @@
+////
+    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.
+////
+
+See https://logging.apache.org/log4j/2.x/security.html[the Security page].
diff --git a/SECURITY.md b/SECURITY.md
diff --git a/src/site/asciidoc/security.adoc b/src/site/asciidoc/security.adoc
@@ -33,7 +33,7 @@ If you need help on building or configuring Log4j or other help on following the
 [TIP]
 ====
 If you need to apply a source code patch, use the building instructions for the Log4j version that you are using.
-These instructions can be found in `BUILDING.md` distributed with the sources.
+These instructions can be found in `BUILDING.adoc` distributed with the sources.
 ====
 
 [#reporting]