Currently, each Pacemaker C library has a number of public, internal, and library-private headers, without a consistent policy for what should be a separate header or which headers source files should include.

We should adopt a consistent policy, maybe:

• Each source file BASENAME.c in a library would have corresponding headers for the APIs defined in it:
  • include/.../BASENAME.h for public APIs
  • include/.../BASENAME_internal.h for Pacemaker-internal APIs
  • lib/.../BASENAME_private.h for library-private APIs (these would remain under lib to make it difficult for source files outside the library to include them)
  • Constants, macros, types, static inline functions, etc. would go in a logically related header.

• Each library would have one top-level public header, one top-level internal header, and one top-level library header.
  • These would contain nothing except includes for all the library's other headers of that type.
  • Source files would include only these headers, never the subheaders directly.
  • The top-level headers would define a magic constant (like PCMK__DIRECT_INCLUDE) before including the subheaders, and undefine it after.
  • The subheaders should #error if the magic constant is not defined. This ensures that nothing besides the top-level headers can easily include the subheaders directly. This could be done immediately for internal and private headers, but public headers would need some leeway for existing external code.
    • Booth, DLM, and sbd are believed to be the only active external projects using the Pacemaker C API. They currently include crm/crm.h, crm_config.h, crm/cib.h, crm/common/ipc.h, crm/common/ipc_pacemakerd.h, crm/common/mainloop.h, crm/common/util.h, crm/common/xml.h, crm/cluster.h, crm/msg_xml.h, crm/pengine/pe_types.h, crm/pengine/status.h, crm/services.h, and crm/stonith-ng.h. Those headers would need to continue to exist under those names and define the same symbols, but they could be deprecated for internal use and simply include the new top-level header.

Feel free to create separate subtasks for particular libraries, to break this into more manageable chunks. (Keep in mind that some libraries may be consolidated as part of T222).