HOME Generic Build Support (GBS) - User Manual
Top Level Directory Structure

Description

The rigid and strict nature of the GBS directory structure allows interchange ability between Systems and SubSystems.
GBS will generate the directory-structure automatically making sure all directories are properly named and added to any specified SCM System.

General overview

For the build process three areas can be distinguished:

The development-area. (dev)
Here developers will develop the software in SubSystems.
The results-area. (res)
This is the interface area between SubSystems as no direct reference is allowed from one SubSystem into another.
An 'external' reference area.(ext)
Here software can be found that is included by, but not developed (read: modified / generated) within the project.
Examples are: 3-rd party software, maybe: compilers with their runtime libraries and system header files, etc..

The above results in a basic directory-structure that looks like this:
Reserved (fixed) directory names are specified in a blue background.

Toplevel Directory

The 'res' directory contains directories with the deliverables of the various SubSystems.
The 'dev' directory contains the top-level directories of the various SubSystems.
The 'ext' directory contains the top-level directories of the various external systems.

In a project that consists of a single Subsystem (i.e. where the SubSystem is the System) still this top-level directory structure is used.

The basics

Software is developed in the SubSystems.
SubSystems contain, amongst others: sources, header-files, make-files and their resulting objects, libraries and executables.
If, for generation purposes, a SubSystem needs items from another SubSystem (like header-files or libraries), these items must be copied from the other SubSystem in the 'res' area. (How is explained later).

During generation of a SubSystem, files needed from another SubSystems are never taken directly from another SubSystem but only from the 'res' area.
Vice versa, a SubSystem will have to 'export' those items that are needed by other SubSystems to the 'res' area.

In a GBS environment a project will be split into SubSystems governed by scope-control.
Note that most (small) Systems will have only one SubSystem.
On a Software-Architectural level, SubSystems will have a hierarchy, defining the order in which SubSystems must be built.
In GBS this hierarchy is not reflected in the directory structure. All SubSystems reside on the same directory level.
The same applies to Software Components within SubSystems.
During the total generation of the system, first the lowest level SubSystem will be built. Using the GBS 'gbsexport' command, its deliverable(s) (e.g. library and header-files) will then be exported into the 'res' area and so made available to the next SubSystem(s). Then the next SubSystem in the Software hierarchy can be built, gradually moving 'up' the scope, generating and incorporating the other SubSystems.

Directories

The System directory

This is the top-level directory for the whole project
In the rest of the document this directory will be referred to as the SYSTEM directory.

The SYSTEM is defined in an Environment Variable (GBS_SYSTEM_PATH) specifying the top directory.
In these documents the UNIX notation of directories will be used for both Windows and Linux.

The 'dev' directory

This directory contains the top-level directories of the various SubSystems.

The 'dev' directory may only contain SubSystem Top-Level directories.
So each directory in the 'dev' directory is considered a SubSystem.
There are 2 basic types of SubSystems:
- Full-GBS Compliant
  Here the internal structure is strictly defined by GBS Components are controlled by GBS
- Non GBS Compliant
  Except for a few mandatory files the structure is completely free
  GBS will not concern itself with internals and most lower level GBS commands like the compile of a single file (gbsbuild) will not work here.
  There are multiples Types:
  - MSVS (Microsoft Visual Studio)
    For Microsoft Visual Studio Projects and Solutions
  - make
    For typical 'make' environments
  - Other
    For any not of the above

The 'res' directory

This directory contains matching SubSystem directories that are used for interfacing between SubSystems.
'res' stands for 'result' i.e. deliverables generated by the SubSystems.

During SubSystem build, the deliverables of a SubSystem are generated. When all is well, the deliverables are copied to the SubSystem's 'export' directory and/or the res/SubSystem directory.
Not all subdirectories in the 'res' directory will be available to all SubSystems.
Each Subsystem has a 'scoping' file that shows which other SubSystem 'ref'-directories may be referred to.
Files may never be modified directly in the 'res' directory.
The total of 'res' directories must be set up in such a way, that it is possible to delete the contents of the 'res' directory and regenerate it by using the proper GBS command.

The 'ext' directory

This directory contains 'static' parts of the project. i.e. those parts that are not generated for the project, are used 'as-is' and are not covered by another version-controlled repository.

The 'ext' area will contain 3-rd party software and maybe operating systems, (cross-) compilers and compiler files like system header files and run-time libraries.
Software controlled by the support-organisation should not be included in 'ext'.

Other Directories

Although not mentioned before, there are also a number of other top-level directories like 'sys', 'sysbuild', 'sysaudit', 'systool', 'silo' and 'tmp'
Their usage is described in Full-GBS Directory Structure

Additional top-level directories

All top-level directories are mandatory.
Additional directories may be placed at this top-level. Names are free except for the following:

- doc

for documentation at system-level

This means that if you use these names, you have to use them for the purpose as specified above.

The SubSystem top directory

GBS allows Subsystems to be either Full-GBS or Non-GBS compliant.

Full-GBS SubSystems

Full-GBS Subsystems adhere completely to the GBS way of working.
The generation of the SubSystem is completely taken care of by GBS

Non-GBS SubSystems

This allows for 'alien' SubSystems to be incorporated in the generation-process.
Non-GBS SubSystems may have any directory-structure and/or generation process.
Non-GBS SubSystems require a number of predefined scripts that will be called by the GBS Top-level functions like: gbssysbuild, gbssysmake, gbssysaudit and cleanup.
The gbsexport functionality to fill res and/.or export directories is also available.

Continue reading

Full Directory Structure

Generic Build Support (GBS) - User Manual - Top Level Directory Structure

top_dir_struct.html