Pacemaker Development¶

Working with the Pacemaker Code Base

#!@PYTHON@

""" <BRIEF-DESCRIPTION>
"""

__copyright__ = "Copyright <YYYY[-YYYY]> the Pacemaker project contributors"
__license__ = "<LICENSE> WITHOUT ANY WARRANTY"

/*!
 * \internal
 * \brief Return string length plus 1
 *
 * Return the number of characters in a given string, plus one.
 *
 * \param[in] s  A string (must not be NULL)
 *
 * \return The length of \p s plus 1.
 */
static int
f(const char *s)
{
   return strlen(s) + 1;
}

/*
 * Copyright <YYYY[-YYYY]> the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under <LICENSE> WITHOUT ANY WARRANTY.
 */

#ifndef PCMK__MY_HEADER__H
#  define PCMK__MY_HEADER__H

// header code here

#endif // PCMK__MY_HEADER__H

#ifdef __cplusplus
extern "C" {
#endif

/*!
 * \file
 * \brief My brief description here
 * \ingroup core
 */

// header code here

#ifdef __cplusplus
}
#endif

/* Single-line comments may look like this */

// ... or this

/* Multi-line comments should start immediately after the comment opening.
 * Subsequent lines should start with an aligned asterisk. The comment
 * closing should be aligned and on a line by itself.
 */

// Operators have spaces on both sides
x = a;

/* (1) Do not rely on operator precedence; use parentheses when mixing
 *     operators with different priority, for readability.
 * (2) No space is used after an opening parenthesis or before a closing
 *     parenthesis.
 */
x = a + b - (c * d);

/*
 * (1) The control keyword is followed by a space, a left parenthesis
 *     without a space, the condition, a right parenthesis, a space, and the
 *     opening bracket on the same line.
 * (2) Always use braces around control statement blocks, even if they only
 *     contain one line. This makes code review diffs smaller if a line gets
 *     added in the future, and avoids the chance of bad indenting making a
 *     line incorrectly appear to be part of the block.
 * (3) The closing bracket is on a line by itself.
 */
if (v < 0) {
    return 0;
}

/* "else" and "else if" are on the same line with the previous ending brace
 * and next opening brace, separated by a space. Blank lines may be used
 * between blocks to help readability.
 */
if (v > 0) {
    return 0;

} else if (a == 0) {
    return 1;

} else {
    return 2;
}

/* Do not use assignments in conditions. This ensures that the developer's
 * intent is always clear, makes code reviews easier, and reduces the chance
 * of using assignment where comparison is intended.
 */
// Do this ...
a = f();
if (a) {
    return 0;
}
// ... NOT this
if (a = f()) {
    return 0;
}

/* It helps readability to use the "!" operator only in boolean
 * comparisons, and explicitly compare numeric values against 0,
 * pointers against NULL, etc. This helps remind the reader of the
 * type being compared.
 */
int i = 0;
char *s = NULL;
bool cond = false;

if (!cond) {
    return 0;
}
if (i == 0) {
    return 0;
}
if (s == NULL) {
    return 0;
}

/* In a "switch" statement, indent "case" one level, and indent the body of
 * each "case" another level.
 */
switch (expression) {
    case 0:
        command1;
        break;
    case 1:
        command2;
        break;
    default:
        command3;
        break;
}

/* (1) The asterisk goes by the variable name, not the type;
 * (2) Avoid leaving pointers uninitialized, to lessen the impact of
 *     use-before-assignment bugs
 */
char *my_string = NULL;

// Use space before asterisk and after closing parenthesis in a cast
char *foo = (char *) bar;

// Do this
if (bool1) {
    fn();
}
if (!bool2) {
    fn2();
}

// Not this
if (bool1 == true) {
    fn();
}
if (bool2 == false) {
    fn2();
}

// Otherwise there's no logical end ...
if ((bool1 == false) == true) {
    fn();
}

#include <stdint.h>

/* (1) Define an enumeration to name the individual flags, for readability.
 *     An enumeration is preferred to a series of "#define" constants
 *     because it is typed, and logically groups the related names.
 * (2) Define the values using left-shifting, which is more readable and
 *     less error-prone than hexadecimal literals (0x0001, 0x0002, 0x0004,
 *     etc.).
 * (3) Using a comma after the last entry makes diffs smaller for reviewing
 *     if a new value needs to be added or removed later.
 */
enum pcmk__some_bitmask_type {
    pcmk__some_value    = (1 << 0),
    pcmk__other_value   = (1 << 1),
    pcmk__another_value = (1 << 2),
};

/* The flag group itself should be an unsigned type from stdint.h (not
 * the enum type, since it will be a mask of the enum values and not just
 * one of them). uint32_t is the most common, since we rarely need more than
 * 32 flags, but a smaller or larger type could be appropriate in some
 * cases.
 */
uint32_t flags = pcmk__some_value|pcmk__other_value;

/* If the values will be used only with uint64_t, define them accordingly,
 * to make compilers happier.
 */
enum pcmk__something_else {
    pcmk__whatever    = (UINT64_C(1) << 0),
};

/*
 * (1) The return type goes on its own line
 * (2) The opening brace goes by itself on a line
 * (3) Use "const" with pointer arguments whenever appropriate, to allow the
 *     function to be used by more callers.
 */
int
my_func1(const char *s)
{
    return 0;
}

/* Functions with no arguments must explicitly list them as void,
 * for compatibility with strict compilers
 */
int
my_func2(void)
{
    return 0;
}

/*
 * (1) For functions with enough arguments that they must break to the next
 *     line, align arguments with the first argument.
 * (2) When a function argument is a function itself, use the pointer form.
 * (3) Declare functions and file-global variables as ``static`` whenever
 *     appropriate. This gains a slight efficiency in shared libraries, and
 *     helps the reader know that it is not used outside the one file.
 */
static int
my_func3(int bar, const char *a, const char *b, const char *c,
         void (*callback)())
{
    return 0;
}

/* The following will log a simple message in the system log, like:

       warning: Action failed: Node not found

   with extra detail in the detail log, like:

       warning: Action failed: Node not found | rc=-1005 id=hgjjg-51006
*/
crm_warn("Action failed: %s " CRM_XS " rc=%d id=%s",
         pcmk_rc_str(rc), rc, id);

" follow Pacemaker coding guidelines when editing C source code files
filetype plugin indent on
au FileType c   setlocal expandtab tabstop=4 softtabstop=4 shiftwidth=4 textwidth=80
autocmd BufNewFile,BufRead *.h set filetype=c
let c_space_errors = 1

$ make -C devel COCCI_FILES=coccinelle/new-file.cocci cocci

$ ASAN_OPTIONS=verbosity=1:replace_str=true crm_mon -1R

$ CFLAGS=-fsanitize=integer-divide-by-zero ./configure --with-sanitizers=ubsan

/lib/*/tests/*/*_test

check_PROGRAMS = \
       pcmk__add_word_test             \
       pcmk__btoa_test                 \
       pcmk__scan_port_test

dnl Other files we output
AC_CONFIG_FILES(Makefile                                            \
                ...
                lib/common/tests/Makefile                           \
                lib/common/tests/acls/Makefile                      \
                lib/common/tests/agents/Makefile                    \
                ...
)

SUBDIRS = agents acls cmdline flags operations strings utils xpath results

check_PROGRAMS = pcmk_acl_required_test

AM_CPPFLAGS += -I$(top_srcdir)
LDADD += $(top_builddir)/lib/pengine/libpe_status_test.la

dnl Other files we output
AC_CONFIG_FILES(Makefile                                            \
                ...
                lib/lrmd/Makefile                                   \
                lib/lrmd/tests/Makefile                             \
                lib/services/Makefile                               \
                ...
)

SUBDIRS = tests

SUBDIRS = lrmd_alerts

/*
 * Copyright 2021 the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under the GNU Lesser General Public License
 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
 */

#include <crm_internal.h>

#include <crm/common/unittest_internal.h>

/* Put your test-specific includes here */

/* Put your test functions here */

PCMK__UNIT_TEST(NULL, NULL,
                /* Register your test functions here */)

static void
regex(void **state) {
    const char *s1 = "abcd";
    const char *s2 = "ABCD";

    assert_true(pcmk__strcmp(NULL, "a..d", pcmk__str_regex) < 0);
    assert_true(pcmk__strcmp(s1, NULL, pcmk__str_regex) > 0);
    assert_int_equal(pcmk__strcmp(s1, "a..d", pcmk__str_regex), 0);
}

PCMK__UNIT_TEST(NULL, NULL,
                cmocka_unit_test(regex))

static void
null_input_variables(void **state)
{
    long long start, end;

    pcmk__assert_asserts(pcmk__parse_ll_range("1234", NULL, &end));
    pcmk__assert_asserts(pcmk__parse_ll_range("1234", &start, NULL));
}

PASS: pcmk__strcmp_test 1 - same_pointer
PASS: pcmk__strcmp_test 2 - one_is_null
PASS: pcmk__strcmp_test 3 - case_matters
PASS: pcmk__strcmp_test 4 - case_insensitive
PASS: pcmk__strcmp_test 5 - regex
============================================================================
Testsuite summary for pacemaker 2.1.0
============================================================================
# TOTAL: 33
# PASS:  33
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================
make[7]: Leaving directory '/home/clumens/src/pacemaker/lib/common/tests/strings'

PASS: pcmk__scan_double_test 3 - trailing_chars
FAIL: pcmk__scan_double_test 4 - typical_case
PASS: pcmk__scan_double_test 5 - double_overflow
PASS: pcmk__scan_double_test 6 - double_underflow
ERROR: pcmk__scan_double_test - exited with status 1
PASS: pcmk__starts_with_test 1 - bad_input
============================================================================
Testsuite summary for pacemaker 2.1.0
============================================================================
# TOTAL: 56
# PASS:  54
# SKIP:  0
# XFAIL: 0
# FAIL:  1
# XPASS: 0
# ERROR: 1
============================================================================
See lib/common/tests/strings/test-suite.log
Please report to users@clusterlabs.org
============================================================================
make[7]: *** [Makefile:1218: test-suite.log] Error 1
make[7]: Leaving directory '/home/clumens/src/pacemaker/lib/common/tests/strings'

ERROR: pcmk__scan_double_test
=============================

1..6
ok 1 - empty_input_string
PASS: pcmk__scan_double_test 1 - empty_input_string
ok 2 - bad_input_string
PASS: pcmk__scan_double_test 2 - bad_input_string
ok 3 - trailing_chars
PASS: pcmk__scan_double_test 3 - trailing_chars
not ok 4 - typical_case
FAIL: pcmk__scan_double_test 4 - typical_case
# 0.000000 != 3.000000
# pcmk__scan_double_test.c:80: error: Failure!
ok 5 - double_overflow
PASS: pcmk__scan_double_test 5 - double_overflow
ok 6 - double_underflow
PASS: pcmk__scan_double_test 6 - double_underflow
# not ok - tests
ERROR: pcmk__scan_double_test - exited with status 1

$ ./configure --with-coverage
$ make

Q:	Who is this document intended for?
A:	Anyone who wishes to read and/or edit the Pacemaker source code. Casual contributors should feel free to read just this FAQ, and consult other chapters as needed.

Q:	How do I build from the source code?
A:	See INSTALL.md in the main checkout directory.

Q:	What if I still have questions?
A:	Ask on the developers@ClusterLabs.org mailing list for development-related questions, or on the users@ClusterLabs.org mailing list for general questions about using Pacemaker. Developers often also hang out on the [ClusterLabs IRC channel](https://wiki.clusterlabs.org/wiki/ClusterLabs_IRC_channel).

Directory	Contents
daemons	the Pacemaker daemons (pacemakerd, pacemaker-based, etc.)
include	header files for library APIs
lib	libraries
tools	command-line tools

Library	Symbol prefix	Source location	API Headers	Description
libcib	cib	lib/cib	include/crm/cib.h include/crm/cib/*	API for pacemaker-based IPC and the CIB
libcrmcluster	pcmk	lib/cluster	include/crm/cluster.h include/crm/cluster/*	Abstract interface to underlying cluster layer
libcrmcommon	pcmk	lib/common	include/crm/common/* some of include/crm/*	Everything else
libcrmservice	svc	lib/services	include/crm/services.h	Abstract interface to supported resource types (OCF, LSB, etc.)
liblrmd	lrmd	lib/lrmd	include/crm/lrmd*.h	API for pacemaker-execd IPC
libpacemaker	pcmk	lib/pacemaker	include/pacemaker.h include/pcmki/	High-level APIs equivalent to command-line tool capabilities (and high-level internal APIs)
libpe_rules	pe	lib/pengine	include/crm/pengine/*	Scheduler functionality related to evaluating rules
libpe_status	pe	lib/pengine	include/crm/pengine/*	Low-level scheduler functionality
libstonithd	stonith	lib/fencing	include/crm/stonith-ng.h include/crm/fencing/*	API for pacemaker-fenced IPC

Sanitizer	Configure Option	Library	Environment Variable
Address	–with-sanitizers=asan	libasan	ASAN_OPTIONS
Threads	–with-sanitizers=tsan	libtsan	TSAN_OPTIONS
Undefined behavior	–with-sanitizers=ubsan	libubsan	UBSAN_OPTIONS

Pacemaker Development¶

Abstract¶

Table of Contents¶

1. Frequently Asked Questions¶

2. General Guidelines for All Languages¶

2.1. Copyright¶

3. Python Coding Guidelines¶

3.1. Python Boilerplate¶

3.2. Python Version Compatibility¶

3.3. Formatting Python Code¶

4. C Coding Guidelines¶

4.1. Code Organization¶

4.2. Pacemaker Libraries¶

4.2.1. Public versus Internal APIs¶

4.2.2. API Symbol Naming¶

4.2.3. API Header File Naming¶

4.2.4. API Documentation¶

4.2.5. Public API Deprecation¶

4.3. C Boilerplate¶

4.4. Line Formatting¶

4.5. Comments¶

4.6. Operators¶

4.7. Control Statements (if, else, while, for, switch)¶

4.8. Macros¶

4.9. Memory Management¶

4.10. Structures¶

4.11. Variables¶

4.11.1. Pointers¶

4.11.2. Globals¶

4.11.3. Variable Naming¶

4.11.4. Booleans¶

4.12. String Handling¶

4.12.1. Define Constants for Magic Strings¶

4.12.2. String-Related Library Functions¶

4.12.3. char*, gchar*, and GString¶

4.12.4. Regular Expressions¶

4.13. Enumerations¶

4.13.1. Flag groups¶

4.14. Functions¶

4.14.1. Function Definitions¶

4.14.2. Return Values¶

4.14.3. Public API Functions¶

4.15. Logging and Output¶

4.15.1. Logging Vs. Output¶

4.15.2. Common Guidelines for All Messages¶

4.15.3. Logging¶

4.15.4. Output¶

4.16. Makefiles¶

4.17. vim Settings¶

5. Coding Particular Pacemaker Components¶

5.1. Controller¶

5.1.1. Join sequence¶

5.2. Fencer¶

5.2.1. Initiating a fencing request¶

5.2.2. Fencing queries¶

5.2.3. Fencing operations¶

5.2.4. Fencing replies¶

5.2.5. Fencing History¶

5.3. Scheduler¶

5.3.1. Challenges¶

5.3.2. Cluster Working Set¶

5.3.3. Resources¶

5.3.4. Nodes¶

5.3.5. Actions¶

5.3.6. Colocations¶

5.3.7. Orderings¶

6. C Development Helpers¶

6.1. Refactoring¶

6.2. Sanitizers¶

6.3. Unit Testing¶

6.3.1. Organization¶

6.3.2. Adding a test¶

6.3.2.1. Testing a new function in an already testable source file¶

6.3.2.2. Testing a function in a source file without tests¶

6.3.2.3. Testing a function in a library without tests¶

6.3.2.4. Adding to an existing test case¶

6.3.3. Writing the test¶

6.3.4. Assertions¶

6.3.5. Running¶

6.4. Code Coverage¶

4.12.3. char, gchar, and GString¶