Documentation updates

.gitignore

@@ -7,6 +7,7 @@
 
 ar-lib
 config**
+!configuration-samples.md
 depcomp
 install-sh
 liblog4cxx.pc

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}")

src/CMakeLists.txt

@@ -13,3 +13,5 @@ if(BUILD_TESTING)
    add_subdirectory(test)
    add_subdirectory(examples/cpp)
 endif()
+
+add_subdirectory(site)

src/examples/cpp/CMakeLists.txt

@@ -1,8 +1,12 @@
-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)
     target_compile_definitions(${exampleName} PRIVATE ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
     target_include_directories(${exampleName} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
     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 )

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 <stdlib.h>
+#include <log4cxx/basicconfigurator.h>
+#include <log4cxx/helpers/object.h>
+#include <log4cxx/appenderskeleton.h>
+#include <log4cxx/helpers/stringhelper.h>
+#include <log4cxx/xml/domconfigurator.h>
+
+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" );
+}

src/examples/cpp/custom-appender.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+  <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+    <param name="Target" value="System.out"/>
+    <layout class="org.apache.log4j.PatternLayout">
+      <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n"/>
+    </layout>
+  </appender>
+
+  <appender name="NullAppender" class="NullWriterAppender">
+    <param name="SomeValue" value="Nothing"/>
+  </appender>
+
+  <root>
+     <priority value="info" />
+     <appender-ref ref="ConsoleAppender"/>
+  </root>
+
+  <logger name="NullLogger" additivity="false">
+     <appender-ref ref="NullAppender"/>
+  </logger>
+</log4j:configuration>

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()