Skip to content

Commit a31ea22

Browse files
vyvy
committed
Improve build instructions
1 parent 8a918f5 commit a31ea22

9 files changed

+181
-145
lines changed

‎BUILDING.adoc

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
[#requirements]
19+
== Requirements
20+
21+
* JDK 11+
22+
* JDK 8 (optional)
23+
* A modern Linux, OSX, or Windows host
24+
25+
[#building]
26+
== Building the sources
27+
28+
You can build and verify the sources as follows:
29+
30+
[source,bash]
31+
----
32+
./mvnw verify
33+
----
34+
35+
`verify` goal runs validation and test steps next to building (i.e., compiling) the sources.
36+
To speed up the build, you can skip verification:
37+
38+
[source,bash]
39+
----
40+
./mvnw -DskipTests package
41+
----
42+
43+
If you want to install generated artifacts to your local Maven repository, replace above `verify` and/or `package` goals with `install`.
44+
45+
[#dns]
46+
=== DNS lookups in tests
47+
48+
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()`.
49+
To remedy this, you can execute the following:
50+
51+
[source,bash]
52+
----
53+
printf '127.0.0.1 %s\n::1 %s\n' `hostname` `hostname` | sudo tee -a /etc/hosts
54+
----
55+
56+
[#java8-tests]
57+
=== Java 8 tests
58+
59+
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:
60+
61+
[source,bash]
62+
----
63+
./mvnw verify -Pjava8-tests
64+
----
65+
66+
[#toolchains]
67+
=== Configuring Maven Toolchains
68+
69+
Maven Toolchains is used to employ additional JDKs required for tests.
70+
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`.
71+
72+
[source,xml]
73+
----
74+
<?xml version="1.0" encoding="UTF8"?>
75+
<toolchains>
76+
<toolchain>
77+
<type>jdk</type>
78+
<provides>
79+
<version>1.8.0_372</version>
80+
</provides>
81+
<configuration>
82+
<jdkHome>/usr/lib/jvm/java-8-openjdk-amd64</jdkHome>
83+
</configuration>
84+
</toolchain>
85+
</toolchains>
86+
----
87+
88+
[#website]
89+
== Building the website and manual
90+
91+
You can build the website and manual as follows:
92+
93+
[source,bash]
94+
----
95+
./mvnw site
96+
----
97+
98+
And view it using a simple HTTP server, e.g., the one comes with the Python:
99+
100+
[source,bash]
101+
----
102+
python3 -m http.server -d target/site
103+
----
104+
105+
[#development]
106+
== Development
107+
108+
You can follow below steps for casual development needs:
109+
110+
. Make sure you installed everything: `./mvnw install -DskipTests`
111+
. After making a change to, say, `log4j-core`, install your changes: `./mvnw install -pl :log4j-core -DskipTests`
112+
. Run all tests associated with `log4j-core`: `./mvnw test -pl :log4j-core-test`
113+
. Run a particular test: `./mvnw test -pl :log4j-core-test -Dtest=FooBarTest`
114+
115+
You can connect your IDE to a `./mvnw test` run by
116+
117+
. Add `-Dmaven.surefire.debug` to the `./mvnw test` command
118+
. Use _"Run > Attach to process"_ in IntelliJ IDEA
119+
120+
[#development-faq]
121+
=== F.A.Q
122+
123+
[#development-faq-idea-plugin-not-found]
124+
==== Compilation in IntelliJ IDEA fails with `java: plug-in not found: ErrorProne`
125+
126+
Try removing all _"Override compiler parameters per-module"_ entries in _"Settings > Build, Execution, Deployment > Compiler > Java Compiler"_.

‎BUILDING.md

-90
This file was deleted.

‎CODE_OF_CONDUCT.adoc

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
See https://www.apache.org/foundation/policies/conduct.html[the Apache Software Foundation's Code of Conduct].

‎CODE_OF_CONDUCT.md

-18
This file was deleted.

‎RELEASE-NOTES.adoc

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
See https://logging.apache.org/log4j/2.x/release-notes.html[the Release Notes page].

‎RELEASE-NOTES.md

-18
This file was deleted.

‎SECURITY.adoc

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
See https://logging.apache.org/log4j/2.x/security.html[the Security page].

‎SECURITY.md

-18
This file was deleted.

‎src/site/asciidoc/security.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ If you need help on building or configuring Log4j or other help on following the
3333
[TIP]
3434
====
3535
If you need to apply a source code patch, use the building instructions for the Log4j version that you are using.
36-
These instructions can be found in `BUILDING.md` distributed with the sources.
36+
These instructions can be found in `BUILDING.adoc` distributed with the sources.
3737
====
3838
3939
[#reporting]

0 commit comments

Comments
 (0)