diff --git a/.gitignore b/.gitignore index dbaf83a8c..a845dd581 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ ar-lib config** +!configuration-samples.md depcomp install-sh liblog4cxx.pc diff --git a/CMakeLists.txt b/CMakeLists.txt index b728ff724..63cbfe5b4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -7,6 +7,8 @@ include(CTest) # (at least in the past it was project vesion: 0.a.b.c and the library so vesion a.b.c.0 set(LIBLOG4CXX_LIB_VERSION ${log4cxx_VERSION_MINOR}.${log4cxx_VERSION_PATCH}.${log4cxx_VERSION_TWEAK}) set(LIBLOG4CXX_LIB_SOVERSION ${log4cxx_VERSION_MINOR}) +# Set the 'release' version. This is the human-readable version +set(LOG4CXX_RELEASE_VERSION ${log4cxx_VERSION_MAJOR}.${log4cxx_VERSION_MINOR}.${log4cxx_VERSION_PATCH}) # FindAPR and FindAPR-util are not provided by APR and APR-Util so source them locally list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/src/cmake") @@ -103,6 +105,25 @@ foreach(varName HAS_STD_LOCALE HAS_ODBC HAS_MBSRTOWCS HAS_WCSTOMBS HAS_FWIDE endif() endforeach() +# +# Package and sign if Apache maintainer +# +option(APACHE_MAINTAINER "Apache maintainer" OFF) +if(APACHE_MAINTAINER) + set(CPACK_SOURCE_PACKAGE_FILE_NAME "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}") + set(CPACK_SOURCE_GENERATOR "TGZ;ZIP") + set(CPACK_SOURCE_IGNORE_FILES ".git/;build/;.vs/;out/") + include(CPack) + + add_custom_target( dist + COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} -- package_source + COMMAND ${CMAKE_COMMAND} -E sha512sum "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512" + COMMAND ${CMAKE_COMMAND} -E sha512sum "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512" + COMMAND gpg -ab --yes "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc" + COMMAND gpg -ab --yes "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc" + ) +endif() + # # Output configuration information # Similar to APR CMake configuration @@ -114,6 +135,7 @@ message(STATUS "") message(STATUS " Build shared library ............ : ${BUILD_SHARED_LIBS}") message(STATUS " Build tests ..................... : ${BUILD_TESTING}") +message(STATUS " Build site ...................... : ${BUILD_SITE}") message(STATUS " Install prefix .................. : ${CMAKE_INSTALL_PREFIX}") message(STATUS " C++ compiler .................... : ${CMAKE_CXX_COMPILER}") message(STATUS " log4cxx char API ................ : ${LOG4CXX_CHAR}") diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index aa2d16ebf..be6917388 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -13,3 +13,5 @@ if(BUILD_TESTING) add_subdirectory(test) add_subdirectory(examples/cpp) endif() + +add_subdirectory(site) diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt index 05614b3f8..4677ebbd9 100644 --- a/src/examples/cpp/CMakeLists.txt +++ b/src/examples/cpp/CMakeLists.txt @@ -1,4 +1,4 @@ -set(ALL_LOG4CXX_EXAMPLES console delayedloop stream trivial) +set(ALL_LOG4CXX_EXAMPLES console delayedloop stream trivial custom-appender) foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES) add_executable(${exampleName} ${exampleName}.cpp) @@ -6,3 +6,7 @@ foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES) target_include_directories(${exampleName} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $) target_link_libraries(${exampleName} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${XMLLIB_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS}) endforeach() + +configure_file( custom-appender.xml + ${CMAKE_CURRENT_BINARY_DIR}/custom-appender.xml + COPYONLY ) diff --git a/src/examples/cpp/custom-appender.cpp b/src/examples/cpp/custom-appender.cpp new file mode 100644 index 000000000..5154090dd --- /dev/null +++ b/src/examples/cpp/custom-appender.cpp @@ -0,0 +1,71 @@ +/* + * 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. + */ + +#include +#include +#include +#include +#include +#include + +namespace log4cxx { + +class NullWriterAppender : public log4cxx::AppenderSkeleton { +public: + DECLARE_LOG4CXX_OBJECT(NullWriterAppender) + BEGIN_LOG4CXX_CAST_MAP() + LOG4CXX_CAST_ENTRY(NullWriterAppender) + LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton) + END_LOG4CXX_CAST_MAP() + + NullWriterAppender(){} + + virtual void close(){} + + virtual bool requiresLayout() const { + return false; + } + + virtual void append(const spi::LoggingEventPtr& event, log4cxx::helpers::Pool& p){ + // This gets called whenever there is a valid event for our appender. + } + + virtual void activateOptions(log4cxx::helpers::Pool& /* pool */) { + // Given all of our options, do something useful(e.g. open a file) + } + + virtual void setOption(const LogString& option, const LogString& value){ + if (helpers::StringHelper::equalsIgnoreCase(option, + LOG4CXX_STR("SOMEVALUE"), LOG4CXX_STR("somevalue"))){ + // Do something with the 'value' here. + } + } +}; + +IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender) + +} + +int main( int argc, char** argv ){ + log4cxx::xml::DOMConfigurator::configure( "custom-appender.xml" ); + + log4cxx::LoggerPtr rootLogger = log4cxx::Logger::getRootLogger(); + log4cxx::LoggerPtr nullLogger = log4cxx::Logger::getLogger( "NullLogger" ); + + LOG4CXX_INFO( rootLogger, "This is some root message" ); + LOG4CXX_INFO( nullLogger, "This message will be discarded" ); +} diff --git a/src/examples/cpp/custom-appender.xml b/src/examples/cpp/custom-appender.xml new file mode 100644 index 000000000..f7b40e8ca --- /dev/null +++ b/src/examples/cpp/custom-appender.xml @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/CMakeLists.txt b/src/site/CMakeLists.txt new file mode 100644 index 000000000..d83949e14 --- /dev/null +++ b/src/site/CMakeLists.txt @@ -0,0 +1,15 @@ +option(BUILD_SITE "Build log4cxx website" OFF) +if(BUILD_SITE) + find_package( Doxygen REQUIRED dot ) + configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/doxy/Doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ) + + configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/markdown/download.md.in + ${CMAKE_CURRENT_BINARY_DIR}/markdown/download.md ) + + add_custom_target( doc_doxygen ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generate site with Doxygen" + VERBATIM ) +endif() diff --git a/src/site/apt/building/cmake.apt b/src/site/apt/building/cmake.apt deleted file mode 100644 index 9bfb7946f..000000000 --- a/src/site/apt/building/cmake.apt +++ /dev/null @@ -1,147 +0,0 @@ -~~ 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. - ------ - Building Apache log4cxx with CMake - ------ - ------ - ------ - -Building Apache log4cxx with CMake - -* Quick start: - - Building and testing log4cxx on a Unix platform with packaged APR and APR-Util. - - Make sure cmake 3.13+, g++ and make are available, install or - build apr 1.x, apr-util 1.x, gzip and zip. - -+------------+ -$ apt-get install build-essential libapr1-dev libaprutil1-dev gzip zip -$ cd apache-log4cxx-x.x.x -$ mkdir build -$ cd build -$ ccmake .. -$ make -$ sudo make install -+------------+ - -* ccmake options - -*------------------------+---------------------------------------------------------------------------------------------+ -| -DLOG4CXX_WCHAR_T=no | Enable wchar_t API methods, choice of yes (default), no. | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DLOG4CXX_UNICHAR=yes | Enable UniChar API methods, choice of yes, no (default). | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DBUILD_TESTING=off | Do not build tests. Tests are built by default | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DBUILD_SHARED_LIBS=off| Build log4cxx as a static library. A dynamically linked log4cxx library is built by default.| -| | Any compilation unit that includes a log4cxx header must define LOG4CXX_STATIC. | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DAPU_STATIC=yes | Link to the APR-Util static library. By default, the log4cxx shared library is linked to the| -| | APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used. | -*------------------------+---------------------------------------------------------------------------------------------+ -| -DAPR_STATIC=yes | Link to the APR static library. By default, the log4cxx shared library is linked to the | -| | APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used. | -*------------------------+---------------------------------------------------------------------------------------------+ -|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs. Log4cxx requires zip, | -| | sed, and grep on the PATH in order for the tests to work properly. | -*------------------------+---------------------------------------------------------------------------------------------+ - - Building and testing log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source - extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%\Libraries. - -+------------+ -$ cd %HOMEPATH%\Libraries -$ cmake -S libexpat\expat -B buildtrees\expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed -$ cmake --build buildtrees\expat --target install --config Release -$ cmake -S apr-1.7.0 -B buildtrees\apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed -$ cmake --build buildtrees\apr --target install --config Release -$ set CMAKE_PREFIX_PATH=%HOMEPATH%\Libraries\installed -$ cmake -S apr-util-1.6.1 -B buildtrees\apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed -$ cmake --build buildtrees\apr-util --target install --config Release -$ cmake -S apache-log4cxx-x.x.x -B buildtrees\log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed -$ cmake --build buildtrees\log4cxx --target install --config Release -+------------+ - -* Platform specific notes: - -** Mac OS/X: - - APR and APR-Util are provided by the platform in Mac OS/X 10.5 and iODBC in 10.4. - - cmake can be installed by typing "brew install cmake". - -** Debian: - - APR, APR-Util, openssl, gzip and zip may be installed by: - -+----+ -$ sudo apt-get install libssl-dev libapr1-dev libaprutil1-dev gzip zip -+----+ - - CMake can be built from source by typing: - -+----+ -$ wget https://github.com/Kitware/CMake/releases/download/v3.16.4/cmake-3.16.4.tar.gz -$ tar xf cmake-3.16.4.tar.gz -$ cd cmake-3.16.4 -$ ./bootstrap -$ make -$ sudo make install -+----+ - -** FreeBSD: - - APR, APR-Util, gzip and zip may be installed from the ports collection by: - -+----+ -$ cd /usr/ports/archivers/zip -$ make -$ make install -$ cd /usr/ports/archivers/gzip -$ make -$ make install -$ cd /usr/ports/devel/apr -$ make -$ make install -+----+ - -** Windows: - -The easiest way to get dependencies installed is to use vcpkg(for APR/expat), and msys2 for the command-line -utilities(zip, grep, sed). - -Msys2 can be downloaded from: https://www.msys2.org/ -By default, this will be installed under C:\msys2, so you can add that to the build PATH by setting -LOG4CXX_TEST_PROGRAM_PATH=C:/msys64/usr/bin in your build settings. - -For vcpkg, follow the directions at https://github.com/microsoft/vcpkg#quick-start-windows and then install -the dependencies needed using `vcpkg install apr apr-util`. - -* Using log4cxx in a CMake build - - A log4cxxConfig.cmake and log4cxxConfigVersion.cmake is installed to allow use of find_package() - in your CMakeLists.txt. - - Below are example cmake commands that compile and link "myApplication" with log4cxx. - -+----+ -find_package(log4cxx 0.11) -add_executable(myApplication myMain.cpp) -target_include_directories(myApplication PRIVATE $) -target_link_libraries( myApplication PRIVATE log4cxx) -+----+ diff --git a/src/site/apt/building/vcpkg.apt b/src/site/apt/building/vcpkg.apt deleted file mode 100644 index 4c3bdecab..000000000 --- a/src/site/apt/building/vcpkg.apt +++ /dev/null @@ -1,43 +0,0 @@ -~~ 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. - ------ - Building Apache log4cxx with vcpkg - ------ - ------ - ------ - -Building Apache log4cxx with vcpkg - -*Preparation - -+----+ - > git clone https://github.com/Microsoft/vcpkg.git - > cd vcpkg - - PS> .\bootstrap-vcpkg.bat - Linux:~/$ ./bootstrap-vcpkg.sh - - Then, to hook up user-wide integration, run (note: requires admin on first use) - - PS> .\vcpkg integrate install - Linux:~/$ ./vcpkg integrate install -+----+ - -*Building log4cxx.dll - -+----+ - PS> .\vcpkg install log4cxx - Linux:~/$ ./vcpkg install log4cxx -+----+ diff --git a/src/site/apt/community/issue-tracking.apt b/src/site/apt/community/issue-tracking.apt deleted file mode 100644 index 745923b7d..000000000 --- a/src/site/apt/community/issue-tracking.apt +++ /dev/null @@ -1,48 +0,0 @@ -~~ 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. - ------ -Issue Tracking - ------ - ------ - ------ - -Overview - - This project uses {{{https://www.atlassian.com/software/jira}JIRA}}, a J2EE-based issue tracking - and project management application. - -Issue Tracking - - <> and <> should be submitted to the following issue tracking system - for this project. - - {{{https://issues.apache.org/jira/browse/LOGCXX}https://issues.apache.org/jira/browse/LOGCXX}} - - <>, some issues simply - don't are bugs in the code base of the project or it's build tools, but may have a lot of - different other reasons. If things don't work for you and you need some help, please subscribe - to the {{{https://logging.apache.org/log4cxx/mail-lists.html}users mailing list}} and describe - the issue you have, the more detailed the better. The mailing list is a far better place to - discuss things than JIRA, besides that there are more users than developers of the project and - issues created in JIRA are only forwarded to the latter. There's always the chance to create an - issue in JIRA later, hopefully with a specific explanation of the problem and even a solution - already. - - As a rule of thumb, if you already digged through the code and found a problem in it or its - build tools, feel free to directly create a bug in {{{https://issues.apache.org/jira/browse/LOGCXX}JIRA}}. - But if things really only don't work and you don't have any clue why, please use the {{{https://logging.apache.org/log4cxx/mail-lists.html}users mailing listt}} - instead. - - Thanks! \ No newline at end of file diff --git a/src/site/apt/download.apt.vm b/src/site/apt/download.apt.vm deleted file mode 100644 index 6b6bdeb01..000000000 --- a/src/site/apt/download.apt.vm +++ /dev/null @@ -1,58 +0,0 @@ -~~ 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. - ------ -Download Apache log4cxx ${releaseVersion} - ------ - ------ - ------ - -Download Apache log4cxx ${releaseVersion} - - Apache log4cxx ${releaseVersion} is distributed under the {{{https://www.apache.org/licenses/LICENSE-2.0.html} Apache License, version 2.0}}. - - The link in the Mirrors column should display a list of available mirrors with a - default selection based on your inferred location. If you do not see that page, - try a different browser. The checksum and signature are links to - the originals on the main distribution server. - -*-------------------------+---------+----------+-----------+ -| | Mirrors | Checksum | Signature | -*-------------------------+---------+----------+-----------+ -| Apache log4cxx ${releaseVersion} (tar.gz) | {{{https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz} ${releaseArtifactId}-${releaseVersion}.tar.gz}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz.sha512} ${releaseArtifactId}-${releaseVersion}.tar.gz.sha512}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz.asc} ${releaseArtifactId}-${releaseVersion}.tar.gz.asc}} | -*-------------------------+---------+----------+-----------+ -| Apache log4cxx ${releaseVersion} (zip) | {{{https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip} ${releaseArtifactId}-${releaseVersion}.zip}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip.sha512} ${releaseArtifactId}-${releaseVersion}.zip.sha512}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip.asc} ${releaseArtifactId}-${releaseVersion}.zip.asc}} | -*-------------------------+---------+----------+-----------+ - - It is essential that you verify the integrity of the downloaded files using the PGP or SHA512 signatures. - Please read {{{https://httpd.apache.org/dev/verification.html}Verifying Apache HTTP Server Releases}} for more - information on why you should verify our releases. - - The PGP signatures can be verified using PGP or GPG. First download the {{{https://www.apache.org/dist/logging/KEYS}KEYS}} - as well as the asc signature file for the relevant distribution. Make sure you get these files from the - {{{https://www.apache.org/dist/logging/}main distribution directory}}, rather than from a mirror. Then verify the signatures using: - ---- -% gpg --import KEYS -% gpg --verify ${releaseArtifactId}-${releaseVersion}.tar.gz.asc ${releaseArtifactId}-${releaseVersion}.tar.gz ---- - - * ${releaseArtifactId}-${releaseVersion} is signed by ${releaseManager} (${releaseKey}) - - Alternatively, you can verify the SHA512 signature on the files. A unix program called sha512 or sha512sum is included - in many unix distributions. - -* Previous Releases - - All previous releases of Apache log4cxx can be found in the {{{https://archive.apache.org/dist/logging/log4cxx}archive repository}}. diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt deleted file mode 100644 index 4eb49dd23..000000000 --- a/src/site/apt/index.apt +++ /dev/null @@ -1,45 +0,0 @@ -~~ 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. - ------ -Short introduction to Apache log4cxx - ------ - ------ - ------ - -Short introduction to Apache log4cxx - - Apache log4cxx is a logging framework for C++ patterned after - {{{https://logging.apache.org/log4j}Apache log4j}}, which uses - {{{https://apr.apache.org}Apache Portable Runtime}} for most platform-specific code and should - be usable on any platform supported by APR. Apache log4cxx is licensed under the - {{{https://www.apache.org/licenses}Apache License}}, an open source license certified by the - {{{https://www.opensource.org}Open Source Initiative}}. - - Almost every large application includes its own logging or tracing API. Inserting log - statements into code is a low-tech method for debugging it. It may also be the only way because - debuggers are not always available or applicable. This is usually the case for multithreaded - applications and distributed applications at large. - - Experience indicates that logging is an important component of the development cycle. It offers - several advantages. It provides precise context about a run of the application. Once inserted - into the code, the generation of logging output requires no human intervention. Moreover, log - output can be saved in persistent medium to be studied at a later time. In addition to its use - in the development cycle, a sufficiently rich logging package can also be viewed as an auditing - tool. - - Logging does have its drawbacks. It can slow down an application. If too verbose, it can cause - scrolling blindness. To alleviate these concerns, log4cxx is designed to be reliable, fast and - extensible. Since logging is rarely the main focus of an application, the log4cxx API strives - to be simple to understand and to use. diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in index 37c21f429..989a9350f 100644 --- a/src/site/doxy/Doxyfile.in +++ b/src/site/doxy/Doxyfile.in @@ -13,7 +13,7 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Doxyfile 1.8.6 +# Doxyfile 1.8.13 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -53,7 +53,7 @@ PROJECT_NAME = "Apache log4cxx" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "Version @version@" +PROJECT_NUMBER = "Version ${LOG4CXX_RELEASE_VERSION}" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -61,10 +61,10 @@ PROJECT_NUMBER = "Version @version@" PROJECT_BRIEF = -# With the PROJECT_LOGO tag one can specify an logo or icon that is included in -# the documentation. The maximum height of the logo should not exceed 55 pixels -# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo -# to the output directory. +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. PROJECT_LOGO = @@ -73,9 +73,9 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = . +OUTPUT_DIRECTORY = -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where @@ -85,6 +85,14 @@ OUTPUT_DIRECTORY = . CREATE_SUBDIRS = NO +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. @@ -100,14 +108,14 @@ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the @@ -125,7 +133,17 @@ REPEAT_BRIEF = YES # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief @@ -142,7 +160,7 @@ ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. @@ -212,9 +230,9 @@ MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a -# new page for each member. If set to NO, the documentation of a member will be -# part of the file/class/namespace that contains it. +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO @@ -276,11 +294,14 @@ OPTIMIZE_OUTPUT_VHDL = NO # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. # -# Note For files without extension you can use no_extension as a placeholder. +# Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. @@ -297,10 +318,19 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 0. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 0 + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by by putting a % sign in front of the word -# or globally by setting AUTOLINK_SUPPORT to NO. +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES @@ -313,7 +343,7 @@ AUTOLINK_SUPPORT = YES # diagrams that involve STL classes more complete and accurate. # The default value is: NO. -BUILTIN_STL_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. @@ -340,13 +370,20 @@ SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first +# tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent @@ -405,7 +442,7 @@ LOOKUP_CACHE_SIZE = 0 # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. @@ -413,37 +450,37 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. EXTRACT_PRIVATE = NO -# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined -# locally in source files will be included in the documentation. If set to NO +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. -EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local methods, +# This flag is only useful for Objective-C code. If set to YES, local methods, # which are defined in the implementation section but not in the interface are -# included in the documentation. If set to NO only methods in the interface are +# included in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. @@ -468,21 +505,21 @@ HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set -# to NO these classes will be included in the various overviews. This option has -# no effect if EXTRACT_ALL is enabled. +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO these declarations will be +# (class|struct|union) declarations. If set to NO, these declarations will be # included in the documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any -# documentation blocks found inside the body of a function. If set to NO these +# documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. @@ -496,26 +533,33 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES upper-case letters are also +# names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. # The default value is: system dependent. -CASE_SENSE_NAMES = NO +CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with -# their full class and namespace scopes in the documentation. If set to YES the +# their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. -HIDE_SCOPE_NAMES = YES +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. -SHOW_INCLUDE_FILES = NO +SHOW_INCLUDE_FILES = YES # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader @@ -538,14 +582,14 @@ INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. +# name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. Note that +# name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. # The default value is: NO. @@ -590,32 +634,30 @@ SORT_BY_SCOPE_NAME = NO STRICT_PROTO_MATCHING = NO -# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the -# todo list. This list is created by putting \todo commands in the -# documentation. +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the -# test list. This list is created by putting \test commands in the -# documentation. +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. # The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in # the documentation. # The default value is: YES. -GENERATE_DEPRECATEDLIST= NO +GENERATE_DEPRECATEDLIST= YES # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond @@ -635,8 +677,8 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at -# the bottom of the documentation of classes and structs. If set to YES the list -# will mention the files that were used to generate the documentation. +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES @@ -676,7 +718,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = +LAYOUT_FILE = ${CMAKE_SOURCE_DIR}/src/site/doxy/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -684,8 +726,7 @@ LAYOUT_FILE = # to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the -# search path. Do not use file names with spaces, bibtex cannot handle them. See -# also \cite for info how to create references. +# search path. See also \cite for info how to create references. CITE_BIB_FILES = @@ -701,7 +742,7 @@ CITE_BIB_FILES = QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. @@ -709,12 +750,12 @@ QUIET = NO WARNINGS = YES -# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -726,12 +767,18 @@ WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO doxygen will only warn about wrong or incomplete parameter -# documentation, but not about the absence of documentation. +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. # The default value is: NO. WARN_NO_PARAMDOC = NO +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated @@ -755,11 +802,12 @@ WARN_LOGFILE = # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with -# spaces. +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @base_dir@/src/main/include \ - @base_dir@/target/mainpage.dox +INPUT = ${CMAKE_SOURCE_DIR}/src/main/include \ + ${CMAKE_SOURCE_DIR}/src/site/markdown \ + ${CMAKE_BINARY_DIR}/src/site/markdown # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -772,14 +820,62 @@ INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank the -# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, -# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, -# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, -# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, -# *.qsf, *.as and *.js. - -FILE_PATTERNS = *.h +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f \ + *.for \ + *.tcl \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -834,7 +930,7 @@ EXAMPLE_PATH = # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = * # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands @@ -847,7 +943,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = ${CMAKE_SOURCE_DIR}/src/site/images # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -863,6 +959,10 @@ IMAGE_PATH = # Note that the filter must not add or remove lines; it is applied before the # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. INPUT_FILTER = @@ -872,11 +972,15 @@ INPUT_FILTER = # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how # filters are used. If the FILTER_PATTERNS tag is empty or if none of the # patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER ) will also be used to filter the input files that are used for +# INPUT_FILTER) will also be used to filter the input files that are used for # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). # The default value is: NO. @@ -895,7 +999,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = ${CMAKE_SOURCE_DIR}/src/site/markdown/index.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -936,7 +1040,7 @@ REFERENCED_BY_RELATION = NO REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set -# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. @@ -981,15 +1085,15 @@ USE_HTAGS = NO # See also: Section \class. # The default value is: YES. -VERBATIM_HEADERS = NO +VERBATIM_HEADERS = YES -# If the CLANG_ASSISTED_PARSING tag is set to YES, then doxygen will use the -# clang parser (see: http://clang.llvm.org/) for more acurate parsing at the +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the # cost of reduced performance. This can be particularly helpful with template # rich C++ code for which doxygen's built-in parser lacks the necessary type # information. # Note: The availability of this option depends on whether or not doxygen was -# compiled with the --with-libclang option. +# generated with the -Duse-libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO @@ -1018,7 +1122,7 @@ ALPHABETICAL_INDEX = YES # Minimum value: 1, maximum value: 20, default value: 5. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. -COLS_IN_ALPHA_INDEX = 2 +COLS_IN_ALPHA_INDEX = 5 # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag @@ -1032,7 +1136,7 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = YES @@ -1043,7 +1147,7 @@ GENERATE_HTML = YES # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_OUTPUT = @manual_dest@ +HTML_OUTPUT = html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). @@ -1080,7 +1184,7 @@ HTML_HEADER = # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = @base_dir@/src/site/doxy/license_notice_footer.txt +HTML_FOOTER = ${CMAKE_SOURCE_DIR}/src/site/doxy/footer.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1094,16 +1198,18 @@ HTML_FOOTER = @base_dir@/src/site/doxy/license_notice_footer.txt HTML_STYLESHEET = -# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- -# defined cascading style sheet that is included after the standard style sheets +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefor more robust against future updates. -# Doxygen will copy the style sheet file to the output directory. For an example -# see the documentation. +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = ${CMAKE_SOURCE_DIR}/src/site/doxy/customdoxygen.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1116,7 +1222,7 @@ HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the stylesheet and background images according to +# will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see # http://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 @@ -1147,8 +1253,9 @@ HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: YES. +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = NO @@ -1244,28 +1351,29 @@ GENERATE_HTMLHELP = NO CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path -# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# including file name) of the HTML help compiler (hhc.exe). If non-empty, # doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = -# The GENERATE_CHI flag controls if a separate .chi index file is generated ( -# YES) or that it should be included in the master .chm file ( NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = -# The BINARY_TOC flag controls whether a binary table of contents is generated ( -# YES) or a normal table of contents ( NO) in the .chm file. +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1378,7 +1486,7 @@ DISABLE_INDEX = NO # index structure (just like the one that is generated for HTML Help). For this # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the -# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine-tune the look of the index. As an example, the default style # sheet generated by doxygen has an example that shows how to put an image at # the root of the tree instead of the PROJECT_NAME. Since the tree basically has @@ -1406,7 +1514,7 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1435,7 +1543,7 @@ FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering -# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path # to it using the MATHJAX_RELPATH option. @@ -1505,11 +1613,11 @@ SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a web server instead of a web client using Javascript. There -# are two flavours of web server based searching depending on the -# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for -# searching and an index file used by the script. When EXTERNAL_SEARCH is -# enabled the indexing and searching needs to be provided by external tools. See -# the section "External Indexing and Searching" for details. +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. # The default value is: NO. # This tag requires that the tag SEARCHENGINE is set to YES. @@ -1521,7 +1629,7 @@ SERVER_BASED_SEARCH = NO # external search engine pointed to by the SEARCHENGINE_URL option to obtain the # search results. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library # Xapian (see: http://xapian.org/). # @@ -1534,7 +1642,7 @@ EXTERNAL_SEARCH = NO # The SEARCHENGINE_URL should point to a search engine hosted by a web server # which will return the search results when EXTERNAL_SEARCH is enabled. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library # Xapian (see: http://xapian.org/). See the section "External Indexing and # Searching" for details. @@ -1572,7 +1680,7 @@ EXTRA_SEARCH_MAPPINGS = # Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. GENERATE_LATEX = NO @@ -1603,7 +1711,7 @@ LATEX_CMD_NAME = latex MAKEINDEX_CMD_NAME = makeindex -# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1618,12 +1726,15 @@ COMPACT_LATEX = NO # The default value is: a4. # This tag requires that the tag GENERATE_LATEX is set to YES. -PAPER_TYPE = a4wide +PAPER_TYPE = a4 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names -# that should be included in the LaTeX output. To get the times font for -# instance you can specify -# EXTRA_PACKAGES=times +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} # If left blank no extra packages will be included. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1637,23 +1748,36 @@ EXTRA_PACKAGES = # # Note: Only use a user-defined header if you know what you are doing! The # following commands have a special meaning inside the header: $title, -# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will -# replace them by respectively the title of the page, the current date and time, -# only the current date, the version number of doxygen, the project name (see -# PROJECT_NAME), or the project number (see PROJECT_NUMBER). +# $datetime, $date, $doxygenversion, $projectname, $projectnumber, +# $projectbrief, $projectlogo. Doxygen will replace $title with the empty +# string, for the replacement values of the other commands the user is referred +# to HTML_HEADER. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = # The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the # generated LaTeX document. The footer should contain everything after the last -# chapter. If it is left blank doxygen will generate a standard footer. +# chapter. If it is left blank doxygen will generate a standard footer. See +# LATEX_HEADER for more information on how to generate a default footer and what +# special commands can be used inside the footer. # # Note: Only use a user-defined footer if you know what you are doing! # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_FOOTER = +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the LATEX_OUTPUT output # directory. Note that the files will be copied as-is; there are no commands or @@ -1669,15 +1793,15 @@ LATEX_EXTRA_FILES = # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -PDF_HYPERLINKS = NO +PDF_HYPERLINKS = YES -# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES to get a +# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES, to get a # higher quality PDF documentation. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -USE_PDFLATEX = NO +USE_PDFLATEX = YES # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode # command to the generated LaTeX files. This will instruct LaTeX to keep running @@ -1713,11 +1837,19 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The # RTF output is optimized for Word 97 and may not look too pretty with other RTF # readers/editors. # The default value is: NO. @@ -1732,7 +1864,7 @@ GENERATE_RTF = NO RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1769,11 +1901,21 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = +# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code +# with syntax highlighting in the RTF output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_SOURCE_CODE = NO + #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for # classes and files. # The default value is: NO. @@ -1797,6 +1939,13 @@ MAN_OUTPUT = man MAN_EXTENSION = .3 +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + # If the MAN_LINKS tag is set to YES and doxygen generates man output, then it # will generate one additional man file for each entity documented in the real # man page(s). These additional files only source the real man page, but without @@ -1810,7 +1959,7 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that # captures the structure of the code including all documentation. # The default value is: NO. @@ -1824,7 +1973,7 @@ GENERATE_XML = NO XML_OUTPUT = xml -# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to # the XML output. Note that enabling this will significantly increase the size # of the XML output. @@ -1837,7 +1986,7 @@ XML_PROGRAMLISTING = YES # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- -# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files # that can be used to generate PDF. # The default value is: NO. @@ -1851,14 +2000,23 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook +# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the +# program listings (including syntax highlighting and cross-referencing +# information) to the DOCBOOK output. Note that enabling this will significantly +# increase the size of the DOCBOOK output. +# The default value is: NO. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_PROGRAMLISTING = NO + #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen -# Definitions (see http://autogen.sf.net) file that captures the structure of -# the code including all documentation. Note that this feature is still -# experimental and incomplete at the moment. +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sf.net) file that captures the +# structure of the code including all documentation. Note that this feature is +# still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -1867,7 +2025,7 @@ GENERATE_AUTOGEN_DEF = NO # Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module # file that captures the structure of the code including all documentation. # # Note that this feature is still experimental and incomplete at the moment. @@ -1875,7 +2033,7 @@ GENERATE_AUTOGEN_DEF = NO GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary # Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI # output from the Perl module output. # The default value is: NO. @@ -1883,9 +2041,9 @@ GENERATE_PERLMOD = NO PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely # formatted so it can be parsed by a human reader. This is useful if you want to -# understand what is going on. On the other hand, if this tag is set to NO the +# understand what is going on. On the other hand, if this tag is set to NO, the # size of the Perl module output will be much smaller and Perl will parse it # just the same. # The default value is: YES. @@ -1905,20 +2063,20 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all # C-preprocessor directives found in the sources and include files. # The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names -# in the source code. If set to NO only conditional compilation will be +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be # performed. Macro expansion can be done in a controlled way by setting # EXPAND_ONLY_PREDEF to YES. # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = YES +MACRO_EXPANSION = NO # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and @@ -1928,7 +2086,7 @@ MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# If the SEARCH_INCLUDES tag is set to YES, the include files in the # INCLUDE_PATH will be searched if a #include is found. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. @@ -1972,9 +2130,9 @@ PREDEFINED = LOG4CXX_WCHAR_T_API \ EXPAND_AS_DEFINED = # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will -# remove all refrences to function-like macros that are alone on a line, have an -# all uppercase name, and do not end with a semicolon. Such function macros are -# typically used for boiler-plate code, and will confuse the parser if not +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not # removed. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. @@ -1994,7 +2152,7 @@ SKIP_FUNCTION_MACROS = YES # where loc1 and loc2 can be relative or absolute paths or URLs. See the # section "Linking to external documentation" for more information about the use # of tag files. -# Note: Each tag file must have an unique name (where the name does NOT include +# Note: Each tag file must have a unique name (where the name does NOT include # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. @@ -2006,20 +2164,21 @@ TAGFILES = GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external class will be listed in the -# class index. If set to NO only the inherited external classes will be listed. +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. # The default value is: NO. ALLEXTERNALS = NO -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in -# the modules index. If set to NO, only the current project's groups will be +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. EXTERNAL_GROUPS = YES -# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in # the related pages index. If set to NO, only the current project's pages will # be listed. # The default value is: YES. @@ -2036,7 +2195,7 @@ PERL_PATH = /usr/bin/perl # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram # (in HTML and LaTeX) for classes with base or super classes. Setting the tag to # NO turns the diagrams off. Note that this option also works with HAVE_DOT # disabled, but it is recommended to install and use dot, since it yields more @@ -2061,7 +2220,7 @@ MSCGEN_PATH = DIA_PATH = -# If set to YES, the inheritance and collaboration graphs will hide inheritance +# If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2072,7 +2231,7 @@ HIDE_UNDOC_RELATIONS = YES # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = NO @@ -2086,7 +2245,7 @@ HAVE_DOT = NO DOT_NUM_THREADS = 0 -# When you want a differently looking font n the dot files that doxygen +# When you want a differently looking font in the dot files that doxygen # generates you can specify the font name using DOT_FONTNAME. You need to make # sure dot is able to find the font, which can be done by putting it in a # standard location or by setting the DOTFONTPATH environment variable or by @@ -2134,7 +2293,7 @@ COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. # The default value is: NO. @@ -2186,7 +2345,8 @@ INCLUDED_BY_GRAPH = YES # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2197,7 +2357,8 @@ CALL_GRAPH = NO # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2208,7 +2369,7 @@ CALLER_GRAPH = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GRAPHICAL_HIERARCHY = NO +GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The @@ -2220,11 +2381,17 @@ GRAPHICAL_HIERARCHY = NO DIRECTORY_GRAPH = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif and svg. +# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, +# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, +# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2267,6 +2434,24 @@ MSCFILE_DIRS = DIAFILE_DIRS = +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file. If left blank, it is assumed +# PlantUML is not used or called during a preprocessing step. Doxygen will +# generate a warning when it encounters a \startuml command in this case and +# will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, doxygen will truncate the graph, which is visualized @@ -2303,7 +2488,7 @@ MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support # this, this feature is disabled by default. @@ -2320,7 +2505,7 @@ DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot # files that are used to generate the various graphs. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. diff --git a/src/site/doxy/DoxygenLayout.xml b/src/site/doxy/DoxygenLayout.xml new file mode 100644 index 000000000..b51cbac91 --- /dev/null +++ b/src/site/doxy/DoxygenLayout.xml @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/doxy/customdoxygen.css b/src/site/doxy/customdoxygen.css new file mode 100644 index 000000000..2109924e5 --- /dev/null +++ b/src/site/doxy/customdoxygen.css @@ -0,0 +1,22 @@ +.navpath li.center +{ + list-style-type:none; + float:none; + padding-left:10px; + padding-right:10px; + background-image:none; + background-repeat:no-repeat; + background-position:right; + color:#364D7C; + font-size: 8pt; + line-height: 100%; + text-align: center; +} + +code +{ + border-radius: 3px; + padding: 3px 4px; + background-color: #f7f7f9; + border: 1px solid #e1e1e8; +} diff --git a/src/site/doxy/footer.html b/src/site/doxy/footer.html new file mode 100644 index 000000000..2639b9aa5 --- /dev/null +++ b/src/site/doxy/footer.html @@ -0,0 +1,25 @@ + + + + + + +
+$generatedby   +doxygen + $doxygenversion +
+ + + diff --git a/src/site/images/add.gif b/src/site/images/add.gif new file mode 100644 index 000000000..ac0bdccc8 Binary files /dev/null and b/src/site/images/add.gif differ diff --git a/src/site/images/fix.gif b/src/site/images/fix.gif new file mode 100644 index 000000000..2585f1308 Binary files /dev/null and b/src/site/images/fix.gif differ diff --git a/src/site/images/update.gif b/src/site/images/update.gif new file mode 100644 index 000000000..71ca225b6 Binary files /dev/null and b/src/site/images/update.gif differ diff --git a/src/site/markdown/0-community.md b/src/site/markdown/0-community.md new file mode 100644 index 000000000..0b819f14d --- /dev/null +++ b/src/site/markdown/0-community.md @@ -0,0 +1,27 @@ +Community {#community} +=== + + + +See the following pages for community information: + +* @subpage issue-tracking +* @subpage mailing-lists diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md new file mode 100644 index 000000000..97ccaef26 --- /dev/null +++ b/src/site/markdown/1-usage.md @@ -0,0 +1,29 @@ +Usage {#usage-overview} +=== + + + +See the following pages for usage information: + +* @subpage usage +* @subpage extending-log4cxx +* @subpage faq +* @subpage configuration-samples diff --git a/src/site/markdown/2-get.md b/src/site/markdown/2-get.md new file mode 100644 index 000000000..baac33b88 --- /dev/null +++ b/src/site/markdown/2-get.md @@ -0,0 +1,26 @@ +Get {#get} +=== + + + +* @subpage download +* @subpage changelog +* @subpage license diff --git a/src/site/markdown/3-development.md b/src/site/markdown/3-development.md new file mode 100644 index 000000000..c0e6c072c --- /dev/null +++ b/src/site/markdown/3-development.md @@ -0,0 +1,30 @@ +Development {#development-overview} +=== + + + +See the following pages for development information: + +* @subpage source-repository +* @subpage dependencies +* @subpage building +* @subpage build-cmake +* @subpage build-vcpkg diff --git a/src/site/markdown/change-report-gh.md b/src/site/markdown/change-report-gh.md new file mode 100644 index 000000000..32c258bce --- /dev/null +++ b/src/site/markdown/change-report-gh.md @@ -0,0 +1,511 @@ +Changelog {#changelog} +=== + + + +## Changes + +### Release History + +| | | | +| -------------------------------------------------------------------------------------- | ---------- | -------------------- | +| Version | Date | Description | +| [0.11.0](#0.11.0) | 2020-08-09 | Maintenance release. | +| [0.10.0](#0.10.0) | 2008-04-03 | First Apache release | +| [0.9.7](#0.9.7) | 2004-05-10 | | +| [0.9.6](#0.9.6) | 2004-04-11 | | +| [0.9.5](#0.9.5) | 2004-02-04 | | +| [0.9.4](#0.9.4) | 2003-10-25 | | +| [0.9.3](#0.9.3) | 2003-09-19 | | +| [0.9.2](#0.9.2) | 2003-08-10 | | +| [0.9.1](#0.9.1) | 2003-08-06 | | +| [0.9.0](#0.9.0) | 2003-08-06 | | +| [0.1.1](#0.1.1) | 2003-07-09 | | +| [0.1.0](#0.1.0) | 2003-07-08 | | +| [0.0.1](#0.0.1) | 2003-05-31 | | + + +### Release 0.11.0 - 2020-08-09 + +| | | | +| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | cmake and autotools generate different versioned binaries Fixes [LOGCXX-512](https://issues.apache.org/jira/browse/LOGCXX-512). | | +| ![](images/fix.gif "fix") | CachedDateFormat reuses timestamps without updating milliseconds after formatting timestamp with ms == 654 Fixes [LOGCXX-506](https://issues.apache.org/jira/browse/LOGCXX-506). | | +| ![](images/update.gif "update") | Checksums/Signatures don't match for log4cxx binaries Fixes [LOGCXX-503](https://issues.apache.org/jira/browse/LOGCXX-503). | | +| ![](images/update.gif "update") | appenderattachable.h function doc formatted "incorrectly" Fixes [LOGCXX-502](https://issues.apache.org/jira/browse/LOGCXX-502). | | +| ![](images/update.gif "update") | Logging in Timing-Critical Applications Fixes [LOGCXX-500](https://issues.apache.org/jira/browse/LOGCXX-500). | | +| ![](images/fix.gif "fix") | Provide a windows build environment for the project by replacing the ant build with a CMake build Fixes [LOGCXX-494](https://issues.apache.org/jira/browse/LOGCXX-494). | | +| ![](images/fix.gif "fix") | Wrong usage of milli- vs. micro- and non- vs. milliseconds in some docs. Fixes [LOGCXX-493](https://issues.apache.org/jira/browse/LOGCXX-493). | | +| ![](images/fix.gif "fix") | conditional expression is constant Fixes [LOGCXX-490](https://issues.apache.org/jira/browse/LOGCXX-490). | | +| ![](images/fix.gif "fix") | Space after log level hides messages Fixes [LOGCXX-488](https://issues.apache.org/jira/browse/LOGCXX-488). | | +| ![](images/fix.gif "fix") | Spelling error s/excute/execute Fixes [LOGCXX-484](https://issues.apache.org/jira/browse/LOGCXX-484). | | +| ![](images/update.gif "update") | Not able to see hebrew values when logging in log4cxx Fixes [LOGCXX-483](https://issues.apache.org/jira/browse/LOGCXX-483). | | +| ![](images/fix.gif "fix") | Build failure with GCC-6 Fixes [LOGCXX-482](https://issues.apache.org/jira/browse/LOGCXX-482). | | +| ![](images/fix.gif "fix") | TimeBasedRollingPolicy should append as configured on rollover Fixes [LOGCXX-464](https://issues.apache.org/jira/browse/LOGCXX-464). | | +| ![](images/fix.gif "fix") | LogLog::setQuietMode(true) does not suppress exception reporting Fixes [LOGCXX-455](https://issues.apache.org/jira/browse/LOGCXX-455). | | +| ![](images/fix.gif "fix") | make install fails, trying to overwrite header files Fixes [LOGCXX-446](https://issues.apache.org/jira/browse/LOGCXX-446). | | +| ![](images/fix.gif "fix") | Return by const reference in Logger::getName() Fixes [LOGCXX-443](https://issues.apache.org/jira/browse/LOGCXX-443). | | +| ![](images/fix.gif "fix") | Autoconf 2.69 needs 'ACLOCAL\_AMFLAGS= -I .' Fixes [LOGCXX-433](https://issues.apache.org/jira/browse/LOGCXX-433). | | +| ![](images/fix.gif "fix") | Wildcards in Makefile.am break either VPATH or non-VPATH installs Fixes [LOGCXX-428](https://issues.apache.org/jira/browse/LOGCXX-428). | | +| ![](images/fix.gif "fix") | exceptions in CachedDateFormatTestCase after LOGCXX-420 Fixes [LOGCXX-425](https://issues.apache.org/jira/browse/LOGCXX-425). | | +| ![](images/fix.gif "fix") | liblog4cxx.pc.in should reflect dependency on apr-1, apr-1-util Fixes [LOGCXX-424](https://issues.apache.org/jira/browse/LOGCXX-424). | | +| ![](images/fix.gif "fix") | Repair autogen script warnings Fixes [LOGCXX-423](https://issues.apache.org/jira/browse/LOGCXX-423). | | +| ![](images/fix.gif "fix") | Regression of LOGCXX-420 Fixes [LOGCXX-422](https://issues.apache.org/jira/browse/LOGCXX-422). | | +| ![](images/fix.gif "fix") | Possible out\_of\_range exception for millisecond formats in CachedDateFormat Fixes [LOGCXX-420](https://issues.apache.org/jira/browse/LOGCXX-420). | | +| ![](images/fix.gif "fix") | atoi undefined on Mac OS 10.9 compiling stringhelper.cpp Fixes [LOGCXX-417](https://issues.apache.org/jira/browse/LOGCXX-417). | | +| ![](images/fix.gif "fix") | Configure and watch could crash on app exit with static linking Fixes [LOGCXX-416](https://issues.apache.org/jira/browse/LOGCXX-416). | | +| ![](images/fix.gif "fix") | Empty XML configuration file causes crash Fixes [LOGCXX-415](https://issues.apache.org/jira/browse/LOGCXX-415). | | +| ![](images/fix.gif "fix") | possibly wrong use of autotools docdir (due to Alex Zbarcea) Fixes [LOGCXX-414](https://issues.apache.org/jira/browse/LOGCXX-414). | | +| ![](images/fix.gif "fix") | log4cxx doesn't compile on openembedded (due to Alex Zbarcea) Fixes [LOGCXX-413](https://issues.apache.org/jira/browse/LOGCXX-413). | | +| ![](images/fix.gif "fix") | Log4cxx doesn't roll normally when working under multiple processes environment Fixes [LOGCXX-412](https://issues.apache.org/jira/browse/LOGCXX-412). | | +| ![](images/fix.gif "fix") | Crash when logging on multiple threads. Fixes [LOGCXX-411](https://issues.apache.org/jira/browse/LOGCXX-411). | | +| ![](images/fix.gif "fix") | C++11 does not allow char literals with highest bit set unless cast Fixes [LOGCXX-400](https://issues.apache.org/jira/browse/LOGCXX-400). | | +| ![](images/fix.gif "fix") | Non-ascii character output wrong. Fixes [LOGCXX-399](https://issues.apache.org/jira/browse/LOGCXX-399). | | +| ![](images/fix.gif "fix") | Infinite loop in Transcoder::encode(const LogString& src, std::wstring& dst) Fixes [LOGCXX-398](https://issues.apache.org/jira/browse/LOGCXX-398). | | +| ![](images/fix.gif "fix") | Levels are not thread safe Fixes [LOGCXX-394](https://issues.apache.org/jira/browse/LOGCXX-394). | | +| ![](images/fix.gif "fix") | Hierarchy::updateParents loops forever on illegal logger-name like '.logger1' Fixes [LOGCXX-388](https://issues.apache.org/jira/browse/LOGCXX-388). | | +| ![](images/fix.gif "fix") | Mingw build type conversion error Fixes [LOGCXX-382](https://issues.apache.org/jira/browse/LOGCXX-382). | | +| ![](images/fix.gif "fix") | Pkgconfig can't find dependencies properly if log4cxx built statically Fixes [LOGCXX-381](https://issues.apache.org/jira/browse/LOGCXX-381). | | +| ![](images/fix.gif "fix") | Load Properties File Fails When There Are multibyte Characters in the Path Fixes [LOGCXX-369](https://issues.apache.org/jira/browse/LOGCXX-369). | | +| ![](images/fix.gif "fix") | method and class name functions not properly implemented Fixes [LOGCXX-368](https://issues.apache.org/jira/browse/LOGCXX-368). | | +| ![](images/fix.gif "fix") | Build fails on Linux with g++ 4.4 Fixes [LOGCXX-367](https://issues.apache.org/jira/browse/LOGCXX-367). | | +| ![](images/fix.gif "fix") | Errors when compile log4cxx 0.10.0 under Win7 x64 with Visual Studio 2010 (due to Christian Boos and Feng Nan) Fixes [LOGCXX-366](https://issues.apache.org/jira/browse/LOGCXX-366). | | +| ![](images/fix.gif "fix") | Unit tests fail on system dates later than 2009-12-31. Fixes [LOGCXX-365](https://issues.apache.org/jira/browse/LOGCXX-365). | | +| ![](images/fix.gif "fix") | SMTPAppender generating Emails with an empty body Fixes [LOGCXX-358](https://issues.apache.org/jira/browse/LOGCXX-358). | | +| ![](images/fix.gif "fix") | apache-log4cxx-0.10.0\\src\\main\\include\\log4cxx\\spi\\configurator.h(57) : warning C4231: nonstandard extension used : 'extern' before template explicit instantiation Fixes [LOGCXX-356](https://issues.apache.org/jira/browse/LOGCXX-356). | | +| ![](images/fix.gif "fix") | When a client disconnects the SocketHubAppender crashes on the next log message Fixes [LOGCXX-353](https://issues.apache.org/jira/browse/LOGCXX-353). | | +| ![](images/fix.gif "fix") | Download page does not have link to KEYS file Fixes [LOGCXX-351](https://issues.apache.org/jira/browse/LOGCXX-351). | | +| ![](images/fix.gif "fix") | Transcoder::encodeCharsetName bungles encoding Fixes [LOGCXX-340](https://issues.apache.org/jira/browse/LOGCXX-340). | | +| ![](images/update.gif "update") | Child thread does not inherit a copy of the mapped diagnostic context of its parent Fixes [LOGCXX-339](https://issues.apache.org/jira/browse/LOGCXX-339). | | +| ![](images/fix.gif "fix") | Suggested fix for socketappender not reconnecting multiple times Fixes [LOGCXX-337](https://issues.apache.org/jira/browse/LOGCXX-337). | | +| ![](images/fix.gif "fix") | Test compilation fails: Overloading ambiguity Fixes [LOGCXX-336](https://issues.apache.org/jira/browse/LOGCXX-336). | | +| ![](images/fix.gif "fix") | DailyRollingFileAppender should roll if program doesn't run at rolling time Fixes [LOGCXX-331](https://issues.apache.org/jira/browse/LOGCXX-331). | | +| ![](images/fix.gif "fix") | TLS memory of APR is not freed in destructor of APRInitializer Fixes [LOGCXX-320](https://issues.apache.org/jira/browse/LOGCXX-320). | | +| ![](images/fix.gif "fix") | Please make sure that the LOG4CXX\_\* macro's can be used as ordinary statements. Fixes [LOGCXX-319](https://issues.apache.org/jira/browse/LOGCXX-319). | | +| ![](images/fix.gif "fix") | Log4cxx triggers locking inversion which can result in a deadlock. Fixes [LOGCXX-317](https://issues.apache.org/jira/browse/LOGCXX-317). | | +| ![](images/fix.gif "fix") | Build process fails in case of absence of iconv support in apr-util Fixes [LOGCXX-313](https://issues.apache.org/jira/browse/LOGCXX-313). | | +| ![](images/fix.gif "fix") | Property/DOMConfigurator::configureAndWatch can continue to run after APR termination Fixes [LOGCXX-305](https://issues.apache.org/jira/browse/LOGCXX-305). | | +| ![](images/fix.gif "fix") | BasicConfigurator::configure results in writer not set warning. Fixes [LOGCXX-304](https://issues.apache.org/jira/browse/LOGCXX-304). | | +| ![](images/fix.gif "fix") | DOMConfigurator does not set ErrorHandler. Fixes [LOGCXX-303](https://issues.apache.org/jira/browse/LOGCXX-303). | | +| ![](images/fix.gif "fix") | ODBCAppender connection settings broken (or just have changed). Fixes [LOGCXX-300](https://issues.apache.org/jira/browse/LOGCXX-300). | | +| ![](images/fix.gif "fix") | odbcappender.cpp does not compile with unixODBC on linux. Fixes [LOGCXX-299](https://issues.apache.org/jira/browse/LOGCXX-299). | | +| ![](images/fix.gif "fix") | SMTPAppender does not build properly with autotools. Fixes [LOGCXX-298](https://issues.apache.org/jira/browse/LOGCXX-298). | | +| ![](images/fix.gif "fix") | Escape sequences not recognized in property files. Fixes [LOGCXX-293](https://issues.apache.org/jira/browse/LOGCXX-293). | | +| ![](images/fix.gif "fix") | Value continuation does not properly handle CRLF in property files. Fixes [LOGCXX-292](https://issues.apache.org/jira/browse/LOGCXX-292). | | +| ![](images/fix.gif "fix") | Tab characters are not recognized in property files. Fixes [LOGCXX-291](https://issues.apache.org/jira/browse/LOGCXX-291). | | +| ![](images/fix.gif "fix") | Unnecessary trailing semi-colons after LOG4CXX\_INFO et al in docs, examples and tests. Fixes [LOGCXX-288](https://issues.apache.org/jira/browse/LOGCXX-288). | | +| ![](images/fix.gif "fix") | gcc 4.3 requires \#include \ when using memcpy and related. Fixes [LOGCXX-286](https://issues.apache.org/jira/browse/LOGCXX-286). | | +| ![](images/fix.gif "fix") | LevelRangeFilter has default value for acceptOnMatch that is different from log4j Fixes [LOGCXX-285](https://issues.apache.org/jira/browse/LOGCXX-285). | | +| ![](images/fix.gif "fix") | Unit tests fail to compile with xlc\_r on AIX Fixes [LOGCXX-284](https://issues.apache.org/jira/browse/LOGCXX-284). | | +| ![](images/fix.gif "fix") | Suspicious, but harmless, reuse of LOCAL1 in SyslogAppender Fixes [LOGCXX-283](https://issues.apache.org/jira/browse/LOGCXX-283). | | +| ![](images/fix.gif "fix") | Thread::sleep not affected by Thread::interrupt. Fixes [LOGCXX-282](https://issues.apache.org/jira/browse/LOGCXX-282). | | +| ![](images/fix.gif "fix") | Sun Studio 11 reports function hides base virtual function warning Fixes [LOGCXX-281](https://issues.apache.org/jira/browse/LOGCXX-281). | | +| ![](images/fix.gif "fix") | tests and sample code unnecessarily compiled during default make target Fixes [LOGCXX-280](https://issues.apache.org/jira/browse/LOGCXX-280). | | +| ![](images/fix.gif "fix") | Threads for reconnecting sockets do not end cleanly when program exits Fixes [LOGCXX-278](https://issues.apache.org/jira/browse/LOGCXX-278). | | +| ![](images/fix.gif "fix") | Reconnection not working for sockets Fixes [LOGCXX-277](https://issues.apache.org/jira/browse/LOGCXX-277). | | +| ![](images/fix.gif "fix") | AndFilter and others defined but not implemented Fixes [LOGCXX-276](https://issues.apache.org/jira/browse/LOGCXX-276). | | +| ![](images/fix.gif "fix") | Headers cannot be included with very strict warning settings Fixes [LOGCXX-275](https://issues.apache.org/jira/browse/LOGCXX-275). | | +| ![](images/fix.gif "fix") | Prevent filenamepatterntestcase from failing in some timezones Fixes [LOGCXX-273](https://issues.apache.org/jira/browse/LOGCXX-273). | | +| ![](images/update.gif "update") | Apache log4cxx 0.11.0 release Fixes [LOGCXX-272](https://issues.apache.org/jira/browse/LOGCXX-272). | | +| ![](images/fix.gif "fix") | MDC::put will not overwrite existing key value pair Fixes [LOGCXX-271](https://issues.apache.org/jira/browse/LOGCXX-271). | | +| ![](images/fix.gif "fix") | Add ability to compile out logging by logging level. Fixes [LOGCXX-270](https://issues.apache.org/jira/browse/LOGCXX-270). | | +| ![](images/fix.gif "fix") | Local variables hide member variables Fixes [LOGCXX-267](https://issues.apache.org/jira/browse/LOGCXX-267). | | +| ![](images/fix.gif "fix") | Eliminate Extra ";" ignored warnings Fixes [LOGCXX-266](https://issues.apache.org/jira/browse/LOGCXX-266). | | +| ![](images/fix.gif "fix") | Eliminate anachronism warnings Fixes [LOGCXX-265](https://issues.apache.org/jira/browse/LOGCXX-265). | | +| ![](images/fix.gif "fix") | Bad link to log4cxx-dev archive Fixes [LOGCXX-263](https://issues.apache.org/jira/browse/LOGCXX-263). | | +| ![](images/fix.gif "fix") | socketappendertestcase and xmlsocketappendertestcase not run Fixes [LOGCXX-262](https://issues.apache.org/jira/browse/LOGCXX-262). | | +| ![](images/fix.gif "fix") | Console appender crashes if layout is not set Fixes [LOGCXX-249](https://issues.apache.org/jira/browse/LOGCXX-249). | | +| ![](images/add.gif "add") | Set SONAME in cmake like autotools based buildsystem would do. Fixes [32](https://github.com/apache/logging-log4cxx/pull/32). | | +| ![](images/add.gif "add") | Implementation of map-based filter. Fixes [24](https://github.com/apache/logging-log4cxx/pull/24). | | +| ![](images/add.gif "add") | Added support for building log4cxx as a statically linked library on Windows. Fixes [21](https://github.com/apache/logging-log4cxx/pull/21). | | +| ![](images/add.gif "add") | Replaced ant build with cmake. Fixes [14](https://github.com/apache/logging-log4cxx/pull/14). | | +| ![](images/add.gif "add") | JSONLayout Fixes [13](https://github.com/apache/logging-log4cxx/pull/13). | | +| ![](images/update.gif "update") | Behavior of StringHelper::startsWith and endsWith synced. | | +| ![](images/update.gif "update") | Documented C (class) and M (method) log format keywords. | | +| ![](images/add.gif "add") | LocationInfo for Borland C++ Builder and successors improved. | | + + +### Release 0.10.0 - 2008-04-03 + +| | | | +| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | Several appenders fail to compile in Visual Studio 2008 Fixes [LOGCXX-259](https://issues.apache.org/jira/browse/LOGCXX-259). | | +| ![](images/fix.gif "fix") | unable to build from make dist package due to missing doxygen file Fixes [LOGCXX-258](https://issues.apache.org/jira/browse/LOGCXX-258). | | +| ![](images/fix.gif "fix") | ServerSocket::accept hangs on Unix Fixes [LOGCXX-257](https://issues.apache.org/jira/browse/LOGCXX-257). | | +| ![](images/fix.gif "fix") | SocketHubAppender fails after accepting connection Fixes [LOGCXX-256](https://issues.apache.org/jira/browse/LOGCXX-256). | | +| ![](images/add.gif "add") | Add build option for static C RTL Fixes [LOGCXX-254](https://issues.apache.org/jira/browse/LOGCXX-254). | | +| ![](images/fix.gif "fix") | Transcoder compilation error with utf-8 charset Fixes [LOGCXX-253](https://issues.apache.org/jira/browse/LOGCXX-253). | | +| ![](images/add.gif "add") | Add documentation for use of operator\<\< in logging requests Fixes [LOGCXX-252](https://issues.apache.org/jira/browse/LOGCXX-252). | | +| ![](images/fix.gif "fix") | NDC::cloneStack and NDC::inherit missing in 0.10.0 RC2 Fixes [LOGCXX-251](https://issues.apache.org/jira/browse/LOGCXX-251). | | +| ![](images/fix.gif "fix") | ODBCAppender has unicode issues Fixes [LOGCXX-248](https://issues.apache.org/jira/browse/LOGCXX-248). | | +| ![](images/fix.gif "fix") | MSVC project has wrong additional include directories Fixes [LOGCXX-247](https://issues.apache.org/jira/browse/LOGCXX-247). | | +| ![](images/fix.gif "fix") | Config refresh hangs a client application that uses TelnetAppender Fixes [LOGCXX-246](https://issues.apache.org/jira/browse/LOGCXX-246). | | +| ![](images/fix.gif "fix") | Problem Compile in Doxy Fixes [LOGCXX-243](https://issues.apache.org/jira/browse/LOGCXX-243). | | +| ![](images/update.gif "update") | Eliminate log4cxx proxies for APR types Fixes [LOGCXX-242](https://issues.apache.org/jira/browse/LOGCXX-242). | | +| ![](images/fix.gif "fix") | Non-ascii named files have names mangled Fixes [LOGCXX-241](https://issues.apache.org/jira/browse/LOGCXX-241). | | +| ![](images/update.gif "update") | Inconsistent const qualification on logging methods. Fixes [LOGCXX-239](https://issues.apache.org/jira/browse/LOGCXX-239). | | +| ![](images/fix.gif "fix") | Include missing headers Fixes [LOGCXX-237](https://issues.apache.org/jira/browse/LOGCXX-237). | | +| ![](images/fix.gif "fix") | Re-order constructor initialiser lists to match declaration order Fixes [LOGCXX-236](https://issues.apache.org/jira/browse/LOGCXX-236). | | +| ![](images/add.gif "add") | Add ObjectPtrT::exchange Fixes [LOGCXX-235](https://issues.apache.org/jira/browse/LOGCXX-235). | | +| ![](images/fix.gif "fix") | Assignment operator removes const qualifier Fixes [LOGCXX-234](https://issues.apache.org/jira/browse/LOGCXX-234). | | +| ![](images/update.gif "update") | Unnecessary casts in ObjectPtrT Fixes [LOGCXX-233](https://issues.apache.org/jira/browse/LOGCXX-233). | | +| ![](images/update.gif "update") | Drop src/performance Fixes [LOGCXX-232](https://issues.apache.org/jira/browse/LOGCXX-232). | | +| ![](images/fix.gif "fix") | Deadlock in AsyncAppender Fixes [LOGCXX-231](https://issues.apache.org/jira/browse/LOGCXX-231). | | +| ![](images/update.gif "update") | Align ant build options with automake Fixes [LOGCXX-230](https://issues.apache.org/jira/browse/LOGCXX-230). | | +| ![](images/update.gif "update") | Remove @author tags Fixes [LOGCXX-228](https://issues.apache.org/jira/browse/LOGCXX-228). | | +| ![](images/update.gif "update") | Remove @since tags Fixes [LOGCXX-227](https://issues.apache.org/jira/browse/LOGCXX-227). | | +| ![](images/update.gif "update") | Default configurator uses \*.properties in preference to \*.xml Fixes [LOGCXX-226](https://issues.apache.org/jira/browse/LOGCXX-226). | | +| ![](images/update.gif "update") | Migrate unit tests from LGPL'd CPPUNIT to an ASL'd testing framework Fixes [LOGCXX-225](https://issues.apache.org/jira/browse/LOGCXX-225). | | +| ![](images/fix.gif "fix") | trunk compile error. Fixes [LOGCXX-222](https://issues.apache.org/jira/browse/LOGCXX-222). | | +| ![](images/fix.gif "fix") | ThreadID layout does not match debugger Fixes [LOGCXX-221](https://issues.apache.org/jira/browse/LOGCXX-221). | | +| ![](images/fix.gif "fix") | Memory leaks when using MFC Fixes [LOGCXX-220](https://issues.apache.org/jira/browse/LOGCXX-220). | | +| ![](images/fix.gif "fix") | suspicious warnings Fixes [LOGCXX-219](https://issues.apache.org/jira/browse/LOGCXX-219). | | +| ![](images/add.gif "add") | Visual Studio 8 build Fixes [LOGCXX-218](https://issues.apache.org/jira/browse/LOGCXX-218). | | +| ![](images/fix.gif "fix") | Not initialized LoggerPtr segfault program. Fixes [LOGCXX-217](https://issues.apache.org/jira/browse/LOGCXX-217). | | +| ![](images/fix.gif "fix") | crash on program exit Fixes [LOGCXX-216](https://issues.apache.org/jira/browse/LOGCXX-216). | | +| ![](images/update.gif "update") | Eliminate sqlext.h from odbcappender.h Fixes [LOGCXX-215](https://issues.apache.org/jira/browse/LOGCXX-215). | | +| ![](images/fix.gif "fix") | Possible memory leak due to fault in build process (via make) Fixes [LOGCXX-214](https://issues.apache.org/jira/browse/LOGCXX-214). | | +| ![](images/fix.gif "fix") | trace method implementation is missing Fixes [LOGCXX-213](https://issues.apache.org/jira/browse/LOGCXX-213). | | +| ![](images/fix.gif "fix") | unittest failed Fixes [LOGCXX-212](https://issues.apache.org/jira/browse/LOGCXX-212). | | +| ![](images/fix.gif "fix") | Crash(Segmentation Fault) in DailyRollingFileAppender when file change Fixes [LOGCXX-211](https://issues.apache.org/jira/browse/LOGCXX-211). | | +| ![](images/fix.gif "fix") | HTMLLayout NDC null check Fixes [LOGCXX-210](https://issues.apache.org/jira/browse/LOGCXX-210). | | +| ![](images/fix.gif "fix") | A message of type wchar\_t\* is not beeing written correctly to the internal message buffer (Revision: 592627) Fixes [LOGCXX-209](https://issues.apache.org/jira/browse/LOGCXX-209). | | +| ![](images/fix.gif "fix") | isTraceEnabled implemenation missing in logger.cpp (Revision: 592627) Fixes [LOGCXX-208](https://issues.apache.org/jira/browse/LOGCXX-208). | | +| ![](images/fix.gif "fix") | PatternParserTestCase and FileNamePatternTestCase fail only with VC6 Fixes [LOGCXX-204](https://issues.apache.org/jira/browse/LOGCXX-204). | | +| ![](images/fix.gif "fix") | ObjectPtrT has inconsistent const-ness on accessors Fixes [LOGCXX-202](https://issues.apache.org/jira/browse/LOGCXX-202). | | +| ![](images/add.gif "add") | Visual Studio 6 build Fixes [LOGCXX-201](https://issues.apache.org/jira/browse/LOGCXX-201). | | +| ![](images/add.gif "add") | Implement compression for RollingFileAppender Fixes [LOGCXX-200](https://issues.apache.org/jira/browse/LOGCXX-200). | | +| ![](images/fix.gif "fix") | ant can't generate vc6 project Fixes [LOGCXX-197](https://issues.apache.org/jira/browse/LOGCXX-197). | | +| ![](images/fix.gif "fix") | Syslog appender destructor can cause core Fixes [LOGCXX-196](https://issues.apache.org/jira/browse/LOGCXX-196). | | +| ![](images/fix.gif "fix") | Syslog appender adds characters to output. Fixes [LOGCXX-195](https://issues.apache.org/jira/browse/LOGCXX-195). | | +| ![](images/fix.gif "fix") | Garbage in log files when appenders are defined in multiple levels of the logger hierarchy Fixes [LOGCXX-194](https://issues.apache.org/jira/browse/LOGCXX-194). | | +| ![](images/update.gif "update") | Please rename or remove new local variable "buf" in Logger.h macros Fixes [LOGCXX-193](https://issues.apache.org/jira/browse/LOGCXX-193). | | +| ![](images/update.gif "update") | Suggested improvements to log4cxx webpages Fixes [LOGCXX-192](https://issues.apache.org/jira/browse/LOGCXX-192). | | +| ![](images/fix.gif "fix") | Application cores when syslog appender is given an unreachable host/ip. Fixes [LOGCXX-191](https://issues.apache.org/jira/browse/LOGCXX-191). | | +| ![](images/fix.gif "fix") | The 'logger.h' header includes itself. Fixes [LOGCXX-190](https://issues.apache.org/jira/browse/LOGCXX-190). | | +| ![](images/update.gif "update") | Migrate to Maven 2.0 for documentation and packaging Fixes [LOGCXX-189](https://issues.apache.org/jira/browse/LOGCXX-189). | | +| ![](images/update.gif "update") | Upgrade to apr 1.2.9 and apr-util 1.2.8 Fixes [LOGCXX-188](https://issues.apache.org/jira/browse/LOGCXX-188). | | +| ![](images/fix.gif "fix") | LogLog::emit() could potentially interleave messages Fixes [LOGCXX-187](https://issues.apache.org/jira/browse/LOGCXX-187). | | +| ![](images/fix.gif "fix") | Garbage characters in log files when log requests from multiple threads with hyperthreading enabled Fixes [LOGCXX-186](https://issues.apache.org/jira/browse/LOGCXX-186). | | +| ![](images/fix.gif "fix") | Crash when log level set to 'inherited' Fixes [LOGCXX-184](https://issues.apache.org/jira/browse/LOGCXX-184). | | +| ![](images/fix.gif "fix") | Compiler warning: dereferencing type-punned pointer will break strict-aliasing rules Fixes [LOGCXX-183](https://issues.apache.org/jira/browse/LOGCXX-183). | | +| ![](images/fix.gif "fix") | missing man page for simplesocketserver Fixes [LOGCXX-182](https://issues.apache.org/jira/browse/LOGCXX-182). | | +| ![](images/fix.gif "fix") | Level::DEBUG and other non-local statics cause crash on app shutdown on AIX Fixes [LOGCXX-181](https://issues.apache.org/jira/browse/LOGCXX-181). | | +| ![](images/fix.gif "fix") | Build fails at domconfigurator.h Fixes [LOGCXX-180](https://issues.apache.org/jira/browse/LOGCXX-180). | | +| ![](images/add.gif "add") | example applications do SIGABRT on aix 5.2 Fixes [LOGCXX-179](https://issues.apache.org/jira/browse/LOGCXX-179). | | +| ![](images/fix.gif "fix") | Link failure if wchar\_t cannot be determined as UTF-16 or UTF-32 Fixes [LOGCXX-178](https://issues.apache.org/jira/browse/LOGCXX-178). | | +| ![](images/fix.gif "fix") | SocketImpl::accept uses private APR function: apr\_wait\_for\_io\_or\_timeout Fixes [LOGCXX-177](https://issues.apache.org/jira/browse/LOGCXX-177). | | +| ![](images/fix.gif "fix") | APRCharsetEncoder is not thread safe Fixes [LOGCXX-175](https://issues.apache.org/jira/browse/LOGCXX-175). | | +| ![](images/fix.gif "fix") | configure fail with ".infig.status: error: cannot find input file:" Fixes [LOGCXX-172](https://issues.apache.org/jira/browse/LOGCXX-172). | | +| ![](images/add.gif "add") | Add project description file for projects.apache.org Fixes [LOGCXX-171](https://issues.apache.org/jira/browse/LOGCXX-171). | | +| ![](images/fix.gif "fix") | XMLLayoutTestCase fails on compilers that do not provide location info Fixes [LOGCXX-169](https://issues.apache.org/jira/browse/LOGCXX-169). | | +| ![](images/fix.gif "fix") | log4j.dtd does not contain rollingPolicy and other o.a.l.r.RFA elements Fixes [LOGCXX-168](https://issues.apache.org/jira/browse/LOGCXX-168). | | +| ![](images/fix.gif "fix") | system locale charmap is not determined properly on Fedora Core 6 Fixes [LOGCXX-167](https://issues.apache.org/jira/browse/LOGCXX-167). | | +| ![](images/fix.gif "fix") | XMLSocketAppender may generate erroneous output due to mismatched encoding Fixes [LOGCXX-165](https://issues.apache.org/jira/browse/LOGCXX-165). | | +| ![](images/fix.gif "fix") | XMLSocketAppender is disabled Fixes [LOGCXX-164](https://issues.apache.org/jira/browse/LOGCXX-164). | | +| ![](images/fix.gif "fix") | liblog4cxx (svn 480882) does not link on Mac OS X 10.4 Fixes [LOGCXX-163](https://issues.apache.org/jira/browse/LOGCXX-163). | | +| ![](images/fix.gif "fix") | Problem printing string with embedded NULL character Fixes [LOGCXX-162](https://issues.apache.org/jira/browse/LOGCXX-162). | | +| ![](images/fix.gif "fix") | Using RollingFileAppender increases the working set with each rollover Fixes [LOGCXX-161](https://issues.apache.org/jira/browse/LOGCXX-161). | | +| ![](images/fix.gif "fix") | helpers/object.h: DECLARE\_LOG4CXX\_OBJECT macro definition is missing virtual destructor declaration Fixes [LOGCXX-160](https://issues.apache.org/jira/browse/LOGCXX-160). | | +| ![](images/fix.gif "fix") | Initialization of local static objects out of order on Linux Fixes [LOGCXX-159](https://issues.apache.org/jira/browse/LOGCXX-159). | | +| ![](images/fix.gif "fix") | tolower not defined in stringhelper.cpp Fixes [LOGCXX-158](https://issues.apache.org/jira/browse/LOGCXX-158). | | +| ![](images/fix.gif "fix") | make install fails since @manual\_dest@ replacement is missing in Makefiles Fixes [LOGCXX-157](https://issues.apache.org/jira/browse/LOGCXX-157). | | +| ![](images/update.gif "update") | immediate flush in console appender Fixes [LOGCXX-156](https://issues.apache.org/jira/browse/LOGCXX-156). | | +| ![](images/update.gif "update") | Update source headers per new ASF header policy Fixes [LOGCXX-155](https://issues.apache.org/jira/browse/LOGCXX-155). | | +| ![](images/add.gif "add") | Automate log4cxx site and doxygen generation and deployment Fixes [LOGCXX-153](https://issues.apache.org/jira/browse/LOGCXX-153). | | +| ![](images/fix.gif "fix") | gcc warning about cast from \`const void\*' to \`log4cxx::helpers::Object\*' discards qualifiers from pointer target typ Fixes [LOGCXX-152](https://issues.apache.org/jira/browse/LOGCXX-152). | | +| ![](images/fix.gif "fix") | Umlauts as literal in patternlayout won't be logged correct Fixes [LOGCXX-151](https://issues.apache.org/jira/browse/LOGCXX-151). | | +| ![](images/fix.gif "fix") | logstream's operator\<\< declared in the wrong namespace Fixes [LOGCXX-150](https://issues.apache.org/jira/browse/LOGCXX-150). | | +| ![](images/fix.gif "fix") | make dist does not work Fixes [LOGCXX-149](https://issues.apache.org/jira/browse/LOGCXX-149). | | +| ![](images/fix.gif "fix") | DailyRollingFileAppender::~DailyRollingFileAppender must call finalize Fixes [LOGCXX-146](https://issues.apache.org/jira/browse/LOGCXX-146). | | +| ![](images/fix.gif "fix") | \-xarch=v8plus should be removed from Makefile.in Fixes [LOGCXX-143](https://issues.apache.org/jira/browse/LOGCXX-143). | | +| ![](images/fix.gif "fix") | socketservertestcase.cpp does not compile with Sun Studio 11 on Solaris Fixes [LOGCXX-142](https://issues.apache.org/jira/browse/LOGCXX-142). | | +| ![](images/update.gif "update") | Upgrade to APR 1.2.7 or later Fixes [LOGCXX-141](https://issues.apache.org/jira/browse/LOGCXX-141). | | +| ![](images/fix.gif "fix") | Handle leak with LoggingEvent::getCurrentThreadName Fixes [LOGCXX-140](https://issues.apache.org/jira/browse/LOGCXX-140). | | +| ![](images/fix.gif "fix") | XMLLayoutTestCase uses inadequate filters for 64 bit platforms Fixes [LOGCXX-139](https://issues.apache.org/jira/browse/LOGCXX-139). | | +| ![](images/fix.gif "fix") | XMLLayoutTestCase output and filtered output gets overwritten Fixes [LOGCXX-138](https://issues.apache.org/jira/browse/LOGCXX-138). | | +| ![](images/fix.gif "fix") | DailyRollingFileAppender not using Property options Fixes [LOGCXX-136](https://issues.apache.org/jira/browse/LOGCXX-136). | | +| ![](images/update.gif "update") | Use std::string with logstream Fixes [LOGCXX-135](https://issues.apache.org/jira/browse/LOGCXX-135). | | +| ![](images/fix.gif "fix") | FileAppender could create missing directories Fixes [LOGCXX-134](https://issues.apache.org/jira/browse/LOGCXX-134). | | +| ![](images/fix.gif "fix") | Missing parenthesis in LOG4CXX\_ASSERT Fixes [LOGCXX-133](https://issues.apache.org/jira/browse/LOGCXX-133). | | +| ![](images/fix.gif "fix") | various segmentation faults in multithreaded application Fixes [LOGCXX-132](https://issues.apache.org/jira/browse/LOGCXX-132). | | +| ![](images/fix.gif "fix") | TimeBasedRollingPolicy is declared "abstract" Fixes [LOGCXX-131](https://issues.apache.org/jira/browse/LOGCXX-131). | | +| ![](images/fix.gif "fix") | Compile fails on gcc4.1 Fixes [LOGCXX-130](https://issues.apache.org/jira/browse/LOGCXX-130). | | +| ![](images/fix.gif "fix") | Asyncappender is full of race conditions (improper use of condition variables) Fixes [LOGCXX-129](https://issues.apache.org/jira/browse/LOGCXX-129). | | +| ![](images/fix.gif "fix") | Main build.xml not referencing "env" properly. Fixes [LOGCXX-127](https://issues.apache.org/jira/browse/LOGCXX-127). | | +| ![](images/fix.gif "fix") | std::cout stops working if log4cxx is first to output Fixes [LOGCXX-126](https://issues.apache.org/jira/browse/LOGCXX-126). | | +| ![](images/update.gif "update") | L7dTestCase is stubbed out Fixes [LOGCXX-125](https://issues.apache.org/jira/browse/LOGCXX-125). | | +| ![](images/fix.gif "fix") | wchar\_t constructor missing in class NDC Fixes [LOGCXX-124](https://issues.apache.org/jira/browse/LOGCXX-124). | | +| ![](images/fix.gif "fix") | UTF-8 build fails on Linux Fixes [LOGCXX-123](https://issues.apache.org/jira/browse/LOGCXX-123). | | +| ![](images/fix.gif "fix") | Wrong parameter description in Patternlayout Fixes [LOGCXX-120](https://issues.apache.org/jira/browse/LOGCXX-120). | | +| ![](images/fix.gif "fix") | ndctestcase not working Fixes [LOGCXX-119](https://issues.apache.org/jira/browse/LOGCXX-119). | | +| ![](images/fix.gif "fix") | Hierarchy corrupts with PropertyConfigurator Fixes [LOGCXX-118](https://issues.apache.org/jira/browse/LOGCXX-118). | | +| ![](images/fix.gif "fix") | Memory leak with ThreadSpecificData on Win32 Fixes [LOGCXX-117](https://issues.apache.org/jira/browse/LOGCXX-117). | | +| ![](images/fix.gif "fix") | SVN head does not compiler with MinGW compiler Fixes [LOGCXX-116](https://issues.apache.org/jira/browse/LOGCXX-116). | | +| ![](images/fix.gif "fix") | SVN head does not compile with Borland C++ compiler Fixes [LOGCXX-115](https://issues.apache.org/jira/browse/LOGCXX-115). | | +| ![](images/update.gif "update") | Upgrade APR to 1.2.2 from 1.1.0 Fixes [LOGCXX-114](https://issues.apache.org/jira/browse/LOGCXX-114). | | +| ![](images/update.gif "update") | separate apr detection m4 codes from aclocal.m4 Fixes [LOGCXX-113](https://issues.apache.org/jira/browse/LOGCXX-113). | | +| ![](images/update.gif "update") | change "static" to "auto" for Transcoder::decode() decoder and CharsetDecoder::getDefaultDecoder() decoder Fixes [LOGCXX-112](https://issues.apache.org/jira/browse/LOGCXX-112). | | +| ![](images/update.gif "update") | make Logger cache a LoggerRepositoryPtr instead of a "blind" pointer Fixes [LOGCXX-111](https://issues.apache.org/jira/browse/LOGCXX-111). | | +| ![](images/fix.gif "fix") | try fix 64bit log4cxx\_intptr\_t Fixes [LOGCXX-110](https://issues.apache.org/jira/browse/LOGCXX-110). | | +| ![](images/fix.gif "fix") | Can't compile log4cxx in ascii on Windows Fixes [LOGCXX-107](https://issues.apache.org/jira/browse/LOGCXX-107). | | +| ![](images/fix.gif "fix") | maxFileSize has bad type in SizeBasedTriggeringPolicy file Fixes [LOGCXX-106](https://issues.apache.org/jira/browse/LOGCXX-106). | | +| ![](images/fix.gif "fix") | Infinite loop in string replacing Fixes [LOGCXX-105](https://issues.apache.org/jira/browse/LOGCXX-105). | | +| ![](images/fix.gif "fix") | ODBCAppender::close does not check if appender is already closed Fixes [LOGCXX-104](https://issues.apache.org/jira/browse/LOGCXX-104). | | +| ![](images/update.gif "update") | Much of CVS HEAD seems \#if 0 out, especially ResourceBundle stuff Fixes [LOGCXX-103](https://issues.apache.org/jira/browse/LOGCXX-103). | | +| ![](images/fix.gif "fix") | Fixes for ODBCAppender Fixes [LOGCXX-100](https://issues.apache.org/jira/browse/LOGCXX-100). | | +| ![](images/fix.gif "fix") | Gump build fails for log4cxx-ant-no-wchar-t target Fixes [LOGCXX-98](https://issues.apache.org/jira/browse/LOGCXX-98). | | +| ![](images/update.gif "update") | simplesocketserver.cpp should use LOG4CXX\_STR("...") not L"..." Fixes [LOGCXX-94](https://issues.apache.org/jira/browse/LOGCXX-94). | | +| ![](images/update.gif "update") | Explore use of security-enhanced CRT methods Fixes [LOGCXX-88](https://issues.apache.org/jira/browse/LOGCXX-88). | | +| ![](images/update.gif "update") | Remove remaining uses of Category and Priority Fixes [LOGCXX-87](https://issues.apache.org/jira/browse/LOGCXX-87). | | +| ![](images/add.gif "add") | Add TRACE level Fixes [LOGCXX-86](https://issues.apache.org/jira/browse/LOGCXX-86). | | +| ![](images/update.gif "update") | Mac OS/X fixes and enhancements Fixes [LOGCXX-85](https://issues.apache.org/jira/browse/LOGCXX-85). | | +| ![](images/fix.gif "fix") | Problems with stream logging in UTF8, no WCHAR\_T build Fixes [LOGCXX-84](https://issues.apache.org/jira/browse/LOGCXX-84). | | +| ![](images/fix.gif "fix") | log4cxx::Level::ERROR fails to compile when GDI enabled Fixes [LOGCXX-83](https://issues.apache.org/jira/browse/LOGCXX-83). | | +| ![](images/fix.gif "fix") | Compiling with stream.h in multiple object files errors Fixes [LOGCXX-82](https://issues.apache.org/jira/browse/LOGCXX-82). | | +| ![](images/fix.gif "fix") | SimpleDateFormat does not compile on Solaris 2.95.2 gcc Fixes [LOGCXX-81](https://issues.apache.org/jira/browse/LOGCXX-81). | | +| ![](images/update.gif "update") | Migrated network appenders to APR network IO Fixes [LOGCXX-80](https://issues.apache.org/jira/browse/LOGCXX-80). | | +| ![](images/update.gif "update") | configure check for apr-util Fixes [LOGCXX-79](https://issues.apache.org/jira/browse/LOGCXX-79). | | +| ![](images/fix.gif "fix") | Static builds broken Fixes [LOGCXX-77](https://issues.apache.org/jira/browse/LOGCXX-77). | | +| ![](images/add.gif "add") | user.home, user.dir, java.io.tmpdir available within configuration files Fixes [LOGCXX-76](https://issues.apache.org/jira/browse/LOGCXX-76). | | +| ![](images/add.gif "add") | Cygwin build Fixes [LOGCXX-75](https://issues.apache.org/jira/browse/LOGCXX-75). | | +| ![](images/add.gif "add") | MinGW build Fixes [LOGCXX-74](https://issues.apache.org/jira/browse/LOGCXX-74). | | +| ![](images/fix.gif "fix") | Not loading configuration from log4cxx.properties or log4cxx.xml Fixes [LOGCXX-73](https://issues.apache.org/jira/browse/LOGCXX-73). | | +| ![](images/update.gif "update") | INSTALL out of date Fixes [LOGCXX-72](https://issues.apache.org/jira/browse/LOGCXX-72). | | +| ![](images/update.gif "update") | Update performance page on web site Fixes [LOGCXX-71](https://issues.apache.org/jira/browse/LOGCXX-71). | | +| ![](images/fix.gif "fix") | Logic flaws in StringHelper::startsWith and StringHelper::endsWith Fixes [LOGCXX-70](https://issues.apache.org/jira/browse/LOGCXX-70). | | +| ![](images/fix.gif "fix") | NTEventLogAppender always uses RPC method for logging and has inadequate error handling. Fixes [LOGCXX-67](https://issues.apache.org/jira/browse/LOGCXX-67). | | +| ![](images/fix.gif "fix") | SyslogAppender append method currently stubbed out Fixes [LOGCXX-66](https://issues.apache.org/jira/browse/LOGCXX-66). | | +| ![](images/update.gif "update") | Migrate to APR network IO Fixes [LOGCXX-64](https://issues.apache.org/jira/browse/LOGCXX-64). | | +| ![](images/update.gif "update") | Platform appropriate line-feed convention Fixes [LOGCXX-63](https://issues.apache.org/jira/browse/LOGCXX-63). | | +| ![](images/update.gif "update") | log4cxx 0.10.0 release Fixes [LOGCXX-62](https://issues.apache.org/jira/browse/LOGCXX-62). | | +| ![](images/fix.gif "fix") | XML layout can be mismatched with document encoding Fixes [LOGCXX-60](https://issues.apache.org/jira/browse/LOGCXX-60). | | +| ![](images/update.gif "update") | Implement encoding support for Writer appender Fixes [LOGCXX-59](https://issues.apache.org/jira/browse/LOGCXX-59). | | +| ![](images/fix.gif "fix") | ImmediateFlush'd FileAppenders extremely slow on Windows Fixes [LOGCXX-58](https://issues.apache.org/jira/browse/LOGCXX-58). | | +| ![](images/add.gif "add") | Port log4j performance test Fixes [LOGCXX-57](https://issues.apache.org/jira/browse/LOGCXX-57). | | +| ![](images/fix.gif "fix") | BasicConfiguration is unreliable Fixes [LOGCXX-56](https://issues.apache.org/jira/browse/LOGCXX-56). | | +| ![](images/add.gif "add") | DailyRolling File Appender Fixes [LOGCXX-55](https://issues.apache.org/jira/browse/LOGCXX-55). | | +| ![](images/fix.gif "fix") | Eliminate use of boost-regex in unit tests Fixes [LOGCXX-54](https://issues.apache.org/jira/browse/LOGCXX-54). | | +| ![](images/fix.gif "fix") | Problems compiling with MsDev 6.0 (space in paths) Fixes [LOGCXX-53](https://issues.apache.org/jira/browse/LOGCXX-53). | | +| ![](images/add.gif "add") | Migrate log4j 1.3 RollingFileAppender Fixes [LOGCXX-52](https://issues.apache.org/jira/browse/LOGCXX-52). | | +| ![](images/fix.gif "fix") | variable name clash in macro Fixes [LOGCXX-50](https://issues.apache.org/jira/browse/LOGCXX-50). | | +| ![](images/add.gif "add") | Move timezone specification into pattern, remove locale specification Fixes [LOGCXX-49](https://issues.apache.org/jira/browse/LOGCXX-49). | | +| ![](images/add.gif "add") | Use hex representation for thread identifier Fixes [LOGCXX-48](https://issues.apache.org/jira/browse/LOGCXX-48). | | +| ![](images/fix.gif "fix") | Check headers for missing declarations and Effective C++ violations Fixes [LOGCXX-47](https://issues.apache.org/jira/browse/LOGCXX-47). | | +| ![](images/fix.gif "fix") | Extra semicolon after namespace closing paren Fixes [LOGCXX-46](https://issues.apache.org/jira/browse/LOGCXX-46). | | +| ![](images/fix.gif "fix") | \_T causes error : 1048576 cannot be used as a function Fixes [LOGCXX-45](https://issues.apache.org/jira/browse/LOGCXX-45). | | +| ![](images/add.gif "add") | GUMP integation Fixes [LOGCXX-44](https://issues.apache.org/jira/browse/LOGCXX-44). | | +| ![](images/add.gif "add") | configure/make help needed Fixes [LOGCXX-43](https://issues.apache.org/jira/browse/LOGCXX-43). | | +| ![](images/fix.gif "fix") | Layout timestamp doesn't seem to adjust for daylight saving Fixes [LOGCXX-41](https://issues.apache.org/jira/browse/LOGCXX-41). | | +| ![](images/fix.gif "fix") | PatternLayout does not support Java date format specifiers Fixes [LOGCXX-40](https://issues.apache.org/jira/browse/LOGCXX-40). | | +| ![](Pictures/100002000000001400000014836C96AED584EDBB.gif "remove") | Remove DailyRollingFileAppender Fixes [LOGCXX-39](https://issues.apache.org/jira/browse/LOGCXX-39). | | +| ![](images/fix.gif "fix") | Unable to build log4cxx under Borland C++ Fixes [LOGCXX-37](https://issues.apache.org/jira/browse/LOGCXX-37). | | +| ![](images/add.gif "add") | Migrate to Apache Portable Runtime threads Fixes [LOGCXX-36](https://issues.apache.org/jira/browse/LOGCXX-36). | | +| ![](Pictures/100002000000001400000014836C96AED584EDBB.gif "remove") | Avoid use of MSXML Fixes [LOGCXX-35](https://issues.apache.org/jira/browse/LOGCXX-35). | | +| ![](images/fix.gif "fix") | Visual Studio 6 CVS build broken Fixes [LOGCXX-34](https://issues.apache.org/jira/browse/LOGCXX-34). | | +| ![](images/fix.gif "fix") | log4cxx::Exception is not derived from std::exception Fixes [LOGCXX-33](https://issues.apache.org/jira/browse/LOGCXX-33). | | +| ![](images/fix.gif "fix") | Missing copy constructors and assignment operators Fixes [LOGCXX-32](https://issues.apache.org/jira/browse/LOGCXX-32). | | +| ![](images/fix.gif "fix") | Missing const qualifiers, Exception::getMessage() in particular. Fixes [LOGCXX-31](https://issues.apache.org/jira/browse/LOGCXX-31). | | +| ![](images/fix.gif "fix") | StringTokenizer uses evil strtok and wcstok functions Fixes [LOGCXX-30](https://issues.apache.org/jira/browse/LOGCXX-30). | | +| ![](images/fix.gif "fix") | Appender attributes are not passed passed to setOption correctly. Fixes [LOGCXX-29](https://issues.apache.org/jira/browse/LOGCXX-29). | | +| ![](images/fix.gif "fix") | Appender threshold cannot be set in configuration files Fixes [LOGCXX-28](https://issues.apache.org/jira/browse/LOGCXX-28). | | +| ![](images/fix.gif "fix") | Appender threshold cannot be set in configuration files Fixes [LOGCXX-27](https://issues.apache.org/jira/browse/LOGCXX-27). | | +| ![](images/fix.gif "fix") | Default initialization is broken Fixes [LOGCXX-26](https://issues.apache.org/jira/browse/LOGCXX-26). | | +| ![](images/add.gif "add") | Add Ant+cpptasks build file Fixes [LOGCXX-25](https://issues.apache.org/jira/browse/LOGCXX-25). | | +| ![](images/fix.gif "fix") | Class and module name not available in LogEvent Fixes [LOGCXX-24](https://issues.apache.org/jira/browse/LOGCXX-24). | | +| ![](images/fix.gif "fix") | Unit tests have become stale Fixes [LOGCXX-23](https://issues.apache.org/jira/browse/LOGCXX-23). | | +| ![](images/fix.gif "fix") | Backslashes in filenames in XML config of FileAppender broken Fixes [LOGCXX-22](https://issues.apache.org/jira/browse/LOGCXX-22). | | +| ![](images/add.gif "add") | Add check that libxml2 not libxml has been included Fixes [LOGCXX-21](https://issues.apache.org/jira/browse/LOGCXX-21). | | +| ![](images/add.gif "add") | Add .cvsignore's to ignore generated files Fixes [LOGCXX-19](https://issues.apache.org/jira/browse/LOGCXX-19). | | +| ![](images/add.gif "add") | LoggerStream Feature Fixes [LOGCXX-18](https://issues.apache.org/jira/browse/LOGCXX-18). | | +| ![](images/update.gif "update") | Use of non reentrant time functions Fixes [LOGCXX-17](https://issues.apache.org/jira/browse/LOGCXX-17). | | +| ![](images/fix.gif "fix") | Misleading statements in Introduction to log4cxx Fixes [LOGCXX-16](https://issues.apache.org/jira/browse/LOGCXX-16). | | +| ![](images/fix.gif "fix") | PatternLayout don't use locale time zone,it's use GMT tome zone Fixes [LOGCXX-15](https://issues.apache.org/jira/browse/LOGCXX-15). | | +| ![](images/add.gif "add") | add -Wall to compile log4cxx will get many warning Fixes [LOGCXX-14](https://issues.apache.org/jira/browse/LOGCXX-14). | | +| ![](images/add.gif "add") | Add branch optimization hint to LOG4CXX\_DEBUG macro Fixes [LOGCXX-13](https://issues.apache.org/jira/browse/LOGCXX-13). | | +| ![](images/fix.gif "fix") | the threshold of ApenderSkeleton can not be set by calling setOption. Fixes [LOGCXX-12](https://issues.apache.org/jira/browse/LOGCXX-12). | | +| ![](images/fix.gif "fix") | Timezone may have side-effects Fixes [LOGCXX-11](https://issues.apache.org/jira/browse/LOGCXX-11). | | +| ![](images/fix.gif "fix") | Conflicting definitions of tchar.h/simulatenous Unicode+MBCS Fixes [LOGCXX-10](https://issues.apache.org/jira/browse/LOGCXX-10). | | +| ![](images/fix.gif "fix") | Compilation problems using VC5 or VC6 with later Platform SDKs Fixes [LOGCXX-8](https://issues.apache.org/jira/browse/LOGCXX-8). | | +| ![](images/fix.gif "fix") | SocketAppender binary format not compatible with Chainsaw Fixes [LOGCXX-7](https://issues.apache.org/jira/browse/LOGCXX-7). | | +| ![](images/add.gif "add") | Win32 OutputDebugString Fixes [LOGCXX-6](https://issues.apache.org/jira/browse/LOGCXX-6). | | +| ![](images/fix.gif "fix") | Preprocessor macro WIN32 used instead of \_WIN32 Fixes [LOGCXX-5](https://issues.apache.org/jira/browse/LOGCXX-5). | | +| ![](images/fix.gif "fix") | initialization not working on many OS's Fixes [LOGCXX-4](https://issues.apache.org/jira/browse/LOGCXX-4). | | +| ![](images/fix.gif "fix") | Missing \#else Fixes [LOGCXX-3](https://issues.apache.org/jira/browse/LOGCXX-3). | | +| ![](images/fix.gif "fix") | logger.h includes config.h Fixes [LOGCXX-2](https://issues.apache.org/jira/browse/LOGCXX-2). | | + + +### Release 0.9.7 - 2004-05-10 + +| | | | +| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | Fixed examples source code in the "Short introduction to log4cxx". | | +| ![](images/fix.gif "fix") | Fixed, in the renaming algorithm of RollingFileAppender and DailyRollingFileAppender, a problem specific to Unicode. | | +| ![](images/fix.gif "fix") | Fixed conflict with Windows macros "min" and "max", by renaming StrictMath::min and StrictMath::max to StrictMath::minimum and StrictMath::maximum. | | +| ![](images/add.gif "add") | Port to HPUX 11.0. | | +| ![](images/fix.gif "fix") | Fixed segmentation fault in PropertyConfigurator. | | +| ![](images/add.gif "add") | Port to Solaris. | | +| ![](images/fix.gif "fix") | Fixed MutexException thrown while destroying RollingFileAppender. | | +| ![](images/fix.gif "fix") | Logging macros can be used without explicity declaring the use of log4cxx namespace. | | +| ![](images/fix.gif "fix") | Fixed static library unresolved externals for msvc 6 and 7.1 | | + + +### Release 0.9.6 - 2004-04-11 + +| | | | +| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/update.gif "update") | Timezone management has been optimized through the class TimeZone | | +| ![](images/update.gif "update") | Inter-thread synchronization and reference counting has been optimized | | +| ![](images/update.gif "update") | Reference counting now uses gcc atomic functions (bug 929078) | | +| ![](images/update.gif "update") | Use of StringBuffer has been optimized. | | +| ![](images/add.gif "add") | Support of localisation throug resourceBundles | | +| ![](images/update.gif "update") | SyslogAppender now uses the system function 'syslog' to log on the local host. (only for POSIX systems) | | +| ![](images/add.gif "add") | Added TimeZone configuration to PatternLayout (bug 912563) | | +| ![](images/add.gif "add") | Support of the DailyRollingFileAppender (feature request 842765) | | + + +### Release 0.9.5 - 2004-02-04 + +| | | | +| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/add.gif "add") | Port of log4j Jnuit tests with Cppunit and Boost Regex. | | +| ![](images/add.gif "add") | Added explicit exports for MSDEV 6 and MSDEV 7 (no further need of .def files) | | +| ![](images/add.gif "add") | Custom levels can be configured through the DOMConfigurator and PropertyConfigurator classes (Level inherites from Object) | | +| ![](images/add.gif "add") | Added a reference counter to LoggingEvent to avoid useless copies (LoggingEvent inherites from Object) | | +| ![](images/add.gif "add") | The file log4j.xml as well as the file log4j.properties are now search for, in log4cxx initialization. | | +| ![](images/add.gif "add") | The root logger can be assigned the "OFF" level. | | +| ![](images/add.gif "add") | Added MSVC6 project missing files mutext.cpp and condition.cpp (bug 847397) | | +| ![](images/fix.gif "fix") | condition.cpp now compiles with MSVC6 (bug 847417) | | +| ![](images/fix.gif "fix") | fixed pure virtual function call in PropertyConfigurator::configureAndWatch (bug 848521) | | +| ![](images/fix.gif "fix") | XMLAppender now displays correct timestamp with MSVC 6 (bug 852836) | | +| ![](images/add.gif "add") | SRLPORT 4.6 support. | | +| ![](images/fix.gif "fix") | Fixed an infinite loop in class Properties. | | +| ![](images/fix.gif "fix") | Fixed compilations problems with unicode. | | +| ![](images/fix.gif "fix") | Fixed SocketAppender bug concerning MDC and NDC. | | + + +### Release 0.9.4 - 2003-10-25 + +| | | | +| ------------------------------------------------------------------- | --------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/update.gif "update") | StringBuffer has been optimized. | | +| ![](images/fix.gif "fix") | Fixed miscellaneous threading problems. | | +| ![](images/add.gif "add") | Added TimeZone support in PatternLayout (bug 796894) | | +| ![](images/fix.gif "fix") | Fixed threading configuration problems (bug 809125) | | +| ![](images/fix.gif "fix") | Fixed miscellaneous MSVC and cygwin compilation problems. | | + + +### Release 0.9.3 - 2003-09-19 + +| | | | +| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/update.gif "update") | Changed tstring to log4cxx::String and tostringstream to log4cxx::StringBuffer. | | +| ![](images/fix.gif "fix") | Fixed MSVC 2003 compilation erros and warnings. | | +| ![](images/add.gif "add") | Added helpers for NDC and MDC. | | +| ![](images/add.gif "add") | Added TimeZone support in TTCCLayout. | | +| ![](images/fix.gif "fix") | Fixed compilation problems with logger macros (LOG4CXX\_...) | | +| ![](images/fix.gif "fix") | Fixed milliseconds formatting problem with MSVC 6.0 and 2003 | | +| ![](images/fix.gif "fix") | Fixed AsyncAppender crash | | +| ![](images/add.gif "add") | Added new tests | | +| ![](images/add.gif "add") | Added benchmarks | | + + +### Release 0.9.2 - 2003-08-10 + +| | | | +| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | Fixed FreeBSD compilation problem with pthread mutex (class CriticalSection). | | +| ![](images/fix.gif "fix") | Fixed milliseconds formatting problem (class DateFormat). | | +| ![](images/add.gif "add") | Long events (\> 1024 chars) are now supported in the class XMLSocketAppender. | | +| ![](images/update.gif "update") | Carriage returns have been normalized in the class XMLLayout. | | + + +### Release 0.9.1 - 2003-08-06 + +| | | | +| ------------------------------------------------------------------- | ------------------------------------------------------------ | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | Fixed deadlock problems in classes Logger and AsyncAppender. | | +| ![](images/fix.gif "fix") | Fixed MSVC 6.0 compilation problems. | | +| ![](images/add.gif "add") | Added MSVC 6.0 static libraty project. | | +| ![](images/update.gif "update") | Default configuration for the SMTP options is "no". | | + + +### Release 0.9.0 - 2003-08-06 + +| | | | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/add.gif "add") | Added ODBCAppender (matching log4j JDBCAppender) | | +| ![](images/add.gif "add") | Added SyslogAppender | | +| ![](images/add.gif "add") | Added SMTPAppender (only for Linux/FreeBSD) | | +| ![](images/add.gif "add") | Added BasicConfigurator | | +| ![](images/add.gif "add") | Added a FileWatchDog in PropertyConfigurator and DOMConfigurator | | +| ![](images/add.gif "add") | Possibility to load a custom LoggerFactory through the DOMConfigurator | | +| ![](images/add.gif "add") | Changed time precision from seconds to milliseconds | | +| ![](images/add.gif "add") | Added MSVC 6.0 'Unicode Debug' and 'Unicode Release' targets | | +| ![](images/add.gif "add") | Added Java like System class. | | + + +### Release 0.1.1 - 2003-07-09 + +| | | | +| ---------------------------------------------------------------- | ------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/fix.gif "fix") | Fixed MSVC 6.0 compilation problems concerning the 'Release' target | | +| ![](images/add.gif "add") | Added MSVC 6.0 tests projects | | + + +### Release 0.1.0 - 2003-07-08 + +| | | | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/add.gif "add") | FreeBSD Autotools/Compilation support | | +| ![](images/fix.gif "fix") | Fixed TelnetAppender crash when a socket bind exception occured. | | +| ![](images/add.gif "add") | Added log4j DTD support to XMLLayout and DOMConfigurator | | +| ![](images/add.gif "add") | Can now send events in XML format over TCP (class XMLSocketAppender) for the log4j Chainsaw UI | | +| ![](images/add.gif "add") | Now compiles with 'configure --enable-unicode' (UTF16 Unicode support) | | +| ![](images/add.gif "add") | Added Java like Properties class. It's a helper for the PropertyConfigurator | | +| ![](images/add.gif "add") | Added Java like objects with dynamic cast and instanciation. Custom objects can be configured through the DOMConfigurator and PropertyConfigurator classes | | +| ![](images/add.gif "add") | Port of the PropertyConfigurator class | | +| ![](images/add.gif "add") | Port of the "Map Diagnostic Context" (MDC) class | | +| ![](images/add.gif "add") | Added 13 tests (try make check) | | + + +### Release 0.0.1 - 2003-05-31 + +| | | | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -- | +| Type | Changes | By | +| ![](images/add.gif "add") | Loggers, Hierarchy, Filters, Appenders, Layouts, NDC | | +| ![](images/add.gif "add") | Appenders: AsyncAppender, ConsoleAppender, FileAppender, NTEventLogAppender, RollingFileAppender, SocketAppender, SocketHubAappender, TelnetAppender | | +| ![](images/add.gif "add") | Layouts: HTMLLayout, PatternLayout, SimpleLayout, TTCCLayout, XMLLayout | | +| ![](images/add.gif "add") | Filters: DenyAllFilter, LevelMatchFilter, LevelRangeFilter, StringMatchFilter | | +| ![](images/add.gif "add") | Configurators: DOMConfigurator | | diff --git a/src/site/markdown/community/issue-tracking.md b/src/site/markdown/community/issue-tracking.md new file mode 100644 index 000000000..ae2c1b38f --- /dev/null +++ b/src/site/markdown/community/issue-tracking.md @@ -0,0 +1,52 @@ +Issue Tracking {#issue-tracking} +=== + + +# Overview + +This project uses [JIRA](https://www.atlassian.com/software/jira), a J2EE-based issue tracking +and project management application. + +# Issue Tracking + +*Bugs* and *feature requests* should be submitted to the following issue tracking system +for this project. + +https://issues.apache.org/jira/browse/LOGCXX + +*Please don't just open bugs only because things don't work for you*, some issues simply +aren't bugs in the code base of the project or it's build tools, but may have a lot of +different other reasons. If things don't work for you and you need some help, please subscribe +to the [users mailing list] and describe +the issue you have, the more detailed the better. The mailing list is a far better place to +discuss things than JIRA, besides that there are more users than developers of the project and +issues created in JIRA are only forwarded to the latter. There's always the chance to create an +issue in JIRA later, hopefully with a specific explanation of the problem and even a solution +already. + +As a rule of thumb, if you already digged through the code and found a problem in it or its +build tools, feel free to directly create a bug in [JIRA](https://issues.apache.org/jira/browse/LOGCXX). +But if things really only don't work and you don't have any clue why, please use the [users mailing list] +instead. + +Thanks! + +[users mailing list]:@ref mailing-lists diff --git a/src/site/markdown/community/mailing-lists.md b/src/site/markdown/community/mailing-lists.md new file mode 100644 index 000000000..81b85529b --- /dev/null +++ b/src/site/markdown/community/mailing-lists.md @@ -0,0 +1,38 @@ +Mailing Lists {#mailing-lists} +=== + + +These are the mailing lists that have been established for +this project. For each list, there is a subscribe, unsubscribe, and an +archive link. +| | | | | | | +| -------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| Name | Subscribe | Unsubscribe | Post | Archive | Other Archives | +| log4cxx usage | [Subscribe](mailto:log4cxx-user-subscribe@logging.apache.org) | [Unsubscribe](mailto:log4cxx-user-unsubscribe@logging.apache.org) | [Post](mailto:log4cxx-user@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-log4cxx-user/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.log4cxx-user) | +| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=log4cxx-user) | +| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.log4cxx.user) | +| log4cxx development | [Subscribe](mailto:dev-subscribe@logging.apache.org) | [Unsubscribe](mailto:dev-unsubscribe@logging.apache.org) | [Post](mailto:dev@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-dev/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.dev) | +| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=dev) | +| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.devel) | +| Old log4cxx development (NOT USED ANYMORE\!) | [Subscribe](mailto:log4cxx-dev-subscribe@logging.apache.org) | [Unsubscribe](mailto:log4cxx-dev-unsubscribe@logging.apache.org) | [Post](mailto:log4cxx-dev@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-log4cxx-dev/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.log4cxx-dev) | +| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=log4cxx-dev) | +| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.log4cxx.devel) | + diff --git a/src/site/markdown/configuration-samples.md b/src/site/markdown/configuration-samples.md new file mode 100644 index 000000000..611ac815c --- /dev/null +++ b/src/site/markdown/configuration-samples.md @@ -0,0 +1,214 @@ +Configuration Samples {#configuration-samples} +=== + + + +The following snippets show various ways of configuring log4cxx. + +[TOC] + +# Patterns {#patterns} + +The basic way of outputing messages is by using a [PatternLayout](@ref log4cxx.PatternLayout), +and then sending the messages to stderr/stdout/file. The following +examples show how you might configure the PatternLayout in order to +achieve the results shown. + +Each example has two blocks of code: the layout for the PatternLayout, +and a sample output message. + +## Pattern 1 {#pattern1} + +This pattern contains the date in an ISO-8601 format(without fractional seconds), +followed by the logger name, the level, and then the message. + +~~~ +[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n +~~~ + +~~~ +[2020-12-24 15:31:46] root INFO - Hello there! +~~~ + +## Pattern 2 {#pattern2} + +Similar to Pattern 1, except using ISO-8601 with fractional seconds + +~~~ +[%d] %c %-5p - %m%n +~~~ + +~~~ +[2020-12-24 15:35:39,225] root INFO - Hello there! +~~~ + +## Pattern 3 {#pattern3} + +Prints out the number of milliseconds since the start of the application, +followed by the level(5 character width), followed by the logger name +(20 character width), followed by the message. + +~~~ +%r %-5p %-20c %m%n +~~~ + +~~~ +0 INFO root Hello there! +~~~ + +# XML Files {#xmlfiles} + +One way of configuring log4cxx is with XML files. The following are some examples +on various ways of using an XML file to configure the logging. + +## XML Example 1 {#xml-example-1} + +This simple example simply writes messages to stdout. +If you want to send messages to stderr instead, simply change the 'Target' value +to `System.err`. + +~~~{.xml} + + + + + + + + + + + + + + + + +~~~ + +Sample output: +~~~ +Hello there! +~~~ + +## XML Example 2 {#xml-example-2} + +This example sends data to both stdout, as well as to a file. In this case, +the file will be in our working directory. The pattern has also been updated +to match with pattern example 1 + +~~~{.xml} + + + + + + + + + + + + + + + + + + + + + + + + +~~~ + +Sample output: +~~~ +[2020-12-24 15:57:35] root INFO - Hello there! +~~~ + +## XML Example 3 {#xml-example-3} + +This example shows how you can configure logging for a particular category. + +Assume that our loggers are in our code as such: + +~~~{.cpp} + log4cxx::LoggerPtr root = log4cxx::Logger::getRootLogger(); + log4cxx::LoggerPtr com = log4cxx::Logger::getLogger( "com" ); + log4cxx::LoggerPtr com_example = log4cxx::Logger::getLogger( "com.example" ); + + LOG4CXX_INFO( root, "Hello there!" ); + LOG4CXX_DEBUG( com, "com logger debug" ); + LOG4CXX_DEBUG( com_example, "com.example debug message" ); + LOG4CXX_TRACE( com, "com debug message" ); + LOG4CXX_TRACE( com_example, "com.example trace message" ); +~~~ + +For this configuration, we have set any logger that is at the `com` level or below +to be debug. However, we have also set the logger `com.example` to have a more +verbose `trace` level to see more information from that particular logger. + +~~~{.xml} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +~~~ + +Sample output: + +~~~ +[2020-12-24 16:05:48] root INFO - Hello there! +[2020-12-24 16:05:48] com DEBUG - com logger debug +[2020-12-24 16:05:48] com.example DEBUG - com.example debug message +[2020-12-24 16:05:48] com.example TRACE - com.example trace message +~~~ diff --git a/src/site/apt/building/autotools.apt b/src/site/markdown/development/autotools.apt similarity index 100% rename from src/site/apt/building/autotools.apt rename to src/site/markdown/development/autotools.apt diff --git a/src/site/markdown/development/build-cmake.md b/src/site/markdown/development/build-cmake.md new file mode 100644 index 000000000..fc7e43fbf --- /dev/null +++ b/src/site/markdown/development/build-cmake.md @@ -0,0 +1,140 @@ +Build with CMake {#build-cmake} +=== + + + +# Building Apache log4cxx with CMake + +* Quick start: + + Building and testing log4cxx on a Unix platform with packaged APR and APR-Util. + + Make sure cmake 3.13+, g++ and make are available, install or + build apr 1.x, apr-util 1.x, gzip and zip. + +~~~ +$ apt-get install build-essential libapr1-dev libaprutil1-dev gzip zip +$ cd apache-log4cxx-x.x.x +$ mkdir build +$ cd build +$ ccmake .. +$ make +$ sudo make install +~~~ + +* ccmake options + +| Option | Usage | +|------------------------|-------| +| -DLOG4CXX_WCHAR_T=no | Enable wchar_t API methods, choice of yes (default), no. | +| -DLOG4CXX_UNICHAR=yes | Enable UniChar API methods, choice of yes, no (default). | +| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). | +| -DBUILD_TESTING=off | Do not build tests. Tests are built by default | +| -DBUILD_SHARED_LIBS=off| Build log4cxx as a static library. A dynamically linked log4cxx library is built by default. Any compilation unit that includes a log4cxx header must define LOG4CXX_STATIC. | +| -DAPU_STATIC=yes | Link to the APR-Util static library. By default, the log4cxx shared library is linked to the APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used. | +| -DAPR_STATIC=yes | Link to the APR static library. By default, the log4cxx shared library is linked to the APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used. | +|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs. Log4cxx requires zip, sed, and grep on the PATH in order for the tests to work properly. | + +Building and testing log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source +extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%\Libraries. + +~~~ +$ cd %HOMEPATH%\Libraries +$ cmake -S libexpat\expat -B buildtrees\expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed +$ cmake --build buildtrees\expat --target install --config Release +$ cmake -S apr-1.7.0 -B buildtrees\apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed +$ cmake --build buildtrees\apr --target install --config Release +$ set CMAKE_PREFIX_PATH=%HOMEPATH%\Libraries\installed +$ cmake -S apr-util-1.6.1 -B buildtrees\apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed +$ cmake --build buildtrees\apr-util --target install --config Release +$ cmake -S apache-log4cxx-x.x.x -B buildtrees\log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed +$ cmake --build buildtrees\log4cxx --target install --config Release +~~~ + +# Platform specific notes: + +## Mac OS/X: + +APR and APR-Util are provided by the platform in Mac OS/X 10.5 and iODBC in 10.4. + +cmake can be installed by typing "brew install cmake". + +## Debian: + +APR, APR-Util, openssl, gzip and zip may be installed by: + +~~~ +$ sudo apt-get install libssl-dev libapr1-dev libaprutil1-dev gzip zip +~~~ + +CMake can be built from source by typing: + +~~~ +$ wget https://github.com/Kitware/CMake/releases/download/v3.16.4/cmake-3.16.4.tar.gz +$ tar xf cmake-3.16.4.tar.gz +$ cd cmake-3.16.4 +$ ./bootstrap +$ make +$ sudo make install +~~~ + +## FreeBSD: + +APR, APR-Util, gzip and zip may be installed from the ports collection by: + +~~~ +$ cd /usr/ports/archivers/zip +$ make +$ make install +$ cd /usr/ports/archivers/gzip +$ make +$ make install +$ cd /usr/ports/devel/apr +$ make +$ make install +~~~ + +## Windows: + +The easiest way to get dependencies installed is to use vcpkg(for APR/expat), and msys2 for the command-line +utilities(zip, grep, sed). + +Msys2 can be downloaded from: https://www.msys2.org/ +By default, this will be installed under C:\msys2, so you can add that to the build PATH by setting +LOG4CXX_TEST_PROGRAM_PATH=C:/msys64/usr/bin in your build settings. + +For vcpkg, follow the directions at https://github.com/microsoft/vcpkg#quick-start-windows and then install +the dependencies needed using `vcpkg install apr apr-util`. + +# Using log4cxx in a CMake build + +A log4cxxConfig.cmake and log4cxxConfigVersion.cmake is installed to allow use of find_package() +in your CMakeLists.txt. + +Below are example cmake commands that compile and link "myApplication" with log4cxx. + +~~~ +find_package(log4cxx 0.11) +add_executable(myApplication myMain.cpp) +target_include_directories(myApplication PRIVATE $) +target_link_libraries( myApplication PRIVATE log4cxx) +~~~ + diff --git a/src/site/markdown/development/build-vcpkg.md b/src/site/markdown/development/build-vcpkg.md new file mode 100644 index 000000000..1dfba510e --- /dev/null +++ b/src/site/markdown/development/build-vcpkg.md @@ -0,0 +1,56 @@ +Building with vcpkg {#build-vcpkg} +=== + + + +# Building Apache log4cxx with vcpkg + +## Preparation + +Windows: +~~~ +> git clone https://github.com/Microsoft/vcpkg.git +> cd vcpkg +> .\bootstrap-vcpkg.bat +# Then, to hook up user-wide integration, run (note: requires admin on first use) +> .\vcpkg integrate install +~~~ + +Linux: +~~~ +$ git clone https://github.com/Microsoft/vcpkg.git +$ cd vcpkg +$ ./bootstrap-vcpkg.sh +$ ./vcpkg integrate install +~~~ + +## Building log4cxx.dll + +Windows: +~~~ +PS> .\vcpkg install log4cxx +~~~ + +Linux: +~~~ +$ ./vcpkg install log4cxx +~~~ + diff --git a/src/site/markdown/development/building.md b/src/site/markdown/development/building.md new file mode 100644 index 000000000..b348e3956 --- /dev/null +++ b/src/site/markdown/development/building.md @@ -0,0 +1,51 @@ +Building {#building} +=== + + + +# Building Apache log4cxx + +The project supports different build tools on different platforms, have a +look at the menu to find the platform you need. If your environment is not +covered already, feel free to ask about it on one of the Mailing Lists or +leave a bug in our Issue Tracker. In this case it would be very helpful of +course if you could already provide some patches to support your environment +or at least provide some technical details about the build tools, compiler +etc. you use. + +## Covered by the team + +The following list provides an overview about the environments some of the +team members have access to and therefore normally should work out of the box +or at least were used sometimes in the past. This list by no means tells +something about how good the support on each platform is, it's just a guide. + +The following platforms/compilers are expected to work correctly: + +* Windows 10(32 and 64-bit) - MSVC +* Windows 10(32-bit) - Embarcadero C++ Builder XE 4 +* Debian 10(32 and 64-bit) - gcc 8.3.0, clang-7 +* Ubuntu 20.04(32 and 64-bit) - gcc, clang +* Mac OSX - clang + +Various Linux distributions already have log4cxx as part of their package +managers - consult the documentation for your distribution to determine +if a package already exists. diff --git a/src/site/markdown/dependencies.md b/src/site/markdown/development/dependencies.md similarity index 94% rename from src/site/markdown/dependencies.md rename to src/site/markdown/development/dependencies.md index 49a21ecf2..5cfe28ffb 100644 --- a/src/site/markdown/dependencies.md +++ b/src/site/markdown/development/dependencies.md @@ -1,3 +1,9 @@ +Dependencies {#dependencies} +=== + + # LOG4CXX Dependencies log4cxx requires the following software to build and/or run correctly: diff --git a/src/site/apt/building/maven.apt b/src/site/markdown/development/maven.apt similarity index 100% rename from src/site/apt/building/maven.apt rename to src/site/markdown/development/maven.apt diff --git a/src/site/markdown/development/source-repository.md b/src/site/markdown/development/source-repository.md new file mode 100644 index 000000000..879f02b24 --- /dev/null +++ b/src/site/markdown/development/source-repository.md @@ -0,0 +1,48 @@ +Source Repository {#source-repository} +=== + + + +# Overview + +Log4cxx uses GIT to manage its source code. Instructions on GIT use can be found at http://git-scm.com/documentation. + +## Web Access + +The default repository can be seen on gitbox at: + +* https://gitbox.apache.org/repos/asf?p=logging-log4cxx.git + +This repository is mirrored to GitHub at the following location: + +* https://github.com/apache/logging-log4cxx + +## Anonymous access + +The source can be checked out anonymously from GIT with this command (See http://git-scm.com/docs/git-clone): + +~~~ + $ git clone http://gitbox.apache.org/repos/asf/logging-log4cxx.git +~~~ + +## Pull Requests + +Pull requests may be submitted through GitHub. diff --git a/src/site/markdown/download.md.in b/src/site/markdown/download.md.in new file mode 100644 index 000000000..cb2d4c906 --- /dev/null +++ b/src/site/markdown/download.md.in @@ -0,0 +1,64 @@ +Download {#download} +=== + + +# Download Apache log4cxx ${LOG4CXX_RELEASE_VERSION} + + Apache log4cxx ${LOG4CXX_RELEASE_VERSION} is distributed under the [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). + + The link in the Mirrors column should display a list of available mirrors with a + default selection based on your inferred location. If you do not see that page, + try a different browser. The checksum and signature are links to + the originals on the main distribution server. + +| | Mirrors | Checksum | Signature | +|-------------------------|---------|----------|-----------| +| Apache log4cxx ${LOG4CXX_RELEASE_VERSION} (tar.gz) | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc] | +| Apache log4cxx ${LOG4CXX_RELEASE_VERSION} (zip) | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc] | + +It is essential that you verify the integrity of the downloaded files using the PGP or SHA512 signatures. +Please read [Verifying Apache HTTP Server Releases](https://httpd.apache.org/dev/verification.html) for more +information on why you should verify our releases. + +The PGP signatures can be verified using PGP or GPG. First download the [KEYS](https://www.apache.org/dist/logging/KEYS) +as well as the asc signature file for the relevant distribution. Make sure you get these files from the +[main distribution directory](https://www.apache.org/dist/logging/), rather than from a mirror. Then verify the signatures using: + +~~~ +% gpg --import KEYS +% gpg --verify apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz +~~~ + +* apache-log4cxx-${LOG4CXX_RELEASE_VERSION} is signed by ${releaseManager} (${releaseKey}) + +Alternatively, you can verify the SHA512 signature on the files. A unix program called sha512 or sha512sum is included +in many unix distributions. + +## Previous Releases + +All previous releases of Apache log4cxx can be found in the [archive repository](https://archive.apache.org/dist/logging/log4cxx). + +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz]:https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512 +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip]:https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512 +[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc diff --git a/src/site/markdown/extending.md b/src/site/markdown/extending.md new file mode 100644 index 000000000..ede583f8a --- /dev/null +++ b/src/site/markdown/extending.md @@ -0,0 +1,141 @@ +Extending Log4cxx {#extending-log4cxx} +=== + + + +Sometimes, you may want to extend log4cxx, for example by creating +a new appender to write out data in a new format. The following +guide shows how you can extend log4cxx in order to add a new appender. + +The full sample application can be found in the src/examples/cpp +directory. + +The first thing for our example is to create a class that extends +log4cxx.AppenderSkeleton so that we don't need to implement all of +the virtual methods that are defined in log4cxx.Appender: + +~~~{.cpp} +namespace log4cxx { + +class NullWriterAppender : public log4cxx::AppenderSkeleton { +}; + +} +~~~ + +Next, we need to add in a few macros in order to properly register +our new appender with log4cxx: + +~~~{.cpp} +namespace log4cxx { + +class NullWriterAppender : public log4cxx::AppenderSkeleton { +public: + DECLARE_LOG4CXX_OBJECT(NullWriterAppender) + BEGIN_LOG4CXX_CAST_MAP() + LOG4CXX_CAST_ENTRY(NullWriterAppender) + LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton) + END_LOG4CXX_CAST_MAP() + +}; + +IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender) + +} +~~~ + +These macros tell log4cxx what the name of our class is, as well as giving +log4cxx a way of instansiating our class. Without these macros, the custom +class will not work. + +Now, let's add some basic functionality to our class. As the name of +our class implies, we are going to do nothing with our appender here, as +this is just an example. To that end, we need to implement the following: +1. Default constructor +2. `close` method +3. `requiresLayout` method +4. `append` method, which does the actual writing of the log event +5. `activateOptions`, which causes the class to reconfigure itself +6. `setOption`, which gets called whenever we get an option in a config file + +These are basically stub methods, with a few comments on their use: + +~~~{.cpp} + NullWriterAppender(){} + + virtual void close(){} + + virtual bool requiresLayout() const { + return false; + } + + virtual void append(const spi::LoggingEventPtr& event, log4cxx::helpers::Pool& p){ + // This gets called whenever there is a valid event for our appender. + } + + virtual void activateOptions(log4cxx::helpers::Pool& /* pool */) { + // Given all of our options, do something useful(e.g. open a file) + } + + virtual void setOption(const LogString& option, const LogString& value){ + if (helpers::StringHelper::equalsIgnoreCase(option, + LOG4CXX_STR("SOMEVALUE"), LOG4CXX_STR("somevalue"))){ + // Do something with the 'value' here. + } + } +~~~ + +At this point, we now have a fully functioning(if useless) custom appender. We can now +refer to this appender in our configuration file like so: + +~~~{.xml} + + + + + + + + + + + + + + + + + + + + + + +~~~ + +When log4cxx is configured, any messages that go to the `NullLogger` will +then be forwarded on to the `NullWriterAppender`. + +This same technique can be used to add new classes of many different kinds +to log4cxx, including(but not limited to): +* [Appenders](@ref log4cxx.Appender) +* [Layouts](@ref log4cxx.Layout) +* [Filters](@ref log4cxx.spi.Filter) diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index 190ff4d1b..b1c7ce6fc 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -1,3 +1,9 @@ +FAQ {#faq} +=== + + +# Short introduction to Apache log4cxx + +Apache log4cxx is a logging framework for C++ patterned after [Apache log4j], +which uses [Apache Portable Runtime] for most platform-specific code and should +be usable on any platform supported by APR. Apache log4cxx is licensed under +the [Apache License], an open source license certified by the [Open Source Initiative]. + +Almost every large application includes its own logging or tracing API. +Inserting log statements into code is a low-tech method for debugging it. +It may also be the only way because debuggers are not always available or +applicable. This is usually the case for multithreaded applications and distributed +applications at large. + +Experience indicates that logging is an important component of the development +cycle. It offers several advantages. It provides precise context about a run of +the application. Once inserted into the code, the generation of logging output +requires no human intervention. Moreover, log output can be saved in persistent +medium to be studied at a later time. In addition to its use in the development +cycle, a sufficiently rich logging package can also be viewed as an auditing tool. + +Logging does have its drawbacks. It can slow down an application. If too verbose, +it can cause scrolling blindness. To alleviate these concerns, log4cxx is +designed to be reliable, fast and extensible. Since logging is rarely the +main focus of an application, the log4cxx API strives to be simple to +understand and to use. + +[Apache log4j]:https://logging.apache.org/log4j/2.x/ +[Apache Portable Runtime]:https://apr.apache.org/ +[Apache License]:https://www.apache.org/licenses/ +[Open Source Initiative]:https://opensource.org/ diff --git a/src/site/markdown/license.md b/src/site/markdown/license.md new file mode 100644 index 000000000..233f889b3 --- /dev/null +++ b/src/site/markdown/license.md @@ -0,0 +1,232 @@ +License {#license} +=== + + + +# Overview + +Typically the licenses listed for the project are that of the project itself, and not of dependencies. + +## Project License +Apache License, Version 2.0 +~~~ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed 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. +~~~ diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md new file mode 100644 index 000000000..84dbd7741 --- /dev/null +++ b/src/site/markdown/usage.md @@ -0,0 +1,813 @@ +Usage {#usage} +=== + + +[TOC] + +# Loggers {#loggers} + +Log4cxx has three main components: *loggers*, *appenders* and *layouts*. +These three types of components work together to enable developers to +log messages according to message type and level, and to control at +runtime how these messages are formatted and where they are reported. + +## Hierarchy {#hierarchy} + +The first and foremost advantage of any logging API over plain +`std::cout` resides in its ability to disable certain log statements +while allowing others to print unhindered. This capability assumes that +the logging space, that is, the space of all possible logging +statements, is categorized according to some developer-chosen criteria. + +Loggers are named entities. Logger names are case-sensitive and they +follow the hierarchical naming rule: + +**Named Hierarchy** + +A logger is said to be an *ancestor* of another logger if its name +followed by a dot is a prefix of the *descendant* logger name. A logger +is said to be a *parent* of a *child* logger if there are no ancestors +between itself and the descendant logger. + +For example, the logger named `com.foo` is a parent of the logger +named `com.foo.Bar`. Similarly, `java` is a parent of `java.util` +and an ancestor of `java.util.Vector`. This naming scheme should be +familiar to most developers. + +The root logger resides at the top of the logger hierarchy. It is +exceptional in two ways: + +1. it always exists, +2. it cannot be retrieved by name. + +Invoking the class static +log4cxx::Logger::getRootLogger method retrieves it. All other loggers are instantiated and retrieved +with the class static log4cxx::Logger::getLogger +method. This method takes the name of the desired logger as a parameter. +Some of the basic methods in the Logger class are listed below. + +~~~{.cpp} + namespace log4cxx { + class Logger { + public: + // Creation & retrieval methods: + static LoggerPtr getRootLogger(); + static LoggerPtr getLogger(const std::string& name); + static LoggerPtr getLogger(const std::wstring& name); + } + } + + // + // Use these macros instead of calling Logger methods directly. + // Macros will handle char or wchar_t pointers or strings + // or most right-hand side expressions of an + // std::basic_string::operator<<. + // + #define LOG4CXX_TRACE(logger, expression) ... + #define LOG4CXX_DEBUG(logger, expression) ... + #define LOG4CXX_INFO(logger, expression) ... + #define LOG4CXX_WARN(logger, expression) ... + #define LOG4CXX_ERROR(logger, expression) ... + #define LOG4CXX_FATAL(logger, expression) ... +~~~ + +## Levels {#levels} + +Loggers *may* be assigned levels. The pre-defined levels: TRACE, DEBUG, +INFO, WARN, ERROR and FATAL are defined in the +log4cxx::Level class which provides accessor functions. + +If a given logger is not assigned a level, then it inherits one from its +closest ancestor with an assigned level. More formally: + +**Level Inheritance** + +The *inherited level* for a given logger *C*, is equal to the first +non-null level in the logger hierarchy, starting at *C* and proceeding +upwards in the hierarchy towards the *root* logger. + +To ensure that all loggers can eventually inherit a level, the root +logger always has an assigned level. + +Below are four tables with various assigned level values and the +resulting inherited levels according to the above rule. + +| Logger name | Assigned level | Inherited level | +| ----------- | -------------- | --------------- | +| root | Proot | Proot | +| X | none | Proot | +| X.Y | none | Proot | +| X.Y.Z | none | Proot | + +Example 1 + +In example 1 above, only the root logger is assigned a level. This level +value, *Proot*, is inherited by the other loggers *X*, *X.Y* and +*X.Y.Z*. + +| Logger name | Assigned level | Inherited level | +| ----------- | -------------- | --------------- | +| root | Proot | Proot | +| X | Px | Px | +| X.Y | Pxy | Pxy | +| X.Y.Z | Pxyz | Pxyz | + +Example 2 + +In example 2, all loggers have an assigned level value. There is no need +for level inheritence. + +| Logger name | Assigned level | Inherited level | +| ----------- | -------------- | --------------- | +| root | Proot | Proot | +| X | Px | Px | +| X.Y | none | Px | +| X.Y.Z | Pxyz | Pxyz | + +Example 3 + +In example 3, the loggers *root*, *X* and *X.Y.Z* are assigned the +levels *Proot*, *Px* and *Pxyz* respectively. The logger *X.Y* inherits +its level value from its parent *X*. + +| Logger name | Assigned level | Inherited level | +| ----------- | -------------- | --------------- | +| root | Proot | Proot | +| X | Px | Px | +| X.Y | none | Px | +| X.Y.Z | none | Px | + +Example 4 + +In example 4, the loggers *root* and *X* and are assigned the levels +*Proot* and *Px* respectively. The loggers *X.Y* and *X.Y.Z* inherits +their level value from their nearest parent *X* having an assigned +level. + +## Requests {#requests} + +Logging requests are made by invoking a method of a logger instance, +preferrably through the use of LOG4CXX\_INFO or similar macros which +support short-circuiting if the threshold is not satisfied and use of +the insertion operator (\<\<) in the message parameter. + +~~~{.cpp} + log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("com.foo")); + const char* region = "World"; + LOG4CXX_INFO(logger, "Simple message text.") + LOG4CXX_INFO(logger, "Hello, " << region) + LOG4CXX_DEBUG(logger, L"Iteration " << i) + LOG4CXX_DEBUG(logger, "e^10 = " << std::scientific << exp(10.0)) + // + // Use a wchar_t first operand to force use of wchar_t based stream. + // + LOG4CXX_WARN(logger, L"" << i << L" is the number of the iteration.") +~~~ + +A logging request is said to be *enabled* if its level is higher than or +equal to the level of its logger. Otherwise, the request is said to be +*disabled*. A logger without an assigned level will inherit one from the +hierarchy. This rule is summarized below. + +**Basic Selection Rule** + +A log request of level *p* in a logger with (either assigned or +inherited, whichever is appropriate) level *q*, is enabled if *p \>= q*. + +This rule is at the heart of log4cxx. It assumes that levels are +ordered. For the standard levels, we have *TRACE \< DEBUG \< INFO \< +WARN \< ERROR \< FATAL*. + +Here is an example of this rule. + +~~~{.cpp} + // get a logger instance named "com.foo" + log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("com.foo")); + + // Now set its level. Normally you do not need to set the + // level of a logger programmatically. This is usually done + // in configuration files. + logger->setLevel(log4cxx::Level::getInfo()); + + log4cxx::LoggerPtr barlogger(log4cxx::Logger::getLogger("com.foo.Bar")); + + // This request is enabled, because WARN >= INFO. + LOG4CXX_WARN(logger, "Low fuel level.") + + // This request is disabled, because DEBUG < INFO. + LOG4CXX_DEBUG(logger, "Starting search for nearest gas station.") + + // The logger instance barlogger, named "com.foo.Bar", + // will inherit its level from the logger named + // "com.foo" Thus, the following request is enabled + // because INFO >= INFO. + LOG4CXX_INFO(barlogger. "Located nearest gas station.") + + // This request is disabled, because DEBUG < INFO. + LOG4CXX_DEBUG(barlogger, "Exiting gas station search") +~~~ + +Calling the *getLogger* method with the same name will always return a +reference to the exact same logger object. + +For example, in + +~~~{.cpp} + log4cxx::LoggerPtr x = log4cxx::Logger::getLogger("wombat"); + log4cxx::LoggerPtr y = log4cxx::Logger::getLogger("wombat"); +~~~ + +*x* and *y* refer to *exactly* the same logger object. + +Thus, it is possible to configure a logger and then to retrieve the same +instance somewhere else in the code without passing around references. +In fundamental contradiction to biological parenthood, where parents +always preceed their children, log4cxx loggers can be created and +configured in any order. In particular, a "parent" logger will find and +link to its descendants even if it is instantiated after them. + +Configuration of the log4cxx environment is typically done at +application initialization. The preferred way is by reading a +configuration file. This approach will be discussed shortly. + +Log4cxx makes it easy to name loggers by *software component*. This can +be accomplished by statically instantiating a logger in each class, with +the logger name equal to the fully qualified name of the class. This is +a useful and straightforward method of defining loggers. As the log +output bears the name of the generating logger, this naming strategy +makes it easy to identify the origin of a log message. However, this is +only one possible, albeit common, strategy for naming loggers. Log4cxx +does not restrict the possible set of loggers. The developer is free to +name the loggers as desired. + +Nevertheless, naming loggers after the class where they are located +seems to be the best strategy known so far. + +# Appenders and Layouts {#appenders-and-layouts} + +The ability to selectively enable or disable logging requests based on +their logger is only part of the picture. Log4cxx allows logging +requests to print to multiple destinations. In log4cxx speak, an output +destination is called an *appender*. Currently, appenders exist for the +[console](@ref log4cxx.ConsoleAppender), [files](@ref log4cxx.FileAppender), +GUI components, [remote socket](@ref log4cxx.net.SocketAppender) +servers, [NT Event Loggers](@ref log4cxx.nt.NTEventLogAppender), +and remote UNIX [Syslog](@ref log4cxx.net.SyslogAppender) +daemons. It is also possible to log +[asynchronously](@ref log4cxx.AsyncAppender). + +More than one appender can be attached to a logger. + +The +[addAppender](@ref log4cxx.Logger.addAppender) +method adds an appender to a given logger. *Each enabled logging +request for a given logger will be forwarded to all the appenders in +that logger as well as the appenders higher in the hierarchy.* In other +words, appenders are inherited additively from the logger hierarchy. For +example, if a console appender is added to the root logger, then all +enabled logging requests will at least print on the console. If in +addition a file appender is added to a logger, say *C*, then enabled +logging requests for *C* and *C*'s children will print on a file *and* +on the console. It is possible to override this default behavior so that +appender accumulation is no longer additive by +[setting the additivity flag](@ref log4cxx.Logger.setAdditivity) to `false`. + +The rules governing appender additivity are summarized below. + +**Appender Additivity** + +The output of a log statement of logger *C* will go to all the appenders +in *C* and its ancestors. This is the meaning of the term "appender +additivity". However, if an ancestor of logger *C*, say *P*, has the +additivity flag set to *false*, then *C*'s output will be directed to +all the appenders in *C* and it's ancestors up to and including *P* but, +not the appenders in any of the ancestors of *P*. + +Loggers have their additivity flag set to *true* by default. + +The table below shows an +example: + +| Logger Name | Added Appenders | Additivity Flag | Output Targets | Comment | +| --------------- | --------------- | --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| root | A1 | not applicable | A1 | The root logger is anonymous but can be accessed with the log4cxx::Logger::getRootLogger() method. There is no default appender attached to root. | +| x | A-x1, A-x2 | true | A1, A-x1, A-x2 | Appenders of "x" and root. | +| x.y | none | true | A1, A-x1, A-x2 | Appenders of "x" and root. | +| x.y.z | A-xyz1 | true | A1, A-x1, A-x2, A-xyz1 | Appenders in "x.y.z", "x" and root. | +| security | A-sec | false | A-sec | No appender accumulation since the additivity flag is set to *false*. | +| security.access | none | true | A-sec | Only appenders of "security" because the additivity flag in "security" is set to *false*. | + +More often than not, users wish to customize not only the output +destination but also the output format. This is accomplished by +associating a *layout* with an appender. The layout is responsible for +formatting the logging request according to the user's wishes, whereas +an appender takes care of sending the formatted output to its +destination. + +The [PatternLayout](@ref log4cxx.PatternLayout), +part of the standard log4cxx distribution, lets the user specify the +output format according to conversion patterns similar to the C language +*printf* function. + +For example, the PatternLayout with the conversion pattern `%%r [%%t] +%%-5p %%c - %%m%%n` will output something akin to: + +~~~ +176 [main] INFO org.foo.Bar - Located nearest gas station. +~~~ + +The first field is the number of milliseconds elapsed since the start of +the program. The second field is the thread making the log request. The +third field is the level of the log statement. The fourth field is the +name of the logger associated with the log request. The text after the +'-' is the message of the statement. + +# Configuration {#configuration} + +Inserting log requests into the application code requires a fair amount +of planning and effort. Observation shows that approximately 4 percent +of code is dedicated to logging. Consequently, even moderately sized +applications will have thousands of logging statements embedded within +their code. Given their number, it becomes imperative to manage these +log statements without the need to modify them manually. + +The log4cxx environment is fully configurable programmatically. However, +it is far more flexible to configure log4cxx using configuration files. +Currently, configuration files can be written in XML or in Java +properties (key=value) format. + +Let us give a taste of how this is done with the help of an imaginary +application *MyApp* that uses log4cxx. + +~~~{.cpp} + #include "com/foo/bar.h" + using namespace com::foo; + + // include log4cxx header files. + #include "log4cxx/logger.h" + #include "log4cxx/basicconfigurator.h" + #include "log4cxx/helpers/exception.h" + + using namespace log4cxx; + using namespace log4cxx::helpers; + + LoggerPtr logger(Logger::getLogger("MyApp")); + + int main(int argc, char **argv) + { + int result = EXIT_SUCCESS; + try + { + // Set up a simple configuration that logs on the console. + BasicConfigurator::configure(); + + LOG4CXX_INFO(logger, "Entering application.") + Bar bar; + bar.doIt(); + LOG4CXX_INFO(logger, "Exiting application.") + } + catch(Exception&) + { + result = EXIT_FAILURE; + } + + return result; + } +~~~ + +*MyApp* begins by including log4cxx headers. It then defines a static +logger variable with the name *MyApp* which happens to be the fully +qualified name of the class. + +*MyApp* uses the *Bar* class defined in header file *com/foo/bar.h*. + +~~~{.cpp} + // file com/foo/bar.h + #include "log4cxx/logger.h" + + namespace com { + namespace foo { + class Bar { + static log4cxx::LoggerPtr logger; + + public: + void doIt(); + } + } + } +~~~ + +~~~{.cpp} + // file bar.cpp + #include "com/foo/bar.h" + + using namespace com::foo; + using namespace log4cxx; + + LoggerPtr Bar::logger(Logger::getLogger("com.foo.bar")); + + void Bar::doIt() { + LOG4CXX_DEBUG(logger, "Did it again!") + } +~~~ + +The invocation of the +[BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.configure) +method creates a rather simple log4cxx setup. This method is hardwired +to add to the root logger a [ConsoleAppender](@ref log4cxx.ConsoleAppender). +The output will be formatted using a +[PatternLayout](@ref log4cxx.PatternLayout) +set to the pattern `%%-4r [%%t] %%-5p %%c %%x - %%m%%n`. + +Note that by default, the root logger is assigned to +*Level::getDebug()*. + +The output of MyApp is: + +~~~ + 0 [12345] INFO MyApp - Entering application. + 36 [12345] DEBUG com.foo.Bar - Did it again! + 51 [12345] INFO MyApp - Exiting application. +~~~ + +The previous example always outputs the same log information. +Fortunately, it is easy to modify *MyApp* so that the log output can be +controlled at run-time. Here is a slightly modified version. + +~~~{.cpp} + // file MyApp2.cpp + + #include "com/foo/bar.h" + using namespace com::foo; + + // include log4cxx header files. + #include "log4cxx/logger.h" + #include "log4cxx/basicconfigurator.h" + #include "log4cxx/propertyconfigurator.h" + #include "log4cxx/helpers/exception.h" + + using namespace log4cxx; + using namespace log4cxx::helpers; + // Define a static logger variable so that it references the + // Logger instance named "MyApp". + LoggerPtr logger(Logger::getLogger("MyApp")); + + int main(int argc, char **argv) + { + int result = EXIT_SUCCESS; + try + { + if (argc > 1) + { + // BasicConfigurator replaced with PropertyConfigurator. + PropertyConfigurator::configure(argv[1]); + } + else + { + BasicConfigurator::configure(); + } + + LOG4CXX_INFO(logger, "Entering application.") + Bar bar + bar.doIt(); + LOG4CXX_INFO(logger, "Exiting application.") + } + catch(Exception&) + { + result = EXIT_FAILURE; + } + + return result; + } +~~~ + +This version of *MyApp* instructs *PropertyConfigurator* to parse a +configuration file and set up logging accordingly. + +Here is a sample configuration file that results in exactly same output +as the previous *BasicConfigurator* based example. + +~~~ + # Set root logger level to DEBUG and its only appender to A1. + log4j.rootLogger=DEBUG, A1 + + # A1 is set to be a ConsoleAppender. + log4j.appender.A1=org.apache.log4j.ConsoleAppender + + # A1 uses PatternLayout. + log4j.appender.A1.layout=org.apache.log4j.PatternLayout + log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n +~~~ + +It can be noticed that the PropertyConfigurator file format is the same +as log4j. + +Suppose we are no longer interested in seeing the output of any +component belonging to the *com::foo* package. The following +configuration file shows one possible way of achieving this. + +~~~ + log4j.rootLogger=DEBUG, A1 + log4j.appender.A1=org.apache.log4j.ConsoleAppender + log4j.appender.A1.layout=org.apache.log4j.PatternLayout + + # Print the date in ISO 8601 format + log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n + + # Print only messages of level WARN or above in the package com.foo. + log4j.logger.com.foo=WARN +~~~ + +The output of *MyApp* configured with this file is shown below. + +~~~ + 2000-09-07 14:07:41,508 [12345] INFO MyApp - Entering application. + 2000-09-07 14:07:41,529 [12345] INFO MyApp - Exiting application. +~~~ + +As the logger *com.foo.Bar* does not have an assigned level, it inherits +its level from *com.foo*, which was set to WARN in the configuration +file. The log statement from the *Bar::doIt* method has the level DEBUG, +lower than the logger level WARN. Consequently, *doIt()* method's log +request is suppressed. + +Here is another configuration file that uses multiple appenders. + +~~~ + log4j.rootLogger=debug, stdout, R + + log4j.appender.stdout=org.apache.log4j.ConsoleAppender + log4j.appender.stdout.layout=org.apache.log4j.PatternLayout + + # Pattern to output the caller's file name and line number. + log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n + + log4j.appender.R=org.apache.log4j.RollingFileAppender + log4j.appender.R.File=example.log + + log4j.appender.R.MaxFileSize=100KB + # Keep one backup file + log4j.appender.R.MaxBackupIndex=1 + + log4j.appender.R.layout=org.apache.log4j.PatternLayout + log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n +~~~ + +Calling the enhanced MyApp with the this configuration file will output +the following on the console. + +~~~ + INFO [12345] (MyApp2.cpp:31) - Entering application. + DEBUG [12345] (Bar.h:16) - Doing it again! + INFO [12345] (MyApp2.cpp:34) - Exiting application. +~~~ + +In addition, as the root logger has been allocated a second appender, +output will also be directed to the *example.log* file. This file will +be rolled over when it reaches 100KB. When roll-over occurs, the old +version of *example.log* is automatically moved to *example.log.1*. + +Note that to obtain these different logging behaviors we did not need to +recompile code. We could just as easily have logged to a UNIX Syslog +daemon, redirected all *com.foo* output to an NT Event logger, or +forwarded logging events to a remote log4cxx server, which would log +according to local server policy, for example by forwarding the log +event to a second log4cxx server. + +# Default Initialization Procedure {#default-initialization-procedure} + +The log4cxx library does not make any assumptions about its environment. +In particular, there are no default log4cxx appenders. Under certain +well-defined circumstances however, the static inializer of the *Logger* +class will attempt to automatically configure log4cxx. + +The exact default initialization algorithm is defined as follows: + +1. Set the configurationOptionStr string variable to the value of the + **LOG4CXX\_CONFIGURATION** environment variable if set, otherwise + the value of the **log4j.configuration** environment variable if + set, otherwise the first of the following file names which exist in + the current working directory, "log4cxx.xml", "log4cxx.properties", + "log4j.xml" and "log4j.properties". If configurationOptionStr has + not been set, then disable logging. +2. Unless a custom configurator is specified using the + **LOG4CXX\_CONFIGURATOR\_CLASS** or **log4j.configuratorClass** + environment variable, the PropertyConfigurator will be used to + configure log4cxx unless the file name ends with the ".xml" + extension, in which case the DOMConfigurator will be used. If a + custom configurator is specified, the environment variable should + contain a fully qualified class name of a class that implements the + Configurator interface. + +# Nested Diagnostic Contexts {#nested-diagnostic-contexts} + +Most real-world systems have to deal with multiple clients +simultaneously. In a typical multithreaded implementation of such a +system, different threads will handle different clients. Logging is +especially well suited to trace and debug complex distributed +applications. A common approach to differentiate the logging output of +one client from another is to instantiate a new separate logger for each +client. This promotes the proliferation of loggers and increases the +management overhead of logging. + +A lighter technique is to uniquely stamp each log request initiated from +the same client interaction. Neil Harrison described this method in the +book "Patterns for Logging Diagnostic Messages," in *Pattern Languages +of Program Design 3*, edited by R. Martin, D. Riehle, and F. Buschmann +(Addison-Wesley, 1997). + +To uniquely stamp each request, the user pushes contextual information +into the NDC, the abbreviation of *Nested Diagnostic Context*. The NDC +class is shown below. + +~~~{.cpp} + namespace log4cxx { + class NDC { + public: + // pushes the value on construction and pops on destruction. + NDC(const std::string& value); + NDC(const std::wstring& value); + + // Remove the top of the context from the NDC. + static LogString pop(); + + // Add diagnostic context for the current thread. + static void push(const std::string& message); + static void push(const std::wstring& message); + } + } +~~~ + +The NDC is managed per thread as a *stack* of contextual information. +Note that all methods of the *log4cxx::NDC* class are static. Assuming +that NDC printing is turned on, every time a log request is made, the +appropriate log4cxx component will include the *entire* NDC stack for +the current thread in the log output. This is done without the +intervention of the user, who is responsible only for placing the +correct information in the NDC by using the *push* and *pop* methods at +a few well-defined points in the code. In contrast, the per-client +logger approach commands extensive changes in the code. + +To illustrate this point, let us take the example of a servlet +delivering content to numerous clients. The servlet can build the NDC at +the very beginning of the request before executing other code. The +contextual information can be the client's host name and other +information inherent to the request, typically information contained in +cookies. Hence, even if the servlet is serving multiple clients +simultaneously, the logs initiated by the same code, i.e. belonging to +the same logger, can still be distinguished because each client request +will have a different NDC stack. Contrast this with the complexity of +passing a freshly instantiated logger to all code exercised during the +client's request. + +Nevertheless, some sophisticated applications, such as virtual hosting +web servers, must log differently depending on the virtual host context +and also depending on the software component issuing the request. Recent +log4cxx releases support multiple hierarchy trees. This enhancement +allows each virtual host to possess its own copy of the logger +hierarchy. + +# Performance {#performance} + +One of the often-cited arguments against logging is its computational +cost. This is a legitimate concern as even moderately sized applications +can generate thousands of log requests. Much effort was spent measuring +and tweaking logging performance. Log4cxx claims to be fast and +flexible: speed first, flexibility second. + +The user should be aware of the following performance issues. + +1. **Logging performance when logging is turned off.** + + When logging is turned off entirely or just for a set of levels, the + cost of a log request consists of a method invocation plus an + integer comparison. The LOG4CXX\_DEBUG and similar macros suppress + unnecessary expression evaluation if the request is not enabled. + +2. **The performance of deciding whether to log or not to log when + logging is turned on.** + + This is essentially the performance of walking the logger hierarchy. + When logging is turned on, log4cxx still needs to compare the level + of the log request with the level of the request logger. However, + loggers may not have an assigned level; they can inherit them from + the logger hierarchy. Thus, before inheriting a level, the logger + may need to search its ancestors. + + There has been a serious effort to make this hierarchy walk to be as + fast as possible. For example, child loggers link only to their + existing ancestors. In the *BasicConfigurator* example shown + earlier, the logger named *com.foo.Bar* is linked directly to the + root logger, thereby circumventing the nonexistent *com* or + *com.foo* loggers. This significantly improves the speed of the + walk, especially in "sparse" hierarchies. + + The cost of walking the hierarchy is typically 3 times slower than + when logging is turned off entirely. + +3. **Actually outputting log messages** + + This is the cost of formatting the log output and sending it to its + target destination. Here again, a serious effort was made to make + layouts (formatters) perform as quickly as possible. The same is + true for appenders. + +# Removing log statements {#removing-log-statements} + +Sometimes, you may want to remove all log statements from your program, +either for speed purposes or to remove sensitive information. This can easily +be accomplished at build-time when using the standard `LOG4CXX_[level]` macros +(`LOG4CXX_TRACE`, `LOG4CXX_DEBUG`, `LOG4CXX_INFO`, `LOG4CXX_WARN`, +`LOG4CXX_ERROR`, `LOG4CXX_FATAL`). + +Log statements can be removed either above a certain level, or they +can be disabled entirely. + +For example, if we want to remove all log statements within our program +that use the `LOG4CXX_[level]` family of macros, add a preprocessor +definition `LOG4CXX_THRESHOLD` set to 50001 +or greater. This will ensure that any log statement that uses the +`LOG4CXX_[level]`-macro will be compiled out of the program. To remove +all log statements at `DEBUG` or below, set `LOG4CXX_THRESHOLD` to a +value between 10001-20000. + +The levels are set as follows: + +|Logger Level|Integer Value| +|------------|-------------| +|TRACE |5000 | +|DEBUG |10000 | +|INFO |20000 | +|WARN |30000 | +|ERROR(1) |40000 | +|FATAL |50000 | + +(1) The `LOG4CXX_ASSERT` macro is the same level as `LOG4CXX_ERROR` + +Note that this has no effect on other macros, such as using the +`LOG4CXX_LOG`, `LOG4CXX_LOGLS`, or `LOG4CXX_L7DLOG` family of macros. + +# Logging Custom Types {#custom-types} + +Often, the data that needs to be logged is not just standard data types +(such as int, string, etc), but amalgamations of those types in a data +structure such as a class or struct. In order to log these custom types, +simply override an `operator<<` function, the same as if you would +print the custom type to `std::cout`. This can be accomplished by +doing the following: + +~~~{.cpp} +struct MyStruct { + int x; +}; + +std::ostream& operator<<( std::ostream& stream, const MyStruct& mystruct ){ + stream << "[MyStruct x:" << mystruct.x << "]"; + return stream; +} + +void someMethod(){ + MyStruct mine; + mine.x = 90; + LOG4CXX_INFO( logger, "Some important information: " << mine ); +} +~~~ + +This will output data similar to the following: + +~~~ +0 [0x7fd1eed63bc0] INFO root null - Some important information: [MyStruct x:90] +~~~ + +# Conclusions {#conclusions} + +Apache Log4cxx is a popular logging package written in C++. One of its +distinctive features is the notion of inheritance in loggers. Using a +logger hierarchy it is possible to control which log statements are +output at arbitrary granularity. This helps reduce the volume of logged +output and minimize the cost of logging. + +One of the advantages of the log4cxx API is its manageability. Once the +log statements have been inserted into the code, they can be controlled +with configuration files. They can be selectively enabled or disabled, +and sent to different and multiple output targets in user-chosen +formats. The log4cxx package is designed so that log statements can +remain in shipped code without incurring a heavy performance cost. diff --git a/src/site/xdoc/usage.xml b/src/site/xdoc/usage.xml deleted file mode 100644 index ad272ca26..000000000 --- a/src/site/xdoc/usage.xml +++ /dev/null @@ -1,1062 +0,0 @@ - - - - How to use Apache log4cxx - - - -
-

- Log4cxx has three main components: loggers, - appenders and layouts. These three types of - components work together to enable developers to log messages according - to message type and level, and to control at runtime how these - messages are formatted and where they are reported. -

- - -

- The first and foremost advantage of any logging API over plain - std::cout resides in its ability to disable - certain log statements while allowing others to print unhindered. This - capability assumes that the logging space, that is, the space of all - possible logging statements, is categorized according to some - developer-chosen criteria. -

- -

- Loggers are named entities. Logger names are case-sensitive and - they follow the hierarchical naming rule: -

- -
-
Named Hierarchy
-
- A logger is said to be an ancestor of another - logger if its name followed by a dot is a prefix of the - descendant logger name. A logger is said to be a - parent of a child logger if there are no - ancestors between itself and the descendant logger. -
-
- -

- For example, the logger named "com.foo" is a parent - of the logger named "com.foo.Bar". Similarly, - "java" is a parent of "java.util" and an - ancestor of "java.util.Vector". This naming scheme - should be familiar to most developers. -

- -

- The root logger resides at the top of the logger hierarchy. It - is exceptional in two ways: -

- -
    -
  1. it always exists,
    2. -
  2. it cannot be retrieved by name.
    3. -
- -

- Invoking the class static log4cxx::Logger::getRootLogger - method retrieves it. All other loggers are instantiated and retrieved with the class static - log4cxx::Logger::getLogger - method. This method takes the name of the desired logger as a parameter. Some of the basic methods in the Logger - class are listed below. -

- - 
-namespace log4cxx {
-	class Logger {
-		public:
-			// Creation & retrieval methods:
-			static LoggerPtr getRootLogger();
-			static LoggerPtr getLogger(const std::string& name);
-			static LoggerPtr getLogger(const std::wstring& name);
-	}
-}
-
-//
-// Use these macros instead of calling Logger methods directly.
-// Macros will handle char or wchar_t pointers or strings
-// or most right-hand side expressions of an
-// std::basic_string::operator<<.
-//
-#define LOG4CXX_TRACE(logger, expression) ...
-#define LOG4CXX_DEBUG(logger, expression) ...
-#define LOG4CXX_INFO(logger, expression) ...
-#define LOG4CXX_WARN(logger, expression) ...
-#define LOG4CXX_ERROR(logger, expression) ...
-#define LOG4CXX_FATAL(logger, expression) ...
- - - -

- Loggers may be assigned levels. The pre-defined - levels: TRACE, DEBUG, INFO, WARN, ERROR and FATAL are defined in the - log4cxx::Level - class which provides accessor functions. -

- -

- If a given logger is not assigned a level, then it inherits - one from its closest ancestor with an assigned level. More - formally: -

- -
-
Level Inheritance
- -
- The inherited level for a given logger C, is equal to the - first non-null level in the logger hierarchy, starting at C and - proceeding upwards in the hierarchy towards the root logger. -
-
- -

- To ensure that all loggers can eventually inherit a level, - the root logger always has an assigned level. -

- -

- Below are four tables with various assigned level values and the - resulting inherited levels according to the above rule. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger nameAssigned levelInherited level
rootProotProot
X noneProot
X.Y noneProot
X.Y.ZnoneProot
Example 1
- -

- In example 1 above, only the root logger is assigned a - level. This level value, Proot, is inherited by the - other loggers X, X.Y and - X.Y.Z. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger nameAssigned levelInherited level
rootProotProot
X PxPx
X.Y PxyPxy
X.Y.ZPxyzPxyz
Example 2
- -

- In example 2, all loggers have an assigned level value. There - is no need for level inheritence. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger nameAssigned levelInherited level
rootProotProot
X PxPx
X.Y nonePx
X.Y.ZPxyzPxyz
Example 3
- -

- In example 3, the loggers root, X and - X.Y.Z are assigned the levels Proot, - Px and Pxyz respectively. The logger - X.Y inherits its level value from its parent - X. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger nameAssigned levelInherited level
rootProotProot
X PxPx
X.Y nonePx
X.Y.ZnonePx
Example 4
- -

- In example 4, the loggers root and X - and are assigned the levels Proot and Px - respectively. The loggers X.Y and X.Y.Z - inherits their level value from their nearest parent X - having an assigned level. -

- - - -

- Logging requests are made by invoking a method of - a logger instance, preferrably through the use of LOG4CXX_INFO or similar - macros which support short-circuiting if the threshold is not satisfied - and use of the insertion operator (<<) in the message parameter. -

- - 
-log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("com.foo"));
-const char* region = "World";
-LOG4CXX_INFO(logger, "Simple message text.")
-LOG4CXX_INFO(logger, "Hello, " << region)
-LOG4CXX_DEBUG(logger, L"Iteration " << i)
-LOG4CXX_DEBUG(logger, "e^10 = " << std::scientific << exp(10.0))
-//
-// Use a wchar_t first operand to force use of wchar_t based stream.
-//
-LOG4CXX_WARN(logger, L"" << i << L" is the number of the iteration.")
- -

- A logging request is said to be enabled if its level is - higher than or equal to the level of its logger. Otherwise, the - request is said to be disabled. A logger without an - assigned level will inherit one from the hierarchy. This rule is - summarized below. -

- -
-
Basic Selection Rule
- -
- A log request of level p in a logger with (either assigned or - inherited, whichever is appropriate) level q, is enabled if - p >= q. -
-
- -

- This rule is at the heart of log4cxx. It assumes that levels are - ordered. For the standard levels, we have TRACE < DEBUG < INFO - < WARN < ERROR < FATAL. -

- -

- Here is an example of this rule. -

- - 
-// get a logger instance named "com.foo"
-log4cxx::LoggerPtr  logger(log4cxx::Logger::getLogger("com.foo"));
-
-// Now set its level. Normally you do not need to set the
-// level of a logger programmatically. This is usually done
-// in configuration files.
-logger->setLevel(log4cxx::Level::getInfo());
-
-log4cxx::LoggerPtr barlogger(log4cxx::Logger::getLogger("com.foo.Bar"));
-
-// This request is enabled, because WARN >= INFO.
-LOG4CXX_WARN(logger, "Low fuel level.")
-
-// This request is disabled, because DEBUG < INFO.
-LOG4CXX_DEBUG(logger, "Starting search for nearest gas station.")
-
-// The logger instance barlogger, named "com.foo.Bar",
-// will inherit its level from the logger named
-// "com.foo" Thus, the following request is enabled
-// because INFO >= INFO.
-LOG4CXX_INFO(barlogger. "Located nearest gas station.")
-
-// This request is disabled, because DEBUG < INFO.
-LOG4CXX_DEBUG(barlogger, "Exiting gas station search")
- -

- Calling the getLogger method with the same name will - always return a reference to the exact same logger object. -

- -

- For example, in -

- - 
-log4cxx::LoggerPtr x = log4cxx::Logger::getLogger("wombat");
-log4cxx::LoggerPtr y = log4cxx::Logger::getLogger("wombat");
-

- x and y refer to exactly the same logger object. -

- -

- Thus, it is possible to configure a logger and then to retrieve - the same instance somewhere else in the code without passing around - references. In fundamental contradiction to biological parenthood, - where parents always preceed their children, log4cxx loggers can be - created and configured in any order. In particular, a "parent" - logger will find and link to its descendants even if it is - instantiated after them. -

- -

- Configuration of the log4cxx environment is typically done at - application initialization. The preferred way is by reading a - configuration file. This approach will be discussed shortly. -

- -

- Log4cxx makes it easy to name loggers by software - component. This can be accomplished by statically instantiating - a logger in each class, with the logger name equal to the fully - qualified name of the class. This is a useful and straightforward - method of defining loggers. As the log output bears the name of the - generating logger, this naming strategy makes it easy to identify - the origin of a log message. However, this is only one possible, - albeit common, strategy for naming loggers. Log4cxx does not restrict - the possible set of loggers. The developer is free to name the - loggers as desired. -

- -

- Nevertheless, naming loggers after the class where they are - located seems to be the best strategy known so far. -

- -
- -
-

- The ability to selectively enable or disable logging requests based - on their logger is only part of the picture. Log4cxx allows logging - requests to print to multiple destinations. In log4cxx speak, an output - destination is called an appender. Currently, appenders exist - for the console, - files, GUI - components, remote socket - servers, NT Event Loggers, and remote UNIX - Syslog - daemons. It is also possible to log asynchronously. -

- -

More than one appender can be attached to a logger.

- -

- The addAppender - method adds an appender to a given logger. - - - Each enabled logging request for a given logger will be forwarded to all the - appenders in that logger as well as the appenders higher in the hierarchy. - - In other words, appenders are inherited additively from the logger hierarchy. - For example, if a console appender is added to the root logger, then all enabled - logging requests will at least print on the console. If in addition a file appender - is added to a logger, say C, then enabled logging requests for C and - C's children will print on a file and on the console. It is possible - to override this default behavior so that appender accumulation is no longer additive - by setting the additivity flag to - false. -

- -

The rules governing appender additivity are summarized below.

- -
-
Appender Additivity
- -
- The output of a log statement of logger C will go to all the appenders - in C and its ancestors. This is the meaning of the term "appender - additivity". However, if an ancestor of logger C, say P, has the - additivity flag set to false, then C's output will be - directed to all the appenders in C and it's ancestors up to and - including P but, not the appenders in any of the ancestors of P. -

- Loggers have their additivity flag set to true by default. -
-
- -

The table below shows an example:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger Name Added AppendersAdditivity FlagOutput TargetsComment
rootA1not applicableA1 - The root logger is anonymous but can be accessed with the - log4cxx::Logger::getRootLogger() method. There is no default appender - attached to root. -
xA-x1, A-x2trueA1, A-x1, A-x2Appenders of "x" and root.
x.ynonetrueA1, A-x1, A-x2Appenders of "x" and root.
x.y.zA-xyz1trueA1, A-x1, A-x2, A-xyz1Appenders in "x.y.z", "x" and root.
securityA-sec - false - A-sec - No appender accumulation since the additivity flag is set to false. -
security.accessnonetrueA-sec - Only appenders of "security" because the additivity flag in "security" is - set to false. -
- -

- More often than not, users wish to customize not only the output - destination but also the output format. This is accomplished by - associating a layout with an appender. The layout is - responsible for formatting the logging request according to the user's - wishes, whereas an appender takes care of sending the formatted output - to its destination. -

- -

- The PatternLayout, part - of the standard log4cxx distribution, lets the user specify the output - format according to conversion patterns similar to the C language - printf function. -

- -

- For example, the PatternLayout with the conversion pattern "%r [%t] - %-5p %c - %m%n" will output something akin to: -

- - 
-176 [main] INFO org.foo.Bar - Located nearest gas station.
- -

- The first field is the number of milliseconds elapsed since the - start of the program. The second field is the thread making the log - request. The third field is the level of the log statement. The - fourth field is the name of the logger associated with the log - request. The text after the '-' is the message of the statement. -

-
- -
-

- Inserting log requests into the application code requires a fair - amount of planning and effort. Observation shows that approximately 4 - percent of code is dedicated to logging. Consequently, even moderately - sized applications will have thousands of logging statements embedded - within their code. Given their number, it becomes imperative to - manage these log statements without the need to modify them manually. -

- -

- The log4cxx environment is fully configurable programmatically. - However, it is far more flexible to configure log4cxx using - configuration files. Currently, configuration files can be written in - XML or in Java properties (key=value) format. -

- -

- Let us give a taste of how this is done with the help of an - imaginary application MyApp that uses log4cxx. -

- - 
-#include "com/foo/bar.h"
-using namespace com::foo;
-
-// include log4cxx header files.
-#include "log4cxx/logger.h"
-#include "log4cxx/basicconfigurator.h"
-#include "log4cxx/helpers/exception.h"
-
-using namespace log4cxx;
-using namespace log4cxx::helpers;
-
-LoggerPtr logger(Logger::getLogger("MyApp"));
-
-int main(int argc, char **argv)
-{
-	int result = EXIT_SUCCESS;
-	try
-	{
-		// Set up a simple configuration that logs on the console.
-		BasicConfigurator::configure();
-
-		LOG4CXX_INFO(logger, "Entering application.")
-		Bar bar;
-		bar.doIt();
-		LOG4CXX_INFO(logger, "Exiting application.")
-	}
-	catch(Exception&)
-	{
-		result = EXIT_FAILURE;
-	}
-
-	return result;
-}
- -

- MyApp begins by including log4cxx headers. It - then defines a static logger variable with the name MyApp - which happens to be the fully qualified name of the - class. -

- -

- MyApp uses the Bar class defined in header - file com/foo/bar.h. -

- - 
-// file com/foo/bar.h
-#include "log4cxx/logger.h"
-
-namespace com {
-	namespace foo {
-		class Bar {
-			static log4cxx::LoggerPtr logger;
-
-			public:
-				void doIt();
-		}
-	}
-}
- - 
-// file bar.cpp
-#include "com/foo/bar.h"
-
-using namespace com::foo;
-using namespace log4cxx;
-
-LoggerPtr Bar::logger(Logger::getLogger("com.foo.bar"));
-
-void Bar::doIt() {
-	LOG4CXX_DEBUG(logger, "Did it again!")
-}
- -

- The invocation of the BasicConfigurator::configure - method creates a rather simple log4cxx setup. This method is hardwired - to add to the root logger a - ConsoleAppender. The output will be formatted using a - PatternLayout set - to the pattern "%-4r [%t] %-5p %c %x - %m%n". -

- -

- Note that by default, the root logger is assigned to - Level::getDebug(). -

- -

- The output of MyApp is: -

- - 
-0    [12345] INFO  MyApp  - Entering application.
-36   [12345] DEBUG com.foo.Bar  - Did it again!
-51   [12345] INFO  MyApp  - Exiting application.
- -

- The previous example always outputs the same log information. - Fortunately, it is easy to modify MyApp so that the log - output can be controlled at run-time. Here is a slightly modified - version. -

- - 
-// file MyApp2.cpp
-
-#include "com/foo/bar.h"
-using namespace com::foo;
-
-// include log4cxx header files.
-#include "log4cxx/logger.h"
-#include "log4cxx/basicconfigurator.h"
-#include "log4cxx/propertyconfigurator.h"
-#include "log4cxx/helpers/exception.h"
-
-using namespace log4cxx;
-using namespace log4cxx::helpers;
-// Define a static logger variable so that it references the
-// Logger instance named "MyApp".
-LoggerPtr logger(Logger::getLogger("MyApp"));
-
-int main(int argc, char **argv)
-{
-	int result = EXIT_SUCCESS;
-	try
-	{
-		if (argc > 1)
-		{
-			// BasicConfigurator replaced with PropertyConfigurator.
-			PropertyConfigurator::configure(argv[1]);
-		}
-		else
-		{
-			BasicConfigurator::configure();
-		}
-
-		LOG4CXX_INFO(logger, "Entering application.")
-		Bar bar
-		bar.doIt();
-		LOG4CXX_INFO(logger, "Exiting application.")
-	}
-	catch(Exception&)
-	{
-		result = EXIT_FAILURE;
-	}
-
-	return result;
-}
- -

- This version of MyApp instructs - PropertyConfigurator to parse a configuration file and - set up logging accordingly. -

- -

- Here is a sample configuration file that results in exactly same - output as the previous BasicConfigurator based example. -

- - 
-# Set root logger level to DEBUG and its only appender to A1.
-log4j.rootLogger=DEBUG, A1
-
-# A1 is set to be a ConsoleAppender.
-log4j.appender.A1=org.apache.log4j.ConsoleAppender
-
-# A1 uses PatternLayout.
-log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
- -

- It can be noticed that the PropertyConfigurator file format is the same as log4j. -

- -

- Suppose we are no longer interested in seeing the output of any - component belonging to the com::foo package. The following - configuration file shows one possible way of achieving this. -

- - 
-log4j.rootLogger=DEBUG, A1
-log4j.appender.A1=org.apache.log4j.ConsoleAppender
-log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-
-# Print the date in ISO 8601 format
-log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
-
-# Print only messages of level WARN or above in the package com.foo.
-log4j.logger.com.foo=WARN
- -

- The output of MyApp configured with this file is shown below. -

- - 
-2000-09-07 14:07:41,508 [12345] INFO  MyApp - Entering application.
-2000-09-07 14:07:41,529 [12345] INFO  MyApp - Exiting application.
- -

- As the logger com.foo.Bar does not have an assigned - level, it inherits its level from com.foo, which - was set to WARN in the configuration file. The log statement from the - Bar::doIt method has the level DEBUG, lower than the - logger level WARN. Consequently, doIt() method's log - request is suppressed. -

- -

- Here is another configuration file that uses multiple appenders. -

- - 
-log4j.rootLogger=debug, stdout, R
-
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-
-# Pattern to output the caller's file name and line number.
-log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n
-
-log4j.appender.R=org.apache.log4j.RollingFileAppender
-log4j.appender.R.File=example.log
-
-log4j.appender.R.MaxFileSize=100KB
-# Keep one backup file
-log4j.appender.R.MaxBackupIndex=1
-
-log4j.appender.R.layout=org.apache.log4j.PatternLayout
-log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
- -

- Calling the enhanced MyApp with the this configuration file will - output the following on the console. -

- - 
-INFO [12345] (MyApp2.cpp:31) - Entering application.
-DEBUG [12345] (Bar.h:16) - Doing it again!
-INFO [12345] (MyApp2.cpp:34) - Exiting application.
- -

- In addition, as the root logger has been allocated a second - appender, output will also be directed to the example.log - file. This file will be rolled over when it reaches 100KB. When - roll-over occurs, the old version of example.log is - automatically moved to example.log.1. -

- -

- Note that to obtain these different logging behaviors we did not - need to recompile code. We could just as easily have logged to a UNIX - Syslog daemon, redirected all com.foo output to an NT - Event logger, or forwarded logging events to a remote log4cxx server, - which would log according to local server policy, for example by - forwarding the log event to a second log4cxx server. -

-
- -
-

- The log4cxx library does not make any assumptions about its - environment. In particular, there are no default log4cxx - appenders. Under certain well-defined circumstances however, the - static inializer of the Logger class will attempt to - automatically configure log4cxx. -

- -

- The exact default initialization algorithm is defined as follows: -

- -
    -
  1. -

    - Set the configurationOptionStr string variable to the value of the - LOG4CXX_CONFIGURATION environment variable if set, otherwise - the value of the log4j.configuration environment variable - if set, otherwise the first of the following file names which exist in the - current working directory, "log4cxx.xml", "log4cxx.properties", - "log4j.xml" and "log4j.properties". If configurationOptionStr has not been - set, then disable logging. -

    -
    2. -
  2. -

    - Unless a custom configurator is specified using the - LOG4CXX_CONFIGURATOR_CLASS or log4j.configuratorClass - environment variable, the PropertyConfigurator will be used to configure - log4cxx unless the file name ends with the ".xml" extension, - in which case the DOMConfigurator will be used. - If a custom configurator is specified, the environment variable - should contain a fully qualified class name of a class that - implements the Configurator interface. -

    -
    3. -
-
- -
-

- Most real-world systems have to deal with multiple clients - simultaneously. In a typical multithreaded implementation of such a - system, different threads will handle different clients. Logging is - especially well suited to trace and debug complex distributed - applications. A common approach to differentiate the logging output of - one client from another is to instantiate a new separate logger for - each client. This promotes the proliferation of loggers and - increases the management overhead of logging. -

- -

- A lighter technique is to uniquely stamp each log request initiated - from the same client interaction. Neil Harrison described this method - in the book "Patterns for Logging Diagnostic Messages," in Pattern - Languages of Program Design 3, edited by R. Martin, D. Riehle, - and F. Buschmann (Addison-Wesley, 1997). -

- -

- To uniquely stamp each request, the - user pushes contextual information into the NDC, the abbreviation of - Nested Diagnostic Context. The NDC class is shown below. -

- - 
-namespace log4cxx {
-	class NDC {
-		public:
-			// pushes the value on construction and pops on destruction.
-			NDC(const std::string& value);
-			NDC(const std::wstring& value);
-
-			// Remove the top of the context from the NDC.
-			static LogString pop();
-
-			// Add diagnostic context for the current thread.
-			static void push(const std::string& message);
-			static void push(const std::wstring& message);
-	}
-}
- -

- The NDC is managed per thread as a stack of contextual - information. Note that all methods of the log4cxx::NDC - class are static. Assuming that NDC printing is turned on, every time - a log request is made, the appropriate log4cxx component will include - the entire NDC stack for the current thread in the log - output. This is done without the intervention of the user, who is - responsible only for placing the correct information in the NDC by - using the push and pop methods at a few - well-defined points in the code. In contrast, the per-client logger - approach commands extensive changes in the code. -

- -

- To illustrate this point, let us take the example of a servlet - delivering content to numerous clients. The servlet can build the NDC - at the very beginning of the request before executing other code. The - contextual information can be the client's host name and other - information inherent to the request, typically information contained - in cookies. Hence, even if the servlet is serving multiple clients - simultaneously, the logs initiated by the same code, i.e. belonging to - the same logger, can still be distinguished because each client - request will have a different NDC stack. Contrast this with the - complexity of passing a freshly instantiated logger to all code - exercised during the client's request. -

- -

- Nevertheless, some sophisticated applications, such as virtual - hosting web servers, must log differently depending on the virtual - host context and also depending on the software component issuing the - request. Recent log4cxx releases support multiple hierarchy trees. This - enhancement allows each virtual host to possess its own copy of the - logger hierarchy. -

-
- -
-

- One of the often-cited arguments against logging is its - computational cost. This is a legitimate concern as even moderately - sized applications can generate thousands of log requests. Much - effort was spent measuring and tweaking logging performance. Log4cxx - claims to be fast and flexible: speed first, flexibility second. -

- -

- The user should be aware of the following performance issues. -

- -
    -
  1. -

    - Logging performance when logging is turned off. -

    - -

    - When logging is turned off entirely or just for a set - of levels, the cost of a log request consists of a method - invocation plus an integer comparison. The LOG4CXX_DEBUG and similar - macros suppress unnecessary expression evaluation if the - request is not enabled. -

    -
    2. - -
  2. -

    - The performance of deciding whether to log or not to log when logging is turned on. -

    - -

    - This is essentially the performance of walking the logger - hierarchy. When logging is turned on, log4cxx still needs to compare - the level of the log request with the level of the request - logger. However, loggers may not have an assigned - level; they can inherit them from the logger hierarchy. Thus, - before inheriting a level, the logger may need to search its - ancestors. -

    - -

    - There has been a serious effort to make this hierarchy walk to - be as fast as possible. For example, child loggers link only to - their existing ancestors. In the BasicConfigurator - example shown earlier, the logger named com.foo.Bar is - linked directly to the root logger, thereby circumventing the - nonexistent com or com.foo loggers. This - significantly improves the speed of the walk, especially in "sparse" - hierarchies. -

    - -

    - The cost of walking the hierarchy is typically 3 - times slower than when logging is turned off entirely. -

    -
    3. -
  3. -

    - Actually outputting log messages -

    - -

    - This is the cost of formatting the log output and sending it to - its target destination. Here again, a serious effort was made to - make layouts (formatters) perform as quickly as possible. The same - is true for appenders. -

    -
    4. -
-
- -
-

- Apache Log4cxx is a popular logging package written in C++. One of its - distinctive features is the notion of inheritance in loggers. Using - a logger hierarchy it is possible to control which log statements - are output at arbitrary granularity. This helps reduce the volume of - logged output and minimize the cost of logging. -

- -

- One of the advantages of the log4cxx API is its manageability. Once - the log statements have been inserted into the code, they can be - controlled with configuration files. They can be selectively enabled - or disabled, and sent to different and multiple output targets in - user-chosen formats. The log4cxx package is designed so that log - statements can remain in shipped code without incurring a heavy - performance cost. -

-
- - \ No newline at end of file