diff --git a/devel/Makefile.am b/devel/Makefile.am index cefe3e0a23..a18a962f69 100644 --- a/devel/Makefile.am +++ b/devel/Makefile.am @@ -1,67 +1,67 @@ # # Copyright 2020 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # # Coccinelle is a tool that takes special patch-like files (called semantic patches) and # applies them throughout a source tree. This is useful when refactoring, changing APIs, # catching dangerous or incorrect code, and other similar tasks. It's not especially # easy to write a semantic patch but most users should only be concerned about running # the target and inspecting the results. # # Documentation (including examples, which are the most useful): # https://coccinelle.gitlabpages.inria.fr/website/docs/ # # Run the "make cocci" target to just output what would be done, or "make cocci-inplace" # to apply the changes to the source tree. # # COCCI_FILES may be set on the command line, if you want to test just a single file # while it's under development. Otherwise, it is a list of all the files that are ready # to be run. # # ref-passed-variables-inited.cocci seems to be returning some false positives around # GHashTableIters, so it is disabled for the moment. COCCI_FILES ?= coccinelle/string-any-of.cocci \ coccinelle/string-empty.cocci \ coccinelle/string-null-matches.cocci \ coccinelle/use-func.cocci dist_noinst_SCRIPTS = coccinelle/test/testrunner.sh -EXTRA_DIST = $(COCCI_FILES) \ +EXTRA_DIST = gdbhelpers $(COCCI_FILES) \ coccinelle/ref-passed-variables-inited.cocci \ coccinelle/string-replacements.cocci \ coccinelle/test/ref-passed-variables-inited.input.c \ coccinelle/test/ref-passed-variables-inited.output # Any file in this list is allowed to use any of the pcmk__ internal functions. # Coccinelle can use any transformation that depends on "internal" to rewrite # code to use the internal functions. MAY_USE_INTERNAL_FILES = $(shell find .. -path "../lib/*.c" -o -path "../tools/*.c" -o -path "../daemons/*.c" -o -path '../include/pcmki/*h' -o -name '*internal.h') # And then any file in this list is public API, which may not use internal # functions. Thus, only those transformations that do not depend on "internal" # may be applied. OTHER_FILES = $(shell find ../include -name '*h' -a \! -name '*internal.h' -a \! -path '../include/pcmki/*') cocci: -for cf in $(COCCI_FILES); do \ for f in $(MAY_USE_INTERNAL_FILES); do \ spatch $(_SPATCH_FLAGS) -D internal --very-quiet --local-includes --preprocess --sp-file $$cf $$f; \ done ; \ for f in $(OTHER_FILES); do \ spatch $(_SPATCH_FLAGS) --very-quiet --local-includes --preprocess --sp-file $$cf $$f; \ done ; \ done cocci-inplace: $(MAKE) $(AM_MAKEFLAGS) _SPATCH_FLAGS=--in-place cocci cocci-test: for f in coccinelle/test/*.c; do \ coccinelle/test/testrunner.sh $$f; \ done diff --git a/maint/gdb/gdbhelpers b/devel/gdbhelpers similarity index 100% rename from maint/gdb/gdbhelpers rename to devel/gdbhelpers diff --git a/doc/sphinx/Pacemaker_Development/hacking.rst b/doc/sphinx/Pacemaker_Development/hacking.rst index 5324fb407c..4a0e0870fd 100644 --- a/doc/sphinx/Pacemaker_Development/hacking.rst +++ b/doc/sphinx/Pacemaker_Development/hacking.rst @@ -1,69 +1,69 @@ Advanced Hacking on the Project ------------------------------- Foreword ######## This chapter aims to be a gentle introduction (or perhaps, rather a summarization of advanced techniques we developed for backreferences) to how deal with the Pacemaker internals effectively. For instance, how to: * debug with an ease * verify various interesting interaction-based properties or simply put, all that is in the interest of the core contributors on the project to know, master, and (preferably) also evolve -- way beyond what is in the presumed repertoire of a generic contributor role, which is detailed in other chapters of this guide. Therefore, if you think you will not benefit from any such details in the scope of this chapter, feel free to skip it. Debugging ######### In the GNU userland tradition, preferred way of debugging is based on ``gdb`` (directly or via specific frontends atop) that is widely available on platforms (semi-)supported with Pacemaker itself. To make some advanced debugging easier, we maintain a script defining some -useful helpers in ``extra/gdb/gdbhelpers`` file, which you can make available +useful helpers in ``devel/gdbhelpers`` file, which you can make available in the debugging session easily when invoking it as ``gdb -x ...``. From within the debugger, you can then invoke the new ``pcmk`` command that will guide you regarding other helper functions available, so we won't replicate that here. Working with mocked daemons ########################### Since the Pacemaker run-time consists of multiple co-operating daemons as detailed elsewhere, tracking down the interaction details amongst them can be rather cumbersome. Since rebuilding existing daemons in a more modular way as opposed to clusters of mutually dependent functions, we elected to grow separate bare-bones counterparts built evolutionary as skeletons just to get the basic (long-term stabilized) communication with typical daemon clients going, and to add new modules in their outer circles (plus minimalistic hook support at those cores) on a demand-driven basis. The code for these is located at ``maint/mocked``; for instance, ``based-notifyfenced.c`` module of ``based.c`` skeleton mocking ``pacemaker-based`` daemon was exactly to fulfill investigation helper role (the case at hand was also an impulse to kick off this very sort of maintenance support material, to begin with). Non-trivial knowledge of Pacemaker internals and other skills are needed to use such devised helpers, but given the other way around, some sorts of investigation may be even heftier, it may be the least effort choice. And when that's the case, advanced contributors are expected to contribute their own extensions they used to validate the reproducibility/actual correctness of the fix along the actual code modifications. This way, the rest of the development teams is not required to deal with elaborate preconditions, be at guess, or even forced to use a blind faith regarding the causes, consequences and validity regarding the raised issues/fixes, for the greater benefit of all.