Reasoning Technology (RT) C file control structure

+ +

Introduction

+ +

This document summarizes some of the coding conventions used in RT C projects. Discussed here are conventions for integrated header designs, ad hoc namespaces, and a structured approach to source file extensions. The document also outlines the associated build process using a standardized makefile.

+ +

Header file integration

+ +

RT C projects adopt an innovative approach by integrating headers directly into source files. This ensures consistency between interfaces and implementations, eliminating mismatches. Each file contains both an interface and an implementation section, gated by preprocessor directives.

+ +

Each RT C source file integrates its header directly into the source file. This locality makes header content easier to maintain as everything is found in a single file. It also eliminates the need to maintain two files for each module.

+ +

Each file has two sections

Interface section: Contains declarations, macros, and #includes needed for the interface. Ensures consistency by defining the interface exactly once, even when the file is included multiple times.
Implementation section: Contains function definitions and additional includes needed for the implementation. This section is compiled only when the file is used as an implementation.

+ +

Each section is turned on and off with the CPP macro IFACE.

+ +

Example


+// If not an IFACE, then an IMPLEMENTATION
+#ifndef IFACE
+  #define MyModuleÂ·IMPLEMENTATION
+  // Ensures included files are processed for their interfaces.
+  #define IFACE
+#endif
+
+// Define the interface exactly once.
+#ifndef MyModuleÂ·IFACE
+#define MyModuleÂ·IFACE
+  // Interface-only includes go here.
+  void MyModuleÂ·function();
+#endif
+
+#ifdef MyModuleÂ·IMPLEMENTATION
+  // Additional includes for implementation go here.
+  #include 
+  void MyModuleÂ·function() {
+    printf("Hello, World!\n");
+  }
+#endif
+

+ +

Explanation

The example above demonstrates the structure and purpose of each block:

First block: Ensures that the file operates correctly based on the value of IFACE. If IFACE is undefined, it defines MyModuleÂ·IMPLEMENTATION to enable the implementation section and sets IFACE to ensure subsequent includes process interface sections.

Second block: Defines the interface, including declarations and interface-specific includes. The #ifndef MyModuleÂ·IFACE macro ensures the interface is defined exactly once, regardless of how many times the file is included.

Third block: Contains implementation-specific includes and function definitions. Guarded by MyModuleÂ·IMPLEMENTATION, it is only included when compiling the implementation.

Interface includes are placed in the interface block, ensuring they are available wherever the interface is used. Implementation includes are isolated in the implementation block, minimizing unnecessary dependencies in other files.

+ +

Namespace conventions

RT projects use ad hoc namespaces to maintain clarity and prevent naming conflicts. This is achieved by prefixing exported identifiers with a module-specific name followed by the Â· (cdot) character.

+ +

Conventions

Prefix: The module name serves as the prefix, ensuring all identifiers are unique across the program.
Separator: The Â· character visually separates the prefix from the identifier name, maintaining readability and avoiding conflicts.

+ +

Example


+void ServerÂ·run();
+

+ +

Source file extensions

RT projects use standardized extensions to distinguish between library and command-line interface (CLI) source files:

.lib.c: Files implementing library functions.
.cli.c: Files implementing command-line tools.

+ +

The .lib.c files compile into libraries, while .cli.c files compile into standalone executables. The makefile processes these files automatically, ensuring a clear separation of functionality.

+ +

Build process

The build process follows these steps:

Dependency generation: Run make dependency to create dependencies. This step is only required when the dependency structure changes.
Compilation: Run make cli to compile CLI sources and link them against the library. The makefile automatically manages targets and dependencies.

+ +

Benefits

Consistency: Integrated headers ensure interface and implementation are always in sync.
Modularity: Each file encapsulates its interface and implementation, reducing coupling.
Clarity: Ad hoc namespaces and standardized extensions improve readability and organization.
Efficiency: The makefile automates builds, minimizing errors and streamlining development.

+ +

Conclusion

This document outlines the conventions and practices for writing and building RT C projects. By integrating headers, adopting namespaces, and standardizing extensions, RT ensures its projects are robust, modular, and easy to maintain.