# 12.7. Source code

## 12.7.1. Code style

We intentionally do not have too many code conventions in the PMIx code base.

### 12.7.1.1. All languages

- 4 space tabs. No more, no less.

- NEVER use actual tab characters; always use spaces. Both emacs and vim have secret mojo that can automatically use spaces when you hit the `<TAB>` key. This makes the code look the same in every browser, regardless of individual tab display settings.

### 12.7.1.2. C / C++

- When comparing constants for equality or inequality, always put the constant on the left. This is defensive programming: if you have a typo in the test and miss a `!` or `=`, you’ll get a compiler error. For example:

      /* Do this */
      if (NULL == foo) { ... }

      /* Because if you have a typo (i.e., = instead of ==), this will
         be a compile error rather than a subtle bug */
      if (NULL = foo) { ... }

- More defensive programming: always include blocks in curly braces `{ }`, even if they are only one line long. For example:

      /* Do this */
      if (whatever) {
          return OMPI_SUCCESS;
      }

      /* Not this */
      if (whatever)
         return OMPI_SUCCESS;

- PMIx requires a C99-compliant compiler.

  - C++-style comments are now allowed (and preferred).

  - C99-style mixing declarations are allow allowable (and preferred).

- ALWAYS include `pmix_config.h` as your first #include file. There are very, very few cases where this is not true (E.g., some bizarre Windows scenarios). But in 99.9999% of cases, this file should be included first so that it can affect system-level #include files if necessary.

- Filenames and symbols must follow the prefix rule (see [e-mail thread](http://www.open-mpi.org/community/lists/devel/2009/07/6389.php)):

  - Filenames must be prefixed with `<framework>_<component>`.

  - Public symbols must be prefixed in components with `pmix_<framework>_<component>`. When in doubt about whether a symbol is public, be safe and add the prefix.

  - Non-public symbols must be declared `static` or otherwise made to not appear in the global scope.

- ALWAYS #define macros, even for logical values.

  - The GNU Way is to `#define` a macro when it is “true” and to `#undef` it when it is “false”.

  - In PMIx, we always `#define` a logical macro to be either 0 or 1 – we never `#undef` it.

  - The reason for this is defensive programming: if you are only checking if a preprocessor macro is defined (via `#ifdef FOO` or `#if defined(FOO)`), you will get no warning when compiling if you accidentally misspell the macro name. However, if you use the logic test `#if FOO` with an undefined macro (e.g., because you misspelled it), you’ll get a compiler warning or error.

    Rationale

    Misspelled macro names can be tremendously difficult to find when they are buried in thousands of lines of code; we will take all the help from the preprocessor/compiler that we can get!

      /* GNU Way - you will get no warning from the compiler if you
         misspell "FOO"; the test will simply be false */
      #ifdef FOO
      ...
      #else
      ...
      #endif

      /* PMIx Way - you will get a warning from the compiler if you
         misspell "FOO"; the result of the test is a different value
         than whether you spelled the macro name right or not */
      #if FOO
      ...
      #else
      ...
      #endif

### 12.7.1.3. Shell scripting

Please read some of the existing shell code in the source code tree and try to use a similar style.

- Always enclose evaluated shell variables in quotes to ensure that multi-token values are handled properly.

      # This is bad
      if test $foo = bar; then

      # This is good
      if test "$foo" = "bar"; then

  - The one exception to this is that when doing an assignment to a shell variable from another shell variable, it is not necessary to use quotes on the right hand side:

        # This is harmless, but unnecessary
        foo="$bar"

        # This is actually sufficient, even for multi-token values of $bar
        foo=$bar

- Do not use the `==` operator for `test` — this is a GNU extension and can cause portability problems on BSD systems. Instead, use the single `=` operator.

      # This is bad
      if test "$foo" == "bar"; then

      # This is good
      if test "$foo" = "bar"; then

### 12.7.1.4. m4

We do not have specific coding style guidelines for m4 (the language used to create the `configure` script). Please read some of the existing m4 code in the source code tree and try to use a similar style.

## 12.7.2. Tree layout

There are a few notable top-level directories in the source tree:

- The main PMIx source is under the `src` directory

- `config`: M4 scripts supporting the top-level `configure` script

- `etc`: Some miscellaneous text files

- `docs`: Source code for PMIx documentation

- `examples`: Trivial example programs

- `include`: The public PMIx headers

The `src` directory generates a top-level library named `libpmix`. It can be built as either a static or shared library. The directory structure under it includes:

- `class`: C++-like “classes” (using the OPAL class system) specific to this project

- `include`: Top-level internal include files

- `mca`: MCA frameworks and components specific to PMIx

- `runtime`: Startup and shutdown of PMIx at runtime

- `tools`: Executables specific to PMIx

- `util`: Random utility code

The layout of the `mca` tree is strictly defined to be of the form:

    mca/FRAMEWORK/COMPONENT

To be explicit: it is forbidden to have a directory under the `mca` tree that does not meet this template (with the exception of `base` directories, explained below). Hence, only framework and component code can be in the `mca` tree.

That is, framework and component names must be valid directory names (and C variables; more on that later). For example, the CLIENT PTL component is located in `mca/ptl/client/`.

The name `base` is reserved; there cannot be a framework or component named `base`. Directories named `base` are reserved for the implementation of the MCA and frameworks. Here are a few examples (as of the v5.0.x source tree):

    # Main implementation of the MCA
    mca/base

    # Implementation of the ptl framework
    mca/ptl/base

    # Implementation of the client component of the ptl framework
    mca/ptl/client

Under these mandated directories, frameworks and/or components may have arbitrary directory structures, however.

## 12.7.3. Symbol Visibility

The `PMIX_EXPORT` macro provides a method to annotate symbols to indicate their intended visibility when compiling dynamically shared object files (e.g., `libpmix.so`).

The macro expands to the appropriate compiler and platform flags for marking whether a symbol should be explicitly made public in the PMIx library namespace. The `PMIX_EXPORT` attribute is used to declare that a symbol is to be visible outside of the PMIx DSO’s scope.

Note

This is entirely related to dynamic library compilation and does not apply to static compilation.