|
@@ -0,0 +1,68 @@
|
|
|
+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.
|