Concerning the Database

We use a database to store semi-permanent build state. This page is where we document how that database is structured and any issues we are aware of.

Data Model

The database is split into a number of tables with relationships between them.

File Table

Each record in this table represents one file in the source tree or working directory. It holds only information strictly relating to the file object. Thus "filename" is appropriate as it comes from the filing system. A hash of the contents is also appropriate as it makes no interpretation of that content, instead treating it as a series of bytes.

Fortran Program Unit Table

This table is used to store information relating to the program units found in Fortran source files. This consists of a program unit name and the file it was found in.

Fortran Program Unit Prerequisite Table

Each program unit will depend on zero or more other program units. This information is captured in a table in which each record consists of a "dependor" and a "dependee".

C Symbol Table (Not yet on master)

This table stores information relating to the symbols found in C source files. Note that a symbol could be a C function, variable or typedef (if at file scope, and not declared "static"). The table consists of the symbol name and the file it was found in.

An additional note for the future - when inter-operating with Fortran, this table can potentially contain entries added via Fortran source as well. Anything declared in Fortran with bind(C, name=this) would constitute an entry in the C symbol table for the name "this" (and thus the containing Fortran source file can effectively appear in the prerequisite table if that interface is called from another C file)

C Prerequisite Table (Not yet on master)

Each C function will depend on zero or more other symbols. This information is captured in a table in which each record consists of a "dependor" and a "dependee".

C/Fortran Mapping Table (Not yet on master)

This table stores a mapping between the program unit in Fortran and the C Symbol name where bind(C) is used.

Known issues

There are a number of complications of which we are aware.

Similarly Named Units

While any given Fortran program may not include more than one unit with a given name it is perfectly acceptible for separate programs to have similarly named units with different behaviour. If we have two such programs in the same project this throws up problems.

When trying to resolve dependencies we could find ourselves in the situation where a given unit name is satisfied by two different implementations. Which one to choose?

For the moment we are going to require that all unit names be unique but this is not a long term solution. Some mechanism to break such ties is required from the project configuration.