Utils/Logger: set defautl compile-time log limit for senf::log::Debug to NOTICE

Utils/Logger: Renoame all 'SENF_LOG_DEF_*' macros to 'SENF_LOG_DEFINE_*'
Utils/Logger: Add documentation on default compile-time limit

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@714 270642c3-0616-0410-b53a-bc976706d245

diff --git a/Utils/Logger/Config.hh b/Utils/Logger/Config.hh
index 80d02cb..4bfb369 100644 (file)
--- a/Utils/Logger/Config.hh
+++ b/Utils/Logger/Config.hh
@@ -65,6 +65,18 @@
     \c foo::SomeClass area, where it is set to \c VERBOSE. Furthermore, the limit on the \c
     foo::Transactions stream is set to \c NOTICE.
 
+    There are two standard uses for this configuration: Either to disable most logging in final
+    builds by changing the compile time limit to something like senf::log::IMPORTANT or to enable
+    senf::log::VERBOSE messages for some area:
+    <pre>
+    # Disable debug logging below 'IMPORTANT' level
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (_), IMPORTANT ))"
+
+    # Or enable verbose messages for the 'some::Area' area
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Verbose), (some)(Area), VERBOSE ))"
+    </pre>
+
+
     \see \ref SENF_LOG_CONF
 
     \section config_runtime Runtime configuration

diff --git a/Utils/Logger/Definitions.hh b/Utils/Logger/Definitions.hh
index f37fc49..a2017b3 100644 (file)
--- a/Utils/Logger/Definitions.hh
+++ b/Utils/Logger/Definitions.hh
@@ -50,9 +50,13 @@ namespace log {
         output.  \a compileLimit defines the default log level limit at compile time: Messages
         posted with a level below \a compileLimit will be discarded at compile time.
 
+        Normally the \a compileLimit will be \c NOTICE. This will enable all messages
+        <em>except</em> \c VERBOSE messages. These must then be enabled explicitly using the compile
+        time \ref config macro.
+
         \hideinitializer
      */
-#   define SENF_LOG_DEF_STREAM(stream, defaultLevel_, runtimeLimit_, compileLimit_)               \
+#   define SENF_LOG_DEFINE_STREAM(stream, defaultLevel_, runtimeLimit_, compileLimit_)               \
         struct stream                                                                             \
             : public senf::log::detail::StreamBase, public senf::singleton<stream>                \
         {                                                                                         \
@@ -73,17 +77,17 @@ namespace log {
 
         \hideinitializer
      */
-#   define SENF_LOG_DEF_AREA(area) SENF_LOG_DEF_AREA_I(area, ; )
+#   define SENF_LOG_DEFINE_AREA(area) SENF_LOG_DEFINE_AREA_I(area, ; )
 
     /** \brief Define new default log area for the class
 
         This command declares the containing class to be it's own default log area. It is such like
-        a combination of \ref SENF_LOG_DEF_AREA and \ref SENF_LOG_DEFAULT_AREA with a twist.
+        a combination of \ref SENF_LOG_DEFINE_AREA and \ref SENF_LOG_DEFAULT_AREA with a twist.
 
         \hideinitializer
      */
 #   define SENF_LOG_CLASS_AREA()                                                                  \
-        SENF_LOG_DEF_AREA_I(                                                                      \
+        SENF_LOG_DEFINE_AREA_I(                                                                      \
             SENFLogArea,                                                                          \
             std::string v_name() const                                                            \
                 { std::string s (fullName()); return std::string(s,0,s.size()-13); });            \
@@ -97,7 +101,7 @@ namespace log {
 
         \hideinitializer
      */
-#   define SENF_LOG_DEF_ALIAS(alias,args)                                                         \
+#   define SENF_LOG_DEFINE_ALIAS(alias,args)                                                         \
         struct alias : public senf::log::detail::AliasBase                                        \
         {                                                                                         \
             template <class Base>                                                                 \
@@ -108,10 +112,10 @@ namespace log {
         }
 
     /** \brief Default global log stream */
-    SENF_LOG_DEF_STREAM(Debug, MESSAGE, MESSAGE, MESSAGE);
+    SENF_LOG_DEFINE_STREAM(Debug, MESSAGE, MESSAGE, NOTICE);
 
     /** \brief Default global %log area */
-    SENF_LOG_DEF_AREA(DefaultArea);
+    SENF_LOG_DEFINE_AREA(DefaultArea);
 
     ///\}
     ///\}

diff --git a/Utils/Logger/Definitions.ih b/Utils/Logger/Definitions.ih
index 0c88f6e..b5d8369 100644 (file)
--- a/Utils/Logger/Definitions.ih
+++ b/Utils/Logger/Definitions.ih
@@ -30,7 +30,7 @@
 
 ///////////////////////////////ih.p////////////////////////////////////////
 
-#define SENF_LOG_DEF_AREA_I(area, decls)                                                          \
+#define SENF_LOG_DEFINE_AREA_I(area, decls)                                                          \
     struct area                                                                                   \
         : public senf::log::detail::AreaBase, public senf::singleton<area>                        \
     {                                                                                             \

diff --git a/Utils/Logger/Levels.hh b/Utils/Logger/Levels.hh
index 1a10285..89845da 100644 (file)
--- a/Utils/Logger/Levels.hh
+++ b/Utils/Logger/Levels.hh
@@ -41,7 +41,8 @@ namespace log {
 
         <dl><dt>VERBOSE</dt><dd>Really verbose %log messages. Messages at this level are used for
         internal debugging. They should be enabled only selectively within the areas currently under
-        inspection.</dd>
+        inspection. The default log stream senf::log::Debug has these messages <em>disabled</em> at
+        compile time by default. To enable them, see \ref config.</dd>
 
         <dt>NOTICE</dt><dd>Arbitrary unimportant notice. Message which normally should be disabled
         but might be informative to better understand the programs operation.</dd>

diff --git a/Utils/Logger/Log.hh b/Utils/Logger/Log.hh
index 8a591dc..4faf2f9 100644 (file)
--- a/Utils/Logger/Log.hh
+++ b/Utils/Logger/Log.hh
@@ -80,7 +80,7 @@
     To further simplify logging commands, aliases may be defined within any scope. An alias is an
     arbitrary collection of %log parameters:
     \code
-    SENF_LOG_DEF_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) );
+    SENF_LOG_DEFINE_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) );
     \endcode
     Within %log statements, aliases may be used like normal parameters. They will be substituted for
     the parameter sequence they represent:

diff --git a/Utils/Logger/Mainpage.dox b/Utils/Logger/Mainpage.dox
index 83d5b1c..7a5509d 100644 (file)
--- a/Utils/Logger/Mainpage.dox
+++ b/Utils/Logger/Mainpage.dox
@@ -44,13 +44,13 @@
 
     A \e stream combines log messages with a single purpose: Debug messages, access logging and so
     on. Any number of streams may be defined. There is one predefined default stream called \c
-    senf::log::Debug. (see: \ref SENF_LOG_DEF_STREAM)
+    senf::log::Debug. (see: \ref SENF_LOG_DEFINE_STREAM)
 
     The \e area gives information about the source location of the message. Areas may be defined and
     assigned arbitrarily but should be used to label messages from a single class or subsystem. It
     is possible to reuse a class as it's own area tag, which is often desireable.  There is a
     default area \c senf::log::DefaultArea which is used, when no other area is assigned. (see: \ref
-    SENF_LOG_DEF_AREA, \ref SENF_LOG_CLASS_AREA)
+    SENF_LOG_DEFINE_AREA, \ref SENF_LOG_CLASS_AREA)
 
     The log \e level gives information on the importance of the message. The list of log-levels is
     fixed. (see: \ref loglevels)
@@ -59,6 +59,15 @@
     or disabled at \e compile time. Messages disabled at compile time should not generate any
     code. (see: \ref SENF_LOG_CONF)
 
+    \attention The default log stream senf::log::Debug has senf::log::VERBOSE messages
+        <em>disabled</em> at compile time. senf::log::VERBOSE message will therefore only appear,
+        if you explictly enable the messages for the area in question using (here for the area
+        <code>some::Area</code>)
+        <pre> 
+        g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (some)(Area), VERBOSE ))" 
+        </pre>
+        in addition to routing the messages at runtime. For more, see \ref config.
+
     To be of any use, the log messages have to be written somewhere. This is the responsibility of
     any number of \e targets. A \e target receives messages and using it's routing information
     decides, wether the message is output or not. A message may be routed to multiple targets
@@ -74,12 +83,12 @@
 
         // Define a new log stream with default level, runtime limit and compile time limit 
         // set to senf::log::MESSAGE
-        SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
+        SENF_LOG_DEFINE_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
 
         class Froblizer
         {
             // Define a log area which will automatically be used by all members of this class.
-            // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
+            // This is a combination of SENF_LOG_DEFINE_AREA and SENF_LOG_DEFAULT_AREA.
             SENF_LOG_CLASS_AREA();
 
             // Set default log parameters for this scope.
@@ -89,7 +98,7 @@
             // Define an alias for emergency debug messages
             // The log area is inherited from the default at the place, where this
             // alias is used *not* where it is defined
-            SENF_LOG_DEF_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
+            SENF_LOG_DEFINE_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
 
             void test();
 

diff --git a/Utils/Logger/SenfLog.hh b/Utils/Logger/SenfLog.hh
index 11b839a..8a6c9c1 100644 (file)
--- a/Utils/Logger/SenfLog.hh
+++ b/Utils/Logger/SenfLog.hh
@@ -35,7 +35,7 @@
 
 namespace senf {
 
-    SENF_LOG_DEF_STREAM(SenfLog, senf::log::MESSAGE, senf::log::MESSAGE, SENF_SENFLOG_LIMIT);
+    SENF_LOG_DEFINE_STREAM(SenfLog, senf::log::MESSAGE, senf::log::MESSAGE, SENF_SENFLOG_LIMIT);
     SENF_LOG_DEFAULT_STREAM(SenfLog);
 
 }

diff --git a/Utils/Logger/Target.hh b/Utils/Logger/Target.hh
index 3d1f055..7c999b8 100644 (file)
--- a/Utils/Logger/Target.hh
+++ b/Utils/Logger/Target.hh
@@ -98,10 +98,10 @@ namespace log {
 
         The different object representations are:
         \li The \e streams is statically represented by it's name, which is the name of a class
-            defined with \ref SENF_LOG_DEF_STREAM. The dynamic representation is a string
+            defined with \ref SENF_LOG_DEFINE_STREAM. The dynamic representation is a string
             representation of this name.
         \li The \e area is statically represented by it's name, which again is the name of a class
-            defined with \ref SENF_LOG_DEF_STREAM. The dynamic representation again is a string
+            defined with \ref SENF_LOG_DEFINE_STREAM. The dynamic representation again is a string
             representation of this class's name. The dynamic representation represents an absent
             area with the empty string.
         \li The \e level is statically represented by a level class from \ref

diff --git a/Utils/Logger/main.test.hh b/Utils/Logger/main.test.hh
index 63a1a73..be89c33 100644 (file)
--- a/Utils/Logger/main.test.hh
+++ b/Utils/Logger/main.test.hh
@@ -53,9 +53,9 @@ namespace test {
         }
     };
 
-    SENF_LOG_DEF_ALIAS( LogCritical, (senf::log::Debug) (senf::log::CRITICAL) );
-    SENF_LOG_DEF_STREAM( myStream, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
-    SENF_LOG_DEF_AREA( myArea );
+    SENF_LOG_DEFINE_ALIAS( LogCritical, (senf::log::Debug) (senf::log::CRITICAL) );
+    SENF_LOG_DEFINE_STREAM( myStream, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
+    SENF_LOG_DEFINE_AREA( myArea );
 
 }}}
 

diff --git a/config.hh b/config.hh
index 2906030..44dddeb 100644 (file)
--- a/config.hh
+++ b/config.hh
@@ -73,7 +73,7 @@
 #     ifndef SENF_DEBUG
 #         define SENF_SENFLOG_LIMIT senf::log::IMPORTANT
 #     else
-#         define SENF_SENFLOG_LIMIT senf::log::VERBOSE
+#         define SENF_SENFLOG_LIMIT senf::log::NOTICE
 #     endif
 # endif
 #