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.  The following are a sample snippet for Makefile.in 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)/mymodule_messages.py
pylogmessagedir = $(pyexecdir)/isc/log_messages/

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

EXTRA_DIST = mymodule_messages.mes

BUILT_SOURCES = $(PYTHON_LOGMSGPKG_DIR)/mymodule_messages.py
CLEANFILES += $(PYTHON_LOGMSGPKG_DIR)/mymodule_messages.py
CLEANFILES += $(PYTHON_LOGMSGPKG_DIR)/mymodule_messages.pyc
EXTRA_DIST += $(PYTHON_LOGMSGPKG_SRCDIR)/mymodule_messages.py

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

$(PYTHON_LOGMSGPKG_DIR)/mymodule_messages.py: Makefile
	echo "from work.mymodule_messages import *" > $@

# 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)/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.  $(PYTHON_LOGMSGPKG_SRCDIR) should be set to point
  to this directory by the configure script.
- The four lines starting from BUILT_SOURCES and the second make rule
  are for preparing the dummy python file under the source tree.
  Note that EXTRA_DIST is specified so that the python script is
  placed in the source tree (not only in the build tree when these
  two are different).  If you don't like this trick, you could
  directly add the file in this directory alternatively.