|
From: Eric E. <eri...@us...> - 2006-05-25 11:41:47
|
Update of /cvsroot/objecthandler/log4cxx-0.9.7/docs In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv25784/docs Added Files: Doxyfile Doxyfile.in Makefile.am introduction.dox mainpage.dox Log Message: --- NEW FILE: Doxyfile --- # Doxyfile 1.2.18 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project # # All text after a hash (#) is considered a comment and will be ignored # The format is: # TAG = value [value, ...] # For lists items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (" ") #--------------------------------------------------------------------------- # General configuration options #--------------------------------------------------------------------------- # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. PROJECT_NAME = log4cxx # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or # if some version control system is used. PROJECT_NUMBER = "Version 0.9.7" # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. OUTPUT_DIRECTORY = . # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # The default language is English, other supported languages are: # Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, # Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en # (Japanese with english messages), Korean, Norwegian, Polish, Portuguese, # Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish and Ukrainian. OUTPUT_LANGUAGE = English # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in # documentation are documented, even if no documentation was available. # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. EXTRACT_STATIC = NO # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. EXTRACT_LOCAL_CLASSES = YES # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members of documented classes, files or namespaces. # If set to NO (the default) these members will be included in the # various overviews, but no documentation section is generated. # This option has no effect if EXTRACT_ALL is enabled. HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. # If set to NO (the default) these class will be included in the various # overviews. This option has no effect if EXTRACT_ALL is enabled. HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all # friend (class|struct|union) declarations. # If set to NO (the default) these declarations will be included in the # documentation. HIDE_FRIEND_COMPOUNDS = NO # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will # include brief member descriptions after the members that are listed in # the file and class documentation (similar to JavaDoc). # Set to NO to disable this. BRIEF_MEMBER_DESC = YES # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend # the brief description of a member or function before the detailed description. # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. REPEAT_BRIEF = YES # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # Doxygen will generate a detailed section even if there is only a brief # description. ALWAYS_DETAILED_SEC = NO # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited # members of a class in the documentation of that class as if those members were # ordinary class members. Constructors, destructors and assignment operators of # the base classes will not be shown. INLINE_INHERITED_MEMB = NO # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full # path before files name in the file list and in the header files. If set # to NO the shortest path that makes the file name unique will be used. FULL_PATH_NAMES = NO # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag # can be used to strip a user defined part of the path. Stripping is # only done if one of the specified strings matches the left-hand part of # the path. It is allowed to use relative paths in the argument list. STRIP_FROM_PATH = # The INTERNAL_DOCS tag determines if documentation # that is typed after a \internal command is included. If the tag is set # to NO (the default) then the documentation will be excluded. # Set it to YES to include the internal documentation. INTERNAL_DOCS = NO # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct # doxygen to hide any special comment blocks from generated source code # fragments. Normal C and C++ comments will always remain visible. STRIP_CODE_COMMENTS = YES # If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate # file names in lower case letters. If set to YES upper case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # users are adviced to set this option to NO. CASE_SENSE_NAMES = YES # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter # (but less readable) file names. This can be useful is your file systems # doesn't support long names like on DOS, Mac, or CD-ROM. SHORT_NAMES = NO # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen # will show members with their full class and namespace scopes in the # documentation. If set to YES the scope will be hidden. HIDE_SCOPE_NAMES = YES # If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen # will generate a verbatim copy of the header file for each class for # which an include is specified. Set to NO to disable this. VERBATIM_HEADERS = NO # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen # will put list of the files that are included by a file in the documentation # of that file. SHOW_INCLUDE_FILES = NO # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen # will interpret the first line (until the first dot) of a JavaDoc-style # comment as the brief description. If set to NO, the JavaDoc # comments will behave just like the Qt-style comments (thus requiring an # explict @brief command for a brief description. JAVADOC_AUTOBRIEF = NO # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// # comments) as a brief description. This used to be the default behaviour. # The new default is to treat a multi-line C++ comment block as a detailed # description. Set this tag to YES if you prefer the old behaviour instead. MULTILINE_CPP_IS_BRIEF = NO # If the DETAILS_AT_TOP tag is set to YES then Doxygen # will output the detailed description near the top, like JavaDoc. # If set to NO, the detailed description appears after the member # documentation. DETAILS_AT_TOP = NO # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented # member inherits the documentation from any documented member that it # reimplements. INHERIT_DOCS = YES # If the INLINE_INFO tag is set to YES (the default) then a tag [inline] # is inserted in the documentation for inline members. INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen # will sort the (detailed) documentation of file and class members # alphabetically by member name. If set to NO the members will appear in # declaration order. SORT_MEMBER_DOCS = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES, then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. DISTRIBUTE_GROUP_DOC = NO # The TAB_SIZE tag can be used to set the number of spaces in a tab. # Doxygen uses this value to replace tabs by spaces in code fragments. TAB_SIZE = 8 # The GENERATE_TODOLIST tag can be used to enable (YES) or # disable (NO) the todo list. This list is created by putting \todo # commands in the documentation. GENERATE_TODOLIST = YES # The GENERATE_TESTLIST tag can be used to enable (YES) or # disable (NO) the test list. This list is created by putting \test # commands in the documentation. GENERATE_TESTLIST = YES # The GENERATE_BUGLIST tag can be used to enable (YES) or # disable (NO) the bug list. This list is created by putting \bug # commands in the documentation. GENERATE_BUGLIST = YES # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or # disable (NO) the deprecated list. This list is created by putting \deprecated commands in the documentation. GENERATE_DEPRECATEDLIST= YES # This tag can be used to specify a number of aliases that acts # as commands in the documentation. An alias has the form "name=value". # For example adding "sideeffect=\par Side Effects:\n" will allow you to # put the command \sideeffect (or @sideeffect) in the documentation, which # will result in a user defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. ALIASES = # The ENABLED_SECTIONS tag can be used to enable conditional # documentation sections, marked by \if sectionname ... \endif. ENABLED_SECTIONS = # The MAX_INITIALIZER_LINES tag determines the maximum number of lines # the initial value of a variable or define consist of for it to appear in # the documentation. If the initializer consists of more lines than specified # here it will be hidden. Use a value of 0 to hide initializers completely. # The appearance of the initializer of individual variables and defines in the # documentation can be controlled using \showinitializer or \hideinitializer # command in the documentation regardless of this setting. MAX_INITIALIZER_LINES = 30 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. # For instance some of the names that are used will be different. The list # of all members will be omitted, etc. OPTIMIZE_OUTPUT_FOR_C = NO # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources # only. Doxygen will then generate output that is more tailored for Java. # For instance namespaces will be presented as packages, qualified scopes # will look different, etc. OPTIMIZE_OUTPUT_JAVA = NO # Set the SHOW_USED_FILES tag to NO to disable the list of files generated # at the bottom of the documentation of classes and structs. If set to YES the # list will mention the files that were used to generate the documentation. SHOW_USED_FILES = YES #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- # The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated by doxygen. Possible values are YES and NO. If left blank # NO is used. WARNINGS = YES # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. WARN_IF_UNDOCUMENTED = NO # The WARN_FORMAT tag determines the format of the warning messages that # doxygen can produce. The string should contain the $file, $line, and $text # tags, which will be replaced by the file and line number from which the # warning originated and the warning text. WARN_FORMAT = "$file:$line: $text" # The WARN_LOGFILE tag can be used to specify a file to which warning # and error messages should be written. If left blank the output is written # to stderr. WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag can be used to specify the files and/or directories that contain # documented source files. You may enter file names like "myfile.cpp" or # directories like "/usr/src/myproject". Separate the files or directories # with spaces. INPUT = \ ../include \ ../src \ ../docs/mainpage.dox \ ../docs/introduction.dox # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp # and *.h) to filter out the source-files in the directories. If left # blank the following patterns are tested: # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp # *.h++ *.idl *.odl FILE_PATTERNS = *.h *.cpp # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories # that are symbolic links (a Unix filesystem feature) are excluded from the input. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. EXCLUDE_PATTERNS = # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see # the \include command). EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp # and *.h) to filter out the source-files in the directories. If left # blank all files are included. EXAMPLE_PATTERNS = # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude # commands irrespective of the value of the RECURSIVE tag. # Possible values are YES and NO. If left blank NO is used. EXAMPLE_RECURSIVE = NO # The IMAGE_PATH tag can be used to specify one or more files or # directories that contain image that are included in the documentation (see # the \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command <filter> <input-file>, where <filter> # is the value of the INPUT_FILTER tag, and <input-file> is the name of an # input file. Doxygen will then use the output that the filter program writes # to standard output. INPUT_FILTER = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will be used to filter the input files when producing source # files to browse (i.e. when SOURCE_BROWSER is set to YES). FILTER_SOURCE_FILES = NO #--------------------------------------------------------------------------- # configuration options related to source browsing #--------------------------------------------------------------------------- # If the SOURCE_BROWSER tag is set to YES then a list of source files will # be generated. Documented entities will be cross-referenced with these sources. SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body # of functions and classes directly in the documentation. INLINE_SOURCES = NO # If the REFERENCED_BY_RELATION tag is set to YES (the default) # then for each documented function all documented # functions referencing it will be listed. REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES (the default) # then for each documented function all documented entities # called/used by that function will be listed. REFERENCES_RELATION = NO #--------------------------------------------------------------------------- # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index # of all compounds will be generated. Enable this if the project # contains a lot of classes, structs, unions or interfaces. ALPHABETICAL_INDEX = YES # If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns # in which this list will be split (can be a number in the range [1..20]) COLS_IN_ALPHA_INDEX = 2 # In case all classes in a project start with a common prefix, all # classes will be put under the same header in the alphabetical index. # The IGNORE_PREFIX tag can be used to specify one or more prefixes that # should be ignored while generating the index headers. IGNORE_PREFIX = #--------------------------------------------------------------------------- # configuration options related to the HTML output #--------------------------------------------------------------------------- # If the GENERATE_HTML tag is set to YES (the default) Doxygen will # generate HTML output. GENERATE_HTML = yes # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `html' will be used as the default path. HTML_OUTPUT = html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for # each generated HTML page (for example: .htm,.php,.asp). If it is left blank # doxygen will generate files with .html extension. HTML_FILE_EXTENSION = .html # The HTML_HEADER tag can be used to specify a personal HTML header for # each generated HTML page. If it is left blank doxygen will generate a # standard header. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a # standard footer. HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user defined cascading # style sheet that is used by each HTML page. It can be used to # fine-tune the look of the HTML output. If the tag is left blank doxygen # will generate a default style sheet HTML_STYLESHEET = # If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, # files or namespaces will be aligned in HTML using tables. If set to # NO a bullet list will be used. HTML_ALIGN_MEMBERS = YES # If the GENERATE_HTMLHELP tag is set to YES, additional index files # will be generated that can be used as input for tools like the # Microsoft HTML help workshop to generate a compressed HTML help file (.chm) # of the generated HTML documentation. GENERATE_HTMLHELP = NO # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can # be used to specify the file name of the resulting .chm file. You # can add a path in front of the file if the result should not be # written to the html output dir. CHM_FILE = # If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can # be used to specify the location (absolute path including file name) of # the HTML help compiler (hhc.exe). If non empty doxygen will try to run # the html help compiler on the generated index.hhp. HHC_LOCATION = # If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag # controls if a separate .chi index file is generated (YES) or that # it should be included in the master .chm file (NO). GENERATE_CHI = NO # If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag # controls whether a binary table of contents is generated (YES) or a # normal table of contents (NO) in the .chm file. BINARY_TOC = NO # The TOC_EXPAND flag can be set to YES to add extra items for group members # to the contents of the Html help documentation and to the tree view. TOC_EXPAND = NO # The DISABLE_INDEX tag can be used to turn on/off the condensed index at # top of each HTML page. The value NO (the default) enables the index and # the value YES disables it. DISABLE_INDEX = NO # This tag can be used to set the number of enum values (range [1..20]) # that doxygen will group on one line in the generated HTML documentation. ENUM_VALUES_PER_LINE = 4 # If the GENERATE_TREEVIEW tag is set to YES, a side panel will be # generated containing a tree-like index structure (just like the one that # is generated for HTML Help). For this to work a browser that supports # JavaScript and frames is required (for instance Mozilla, Netscape 4.0+, # or Internet explorer 4.0+). Note that for large projects the tree generation # can take a very long time. In such cases it is better to disable this feature. # Windows users are probably better off using the HTML help feature. GENERATE_TREEVIEW = YES # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be # used to set the initial width (in pixels) of the frame in which the tree # is shown. TREEVIEW_WIDTH = 250 #--------------------------------------------------------------------------- # configuration options related to the LaTeX output #--------------------------------------------------------------------------- # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. GENERATE_LATEX = no # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `latex' will be used as the default path. LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be invoked. If left blank `latex' will be used as the default command name. LATEX_CMD_NAME = latex # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to # generate index for LaTeX. If left blank `makeindex' will be used as the # default command name. MAKEINDEX_CMD_NAME = makeindex # If the COMPACT_LATEX tag is set to YES Doxygen generates more compact # LaTeX documents. This may be useful for small projects and may help to # save some trees in general. COMPACT_LATEX = NO # The PAPER_TYPE tag can be used to set the paper type that is used # by the printer. Possible values are: a4, a4wide, letter, legal and # executive. If left blank a4wide will be used. PAPER_TYPE = a4wide # The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX # packages that should be included in the LaTeX output. EXTRA_PACKAGES = # The LATEX_HEADER tag can be used to specify a personal LaTeX header for # the generated latex document. The header should contain everything until # the first chapter. If it is left blank doxygen will generate a # standard header. Notice: only use this tag if you know what you are doing! LATEX_HEADER = # If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated # is prepared for conversion to pdf (using ps2pdf). The pdf file will # contain links (just like the HTML output) instead of page references # This makes the output suitable for online browsing using a pdf viewer. PDF_HYPERLINKS = NO # If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of # plain latex in the generated Makefile. Set this option to YES to get a # higher quality PDF documentation. USE_PDFLATEX = NO # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. # command to the generated LaTeX files. This will instruct LaTeX to keep # running if errors occur, instead of asking the user for help. # This option is also used when generating formulas in HTML. LATEX_BATCHMODE = NO #--------------------------------------------------------------------------- # configuration options related to the RTF output #--------------------------------------------------------------------------- # If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output # The RTF output is optimised for Word 97 and may not look very pretty with # other RTF readers or editors. GENERATE_RTF = NO # The RTF_OUTPUT tag is used to specify where the RTF docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `rtf' will be used as the default path. RTF_OUTPUT = rtf # If the COMPACT_RTF tag is set to YES Doxygen generates more compact # RTF documents. This may be useful for small projects and may help to # save some trees in general. COMPACT_RTF = NO # If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated # will contain hyperlink fields. The RTF file will # contain links (just like the HTML output) instead of page references. # This makes the output suitable for online browsing using WORD or other # programs which support those fields. # Note: wordpad (write) and others do not support links. RTF_HYPERLINKS = NO # Load stylesheet definitions from file. Syntax is similar to doxygen's # config file, i.e. a series of assigments. You only have to provide # replacements, missing definitions are set to their default value. RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an rtf document. # Syntax is similar to doxygen's config file. RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- # configuration options related to the man page output #--------------------------------------------------------------------------- # If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages GENERATE_MAN = NO # The MAN_OUTPUT tag is used to specify where the man pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `man' will be used as the default path. MAN_OUTPUT = man # The MAN_EXTENSION tag determines the extension that is added to # the generated man pages (default is the subroutine's section .3) MAN_EXTENSION = .3 # If the MAN_LINKS tag is set to YES and Doxygen generates man output, # then it will generate one additional man file for each entity # documented in the real man page(s). These additional files # only source the real man page, but without them the man command # would be unable to find the correct page. The default is NO. MAN_LINKS = NO #--------------------------------------------------------------------------- # configuration options related to the XML output #--------------------------------------------------------------------------- # If the GENERATE_XML tag is set to YES Doxygen will # generate an XML file that captures the structure of # the code including all documentation. Note that this # feature is still experimental and incomplete at the # moment. GENERATE_XML = NO # The XML_SCHEMA tag can be used to specify an XML schema, # which can be used by a validating XML parser to check the # syntax of the XML files. XML_SCHEMA = # The XML_DTD tag can be used to specify an XML DTD, # which can be used by a validating XML parser to check the # syntax of the XML files. XML_DTD = #--------------------------------------------------------------------------- # configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will # generate an AutoGen Definitions (see autogen.sf.net) file # that captures the structure of the code including all # documentation. Note that this feature is still experimental # and incomplete at the moment. GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- # If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will # evaluate all C-preprocessor directives found in the sources and include # files. ENABLE_PREPROCESSING = YES # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro # names in the source code. If set to NO (the default) only conditional # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. MACRO_EXPANSION = NO # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_PREDEFINED tags. EXPAND_ONLY_PREDEF = NO # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by # the preprocessor. INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the # directories. If left blank, the patterns specified with FILE_PATTERNS will # be used. INCLUDE_FILE_PATTERNS = # The PREDEFINED tag can be used to specify one or more macro names that # are defined before the preprocessor is started (similar to the -D option of # gcc). The argument of the tag is a list of macros of the form: name # or name=definition (no spaces). If the definition and the = are # omitted =1 is assumed. PREDEFINED = HAVE_SMTP HAVE_ODBC HAVE_XML # If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. # The macro definition that is found in the sources will be used. # Use the PREDEFINED tag if you want to use a different macro definition. EXPAND_AS_DEFINED = # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then # doxygen's preprocessor will remove all function-like macros that are alone # on a line, have an all uppercase name, and do not end with a semicolon. Such # function macros are typically used for boiler-plate code, and will confuse the # parser if not removed. SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration::addtions related to external references #--------------------------------------------------------------------------- # The TAGFILES tag can be used to specify one or more tagfiles. TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. GENERATE_TAGFILE = # If the ALLEXTERNALS tag is set to YES all external classes will be listed # in the class index. If set to NO only the inherited external classes # will be listed. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed # in the modules index. If set to NO, only the current project's groups will # be listed. EXTERNAL_GROUPS = YES # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- # If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will # generate a inheritance diagram (in Html, RTF and LaTeX) for classes with base or # super classes. Setting the tag to NO turns the diagrams off. Note that this # option is superceded by the HAVE_DOT option below. This is only a fallback. It is # recommended to install and use dot, since it yield more powerful graphs. CLASS_DIAGRAMS = YES # If set to YES, the inheritance and collaboration graphs will hide # inheritance and usage relations if the target is undocumented # or is not a class. HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz, a graph visualization # toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) HAVE_DOT = yes # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and # indirect inheritance relations. Setting this tag to YES will force the # the CLASS_DIAGRAMS tag to NO. CLASS_GRAPH = YES # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and # indirect implementation dependencies (inheritance, containment, and # class references variables) of the class with other documented classes. COLLABORATION_GRAPH = YES # If set to YES, the inheritance and collaboration graphs will show the # relations between templates and their instances. TEMPLATE_RELATIONS = YES # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT # tags are set to YES then doxygen will generate a graph for each documented # file showing the direct and indirect include dependencies of the file with # other documented files. INCLUDE_GRAPH = YES # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and # HAVE_DOT tags are set to YES then doxygen will generate a graph for each # documented header file showing the documented files that directly or # indirectly include this file. INCLUDED_BY_GRAPH = YES # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen # will graphical hierarchy of all classes instead of a textual one. GRAPHICAL_HIERARCHY = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. Possible values are png, jpg, or gif # If left blank png will be used. DOT_IMAGE_FORMAT = png # The tag DOT_PATH can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found on the path. DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that # contain dot files that are included in the documentation (see the # \dotfile command). DOTFILE_DIRS = # The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width # (in pixels) of the graphs generated by dot. If a graph becomes larger than # this value, doxygen will try to truncate the graph, so that it fits within # the specified constraint. Beware that most browsers cannot cope with very # large images. MAX_DOT_GRAPH_WIDTH = 1024 # The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height # (in pixels) of the graphs generated by dot. If a graph becomes larger than # this value, doxygen will try to truncate the graph, so that it fits within # the specified constraint. Beware that most browsers cannot cope with very # large images. MAX_DOT_GRAPH_HEIGHT = 1024 # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will # generate a legend page explaining the meaning of the various boxes and # arrows in the dot generated graphs. GENERATE_LEGEND = YES # If the DOT_CLEANUP tag is set to YES (the default) Doxygen will # remove the intermedate dot files that are used to generate # the various graphs. DOT_CLEANUP = YES #--------------------------------------------------------------------------- # Configuration::addtions related to the search engine #--------------------------------------------------------------------------- # The SEARCHENGINE tag specifies whether or not a search engine should be # used. If set to NO the values of all tags below this one will be ignored. SEARCHENGINE = NO --- NEW FILE: introduction.dox --- /** @page Introduction Short introduction to log4cxx This document is largely inspired of the <a href=http://logging.apache.org/log4j/docs/manual.html>Short introduction to log4j</a> by <i>Ceki Gülcü</i> @section Contents - @ref Abstract - @ref IntroductionIntroduction - @ref LoggersAppendersAndLayouts - @ref LoggerHierarchy - @ref AppendersAndLayouts . - @ref Configuration - @ref DefaultInitializationProcedure - @ref NDC - @ref Performance - @ref Conclusion @section Abstract This document describes the log4cxx API, its unique features and design rationale. Log4cxx is an open source project based on the work of several authors. It allows the developer to control which log statements are output with arbitrary granularity. It is fully configurable at runtime using external configuration files. Best of all, log4cxx has a gentle learning curve. Beware: judging from user feedback, it is also quite addictive. @section IntroductionIntroduction Introduction The log4cxx framework is based on log4j, see http://logging.apache.org/log4j for more information on log4cxx. The package is distributed under the <a href=http://logging.apache.org/log4j/LICENSE.txt>Apache Software License </a>, a fully-fledged open source license certified by the <a href=http://www.opensource.org/> open source</a> initiative. The latest log4cxx version, including full-source code, class files and documentation can be found at http://logging.apache.org/log4cxx . Almost every large application includes its own logging or tracing API. Inserting log statements into code is a low-tech method for debugging it. It may also be the only way because debuggers are not always available or applicable. This is usually the case for multithreaded applications and distributed applications at large. Experience indicates that logging was an important component of the development cycle. It offeres several advantages. It provides precise context about a run of the application. Once inserted into the code, the generation of logging output requires no human intervention. Moreover, log output can be saved in persistent medium to be studied at a later time. In addition to its use in the development cycle, a sufficiently rich logging package can also be viewed as an auditing tool. Logging does have its drawbacks. It can slow down an application. If too verbose, it can cause scrolling blindness. To alleviate these concerns, log4cxx is designed to be reliable, fast and extensible. Since logging is rarely the main focus of an application, the log4cxx API strives to be simple to understand and to use. @section LoggersAppendersAndLayouts Loggers, Appenders and Layouts Log4cxx has three main components: loggers, appenders and layouts. These three types of components work together to enable developers to log messages according to message type and level, and to control at runtime how these messages are formatted and where they are reported. @subsection LoggerHierarchy Logger hierarchy The first and foremost advantage of any logging API over plain std::cout resides in its ability to disable certain log statements while allowing others to print unhindered. This capability assumes that the logging space, that is, the space of all possible logging statements, is categorized according to some developer-chosen criteria. Loggers are named entities. Logger names are case-sensitive and they follow the hierarchical naming rule: <table bgcolor="#EEEE99"> <tr> <td> <dl> <dt><b>Named Hierarchy</b> <dd><p>A logger is said to be an <em>ancestor</em> of another logger if its name followed by a dot is a prefix of the <em>descendant</em> logger name. A logger is said to be a <em>parent</em> of a <em>child</em> logger if there are no ancestors between itself and the descendant logger. </dl> </table> For example, the logger named <code>com.foo</code> is a parent of the logger named <code>com.foo.Bar</code>. Similarly, <code>cpp</code> is a parent of <code>cpp.util</code> and an ancestor of <code>cpp.util.Vector</code>. This naming scheme should be familiar to most developers. The root logger resides at the top of the logger hierarchy. It is exceptional in two ways: -# it always exists, -# it cannot be retrieved by name. Invoking the class static log4cxx::Logger::getRootLogger method retrieves it. All other loggers are instantiated and retrieved with the class static log4cxx::Logger::getLogger method. This method takes the name of the desired logger as a parameter.Some of the basic methods in the Logger class are listed below. @code #include <log4cxx/logger.h> class Logger { public: // Creation & retrieval methods: static LoggerPtr getRootLogger(); static LoggerPtr getLogger(const String& name); // printing methods: void debug(const String& message); void info(const String& message); void warn(const String& message); void error(const String& message); void fatal(const String& message); // generic printing method: void log(const LevelPtr& l, const String& message); }; @endcode Loggers may be assigned levels. The set of possible levels, that is {@link log4cxx::Level::DEBUG DEBUG}, {@link log4cxx::Level::INFO INFO}, {@link log4cxx::Level::WARN WARN}, {@link log4cxx::Level::ERROR ERROR} and {@link log4cxx::Level::FATAL FATAL} are defined in the log4cxx::Level class. Although we do not encourage you to do so, you may define your own levels by sub-classing the Level class. A perhaps better approach will be explained later on. If a given logger is not assigned a level, then it inherits one from its closest ancestor with an assigned level. More formally: <table bgcolor="#EEEE99"> <tr> <td> <dl> <dt><b>Level Inheritance</b> <dd><p>The <em>inherited level</em> for a given logger <i>C</i>, is equal to the first non-null level in the logger hierarchy, starting at <i>C</i> and proceeding upwards in the hierarchy towards the <code>root</code> logger. </dl> </table> To ensure that all loggers can eventually inherit a level, the root logger always has an assigned level. Below are four tables with various assigned level values and the resulting inherited levels according to the above rule. <table border="1" > <caption align=bottom>Example 1</caption> <tr><th>Logger<br>name</th><th>Assigned<br>level</th> <th>Inherited<br>level</th></tr> <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr> <tr align=left><td>X </td> <td>none</td> <td>Proot</td></tr> <tr align=left><td>X.Y </td> <td>none</td> <td>Proot</td></tr> <tr align=left><td>X.Y.Z</td> <td>none</td> <td>Proot</td></tr> </table> In example 1 above, only the root logger is assigned a level. This level value, <code>Proot</code>, is inherited by the other loggers <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code>. <table border="1"> <caption align=bottom>Example 2</caption> <tr><th>Logger<br>name</th><th>Assigned<br>level</th> <th>Inherited<br>level</th></tr> <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr> <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr> <tr align=left><td>X.Y </td> <td>Pxy</td> <td>Pxy</td></tr> <tr align=left><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr> </table> In example 2, all loggers have an assigned level value. There is no need for level inheritence. <table border="1"> <caption align=bottom>Example 3</caption> <tr><th>Logger<br>name</th><th>Assigned<br>level</th> <th>Inherited<br>level</th></tr> <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr> <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr> <tr align=left><td>X.Y </td> <td>none</td> <td>Px</td></tr> <tr align=left><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr> </table> In example 3, the loggers <code>root</code>, <code>X</code> and <code>X.Y.Z</code> are assigned the levels <code>Proot</code>, <code>Px</code> and <code>Pxyz</code> respectively. The logger <code>X.Y</code> inherits its level value from its parent <code>X</code>. <table border=1> <caption align=bottom>Example 4</caption> <tr><th>Logger<br>name</th><th>Assigned<br>level</th> <th>Inherited<br>level</th></tr> <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr> <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr> <tr align=left><td>X.Y </td> <td>none</td> <td>Px</td></tr> <tr align=left><td>X.Y.Z</td> <td>none</td> <td>Px</td></tr> </table> In example 4, the loggers <code>root</code> and <code>X</code> and are assigned the levels <code>Proot</code> and <code>Px</code> respectively. The loggers <code>X.Y</code> and <code>X.Y.Z</code> inherits their level value from their nearest parent <code>X</code> having an assigned level.. Logging requests are made by invoking one of the printing methods of a logger instance. These printing methods are {@link log4cxx::Logger::debug debug}, {@link log4cxx::Logger::info info}, {@link log4cxx::Logger::warn warn}, {@link log4cxx::Logger::error error}, {@link log4cxx::Logger::fatal fatal} and {@link log4cxx::Logger::log log}. By definition, the printing method determines the level of a logging request. For example, if <code>c</code> is a logger instance, then the statement <code>c.info("..")</code> is a logging request of level INFO. A logging request is said to be <em>enabled</em> if its level is higher than or equal to the level of its logger. Otherwise, the request is said to be <em>disabled</em>. A logger without an assigned level will inherit one from the hierarchy. This rule is summarized below. <a name="selectionRule"><table bgcolor="#EEEE99"> <tr> <td> <dl> <dt><b>Basic Selection Rule</b> <dd><p>A log request of level <i>p</i> in a logger with (either assigned or inherited, whichever is appropriate) level <i>q</i>, is enabled if <i> p >= q</i>. </dl> </table> This rule is at the heart of log4cxx. It assumes that levels are ordered. For the standard levels, we have DEBUG < INFO < WARN < ERROR < FATAL. Here is an example of this rule. @code // get a logger instance named "com.foo" LoggerPtr logger = Logger::getLogger(_T("com.foo")); // Now set its level. Normally you do not need to set the // level of a logger programmatically. This is usually done // in configuration files. logger->setLevel(Level::INFO); LoggerPtr barlogger = Logger::getLogger(_T("com.foo.Bar")); // This request is enabled, because WARN >= INFO. logger->warn(_T("Low fuel level.")); // This request is disabled, because DEBUG < INFO. logger->debug(_T("Starting search for nearest gas station.")); // The logger instance barlogger, named "com.foo.Bar", // will inherit its level from the logger named // "com.foo" Thus, the following request is enabled // because INFO >= INFO. barlogger->info(_T("Located nearest gas station.")); // This request is disabled, because DEBUG < INFO. barlogger->debug(_T("Exiting gas station search")); @endcode Calling the <code>getLogger</code> method with the same name will always return a reference to the exact same logger object. For example, in @code LoggerPtr x = Logger::getLogger("wombat"); LoggerPtr y = Logger::getLogger("wombat"); @endcode <code>x</code> and <code>y</code> refer to <em>exactly</em> the same logger object. Thus, it is possible to configure a logger and then to retrieve the same instance somewhere else in the code without passing around references. In fundamental contradiction to biological parenthood, where parents always preceed their children, log4cxx loggers can be created and configured in any order. In particular, a "parent" logger will find and link to its descendants even if it is instantiated after them. Configuration of the log4cxx environment is typically done at application initialization. The preferred way is by reading a configuration file. This approach will be discussed shortly. Log4cxx makes it easy to name loggers by <em>software component</em>. This can be accomplished by statically instantiating a logger in each class, with the logger name equal to the fully qualified name of the class. This is a useful and straightforward method of defining loggers. As the log output bears the name of the generating logger, this naming strategy makes it easy to identify the origin of a log message. However, this is only one possible, albeit common, strategy for naming loggers. Log4cxx does not restrict the possible set of loggers. The developer is free to name the loggers as desired. Nevertheless, naming loggers after the class where they are located seems to be the best strategy known so far. @subsection AppendersAndLayouts Appenders and Layouts The ability to selectively enable or disable logging requests based on their logger is only part of the picture. Log4cxx allows logging requests to print to multiple destinations. In log4cxx speak, an output destination is called an <em>appender</em>. Currently, appenders exist for the {@link log4cxx::ConsoleAppender console}, {@link log4cxx::FileAppender files}, GUI components, {@link log4cxx::net::SocketAppender remote socket} servers, {@link log4cxx::nt::NTEventLogAppender NT Event Loggers}, and remote UNIX {@link log4cxx::net::SyslogAppender Syslog} daemons. It is also possible to log {@link log4cxx::AsyncAppender asynchronously}. More than one appender can be attached to a logger. The {@link log4cxx::Logger::addAppender addAppender} method adds an appender to a given logger. <b>Each enabled logging request for a given logger will be forwarded to all the appenders in that logger as well as the appenders higher in the hierarchy.</b> In other words, appenders are inherited additively from the logger hierarchy. For example, if a console appender is added to the root logger, then all enabled logging requests will at least print on the console. If in addition a file appender is added to a logger, say <em>C</em>, then enabled logging requests for <em>C</em> and <em>C</em>'s children will print on a file <em>and</em> on the console. It is possible to override this default behavior so that appender accumulation is no longer additive by {@link log4cxx::Logger::setAdditivity setting the additivity flag} to <code>false</code>. The rules governing appender additivity are summarized below. <a name="additivity"><table bgcolor="#EEEE99"> <tr> <td> <dl> <dt><b>Appender Additivity</b> <dd><p>The output of a log statement of logger <i>C</i> will go to all the appenders in <i>C</i> and its ancestors. This is the meaning of the term "appender additivity". <p>However, if an ancestor of logger <i>C</i>, say <i>P</i>, has the additivity flag set to <code>false</code>, then <i>C</i>'s output will be directed to all the appenders in <i>C</i> and it's ancestors upto and including <i>P</i> but not the appenders in any of the ancestors of <i>P</i>. <p>Loggers have their additivity flag set to <code>true</code> by default. </dl> </table> The table below shows an example: <table align=center border=3 cellpadding=10> <tr rowspan="2"> <th>Logger<br>Name <th>Added<br>Appenders <th>Additivity<br>Flag <th>Output Targets <th>Comment <tr><td>root <td>A1 <td>not applicable <td>A1 <td>The root logger is anonymous but can be accessed with the Logger::getRootLogger() method. There is no default appender attached to root. <tr><td>x <td>A-x1, A-x2 <td>true <td>A1, A-x1, A-x2 <td>Appenders of "x" and root. <tr><td>x.y <td>none <td>true <td>A1, A-x1, A-x2 <td>Appenders of "x" and root. <tr><td>x.y.z <td>A-xyz1 <td>true <td>A1, A-x1, A-x2, A-xyz1 <td>Appenders in "x.y.z", "x" and root. <tr><td>security <td>A-sec <td>false <td>A-sec <td>No appender accumulation since the additivity flag is set to <code>false</code>. <tr><td>security.access <td>none <td> true <td> A-sec <td>Only appenders of "security" because the additivity flag in "security" is set to <code>false</code>. </table> More often than not, users wish to customize not only the output destination but also the output format. This is accomplished by associating a <em>layout</em> with an appender. The layout is responsible for formatting the logging request according to the user's wishes, whereas an appender takes care of sending the formatted output to its destination. The {@link log4cxx::PatternLayout PatternLayout}, part of the standard log4cxx distribution, lets the user specify the output format according to conversion patterns similar to the C language <code>printf</code> function. For example, the PatternLayout with the conversion pattern "\%r [\%t] \%-5p \%c - \%m\%n" will output something akin to: <pre>176 [12345] INFO org.foo.Bar - Located nearest gas station. </pre> The first field is the number of milliseconds elapsed since the start of the program. The second field is the identifier of the thread making the log request. The third field is the level of the log statement. The fourth field is the name of the logger associated with the log request. The text after the '-' is the message of the statement. @section Configuration Inserting log requests into the application code requires a fair amount of planning and effort. Observation shows that approximately 4 percent of code is dedicated to logging. Consequently, even moderately sized applications will have thousands of logging statements embedded within their code. Given their number, it becomes imperative to manage these log statements without the need to modify them manually. The log4cxx environment is fully configurable programmatically. However, it is far more flexible to configure log4cxx using configuration files. Currently, configuration files can be written in XML or in properties (key=value) format. <p>Let us give a taste of how this is done with the help of an imaginary application <code>MyApp</code> that uses log4cxx. @code // file MyApp.cpp #include "com/foo/bar.h"; using namespace com::foo; // include log4cxx header files. #include <log4cxx/logger.h> #include <log4cxx/basicconfigurator.h> #include <log4cxx/helpers/exception.h> using namespace log4cxx; using namespace log4cxx::helpers; // Define a static logger variable so that it references the // Logger instance named "MyApp". LoggerPtr logger = Logger::getLogger(_T("MyApp")); int main(int argc, char **argv) { int result = EXIT_SUCCESS; try { // Set up a simple configuration that logs on the console. BasicConfigurator::configure(); logger->info(_T("Entering application.")); Bar bar; bar.doIt(); logger->info(_T("Exiting application.")); } catch(Exception&) { result = EXIT_FAILURE; } return result; } @endcode <code>MyApp</code> begins by including log4cxx related headers. It then defines a static logger variable with the name <code>MyApp</code> which happens to be the fully qualified name of the class. <code>MyApp</code> uses the <code>Bar</code> class defined in the header file <code>com/foo/bar.h</code> and the source file <code>bar.cpp</code>. @code // file <com/foo/bar.h> #include <log4cxx/logger.h>; namespace com { namespace foo { class Bar { static log4cxx::LoggerPtr logger; public: void doIt(); }; }; }; @endcode @code // file <bar.cpp> #include "com/foo/bar.h" using namespace com::foo; using namespace log4cxx; LoggerPtr Bar::logger = Logger::getLogger(_T("com.foo.bar")); void Bar::doIt() { logger->debug(_T("Did it again!")); } @endcode The invocation of the {@link log4cxx::BasicConfigurator::configure BasicConfigurator::configure} method creates a rather simple log4cxx setup. This method is hardwired to add to the root logger {@link log4cxx::ConsoleAppender ConsoleAppender}. The output will be formatted using a {@link log4cxx::PatternLayout PatternLayout} set to the pattern "\%-4r [\%t] \%-5p \%c \%x - \%m\%n". Note that by default, the root logger is assigned to <code>Level::DEBUG</code>. The output of MyApp is: <pre>0 [12345] INFO MyApp - Entering application. 36 [12345] DEBUG com.foo.Bar - Did it again! 51 [12345] INFO MyApp - Exiting application. </pre> As a side note, let me mention that in log4cxx child loggers link only to their existing ancestors. In particular, the logger named <code>com.foo.Bar</code> is linked directly to the <code>root</code> logger, thereby circumventing the unused <code>com</code> or <code>com.foo</code> loggers. This significantly increases performance and reduces log4cxx's memory footprint. The <code>MyApp</code> class configures log4cxx by invoking <code>BasicConfigurator::configure</code> method. Other classes only need to include the <code><log4cxx/logger.h></code> header file, retrieve the loggers they wish to use, and log away. The previous example always outputs the same log information. Fortunately, it is easy to modify <code>MyApp</code> so that the log output can be controlled at run-time. Here is a slightly modified version. @code // file MyApp2.cpp #include "com/foo/bar.h"; using namespace com::foo; // include log4cxx header files. #include <log4cxx/logger.h> #include <log4cxx/basicconfigurator.h> #include <log4cxx/propertyconfigurator.h> #include <log4cxx/helpers/exception.h> using namespace log4cxx; using namespace log4cxx::helpers; // Define a static logger variable so that it references the // Logger instance named "MyApp". LoggerPtr logger = Logger::getLogger(_T("MyApp")); int main(int argc, char **argv) { int result = EXIT_SUCCESS; try { if (argc > 1) { // BasicConfigurator replaced with PropertyConfigurator. USES_CONVERSION; String propertyFileName = A2W(argv[1]); PropertyConfigurator::configure(propertyFileName); } else { BasicConfigurator::configure(); } logger->info(_T("Entering application.")); Bar bar bar.doIt(); logger->info(_T("Exiting application.")); } catch(Exception&) { result = EXIT_FAILURE; } return result; } @endcode This version of <code>MyApp</code> instructs <code>PropertyConfigurator</code> to parse a configuration file and se... [truncated message content] |
