README-log4cplus.tex

% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
  american,
]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math}
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
  \setmainfont[Ligatures={TeX, Common}]{TeX Gyre Pagella}
  \setmonofont[Ligatures={}]{DejaVu Sans Mono}
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\hypersetup{
  pdftitle={log4cplus README},
  pdflang={en-US},
  hidelinks,
  pdfcreator={LaTeX via pandoc}}
\urlstyle{same} % disable monospaced font for URLs
\usepackage[a4paper]{geometry}
\usepackage{listings}
\newcommand{\passthrough}[1]{#1}
\lstset{defaultdialect=[5.3]Lua}
\lstset{defaultdialect=[x86masm]Assembler}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
%%
%% latex-header.tex begin
%%

\usepackage{graphicx}
\usepackage{epstopdf}
\usepackage{anyfontsize}
\usepackage{amssymb}
\usepackage{newunicodechar}
\usepackage{fancyhdr}
\usepackage{listings}
\usepackage{accsupp}
\usepackage{MnSymbol}
\usepackage{textcomp}
\usepackage{upquote}
\usepackage{etoolbox}

%\setmainfont[Ligatures={TeX, Common}]{TeX Gyre Pagella}
%\setmonofont[Scale=MatchLowercase,Ligatures={NoCommon}]{DejaVu Sans Mono}
%\setromanfont{Georgia}
%\setsansfont{DejaVu Sans}

\newfontfamily\cjkfont{WenQuanYi Zen Hei}[]
\newfontfamily\devanagarifont{Noto Serif Devanagari}[]
\newfontfamily\tamilfont{Noto Serif Tamil}[]
\newfontfamily\cyrilicfont{PTSerif}[]

%% These unfortunately break too many things. PDF will have to be without
%% contributors' native names.
% \ifxetex
%   \usepackage{xeCJK}
%   \setCJKmainfont{WenQuanYi Zen Hei}
%   \setCJKmonofont{WenQuanYi Zen Hei Mono}
% \else
%   %% Adding senolig breaks compilation in the CJK support.
%   %\usepackage{selnolig}
%   \usepackage{luatexja-fontspec}
%   \setmainjfont{WenQuanYi Zen Hei}
% \fi

\pagestyle{fancy}
\chead{\raisebox{\baselineskip}{\includegraphics[width=1.5cm,keepaspectratio]{./docs/log4cplus}}}
\setlength{\headheight}{47.0pt}
\addtolength{\topmargin}{-4\baselineskip}

%\title{}
%\author[The author]{Václav Zeman}
%\institute{}
%\date{\today}


\urlstyle{same}

\AtBeginEnvironment{quote}{\slshape}

\newunicodechar{⊆}{$\subseteq$}
\newunicodechar{↔}{$\leftrightarrow$}

\newcommand{\noncopy}[1]{%
    \BeginAccSupp{method=escape,ActualText={}}%
    #1%
    \EndAccSupp{}%
}

\lstset{breaklines=true,
  basicstyle=\ttfamily,
  %upquote=true,
  literate={`}{{\BeginAccSupp{method=plain,ActualText=`}‵\EndAccSupp{}}}1
  {"}{{\BeginAccSupp{method=plain,ActualText="}"\EndAccSupp{}}}1
  {'}{{\BeginAccSupp{method=plain,ActualText='}'\EndAccSupp{}}}1,
  showstringspaces=false,
  numbers=left, numberstyle=\scriptsize\noncopy,
  prebreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\noncopy{\rhookswarrow}}}}}

%%
%% latex-header.tex end
%%
\ifxetex
  % Load polyglossia as late as possible: uses bidi with RTL langages (e.g. Hebrew, Arabic)
  \usepackage{polyglossia}
  \setmainlanguage[variant=american]{english}
\else
  \usepackage[shorthands=off,main=american]{babel}
\fi

\title{log4cplus README}
\date{}

\begin{document}
\maketitle

%%
%% latex-body.tex begin
%%

\begin{figure}[h!]
  \centering
  \includegraphics[width=25em,keepaspectratio]{./docs/log4cplus}
\end{figure}
\newpage

%%
%% latex-body.tex end
%%

{
\setcounter{tocdepth}{3}
\tableofcontents
}
\hypertarget{short-description}{%
\section{Short Description}\label{short-description}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is a
simple to use C++11 logging API providing thread--safe, flexible, and
arbitrarily granular control over log management and configuration. It
is modeled after the Java log4j API.

\hypertarget{latest-project-information}{%
\section{Latest Project Information}\label{latest-project-information}}

The latest up-to-date information for this project can be found at
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
SourceForge project pages or
\href{https://sourceforge.net/p/log4cplus/wiki/Home/}{log4cplus wiki} on
SourceForge. Please submit bugs, patches, feature requests, etc., there,
or on \href{https://github.com/log4cplus/log4cplus}{GitHub}.

\hypertarget{mission-statement}{%
\section{Mission statement}\label{mission-statement}}

The aim of this project is to develop log4j--like logging framework for
use in (primarily) C++. One of the major design goals is to avoid huge
dependencies (like Boost) in the core functionality and to use standard
C++ facilities instead. Where possible, the project takes inspiration
from other logging libraries, beside from log4j (e.g., from log4net,
log4cxx, log4cpp).

\hypertarget{platform-support}{%
\section{Platform support}\label{platform-support}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} version
2.0 and beyond require C++11.
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} has been
ported to and tested on the following platforms:

\begin{itemize}
\tightlist
\item
  Linux/AMD64 with GCC version 6.2.0 20161005 (Ubuntu 6.2.0-5ubuntu12)
\item
  Linux/AMD64 with Clang version 3.8.1-12ubuntu1
  (tags/RELEASE\_381/final)
\item
  Windows/AMD64 with GCC version 4.8.2 (x86\_64-posix-seh-rev3, Built by
  MinGW-W64 project) using CMake build system
\item
  Windows/AMD64 with GCC version 4.9.2 (tdm64-1) using CMake build
  system
\item
  Windows 7 with MS Visual Studio 2015
\item
  OpenBSD 5.6/AMD64 with GCC version 4.9.0
\item
  FreeBSD 10.1/i386 with Clang version 3.4.1
  (tags/RELEASE\_34/dot1-final 208032)
\item
  NetBSD 6.1.5/AMD64 with GCC version 4.9.1
\item
  DragonflyBSD 4.0.1/AMD64 with GCC version 4.9.3 20141126 (prerelease)
  (FreeBSD Ports Collection)
\item
  OpenIndiana Hipster 2016.10 with GCC version 4.9.4
\end{itemize}

The testing on the above listed platforms has been done at some point in
time with some version of source. Continuous testing is done only on
Linux platform offered by
\href{https://sourceforge.net/p/log4cplus/travis-ci/}{Travis CI}
service.

The oldest Windows version that is supported by 2.x releases is Windows
Vista.

The following platforms were supported by the 1.x series of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}. They
either do not have a reasonable C++11 capable compiler or have not been
checked with
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} 2.x, yet:

\begin{itemize}
\tightlist
\item
  Minix 3.3.0/i386 with Clang version 3.4 (branches/release\_34) with
  \passthrough{\lstinline!--disable-threads!}
\item
  Linux/AMD64 with Intel Parallel Studio XE 2015, ICPC version 15.0.1
\item
  OpenSolaris with \passthrough{\lstinline!-library=stlport4!}
\item
  Solaris with \passthrough{\lstinline!-library=stlport4!} and with
  \passthrough{\lstinline!-library=Cstd!}.
\item
  Solaris 5.10/Sparc
\item
  MacOS X 10.8
\item
  MacOS X 11.4.2
\item
  HP-UX (hppa2.0w-hp-hpux11.11)
\item
  Haiku R1 Alpha 4.1
\item
  AIX 5.3 with IBM XL C/C++ for AIX
\end{itemize}

\hypertarget{installation-instruction}{%
\section{Installation instruction}\label{installation-instruction}}

Generic Autotools installation instructions are in
\passthrough{\lstinline!INSTALL!} file. The following are
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} specific
instructions.

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} uses Git
sub-modules. Always use \passthrough{\lstinline!--recurse-submodules!}
option when doing \passthrough{\lstinline!git clone!}.

\hypertarget{configure-script-options}{%
\section{Configure script options}\label{configure-script-options}}

\hypertarget{enable-debugging}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-debugging}}{-\/-enable-debugging}}\label{enable-debugging}}

This option is disabled by default. This option mainly affects GCC
builds but it also has some limited effect on non-GCC builds. It turns
on debugging information generation, undefines
\passthrough{\lstinline!NDEBUG!} symbol and adds
\passthrough{\lstinline!-fstack-check!} (GCC).

\hypertarget{enable-warnings}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-warnings}}{-\/-enable-warnings}}\label{enable-warnings}}

This option is enabled by default. It adds platform / compiler dependent
warning options to compiler command line.

\hypertarget{enable-so-version}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-so-version}}{-\/-enable-so-version}}\label{enable-so-version}}

This option is enabled by default. It enables SO version decoration on
resulting library file, e.g., the \passthrough{\lstinline!.2.0.0!} in
\passthrough{\lstinline!liblog4cplus-1.2.so.2.0.0!}.

\hypertarget{enable-release-version}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-release-version}}{-\/-enable-release-version}}\label{enable-release-version}}

This option is enabled by default. It enables release version decoration
on the resulting library file, e.g., the \passthrough{\lstinline!-1.2!}
in \passthrough{\lstinline!liblog4cplus-1.2.so.2.0.0!}.

\hypertarget{enable-symbols-visibility-options}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-symbols-visibility-options}}{-\/-enable-symbols-visibility-options}}\label{enable-symbols-visibility-options}}

This option is enabled by default. It enables use of compiler and
platform specific option for symbols visibility. See also the
\href{http://gcc.gnu.org/wiki/Visibility}{Visibility} page on GCC Wiki.

\hypertarget{enable-profiling}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-profiling}}{-\/-enable-profiling}}\label{enable-profiling}}

This option is disabled by default. This option adds profiling
information generation compiler option \passthrough{\lstinline!-pg!} to
GCC and Sun CC / Solaris Studio builds.

\hypertarget{enable-threads}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-threads}}{-\/-enable-threads}}\label{enable-threads}}

This option is enabled by default. It turns on detection of necessary
compiler and linker flags that enable POSIX threading support.

While this detection usually works well, some platforms still need help
with configuration by supplying additional flags to the
\passthrough{\lstinline!configure!} script. One of the know deficiencies
is Solaris Studio on Linux. See one of the later note for details.

\hypertarget{with-wchar_t-support}{%
\subsection{\texorpdfstring{\texttt{-\/-with-wchar\_t-support}}{-\/-with-wchar\_t-support}}\label{with-wchar_t-support}}

This option is enabled by default. When enabled, additional binaries
will be built, marked with \passthrough{\lstinline!U!} suffix in file
name and compiled with \passthrough{\lstinline!-DUNICODE=1!} flag. In
effect, these binaries assume that
\passthrough{\lstinline!log4cplus::tchar!} is
\passthrough{\lstinline!wchar\_t!}.

\hypertarget{with-working-locale}{%
\subsection{\texorpdfstring{\texttt{-\/-with-working-locale}}{-\/-with-working-locale}}\label{with-working-locale}}

This is one of three locale and
\passthrough{\lstinline!wchar\_t!}↔\passthrough{\lstinline!char!}
conversion related options. It is disabled by default.

It is know to work well with GCC on Linux. Other platforms generally
have lesser locale support in their implementations of the C++ standard
library. It is known not to work well on any BSDs.

See also docs/unicode.txt.

\hypertarget{with-working-c-locale}{%
\subsection{\texorpdfstring{\texttt{-\/-with-working-c-locale}}{-\/-with-working-c-locale}}\label{with-working-c-locale}}

This is second of
\passthrough{\lstinline!wchar\_t!}↔\passthrough{\lstinline!char!}
conversion related options. It is disabled by default.

It is known to work well on most Unix--like platforms, including recent
Cygwin.

\hypertarget{with-iconv}{%
\subsection{\texorpdfstring{\texttt{-\/-with-iconv}}{-\/-with-iconv}}\label{with-iconv}}

This is third of
\passthrough{\lstinline!wchar\_t!}↔\passthrough{\lstinline!char!}
conversion related options. It is disabled by default.

The conversion using iconv() function always uses
\passthrough{\lstinline!"UTF-8"!} and
\passthrough{\lstinline!"WCHAR\_T"!} as source/target encoding. It is
known to work well on platforms with GNU iconv. Different
implementations of \passthrough{\lstinline!iconv()!} might not support
\passthrough{\lstinline!"WCHAR\_T"!} encoding selector.

Either system provided \passthrough{\lstinline!iconv()!} or library
provided \passthrough{\lstinline!libiconv()!} are detected and accepted.
Also both SUSv3 and GNU \passthrough{\lstinline!iconv()!} function
signatures are accepted.

\hypertarget{with-qt}{%
\subsection{\texorpdfstring{\texttt{-\/-with-qt}}{-\/-with-qt}}\label{with-qt}}

This option is disabled by default. It enables compilation of a separate
shared library (liblog4cplusqt4debugappender) that implements
\passthrough{\lstinline!Qt4DebugAppender!}. It requires Qt4 and
pkg-config to be installed.

\hypertarget{enable-tests}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-tests}}{-\/-enable-tests}}\label{enable-tests}}

This option is enabled by default. It enables compilation of test
executables.

\hypertarget{enable-unit-tests}{%
\subsection{\texorpdfstring{\texttt{-\/-enable-unit-tests}}{-\/-enable-unit-tests}}\label{enable-unit-tests}}

This option is disabled by default. It enables compilation of unit tests
along their units. These unit tests then can be executed through
\passthrough{\lstinline!unit\_tests!} test executable that is built
during compilation.

\hypertarget{notes}{%
\section{Notes}\label{notes}}

\hypertarget{compilation}{%
\subsection{Compilation}\label{compilation}}

On Unix--like platforms,
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} can be
compiled using either autotools based build system or using CMake build
system. The autotools based build system is considered to be primary for
Unix--like platforms.

On Windows, the primary build system is Visual Studio 2015 solution and
projects (\passthrough{\lstinline!msvc14/log4cplus.sln!}).

MinGW is supported by autotools based build system. CMake build system
is supported as well and it should be used to compile
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} with older
versions of Visual Studio or with less common compiler suites (e.g.,
Embarcadero, Code::Blocks, etc.).

\hypertarget{cygwin}{%
\subsection{Cygwin}\label{cygwin}}

Cygwin 2.5.x has a problem\footnote{\url{https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64697}}
linking binaries that use language level thread-local storage and share
thread-local variables across translation units. To avoid the issue
language level thread-local storage is not used on Cygwin and
traditional POSIX thread-local storage is used instead.

\hypertarget{mingw-and-msvcrt-version}{%
\subsection{MinGW and MSVCRT version}\label{mingw-and-msvcrt-version}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} can use
functions like \passthrough{\lstinline!\_vsnprintf\_s()!} (Microsoft's
secure version of \passthrough{\lstinline!vsnprintf()!}). MinGW
tool--chains (by default) link to the system
\passthrough{\lstinline!MSVCRT.DLL!}. Unfortunately, older systems, like
Windows XP, ship with \passthrough{\lstinline!MSVCRT.DLL!} that lacks
these functions. It is possible to compile
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} with MinGW
tool--chains but \emph{without} using Microsoft's secure functions by
defining \passthrough{\lstinline!\_\_MSVCRT\_VERSION\_\_!} to value less
than \passthrough{\lstinline!0x900!} and vice versa.

\begin{lstlisting}
$ ../configure CPPFLAGS="-D__MSVCRT_VERSION__=0x700"
\end{lstlisting}

\hypertarget{windows-and-visual-studio}{%
\subsection{Windows and Visual Studio}\label{windows-and-visual-studio}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} uses C++11
thread and synchronization facilities. The synchronization facilities
are implemented in Visual Studio C++ standard library in a way that
utilizes global variables. Therefore it is impossible (due to ``static
initialization order fiasco'') to use them outside
\passthrough{\lstinline!main()!}. This issue manifests as a deadlock on
exit during destruction of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}' thread
pool.

To overcome this limitation,

\begin{itemize}
\item
  always use
  \passthrough{\lstinline!log4cplus::Initializer initializer;!} as the
  first thing in \passthrough{\lstinline!main()!};
\item
  never try to log from static/global objects constructors;
\item
  never try to log from static/global object destructors.
\end{itemize}

Defining the \passthrough{\lstinline!log4cplus::Initializer!} instance
as the first thing in \passthrough{\lstinline!main()!} ensures that
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is
initialized. More importantly, it ensures that
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} shuts down
before the execution leaves the \passthrough{\lstinline!main()!}
function. \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
will try to automatically initialize at process startup and/or on DLL
load, and will not tear down until all
\passthrough{\lstinline!log4cplus:Initializer!} instances are destroyed.

\hypertarget{windows-and-rolling-file-appenders}{%
\subsection{Windows and rolling file
Appenders}\label{windows-and-rolling-file-appenders}}

On Windows, the standard C++ file streams open files in way that
underlying Win32 file \passthrough{\lstinline!HANDLE!} is not open with
\passthrough{\lstinline!FILE\_SHARE\_DELETE!} flag. This flag, beside
shared delete, allows renaming files that have handles open to them.
This issue manifests as error code 13 when the file needs to be rolled
over and it is still open by another process.

This is also \href{https://sourceforge.net/p/log4cplus/bugs/167/}{bug
\#167} on SourceForge.

\hypertarget{windows-and-tls}{%
\subsection{Windows and TLS}\label{windows-and-tls}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} uses
thread--local storage (TLS) for NDC, MDC and to optimize use of some
temporary objects. On Windows there are two ways to get TLS:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  using \passthrough{\lstinline!TlsAlloc()!}, etc., functions
\item
  using \passthrough{\lstinline!\_\_declspec(thread)!}
\end{enumerate}

While method (2) generates faster code, it has
\href{http://support.microsoft.com/kb/118816/en-us}{some limitations
prior to Windows Vista}. If \passthrough{\lstinline!log4cplus.dll!} is
loaded at run time using \passthrough{\lstinline!LoadLibrary()!} (or as
a dependency of such loaded library), then accessing
\passthrough{\lstinline!\_\_declspec(thread)!} variables can cause
general protection fault (GPF) errors. This is because Windows prior to
Windows Vista do not extend the TLS for libraries loaded at run time
using \passthrough{\lstinline!LoadLibrary()!}. To allow using the best
available method,
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} enables
the method (2) by checking
\passthrough{\lstinline!\_WIN32\_WINNT >= 0x0600!} condition, when
compiling \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
targeted to Windows Vista or later.

\hypertarget{linking-on-windows}{%
\subsection{Linking on Windows}\label{linking-on-windows}}

If you are linking your application with DLL variant of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}, define
\passthrough{\lstinline!LOG4CPLUS\_BUILD\_DLL!} preprocessor symbol.
This changes definition of \passthrough{\lstinline!LOG4CPLUS\_EXPORT!}
symbol to \passthrough{\lstinline!\_\_declspec(dllimport)!}.

\hypertarget{android-tls-and-cmake}{%
\subsection{Android, TLS and CMake}\label{android-tls-and-cmake}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} uses
thread--local storage (TLS, see ``Windows and TLS'' for details). On the
Android platform, when
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is being
compiled using the
\passthrough{\lstinline!android/android.toolchain.cmake!}, you might get
errors featuring the \passthrough{\lstinline!\_\_emutls!} symbol:

\begin{lstlisting}
global-init.cxx:268:46: error: log4cplus::internal::__emutls_t._ZN9log4cplus8internal3ptdE causes a section type conflict with log4cplus::internal::ptd
\end{lstlisting}

To work around this issue, invoke CMake with
\passthrough{\lstinline!-DANDROID\_FUNCTION\_LEVEL\_LINKING:BOOL=OFF!}
option.

\hypertarget{threads-and-signals}{%
\subsection{Threads and signals}\label{threads-and-signals}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is not
safe to be used from asynchronous signals' handlers. This is a property
of most threaded programmes in general. If you are going to use
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} in
threaded application and if you want to use
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} from
signal handlers then your only option is to block signals in all threads
but one that will handle all signals. On POSIX platforms, this is
possible using the \passthrough{\lstinline!sigwait()!} call.
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} enables
this approach by blocking all signals in any threads created through its
threads helpers.

\hypertarget{ibms-xl-cc-compiler}{%
\subsection{IBM's XL C/C++ compiler}\label{ibms-xl-cc-compiler}}

IBM's XL C/C++ compiler executable has
\href{http://www.ibm.com/support/knowledgecenter/en/SSGH3R_12.1.0/com.ibm.xlcpp121.aix.doc/compiler_ref/tucmpinv.html}{many
variants}. To compile
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} with
threading support specify one of the compiler variants that support
threading using the \passthrough{\lstinline!CXX!} variable on
\passthrough{\lstinline!configure!} script command line. E.g.:

\begin{lstlisting}
$ ../configure --enable-threads CXX=xlC_r
\end{lstlisting}

\hypertarget{aix-reentrancy-problem}{%
\subsection{AIX reentrancy problem}\label{aix-reentrancy-problem}}

There appears to be a reentracy problem with AIX 5.3 and xlC 8 which can
result into a deadlock condition in some circumstances. It is unknown
whether the problem manifests with other versions of either the OS or
the compiler, too. The problem was initially reported in a bug report
\href{http://sourceforge.net/p/log4cplus/bugs/103/}{\#103}.

The core of the problem is that IBM's/xlC's standard C++ IOStreams
implementation uses global non recursive lock to protect some of its
state. The application in the bug report was trying to do logging using
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} from
inside \passthrough{\lstinline!overflow()!} member function of a class
derived from \passthrough{\lstinline!std::streambuf!} class.
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} itself
uses \passthrough{\lstinline!std::ostringstream!}. This resulted into an
attempt to recursively lock the global non recursive lock and a
deadlock.

\hypertarget{solaris-sunos}{%
\subsection{Solaris / SunOS}\label{solaris-sunos}}

Some older version of this operating system might have problems linking
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} due to
\href{https://groups.google.com/d/msg/comp.unix.solaris/AAMqkK0QZ6U/zlkVKA1L_QcJ}{missing
\passthrough{\lstinline!\_\_tls\_get\_addr!}} in their unpatched state.

\hypertarget{solaris-studio}{%
\subsection{Solaris Studio}\label{solaris-studio}}

Solaris Studio compilers' default standard C++ library is very
non-standard. It seems that it is not conforming enough in, e.g., Sun
C++ 5.12 Linux\_i386 2011/11/16 (missing
\passthrough{\lstinline!std::time\_t!}, etc.), but it works well enough
on Solaris with Sun C++ 5.8 2005/10/13. Thus
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} adds
\passthrough{\lstinline!-library=stlport4!} to the
\passthrough{\lstinline!CXXFLAGS!} environment variable, unless a switch
matching \passthrough{\lstinline!-library=(stlport4|stdcxx4|Cstd)!} is
already present there. If you want to override the default supplied by
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}, just set
it into \passthrough{\lstinline!CXXFLAGS!} on
\passthrough{\lstinline!configure!} script command line.

Solaris Studio supports the \passthrough{\lstinline!\_\_func\_\_!}
symbol which can be used by
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} to record
function name in logged events. To enable this feature, add
\passthrough{\lstinline!-features=extensions!} switch to
\passthrough{\lstinline!CXXFLAGS!} for
\passthrough{\lstinline!configure!} script. Subsequently, you will have
to add this switch to your application's build flags as well.

\hypertarget{solaris-studio-on-gnulinux}{%
\subsection{Solaris Studio on
GNU/Linux}\label{solaris-studio-on-gnulinux}}

The autotools and our \passthrough{\lstinline!configure.ac!} combo does
not handle Solaris Studio compiler on Linux well enough and needs a
little help with configuration of POSIX threads:

\begin{lstlisting}[language=bash]
$ COMMON_FLAGS="-L/lib/x86_64-linux-gnu/ \
-L/usr/lib/x86_64-linux-gnu/ -mt=yes -O"

$ ../configure --enable-threads=yes \
CC=/opt/solarisstudio12.3/bin/cc \
CXX=/opt/solarisstudio12.3/bin/CC \
CFLAGS="$COMMON_FLAGS" \
CXXFLAGS="$COMMON_FLAGS" \
LDFLAGS="-lpthread"
\end{lstlisting}

\hypertarget{hp-ux-with-acc}{%
\subsection{\texorpdfstring{HP-UX with
\texttt{aCC}}{HP-UX with aCC}}\label{hp-ux-with-acc}}

It is necessary to turn on C++98 mode of \passthrough{\lstinline!aCC!}
by providing the \passthrough{\lstinline!-AA!} flag:

\begin{lstlisting}
$ ../configure --enable-threads=yes CXXFLAGS="-AA"
\end{lstlisting}

\hypertarget{hp-ux-with-acc-on-ia64}{%
\subsection{\texorpdfstring{HP-UX with \texttt{aCC} on
IA64}{HP-UX with aCC on IA64}}\label{hp-ux-with-acc-on-ia64}}

There is a problem on IA64 HP-UX with \passthrough{\lstinline!aCC!} (HP
C/aC++ B3910B A.06.20). The problem manifests as
\href{http://h30499.www3.hp.com/t5/Languages-and-Scripting/Building-Log4cplus-fails-with-quot-ld-Unsatisfied-symbol-virtual/td-p/6261411\#.UoHtgPmet8G}{unsatisfied
symbols during linking of \passthrough{\lstinline!loggingserver!}}:

\begin{lstlisting}
ld: Unsatisfied symbol "virtual table of loggingserver::ClientThread" in file loggingserver.o
\end{lstlisting}

The problem appears to be a deficiency in \passthrough{\lstinline!aCC!}
and its support of \passthrough{\lstinline!\_\_declspec(dllexport)!}. To
work around this issue, add
\passthrough{\lstinline!--disable-symbols-visibility-options!} to
\passthrough{\lstinline!configure!} script command line:

\begin{lstlisting}
$ ../configure --disable-symbols-visibility-options \
--enable-threads=yes CXXFLAGS="-AA"
\end{lstlisting}

\hypertarget{haiku}{%
\subsection{Haiku}\label{haiku}}

Haiku is supported with GCC 4+. The default GCC version in Haiku is set
to version 2 (based on GCC 2.95.x). To change the default GCC version to
version 4, please run \passthrough{\lstinline!setgcc gcc4!} command.
This is to avoid linking errors like this:

\begin{lstlisting}
main.cpp:(.text.startup+0x54a): undefined reference to `_Unwind_Resume'
\end{lstlisting}

Running the command switches the \emph{current} GCC version to version
4. This change is permanent and global. See also Haiku ticket
\href{http://dev.haiku-os.org/ticket/8368}{\#8368}.

\hypertarget{qt4-win32-msvc}{%
\subsection{Qt4 / Win32 / MSVC}\label{qt4-win32-msvc}}

In order to use
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} in Qt4
programs it is necessary to set following option:
\passthrough{\lstinline!Treat WChar\_t As Built in Type: No (/Zc:wchar\_t-)!}

Set this option for
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} project
and \passthrough{\lstinline!Qt4DebugAppender!} project in MS Visual
Studio. Remember to use Unicode versions of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} libraries
with Qt. It is also necessary to make clear distinction between debug
and release builds of Qt project and
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}. Do not
use \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
release library with debug version of Qt program and vice versa.

For registering Qt4DebugAppender library at runtime, call this function:
\passthrough{\lstinline!log4cplus::Qt4DebugAppender::registerAppender()!}

Add these lines to qmake project file for using
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} and
\passthrough{\lstinline!Qt4DebugAppender!}:

\begin{lstlisting}
INCLUDEPATH += C:\log4cplus\include
win32 {
    CONFIG(debug, debug|release) {
        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplusUD
        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplus-Qt4DebugAppender
    } else {
        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplusU
        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplus-Qt4DebugAppender
    }
}
\end{lstlisting}

\hypertarget{qt-gcc}{%
\subsection{Qt / GCC}\label{qt-gcc}}

You might encounter the following error during compilation with
\passthrough{\lstinline!--with-qt!} option:

\begin{lstlisting}
qglobal.h:943: error: ISO C++ does not support 'long long'
\end{lstlisting}

This is caused by \passthrough{\lstinline!-pedantic!} option that
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} adds to
\passthrough{\lstinline!CXXFLAGS!} when compiling with GCC. To work
around this issue, add \passthrough{\lstinline!-Wno-long-long!} GCC
option to \passthrough{\lstinline!CXXFLAGS!}.

\hypertarget{openbsd}{%
\subsection{OpenBSD}\label{openbsd}}

OpenBSD 5.2 and earlier have a bug in
\passthrough{\lstinline!wcsftime()!} function in handling of
\passthrough{\lstinline!\%\%!} and \passthrough{\lstinline!\%N!} where N
is not a supported formatter. This is fixed in OpenBSD 5.3 and later.
This shows as failing \passthrough{\lstinline!timeformat\_test!} when
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is
compiled with \passthrough{\lstinline!-DUNICODE!} in
\passthrough{\lstinline!CXXFLAGS!}.

\hypertarget{ios-support}{%
\subsection{iOS support}\label{ios-support}}

iOS support is based on CMake build. Use the scripts in
\passthrough{\lstinline!iOS!} directory. The
\passthrough{\lstinline!iOS.cmake!} toolchain file was originally taken
from \href{https://code.google.com/p/ios-cmake/}{ios-cmake} project.

To build the library for iOS, being in current folder, perform the steps
below. For ARMv7 architecture:

\begin{lstlisting}
$ ./scripts/cmake_ios_armv7.sh
$ cmake --build ./build_armv7 --config "Release"
$ cmake --build ./build_armv7 --config "Debug"
\end{lstlisting}

For i386 architecture:

\begin{lstlisting}
$ ./scripts/cmake_ios_i386.sh
$ cmake --build ./build_i386 --config "Release"
$ cmake --build ./build_i386 --config "Debug"
\end{lstlisting}

Some versions of the iOS and/or its SDK have problems with thread-local
storage (TLS) and getting through CMake's environment detection phase.
To work around these issues, make these changes:

Edit the \passthrough{\lstinline!iOS.cmake!} file and add these two
lines.

\begin{lstlisting}
set (CMAKE_CXX_COMPILER_WORKS TRUE)
set (CMAKE_C_COMPILER_WORKS TRUE)
\end{lstlisting}

Add these lines. Customize them accordingly:

\begin{lstlisting}
set(MACOSX_BUNDLE_GUI_IDENTIFIER com.example)
set(CMAKE_MACOSX_BUNDLE YES)
set(CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer")
set(IPHONEOS_ARCHS arm64)
\end{lstlisting}

If you have issues with TLS, also comment out these lines:

\begin{lstlisting}
set(LOG4CPLUS_HAVE_TLS_SUPPORT 1)
set(LOG4CPLUS_THREAD_LOCAL_VAR "__thread")
\end{lstlisting}

\hypertarget{log4cplus__fmt-and-unicode}{%
\subsection{\texorpdfstring{\texttt{LOG4CPLUS\_*\_FMT()} and
UNICODE}{LOG4CPLUS\_*\_FMT() and UNICODE}}\label{log4cplus__fmt-and-unicode}}

Beware, the \passthrough{\lstinline!\%s!} specifier does not work the
same way on Unix--like platforms as it does on Windows with Visual
Studio. With Visual Studio the \passthrough{\lstinline!\%s!} specifier
changes its meaning conveniently by printing
\passthrough{\lstinline!wchar\_t!} string when used with
\passthrough{\lstinline!wprintf()!} and \passthrough{\lstinline!char!}
strings when used with \passthrough{\lstinline!printf()!}. On the other
hand, Unix--like platforms keeps the meaning of printing
\passthrough{\lstinline!char!} strings when used with both
\passthrough{\lstinline!wprintf()!} and
\passthrough{\lstinline!printf()!}. It is necessary to use
\passthrough{\lstinline!\%ls!} (C99) specifier or
\passthrough{\lstinline!\%S!} (SUSv2) specifier to print
\passthrough{\lstinline!wchar\_t!} strings on Unix--like platforms.

The common ground for both platforms appears to be use of
\passthrough{\lstinline!\%ls!} and \passthrough{\lstinline!wchar\_t!}
string to print strings with unmodified formatting string argument on
both Unix--like platforms and Windows. The conversion of
\passthrough{\lstinline!wchar\_t!} back to
\passthrough{\lstinline!char!} then depends on C locale.

\hypertarget{unsupported-compilers-and-platforms}{%
\subsection{Unsupported compilers and
platforms}\label{unsupported-compilers-and-platforms}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} does not
support too old or broken C++ compilers. Since
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} version
2.0.0, it means it does not support any platform or compiler without
decent C++11 support.

\begin{itemize}
\tightlist
\item
  Visual Studio prior to 2015
\item
  GCC prior to 4.8
\end{itemize}

\hypertarget{bug-reporting-instructions}{%
\subsection{Bug reporting
instructions}\label{bug-reporting-instructions}}

For successful resolution of reported bugs, it is necessary to provide
enough information:

\begin{itemize}
\tightlist
\item
  \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}

  \begin{itemize}
  \tightlist
  \item
    What is the exact release version or Git branch and revision?
  \item
    What is the build system that you are building
    \href{https://sourceforge.net/projects/log4cplus/}{log4cplus} with
    (Autotools, Visual Studio solution and its version, CMake).
  \item
    Autotools -- Provide \passthrough{\lstinline!configure!} script
    parameters and environment variables, attach generated
    \passthrough{\lstinline!config.log!} and
    \passthrough{\lstinline!defines.hxx!} files.
  \item
    CMake -- Provide build configuration
    (\passthrough{\lstinline!Release!}, \passthrough{\lstinline!Debug!},
    \passthrough{\lstinline!RelWithDebInfo!}) and non--default
    \passthrough{\lstinline!CMAKE\_*!} variables values.
  \item
    Visual Studio -- Provide project configuration
    (\passthrough{\lstinline!Release!},
    \passthrough{\lstinline!Release\_Unicode!},
    \passthrough{\lstinline!Debug!},
    \passthrough{\lstinline!Debug\_Unicode!}) and Visual Studio version.
  \item
    Provide target OS and CPU. In case of MinGW, provide its exact
    compiler distribution -- TDM? Nuwen? Other?
  \end{itemize}
\item
  \href{https://sourceforge.net/projects/log4cplus/}{log4cplus} client
  application

  \begin{itemize}
  \tightlist
  \item
    Are you using shared library
    \href{https://sourceforge.net/projects/log4cplus/}{log4cplus} or as
    static library
    \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}?
  \item
    Is \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
    linked into an executable or into a shared library (DLL or SO)?
  \item
    If \href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is
    linked into a shared library, is this library loaded dynamically or
    not?
  \item
    What library file you are linking your application with --
    \passthrough{\lstinline!log4cplus.lib!},
    \passthrough{\lstinline!log4cplusUSD.lib!},
    \passthrough{\lstinline!liblog4cplus.dll.a!}, etc., on Windows?
  \item
    Is your application is using
    Unicode/\passthrough{\lstinline!wchar\_t!} or not?
  \item
    Provide any error messages.
  \item
    Provide stack trace.
  \item
    Provide
    \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
    properties/configuration files.
  \item
    Provide a self--contained test case, if possible.
  \end{itemize}
\end{itemize}

\hypertarget{license}{%
\section{License}\label{license}}

This library is licensed under the Apache Public License 2.0 and two
clause BSD license. Please read the included LICENSE file for details.

\hypertarget{contributions}{%
\section{Contributions}\label{contributions}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} (bug
tracker, files, wiki) is hosted on SourceForge, except for
\href{https://sourceforge.net/p/log4cplus/source-code-link/}{log4cplus
source}, which is hosted on GitHub. This allows the project to integrate
with \href{https://sourceforge.net/p/log4cplus/travis-ci/}{Travis CI}
service offered by GitHub.

\hypertarget{patches}{%
\subsection{Patches}\label{patches}}

Anybody can contribute to log4cplus development. If you are contributing
a source code change, use a reasonable form: a merge request of a Git
branch or a patch file attached to a ticket in
\href{https://sourceforge.net/p/log4cplus/bugs/}{Bugs tracker} or sent
to \href{mailto:log4cplus-devel@lists.sourceforge.net}{log4cplus-devel
mailing list}. Unless it is obvious, always state what branch or release
tarball is your patch based upon.

\hypertarget{formatting}{%
\subsection{Formatting}\label{formatting}}

Please use common sense. Follow the style of surrounding code. You can
use the following Emacs style that is based on Microsoft's style as a
guide line:

\begin{lstlisting}[language=Lisp]
;; Custom MS like indentation style.
(c-add-style "microsoft"
             '("stroustrup"
               (c-offsets-alist
                (innamespace . -)
                (inline-open . 0)
                (inher-cont . c-lineup-multi-inher)
                (arglist-cont-nonempty . +)
                (template-args-cont . +))))
\end{lstlisting}

\hypertarget{tools}{%
\subsection{Tools}\label{tools}}

\hypertarget{build-system}{%
\subsubsection{Build system}\label{build-system}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} supports
multiple build systems (GNU Autoconf/Automake/Libtool aka Autotools,
CMake and Visual Studio solution and project files).

Autotools is considered the primary build system on Unix--like
platforms. However, CMake should still be usable on Unix--like platforms
as well.

On Windows, it depends on compiler and tool-chain that you want to use.
When using Visual Studio, use Visual Studio solution and project files.
However, CMake build system should still work and produce useful
results. When using some form of MinGW64 tool-chain, the CMake build
system is considered primary and the Autotools based build system is
unsupported. Use the \passthrough{\lstinline!MinGW Makefiles!} option
and build with \passthrough{\lstinline!mingw-make!} (or similar). The
\passthrough{\lstinline!MSYS Makefiles!} option is untested and
unsupported.

\hypertarget{autotools}{%
\paragraph{Autotools}\label{autotools}}

The \passthrough{\lstinline!Makefile.am!} files for this build systems
are hand written. Some of them, however, are generated from
\passthrough{\lstinline!Makefile.am.tpl!} and
\passthrough{\lstinline!Makefile.am.def!} by
\href{http://www.gnu.org/software/autogen/}{GNU Autogen}. This is to
make adding new files to the source easier.

To regenerate \passthrough{\lstinline!Makefile.am!} files,
\passthrough{\lstinline!configure!} script,
\passthrough{\lstinline!testsuite!} script or any other part of the
Autotools build system, use the
\passthrough{\lstinline!scripts/doautoreconf.sh!} script from source
root directory. It will invoke all the necessary tools in the correct
order.

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} closely
follows Autoconf's, Automake's and Libtool's development and its master
branch files are always generated using the latest available version of
the tools.

\hypertarget{code-examples}{%
\section{Code Examples}\label{code-examples}}

\hypertarget{hello-world}{%
\subsection{Hello World}\label{hello-world}}

Here is a minimal
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} example
for \href{https://sourceforge.net/projects/log4cplus/}{log4cplus}
version 2.0 and later:

\begin{lstlisting}[language={C++}]
#include <log4cplus/logger.h>
#include <log4cplus/loggingmacros.h>
#include <log4cplus/configurator.h>
#include <log4cplus/initializer.h>

int
main()
{
    // Initialization and deinitialization.
    log4cplus::Initializer initializer;

    log4cplus::BasicConfigurator config;
    config.configure();

    log4cplus::Logger logger = log4cplus::Logger::getInstance(
        LOG4CPLUS_TEXT("main"));
    LOG4CPLUS_WARN(logger, LOG4CPLUS_TEXT("Hello, World!"));
    return 0;
}
\end{lstlisting}

The above code prints \passthrough{\lstinline"WARN - Hello, World!"} on
console. Let's dissect it:

\begin{lstlisting}[language={C++}]
#include <log4cplus/logger.h>
\end{lstlisting}

We need this header to get \passthrough{\lstinline!Logger!} class which
represents a handle to named logger.

\begin{lstlisting}[language={C++}]
#include <log4cplus/loggingmacros.h>
\end{lstlisting}

This header declares \passthrough{\lstinline!LOG4CPLUS\_WARN()!} logging
macro. Beside this one, it also declares one for each standard logging
level: FATAL, ERROR, WARN, INFO, DEBUG, TRACE.

\begin{lstlisting}[language={C++}]
#include <log4cplus/configurator.h>
\end{lstlisting}

This header declares \passthrough{\lstinline!BasicConfigurator!} class.

\begin{lstlisting}[language={C++}]
#include <log4cplus/initializer.h>
\end{lstlisting}

This header declares \passthrough{\lstinline!Initializer!} class.

\begin{lstlisting}[language={C++}]
log4cplus::Initializer initializer;
\end{lstlisting}

Instantiating the \passthrough{\lstinline!Initializer!} class internally
initializes
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus}.

The \passthrough{\lstinline!Initializer!} class also maintains a
reference count. The class can be instantiated multiple times. When this
reference count reaches zero, after the last instance of
\passthrough{\lstinline!Initializer!} is destroyed, it shuts down
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} internals.
Currently, after
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is
deinitialized, it cannot be re-initialized.

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} tries to
use some other methods of shutting down its internals. However, that
means that it \textbf{\emph{cannot be used after
\passthrough{\lstinline!main()!} exits}}.

\begin{lstlisting}[language={C++}]
log4cplus::BasicConfigurator config;
config.configure();
\end{lstlisting}

These two lines configure \emph{root logger} with
\passthrough{\lstinline!ConsoleAppender!} and simple layout.

\begin{lstlisting}[language={C++}]
log4cplus::Logger logger = log4cplus::Logger::getInstance(
    LOG4CPLUS_TEXT("main"));
\end{lstlisting}

Here we obtain logger handle to logger named \emph{main}.

The \passthrough{\lstinline!LOG4CPLUS\_TEXT()!} macro used above has the
same function as the \passthrough{\lstinline!TEXT()!} or
\passthrough{\lstinline!\_T()!} macros do on Windows: In case
\passthrough{\lstinline!UNICODE!} preprocessor symbol is defined, it
prefixes the string literal that is passed as its parameter with the
\passthrough{\lstinline!L!} to make it wide character string literal.

\begin{lstlisting}[language={C++}]
LOG4CPLUS_WARN(logger, LOG4CPLUS_TEXT("Hello, World!"));
\end{lstlisting}

Here we invoke the \passthrough{\lstinline!LOG4CPLUS\_WARN()!} macro to
log the \emph{Hello, World!} message into the \emph{main} logger. The
logged message will be propagated from the \emph{main} logger towards
the \emph{root logger} which has a
\passthrough{\lstinline!ConsoleAppender!} attached to it to print it on
console.

Internally, this macro uses C++ string stream to format the \emph{Hello,
World!} message. The consequence of this is that you can use all of the
standard C++ streams manipulators.

\hypertarget{de-initialization}{%
\subsection{(De-)Initialization}\label{de-initialization}}

\hypertarget{initialization}{%
\subsubsection{Initialization}\label{initialization}}

In most cases,
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is
initialized before \passthrough{\lstinline!main()!} is executed.
However, depending on compiler, platform, run time libraries and how
log4cplus is linked to, it is possible it will not be initialized
automatically. This is why initializing
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} on top of
\passthrough{\lstinline!main()!} is a good rule of thumb.

As the previous code example shows, initialization of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} is done by
instantiation of \passthrough{\lstinline!log4cplus::Initializer!} class.
This is true for
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} versions
2.0 and later. In previous versions, instead of instantiating this class
(the header \passthrough{\lstinline!log4cplus/initializer.h!} and the
class do not exist there), call to function
\passthrough{\lstinline!log4cplus::initialize()!} is used.

\hypertarget{deinitialization}{%
\subsubsection{Deinitialization}\label{deinitialization}}

\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} tries to
deinitialize itself and free all of its allocated resources after
\passthrough{\lstinline!main()!} exits. However, again, depending on
compiler, platform and run time libraries, it might not be possible.
This is why proper deinitialization is \emph{necessary}.

In version 2.0 and later, it is done by the last instance of
\passthrough{\lstinline!log4cplus::Initializer!} class and its
destructor. In previous versions, calling
\passthrough{\lstinline!Logger::shutdown()!} was the proper shutdown
method.

\hypertarget{logging-macros}{%
\subsection{Logging macros}\label{logging-macros}}

As we have mentioned earlier,
\passthrough{\lstinline!LOG4CPLUS\_WARN()!},
\passthrough{\lstinline!LOG4CPLUS\_ERROR()!}, etc., macros use C++
string stream under the hood. The following example demonstrates how is
it possible to use it with the macros.

Beside these macros, there are two more groups of logging macros.
\passthrough{\lstinline!LOG4CPLUS\_*\_STR()!} can be used for logging
messages that are just plain strings that do not need any kind of
formatting. There is also group of
\passthrough{\lstinline!LOG4CPLUS\_*\_FMT()!} macros which format logged
message using \passthrough{\lstinline!printf()!} formatting string.

\begin{lstlisting}[language={C++}]
#include <log4cplus/logger.h>
#include <log4cplus/loggingmacros.h>
#include <log4cplus/configurator.h>
#include <log4cplus/initializer.h>
#include <iomanip>

int
main()
{
    log4cplus::Initializer initializer;

    log4cplus::BasicConfigurator config;
    config.configure();

    log4cplus::Logger logger = log4cplus::Logger::getInstance(
        LOG4CPLUS_TEXT("main"));

    LOG4CPLUS_INFO(logger,
        LOG4CPLUS_TEXT("This is")
        << LOG4CPLUS_TEXT(" a reall")
        << LOG4CPLUS_TEXT("y long message.") << std::endl
        << LOG4CPLUS_TEXT("Just testing it out") << std::endl
        << LOG4CPLUS_TEXT("What do you think?"));
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a bool: ") << true);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a char: ")
        << LOG4CPLUS_TEXT('x'));
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a short: ")
        << static_cast<short>(-100));
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a unsigned short: ")
        << static_cast<unsigned short>(100));
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a int: ") << 1000);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a unsigned int: ") << 1000U);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a long(hex): ")
        << std::hex << 100000000L);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a unsigned long: ")
        << static_cast<unsigned long>(100000000U));
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a float: ") << 1.2345f);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a double: ")
        << std::setprecision(15)
        << 1.2345234234);
    LOG4CPLUS_INFO(logger, LOG4CPLUS_TEXT("This is a long double: ")
        << std::setprecision(15)
        << 123452342342.342L);

    return 0;
}
\end{lstlisting}

The code above should just print the expected:

\begin{lstlisting}
INFO - This is a really long message.
Just testing it out
What do you think?
INFO - This is a bool: 1
INFO - This is a char: x
INFO - This is a short: -100
INFO - This is a unsigned short: 100
INFO - This is a int: 1000
INFO - This is a unsigned int: 1000
INFO - This is a long(hex): 5f5e100
INFO - This is a unsigned long: 100000000
INFO - This is a float: 1.2345
INFO - This is a double: 1.2345234234
INFO - This is a long double: 123452342342.342
\end{lstlisting}

Beside these macros, there are two more groups of logging macros.
\passthrough{\lstinline!LOG4CPLUS\_*\_STR()!} can be used for logging
messages that are just plain strings that do not need any kind of
formatting. There is also group of
\passthrough{\lstinline!LOG4CPLUS\_*\_FMT()!} macros which format logged
message using \passthrough{\lstinline!printf()!} formatting string.

\hypertarget{log-level}{%
\subsection{Log level}\label{log-level}}

This example shows how log messages can be filtered at run time by
adjusting the \emph{log level threshold} on
\passthrough{\lstinline!Logger!} instance.

\begin{lstlisting}[language={C++}]
#include <log4cplus/logger.h>
#include <log4cplus/loglevel.h>
#include <log4cplus/loggingmacros.h>
#include <log4cplus/configurator.h>
#include <log4cplus/initializer.h>
#include <iomanip>

void
printMessages(log4cplus::Logger const & logger)
{
    // Print messages using all common log levels.
    LOG4CPLUS_TRACE (logger, "printMessages()");
    LOG4CPLUS_DEBUG (logger, "This is a DEBUG message");
    LOG4CPLUS_INFO (logger, "This is a INFO message");
    LOG4CPLUS_WARN (logger, "This is a WARN message");
    LOG4CPLUS_ERROR (logger, "This is a ERROR message");
    LOG4CPLUS_FATAL (logger, "This is a FATAL message");
}

void
thresholdTest(log4cplus::LogLevel ll)
{
    log4cplus::Logger logger
        = log4cplus::Logger::getInstance(LOG4CPLUS_TEXT("main"));

    // Set log level threshold on logger.
    logger.setLogLevel(ll);

    // Print messages.
    log4cplus::tcout
        << LOG4CPLUS_TEXT("*** calling printMessages() with ")
        << log4cplus::getLogLevelManager().toString(ll)
        << LOG4CPLUS_TEXT(" set: ***")
        << std::endl;
    printMessages(logger);
    log4cplus::tcout << std::endl;
}

int
main()
{
    log4cplus::Initializer initializer;

    log4cplus::BasicConfigurator config;
    config.configure();

    thresholdTest(log4cplus::TRACE_LOG_LEVEL);
    thresholdTest(log4cplus::DEBUG_LOG_LEVEL);
    thresholdTest(log4cplus::INFO_LOG_LEVEL);
    thresholdTest(log4cplus::WARN_LOG_LEVEL);
    thresholdTest(log4cplus::ERROR_LOG_LEVEL);
    thresholdTest(log4cplus::FATAL_LOG_LEVEL);

    return 0;
}
\end{lstlisting}

The code prints fewer and fewer messages as the log level threshold is
being risen.

\begin{lstlisting}
*** calling printMessages() with TRACE set: ***
TRACE - printMessages()
DEBUG - This is a DEBUG message
INFO - This is a INFO message
WARN - This is a WARN message
ERROR - This is a ERROR message
FATAL - This is a FATAL message

*** calling printMessages() with DEBUG set: ***
DEBUG - This is a DEBUG message
INFO - This is a INFO message
WARN - This is a WARN message
ERROR - This is a ERROR message
FATAL - This is a FATAL message

*** calling printMessages() with INFO set: ***
INFO - This is a INFO message
WARN - This is a WARN message
ERROR - This is a ERROR message
FATAL - This is a FATAL message

*** calling printMessages() with WARN set: ***
WARN - This is a WARN message
ERROR - This is a ERROR message
FATAL - This is a FATAL message

*** calling printMessages() with ERROR set: ***
ERROR - This is a ERROR message
FATAL - This is a FATAL message

*** calling printMessages() with FATAL set: ***
FATAL - This is a FATAL message
\end{lstlisting}

\hypertarget{more-examples}{%
\subsection{More examples}\label{more-examples}}

See sources in \passthrough{\lstinline!tests/!} directory in
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} source
distribution for more examples of
\href{https://sourceforge.net/projects/log4cplus/}{log4cplus} usage.

\hypertarget{unicode}{%
\section{UNICODE}\label{unicode}}

Log4cplus uses the expression ``UNICODE'' in at least two not so equal
meanings:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  the \href{http://unicode.org/}{Unicode} standard as defined by the
  Unicode Consortium
\item
  compiler's and/or C++ standard library's support for strings of
  \passthrough{\lstinline!wchar\_t!}s and their manipulation
\end{enumerate}

\hypertarget{wchar_t-support}{%
\subsection{\texorpdfstring{\texttt{wchar\_t}
support}{wchar\_t support}}\label{wchar_t-support}}

Log4cplus is aimed to be portable and to have as little 3rd party
dependencies as possible. To fulfill this goal it has to use facilities
offered by the operating systems and standard libraries it runs on. To
offer the best possible level of support of national character, it has
to support usage of \passthrough{\lstinline!wchar\_t!} and it has to use
\passthrough{\lstinline!wchar\_t!} support (especially on Windows)
provided by operating system and standard C and C++ libraries.

This approach to portability has some limitations. One of the
limitations is lacking support for C++ locales in various operating
systems and standard C++ libraries. Some standard C++ libraries do not
support other than the ``C'' and ``POSIX'' locales. This usually means
that \passthrough{\lstinline!wchar\_t!}↔\passthrough{\lstinline!char!}
conversion using \passthrough{\lstinline!std::codecvt<>!} facet is
impossible. On such deficient platforms, log4cplus can use either
standard C locale support or \passthrough{\lstinline!iconv()!} (through
libiconv or built--in).

\hypertarget{unicode-and-file-appenders}{%
\subsection{Unicode and file
appenders}\label{unicode-and-file-appenders}}

Another limitation related to Unicode support is then inability to write
\passthrough{\lstinline!wchar\_t!} messages that contain national
characters that do not map to any code point in single byte code page to
log files using \passthrough{\lstinline!FileAppender!}. This is a
problem mainly on Windows. Linux and other Unix--like systems can avoid
it because they do not need to use \passthrough{\lstinline!wchar\_t!}
interfaces to have Unicode aware applications. They usually (as of year
2012) use UTF-8 based locales. With proper C++ locale setup in client
applications, national characters can come through into log files
unharmed. But if they choose to use \passthrough{\lstinline!wchar\_t!}
strings, they face the problem as well.

\hypertarget{unixlike-platforms}{%
\subsection{Unix--like platforms}\label{unixlike-platforms}}

To support output of non-ASCII characters in
\passthrough{\lstinline!wchar\_t!} message on Unix--like platforms, it
is necessary to use UTF-8 based locale (e.g.,
\passthrough{\lstinline!en\_US.UTF-8!}) and to set up global locale with
\passthrough{\lstinline!std::codecvt<>!} facet or imbue individual
\passthrough{\lstinline!FileAppender!}s with that facet. The following
code can be used to get such \passthrough{\lstinline!std::locale!}
instance and to set it into global locale:

\begin{lstlisting}[language={C++}]
std::locale::global (     // set global locale
    std::locale (         // using std::locale constructed from
        std::locale (),   // global locale
                          // and codecvt facet from user locale
        new std::codecvt_byname<wchar_t, char, std::mbstate_t>("")));
\end{lstlisting}

\hypertarget{windows}{%
\subsection{Windows}\label{windows}}

Windows do not support UTF-8 based locales. The above approach will
yield a \passthrough{\lstinline!std::locale!} instance converting
\passthrough{\lstinline!wchar\_t!}s to current process' code page. Such
locale will not be able to convert Unicode code points outside the
process' code page. This is true at least with the
\passthrough{\lstinline!std::codecvt!} facet implemented in Visual
Studio 2010. Instead, with Visual Studio 2010 and later, it is possible
to use \passthrough{\lstinline!std::codecvt\_utf8!} facet:

\begin{lstlisting}[language={C++}]
std::locale::global (     // set global locale
    std::locale (         // using std::locale constructed from
        std::locale (),   // global locale
                          // and codecvt_utf8 facet
        new std::codecvt_utf8<tchar, 0x10FFFF,
            static_cast<std::codecvt_mode>(std::consume_header
                | std::little_endian)>));
\end{lstlisting}

\hypertarget{release-procedure}{%
\section{Release Procedure}\label{release-procedure}}

This describes log4cplus release procedure:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  Update \passthrough{\lstinline!ChangeLog!} file with worthy changes.
\item
  Make sure that version information in
  \passthrough{\lstinline!version.h!} and
  \passthrough{\lstinline!configure.ac!} is up to date. Run
  \passthrough{\lstinline!scripts/propagate-version.sh!} followed by
  \passthrough{\lstinline!scripts/doautoreconf.sh!}. \emph{Do not forget
  to commit the changes.}
\item
  Run \passthrough{\lstinline!scripts/prepare\_dist\_from\_git.sh!} to
  prepare tarballs. \emph{Do not tag the revision, yet.}
\item
  \href{https://sourceforge.net/projects/log4cplus/files/}{Upload
  tarballs} to SourceForge.
\item
  Send announcement to
  \href{mailto:log4cplus-devel@lists.sourceforge.net}{\nolinkurl{log4cplus-devel@lists.sourceforge.net}}.
\item
  Tag revision on branch.
\item
  Write \href{https://sourceforge.net/p/log4cplus/news/new}{news entry}
  to SourceForge.
\item
  Use Pandoc with parameters
  \passthrough{\lstinline!--standalone -f markdown+smart -t markdown\_strict+hard\_line\_breaks+fenced\_code\_blocks+fenced\_code\_attributes-intraword\_underscores!}
  to generate a version of README file with Markdown compatible with
  SourceForge's wiki. Upload resulting file to project's SourceForge
  wiki page using the
  \passthrough{\lstinline!scripts/upload\_to\_wiki.pl!} script.
\item
  Post release information to
  \href{https://plus.google.com/u/0/b/111599007078013023156/}{G+
  log4cplus page} and share it with the
  \href{https://plus.google.com/u/0/b/111599007078013023156/communities/117815353450765593933}{log4cplus
  community}.
\end{enumerate}

\hypertarget{contributors}{%
\section{Contributors}\label{contributors}}

\begin{itemize}
\tightlist
\item
  Tad E. Smith
  \href{mailto:tcsmith@users.sourceforge.net}{\nolinkurl{tcsmith@users.sourceforge.net}}
\item
  Michael Catanzariti
  \href{mailto:mcatan@users.sourceforge.net}{\nolinkurl{mcatan@users.sourceforge.net}}
\item
  Steighton Haley
  \href{mailto:baldheadedguy@users.sourceforge.net}{\nolinkurl{baldheadedguy@users.sourceforge.net}}
\item
  Eduardo Francos
  \href{mailto:gualo@users.sourceforge.net}{\nolinkurl{gualo@users.sourceforge.net}}
\item
  Václav Zeman
  \href{mailto:wilx@users.sourceforge.net}{\nolinkurl{wilx@users.sourceforge.net}}
\item
  Psychon
  \href{mailto:psychon@users.sourceforge.net}{\nolinkurl{psychon@users.sourceforge.net}}
\item
  Marcel Loose
  \href{mailto:mloose@users.sourceforge.net}{\nolinkurl{mloose@users.sourceforge.net}}
\item
  Hannah Schroeter
  \href{mailto:hannah.schroeter@1und1.de}{\nolinkurl{hannah.schroeter@1und1.de}}
\item
  Ricardo Andrade
  \href{mailto:ricardo.andrade@softideas.com.br}{\nolinkurl{ricardo.andrade@softideas.com.br}}
\item
  Alexander Neundorf
  \href{mailto:neundorf@kde.org}{\nolinkurl{neundorf@kde.org}}
\item
  Mikael Tintinger
  \href{mailto:mtintinger@users.sourceforge.net}{\nolinkurl{mtintinger@users.sourceforge.net}}
\item
  Aaron Thompson
  \href{mailto:meteu11@users.sourceforge.net}{\nolinkurl{meteu11@users.sourceforge.net}}
\item
  Cosmin Cremarenco
  \href{mailto:Cosmin.CREMARENCO@murex.com}{\nolinkurl{Cosmin.CREMARENCO@murex.com}}
\item
  Christian Gudrian
  \href{mailto:cgudrian@users.sourceforge.net}{\nolinkurl{cgudrian@users.sourceforge.net}}
\item
  Nikita Manovich
  \href{mailto:nikita.manovich@gmail.com}{\nolinkurl{nikita.manovich@gmail.com}}
\item
  Andreas Bießmann
  \href{mailto:biessmann@corscience.de}{\nolinkurl{biessmann@corscience.de}}
\item
  Jens Rehsack
  \href{mailto:rehsack@googlemail.com}{\nolinkurl{rehsack@googlemail.com}}
\item
  Siva Chandran P ({\tamilfont{}ப}.{\tamilfont{}சிவச்சந்திரன்})
  \href{mailto:siva.chandran.p@gmail.com}{\nolinkurl{siva.chandran.p@gmail.com}}
\item
  Chernyshev Vyacheslav ({\cyrilicfont{}Вячеслав} {\cyrilicfont{}Чернышев})
  \href{mailto:astellar@ro.ru}{\nolinkurl{astellar@ro.ru}}
\item
  Chris Steenwyk
  \href{mailto:csteenwyk@users.sourceforge.net}{\nolinkurl{csteenwyk@users.sourceforge.net}}
\item
  Jukka Lantto
  \href{mailto:jukka.lantto@outokumpu.com}{\nolinkurl{jukka.lantto@outokumpu.com}}
\item
  Konstantin Baumann
  \href{mailto:konstantin@ks-baumann.de}{\nolinkurl{konstantin@ks-baumann.de}}
\item
  Yaqian Shen ({\cjkfont{}沈亚谦})
  \href{mailto:yshen@kinaxis.com}{\nolinkurl{yshen@kinaxis.com}}
\item
  Sergey Nikulov ({\cyrilicfont{}Сергей} {\cyrilicfont{}Никулов})
  \href{mailto:snikulov@users.sourceforge.net}{\nolinkurl{snikulov@users.sourceforge.net}}
\item
  Ray Logel
  \href{mailto:rlogel@users.sourceforge.net}{\nolinkurl{rlogel@users.sourceforge.net}}
\item
  Zhang Shengfa
  \href{mailto:shengfazhang@yeah.net}{\nolinkurl{shengfazhang@yeah.net}}
\item
  Oskari Timperi
  \href{mailto:oskari.timperi@novatron.fi}{\nolinkurl{oskari.timperi@novatron.fi}}
\item
  Prabhat Ranjan Kanth
  \href{mailto:prabhatkanth@users.sourceforge.net}{\nolinkurl{prabhatkanth@users.sourceforge.net}}
\end{itemize}

\hypertarget{log4cplus-license}{%
\section{Log4cplus license}\label{log4cplus-license}}

Each file of log4cplus source is licensed using either two clause BSD
license or Apache license 2.0. Log4cplus is derived work from log4j.

Threadpool code is licensed under separate license.

\hypertarget{two-clause-bsd-license}{%
\subsection{Two clause BSD license}\label{two-clause-bsd-license}}

Copyright © 1999--2009 Contributors to log4cplus project. All rights
reserved.

Redistribution and use in source and binary forms, with or without
modifica tion, are permitted provided that the following conditions are
met:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
\item
  Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
\end{enumerate}

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

\hypertarget{apache-2.0-license}{%
\subsection{Apache 2.0 license}\label{apache-2.0-license}}

Apache License; Version 2.0, January 2004;
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  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.
\item
  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.
\item
  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.
\item
  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:

  \begin{enumerate}
  \def\labelenumii{(\alph{enumii})}
  \item
    You must give any other recipients of the Work or Derivative Works a
    copy of this License; and
  \item
    You must cause any modified files to carry prominent notices stating
    that You changed the files; and
  \item
    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
  \item
    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.
  \end{enumerate}

  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.
\item
  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.
\item
  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.
\item
  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.
\item
  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.
\item
  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{enumerate}

END OF TERMS AND CONDITIONS

\hypertarget{log4j-license}{%
\section{Log4j license}\label{log4j-license}}

Apache License; Version 2.0, January 2004;
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  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.
\item
  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.
\item
  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.
\item
  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:

  \begin{enumerate}
  \def\labelenumii{(\alph{enumii})}
  \item
    You must give any other recipients of the Work or Derivative Works a
    copy of this License; and
  \item
    You must cause any modified files to carry prominent notices stating
    that You changed the files; and
  \item
    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
  \item
    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.
  \end{enumerate}

  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.
\item
  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.
\item
  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.
\item
  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.
\item
  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.
\item
  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{enumerate}

END OF TERMS AND CONDITIONS

\hypertarget{appendix-how-to-apply-the-apache-license-to-your-work}{%
\section{APPENDIX: How to apply the Apache License to your
work}\label{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.

\begin{lstlisting}
Copyright 1999-2009 [Contributors to log4cplus project]

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.
\end{lstlisting}

\hypertarget{threadpool-license}{%
\section{Threadpool license}\label{threadpool-license}}

Copyright (c) 2012-2015 Jakob Progsch

This software is provided `as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  The origin of this software must not be misrepresented; you must not
  claim that you wrote the original software. If you use this software
  in a product, an acknowledgment in the product documentation would be
  appreciated but is not required.
\item
  Altered source versions must be plainly marked as such, and must not
  be misrepresented as being the original software.
\item
  This notice may not be removed or altered from any source
  distribution.
\end{enumerate}

Modified for log4cplus, copyright (c) 2014-2015 Václav Zeman.

\end{document}