ppkarwasz commented on code in PR #2480: URL: https://github.com/apache/logging-log4j2/pull/2480#discussion_r1570350145
########## src/site/antora/modules/ROOT/pages/manual/installation.adoc: ########## @@ -0,0 +1,722 @@ +//// + 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. +//// + +:jcl-link: https://commons.apache.org/proper/commons-logging/[JCL (Apache Commons Logging)] +:jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] +:jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] +:jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging] + += Installation + +In this page we will elaborate on various ways to install Log4j in your library or application. + +[#impatient] +== For the impatient + +Below we share some shortcuts for the impatient. + +[WARNING] +==== +We strongly advise you to skim through this page to get a grip on fundamental logging concepts and understand which recipe fits to your bill best. +==== + +Are you a library developer?:: +You just need to log against xref:#logging-api[a logging API]. +See <<api>>. + +Are you an application developer?:: +Your code and libraries it depends on are most probably already logging against a logging API, you just need to install xref:#logging-impl[a logging implementation]. +See <<impl-core>>. + +Are you a Spring Boot application developer?:: +See <<impl-core-spring-boot>>. + +[#concepts] +== Concepts (APIs, Implementations, and Bridges) + +It is crucial to understand certain concepts in logging to be able to talk about the installation of them. + +[#logging-api] +Logging API:: +A logging API is an interface your code or your dependencies directly logs against. +It is implementation agnostic. +Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. + +[#logging-impl] +Logging implementation:: +A logging implementation is only required at runtime and can be changed without the need to recompile your software. +Log4j Core, {jul-link}, {logback-link} are the most well-known logging implementations. ++ +[TIP] +==== +Note that JUL and Log4j provide both an API and its implementation. +In the case of Log4j, the API is called _Log4j API_, and its reference implementation is called _Log4j Core_. +==== + +[#logging-bridge] +Logging API bridges:: +Logging implementations are generally developed to directly accept input from a primary API of their preference; Log4j Core from Log4j API, Logback from SLF4J, etc. +Logging API bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API. Review Comment: _Nit_: technically logging bridges are logging implementations. So maybe: "Logging implementations accept input only from one API:..." And: "Logging bridges are simple implementations of a logging API that forward all messages to a foreign API" -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
