Code modules

By definition, a Contexo code module is an encapsulated, self-contained source code component with distinct purpose and functionality. The interface (if any) of the code module is provided by one or more public header files where its public interface is declared.

Contexo exercises a strict filesystem structure for code modules. The main reasons for this is to ensure a unified outline of sourcecode components and to relieve the system from having to deal with yet another format for specifying details of how a particular module is organized. This strategy leads to a clear deviation from “regular” build systems that no configuration format exists for specifying individual source and headerfiles – all sourcefiles hosted by the module are unconditionally built when the module is included in a build session.

Directory structure

A Contexo code module is defined by its filesystem structure. An invalid directory structure will be rejected by the system at build time.

The name of the module’s root directory serves as the title of the module. A code module may contain any kind of directories and files but must comply to at least the following outline:

[module_name]       - The root directory of the code module.
    [src]           - Subdirectory for source files.
    [inc]           - Subdirectory for internal header files. 
    [contexo]       - Build system files. 
    [output]        - Output directory, used mainly for intermediate build files.
    [doc]           - Documentation files.
    [test]          - Module test files.
    module_name.h   - Header defining the public interface.

The build system by its default bahaviour uses no interface or format for the user to specify the source files to build for the code module, all source files located within the src directory are used in the build. Source files with *.c extension are compiled as plain C, source files with *.cpp extension are compiled as C++. The inc directory is automatically appended to the include paths of the build environment when the module is included.

Note: There is no guarantee that a particular build session is performed with compiler tools capable of handling C++ source code. Using sufficient build tools for a particular code module is up to the user of the system.

Public interface

If a code module exposes a public interface through one or more header files, these must be located at the root directory of the codemodule and at least one of the header files must have the same name as the title of the code module and should serve as the “main” header. Even though multiple header files are allowed for the public interface, it is recommended to use only one whenever possible.

The public interface of a code module is included and used by other code modules depending on it. Code modules are prohibited to use any other components of eachother apart from the public interface. E.g a code module may not include header files located in the inc directory of itself or another code module.

Dependencies between code modules

Compile time dependencies between code modules are calculated by Contexo.
There is no longer any explicit format used for specifying dependencies.

Custom dependencies (e.g depending on third party components)

In some cases a code module may depend on components which are not conforming to the Contexo code module convention, which typically involves third party components. Such dependencies should be declared within a special dependency file called xdepends. The outline of this file is the same as for the regular dependency files, but instead of listing code module names it must list environment variables that point to the location of the interface header(s) of the required components.

This example shows a typical custom dependency declaration file, the module depends on RealView 2.1 and 2.2 headers, thus declaring two environment variables where the include files for these interfaces may be found:

------- contexo/xdepends ------------------
RVCT21INC
RVCT22INC
-------------------------------------------

The declaration of these variables may for instance look like this:

RVCT21INC=C:\Program Files\ARM\RVCT\Data\2.1\328\include\windows
RVCT22INC=C:\Program Files\ARM\RVCT\Data\2.2\349\include\windows

Note: It is allowed for environment variables to specify multiple paths delimited by semicolon.

Module tests

todo: Describe how Contexo uses the test directory for unit tests.