kea/src/lib/python/isc/log_messages/README

This is a placeholder package for logging messages of various modules
in the form of python scripts.  This package is expected to be installed
somewhere like <top-install-dir>/python3.x/site-packages/isc/log_messages
and each message script is expected to be imported as
"isc.log_messages.some_module_messages".

We also need to allow in-source test code to get access to the message
scripts in the same manner.  That's why the package is stored in the
directory that shares the same trailing part as the install directory,
i.e., isc/log_messages.

Furthermore, we need to support a build mode using a separate build
tree (such as in the case with 'make distcheck').  In that case if an
application (via a test script) imports "isc.log_messages.xxx", it
would try to import the module under the source tree, where the
generated message script doesn't exist.  So, in the source directory
(i.e., here) we provide dummy scripts that subsequently import the
same name of module under the "work" sub-package.  The caller
application is assumed to have <top_builddir>/src/lib/python/isc/log_messages
in its module search path (this is done by including
$(COMMON_PYTHON_PATH) in the PYTHONPATH environment variable),
which ensures the right directory is chosen.

A python module or program that defines its own log messages needs to
make sure that the setup described above is implemented.  It's a
complicated process, but can generally be done by following a common
pattern:

1. Create the dummy script (see above) for the module and update
   Makefile.am in this directory accordingly.  See (and use)
   a helper shell script named gen-forwarder.sh.
2. Update Makefil.am of the module that defines the log message.  The
   following are a sample snippet for Makefile.am for a module named
   "mymodule" (which is supposed to be generated from a file
   "mymodule_messages.mes").  In many cases it should work simply by
   replacing 'mymodule' with the actual module name.

====================  begin Makefile.am additions ===================
nodist_pylogmessage_PYTHON = $(PYTHON_LOGMSGPKG_DIR)/work/mymodule_messages.py
pylogmessagedir = $(pyexecdir)/isc/log_messages/

CLEANFILES = $(PYTHON_LOGMSGPKG_DIR)/work/mymodule_messages.py
CLEANFILES += $(PYTHON_LOGMSGPKG_DIR)/work/mymodule_messages.pyc

EXTRA_DIST = mymodule_messages.mes

$(PYTHON_LOGMSGPKG_DIR)/work/mymodule_messages.py : mymodule_messages.mes
	$(top_builddir)/src/lib/log/compiler/message \
	-d $(PYTHON_LOGMSGPKG_DIR)/work -p $(srcdir)/mymodule_messages.mes

# This rule ensures mymodule_messages.py is (re)generated as a result of
# 'make'.  If there's no other appropriate target, specify
# mymodule_messages.py in BUILT_SOURCES.
mymodule: <other source files> $(PYTHON_LOGMSGPKG_DIR)/work/mymodule_messages.py
=====================  end Makefile.am additions ====================

Notes:
- "nodist_" prefix is important.  Without this, 'make distcheck' tries
  to make _messages.py before actually starting the main build, which
  would fail because the message compiler isn't built yet.
- "pylogmessage" is a prefix for python scripts that define log
  messages and are expected to be installed in the common isc/log_messages
  directory.   It's intentionally named differently from the common
  "python" prefix (as in python_PYTHON), because the latter may be
  used for other scripts in the same Makefile.am file.
- $(PYTHON_LOGMSGPKG_DIR) should be set to point to this directory (or
  the corresponding build directory if it's different) by the
  configure script.