Commit bcff2ef4 authored by Francis Dupont's avatar Francis Dupont
Browse files

[3734] removed python from log library and compiler

parent 95750a3a
// Copyright (C) 2011,2015 Internet Systems Consortium, Inc. ("ISC")
// Copyright (C) 2011, 2015 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
......@@ -58,16 +58,15 @@ static const char* VERSION = "1.0-0";
/// \b Invocation<BR>
/// The program is invoked with the command:
///
/// <tt>message [-v | -h | -p | -d &lt;dir&gt; | <message-file>]</tt>
/// <tt>message [-v | -h | -d &lt;dir&gt; | <message-file>]</tt>
///
/// It reads the message file and writes out two files of the same
/// name in the current working directory (unless -d is used) but
/// with extensions of .h and .cc, or .py if -p is used.
/// with extensions of .h and .cc.
///
/// -v causes it to print the version number and exit. -h prints a help
/// message (and exits). -p sets the output to python. -d &lt;dir&gt; will make
/// it write the output file(s) to dir instead of current working
/// directory
/// -v causes it to print the version number and exit. -h prints a
/// help message (and exits). -d &lt;dir&gt; will make it write the
/// output file(s) to dir instead of current working directory
/// \brief Print Version
......@@ -86,11 +85,10 @@ version() {
void
usage() {
cout <<
"Usage: message [-h] [-v] [-p] [-d dir] <message-file>\n" <<
"Usage: message [-h] [-v] [-d dir] <message-file>\n" <<
"\n" <<
"-h Print this message and exit\n" <<
"-v Print the program version and exit\n" <<
"-p Output python source instead of C++ ones\n" <<
"-d <dir> Place output files in given directory\n" <<
"\n" <<
"<message-file> is the name of the input message file.\n";
......@@ -249,53 +247,6 @@ writeClosingNamespace(ostream& output, const vector<string>& ns) {
}
}
/// \brief Write python file
///
/// Writes the python file containing the symbol definitions as module level
/// constants. These are objects which register themselves at creation time,
/// so they can be replaced by dictionary later.
///
/// \param file Name of the message file. The source code is written to a file
/// file of the same name but with a .py suffix.
/// \param dictionary The dictionary holding the message definitions.
/// \param output_directory if not null NULL, output files are written
/// to the given directory. If NULL, they are written to the current
/// working directory.
///
/// \note We don't use the namespace as in C++. We don't need it, because
/// python file/module works as implicit namespace as well.
void
writePythonFile(const string& file, MessageDictionary& dictionary,
const char* output_directory)
{
Filename message_file(file);
Filename python_file(Filename(message_file.name()).useAsDefault(".py"));
if (output_directory != NULL) {
python_file.setDirectory(output_directory);
}
// Open the file for writing
ofstream pyfile(python_file.fullName().c_str());
// Write the comment and imports
pyfile <<
"# File created from " << message_file.fullName() << " on " <<
currentTime() << "\n" <<
"\n" <<
"import isc.log\n" <<
"\n";
vector<string> idents(sortedIdentifiers(dictionary));
BOOST_FOREACH(const string& ident, idents) {
pyfile << ident << " = isc.log.create_message(\"" <<
ident << "\", \"" << quoteString(dictionary.getText(ident)) <<
"\")\n";
}
pyfile.close();
}
/// \brief Write Header File
///
/// Writes the C++ header file containing the symbol definitions. These are
......@@ -541,7 +492,6 @@ main(int argc, char* argv[]) {
optind = 1; // Ensure we start a new scan
int opt; // Value of the option
bool doPython = false;
const char *output_directory = NULL;
while ((opt = getopt(argc, argv, soptions)) != -1) {
......@@ -550,10 +500,6 @@ main(int argc, char* argv[]) {
output_directory = optarg;
break;
case 'p':
doPython = true;
break;
case 'h':
usage();
return (0);
......@@ -592,29 +538,18 @@ main(int argc, char* argv[]) {
// Error (and quit) if there are of any duplicates encountered.
errorDuplicates(reader);
if (doPython) {
// Warn in case of ignored directives
if (!reader.getNamespace().empty()) {
cerr << "Python mode, ignoring the $NAMESPACE directive" <<
endl;
}
// Write the whole python file
writePythonFile(message_file, dictionary, output_directory);
} else {
// Get the namespace into which the message definitions will be put and
// split it into components.
vector<string> ns_components =
splitNamespace(reader.getNamespace());
// Write the header file.
writeHeaderFile(message_file, ns_components, dictionary,
output_directory);
// Write the file that defines the message symbols and text
writeProgramFile(message_file, ns_components, dictionary,
output_directory);
}
// Get the namespace into which the message definitions will be put and
// split it into components.
vector<string> ns_components =
splitNamespace(reader.getNamespace());
// Write the header file.
writeHeaderFile(message_file, ns_components, dictionary,
output_directory);
// Write the file that defines the message symbols and text
writeProgramFile(message_file, ns_components, dictionary,
output_directory);
}
catch (const MessageException& e) {
......
// Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
// Copyright (C) 2011, 2015 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
......@@ -45,11 +45,6 @@
/// In this way users can have some expectation of what will be output when
/// enabling debugging. Symbols are prefixed DBGLVL so as not to clash with
/// DBG_ symbols in the various modules.
///
/// \note If the names of debug constants are changed, or if ones are added or
/// removed, edit the file src/lib/python/isc/log/log.cc to update the log
/// level definitions available to Python. The change does not need to be
/// made if only the numeric values of constants are updated.
namespace {
......
......@@ -121,10 +121,10 @@ logger. The top of the hierarchy is the root logger; this does not
have a parent. The reason for this hierarchy is that unless a logger
explicitly assigns a value to an attribute (such as severity of messages
it should log), it picks it up the value from the parent. In Kea,
each component (b10-dhcp4, b10-dhcp-ddns etc.) has a root logger (named
each component (kea-dhcp4, kea-dhcp-ddns etc.) has a root logger (named
after the program) and every other logger in the component is a child
of that. So in the example above, the error/syslog attributes could be
associated with the b10-resolver logger while the logger associated with
associated with the kea-resolver logger while the logger associated with
the cache sets its own values for the debug/file attributes.
More information about the logging hierarchy can be found in the section
......@@ -177,11 +177,10 @@ compiling the message files of all Kea components and libraries.
For C++ development, the message compiler produces two files in the
default directory, having the same name as the input file but with file
types of ".h" and ".cc". For Python, the message compiler will produce
a Python module containing the symbols.</li>
types of ".h" and ".cc".</li>
<li>Include the resultant files in your source code to define message symbols,
and (for C++) compile the code and link it into your program.</li>
and compile the code and link it into your program.</li>
<li>Declare loggers in your code and use them to log messages.</li>
......@@ -351,17 +350,14 @@ programs.
The message compiler is a program built in the src/log/compiler directory.
It is invoked by the command:
@code
message [-h] [-v] [-p] [-d dir] <message-file>
message [-h] [-v] [-d dir] <message-file>
@endcode
"-v" prints the version number and exits; "-h" prints brief help text.
The compiler produces source files for C++ unless the "-p" switch is
specified, in which case it produces Python code. Finally, the "-d"
switch directs the compiler to produce the output files in the specified
directory (the default being the current working directory).
Finally, the "-d" switch directs the compiler to produce the output
files in the specified directory (the default being the current
working directory).
<b>C++ Files</b><br/>
Without the "-p" option, the message compiler processes the message file
to produce two files:
<ol>
<li>A C++ header file (called <message-file-name>.h) holding lines of
......@@ -415,28 +411,13 @@ The appearance of such a message indicates a programming error.
</li>
</ol>
<b>Python Files</b><br/>
If the "-p" option is given, the compiler produces a Python module defining
the messages. The content of this is of the form:
@code
import isc.log
:
LOG_WRITE_ERROR = isc.log.create_message("LOG_WRITE_ERROR",
"error writing to %1 : %2")
@endcode
(The definition is output on one line - it is split across two lines in this
document for readability.)
The module can be imported into other Python code, and messages logged
in a similar way to C++ using the Python logging library.
@subsubsection logMakefile Include Message Compilation in Makefile
The source file for the messages is the ".mes" file, but the files used
by the code (which, in the case of C++, must be compiled and linked)
are the output of the message compiler. (The compiler is produced very
early on in the Kea build sequence, so is available for use in the
building of subsequent components.) To allow this, certain dependencies
must be included in the Makefile.am for each component that uses logging.
The source file for the messages is the ".mes" file, but the files
used by the code which must be compiled and linked are the output of
the message compiler. (The compiler is produced very early on in the
Kea build sequence, so is available for use in the building of
subsequent components.) To allow this, certain dependencies must be
included in the Makefile.am for each component that uses logging.
<b>Including Message files in C++ Component Builds</b><br/>
The following segment from the "hooks" Makefile.am illustrates
......@@ -485,31 +466,6 @@ These files are therefore included in the definition of the CLEANFILES macro.
Not shown are the Makefile.am lines where the .h and .cc file are used. These
are the same as other lines specifying .h and .cc source files.
<b>Including Message files in Python Component Builds</b><br/>
The following (modified) segments from the "xfrin" Makefile.am illustrates
the entries needed.
@code
CLEANFILES = $(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.py
CLEANFILES += $(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.pyc
:
EXTRA_DIST += xfrin_messages.mes
:
# Define rule to build logging source files from message file
$(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.py : xfrin_messages.mes
$(top_builddir)/src/lib/log/compiler/message \
-d $(PYTHON_LOGMSGPKG_DIR)/work -p $(srcdir)/xfrin_messages.mes
@endcode
The CLEANFILES lines remove the created Python (and compiled Python)
code when "make clean" is run.
The EXTRA_DIST line ensures that the .mes file is copied to the
distribution tarball.
The final dependency shows the use of the message compiler to
create the Python message module in a working directory.
@subsection logUsage Using Logging Files in Program Development
@subsubsection logCppUsage Use in a C++ Program or Module
......@@ -529,8 +485,8 @@ in file scope. The string passed to the constructor is the name of
the logger (it can be any string) and is used when configuring it.
(Remember though that the name of root logger for the program will be
prepended to the name chosen. So if, for example, the name "cache"
is chosen and the model is included in the "b10-resolver" program, the
full name of the logger will be "b10-resolver.cache".) Loggers with
is chosen and the model is included in the "kea-resolver" program, the
full name of the logger will be "kea-resolver.cache".) Loggers with
the same name share the same configuration. For this reason if, as is
usual, messages logged in different files in the same component (e.g.
hooks module, nameserver address store, etc.) originate from loggers
......@@ -565,34 +521,6 @@ messages of INFO severity or above).</li>
level, and external message file.
</ol>
@subsubsection logPythonUsage Use in a Python Module
To use logging in a Python module:
<ol>
<li>Build message module as described above.</li>
<li>Declare a logger through which the message will be logged.
@code
isc.log.Logger logger("name")
@endcode
The string passed to the constructor is the name of the logger (it can
be any string) and is used when configuring it. Loggers with the same
name share the same configuration.</li>
<li>Issue calls to the logging methods:
@code
logger.error(LOG_WRITE_ERROR, "output.txt")
@endcode
The message parameters are included as trailing arguments in the
logger call.</li>
<li>The main program unit must include a call to isc.log.init() (described
in more detail below) to set the to set the logging severity, debug log
level, and external message file. The settings remain in effect until
the logging configuration is read, so are the ones used during program
initialization.</li>
</ol>
@subsection logInitialization Logging Initialization
In all cases, if an attempt is made to use a logging method before
the logging has been initialized, the program will terminate with a
......@@ -615,7 +543,7 @@ Arguments are:
<dl>
<dt><code>root</code></dt>
<dd>Name of the root logger. This should be the name of the program
(e.g. "b10-auth") and is used when configuring logging.</dd>
(e.g. "kea-auth") and is used when configuring logging.</dd>
<dt><code>severity</code></dt>
<dd>Default severity that the program will start logging with. Although
......@@ -732,38 +660,6 @@ instance from the global dictionary.
The hook library itself must not perform any action to register or
unregister log messages in the global dictionary!
@subsection logInitializationPython Python Initialization
To initialize the logger in a Python program, the "init" method must be
called:
@code
isc.log.init(name, severity, debuglevel, file, buffer)
@endcode
<dl>
<dt><code>name</code></dt>
<dd>String giving the name of the root logger. This is the only mandatory
argument, the rest are optional.</dd>
<dt><code>severity</code></dt>
<dd>The severity, and is one of the strings "DEBUG", INFO" etc.
The default is "INFO".</dd>
<dt><code>debuglevel</code></dt>
<dd>Debug level, an integer between 0 and 99. A default value of 0 will
be used if this is not specified.</dd>
<dt><code>file</code></dt>
<dd>Name of the external message file (if present). By default, no
external message file is used.</dd>
<dt><code>buffer</code></dt>
<dd>If set to true, initial log messages will be internally buffered,
until the first time a logger specification is processed. This
way the program can use logging before even processing its logging
configuration. By default, no buffer is used.</dd>
</dl>
@section logNotes Notes on the Use of Logging
One thing that should always be kept in mind is whether the logging
could be used as a means for a DOS attack. For example, if a warning
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment