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.
 */

/* (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;

// 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;
}

#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;
}

" 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

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

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 Documentation¶

4.2.3. API Header File Naming¶

4.2.4. API Symbol Naming¶

4.3. C Boilerplate¶

4.4. Line Formatting¶

4.5. Comments¶

4.6. Variables¶

4.7. Operators¶

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

4.9. Structures¶

4.10. Enumerations¶

4.10.1. Flag groups¶

4.11. Functions¶

4.11.1. Function Definitions¶

4.11.2. Return Values¶

4.11.3. Public API Functions¶

4.12. Memory Management¶

4.13. Logging¶

4.14. Regular Expressions¶

4.15. Makefiles¶

4.16. vim Settings¶

5. Evolution of the project¶

5.1. Foreword¶

5.2. Ancestor: Heartbeat project¶

5.2.1. Influence of Heartbeat on Pacemaker¶

5.3. Notable Restructuring Steps in the Codebase¶

6. Advanced Hacking on the Project¶

6.1. Foreword¶

6.2. Debugging¶

6.3. Working with mocked daemons¶

Index¶