In this section the essentials of some GBS procedures are described.
This is in no way a specification, final document or manual.
It shows the basic idea of what is possible in GBS.
Start-up the GBS environment
The 'gbs' command sets up the GBS environment.
The first time it is called, it will prompt the user for things like System Root directory and a SubSystem name.
This information is remembered between logins.
Four main Environment Variables are defined:
$GBS_ROOT_PATH
$GBS_SUBSYS
$GBS_TARGET
$GBS_COMPONENT
These Environment Variables form the basics of the GBS build-environment. All GBS actions involve the currencies as indicated by these Environment Variables.
GBS maintains the contents of these variables. Never change these Environment Variables yourself. Use the GBS commands to do that.
Navigating the directory structure
GBS is based on a system of currencies: current-Root, current-SubSystem, current-Component, and current-Target.
Whenever you make another Root, SubSystem, Component or Target current (switch) the appropriate Environment Variables
are set accordingly.
Targets are always current for a whole Root.
Switch Root (System)
To switch to another Root (System) enter: swrRoot-directory
or, if you do not know the name of the Root enter:
swr
and you will be presented a list of Roots (Systems) to choose from.
GBS_ROOT_PATH and additional Environment Variables needed for this Root (System) will be set.
Switch Subsystem
To switch to another Subsystem enter:
swsSubSystem-name
or, if you do not know the name of the SubSystem enter:
sws
and you will be presented a list of SubSystems to choose from.
GBS_SUBSYS and additional Environment Variables will be set.
Switch Component
To switch to another Component enter: swcComponent-name
or, if you do not know the name of the Component enter:
swc
and you will be presented a list of Components to choose from.
GBS_COMPONENT and additional Environment Variables will be set
Switch Target
To switch to another target enter swtTarget-name
or, if you do not know the name of the Target enter:
swt
and you will be presented a list of Targets to choose from.
GBS_TARGET and additional Environment Variables will be set
Building
Building is the process of generating one or more items from a file in the 'src' directory to one or more files in the 'bld/target' directories.
Typical builds are: compilation, creating a library (archiving), linking.
The file-extension specifies the type of build that is required. (e.g.: *.c →C-compile)
The building process of a single file goes via specific, generic rules:
The source file is an argument in the command-line and is taken from the current 'src' directory.
More than one file from the 'src' directory may be specified. Wildcards are honoured.
The resulting files (e.g.) object-files will be written to the current 'bld/target' directories.
The name of the resulting file will be equal to the name of the source-file.
Filename extensions may differ and will be specific for various platforms. i.e.:
name.c →name.obj
If the build fails, name.* will be deleted from the 'bld' Sub-Directories.
The include path (-I) will be assembled in the following order:
The current 'loc' directory.
The current 'inc' directory
The 'inc' directories of the other Components within the same SubSystem:
In the order and as specified in the 'scope.gbs' file
or if not present:
the alphabetical order as found in the comp directory.
As specified by the contents of the inc_sourefiletype.gbs files, if present, in the order as
found in the following directories, if present:
$GBS_COMPONENT_PATH/opt/$GBS_TARGET
$GBS_COMPONENT_PATH/opt
$GBS_SUBSYS_PATH/build/$GBS_TARGET
$GBS_SUBSYS_PATH/build
$GBS_ROOT_PATH/sysbuild/$GBS_TARGET
$GBS_ROOT_PATH/sysbuild
This enables references to external stuff and from the 'import', 'res' and 'ext' areas.
The build-time options (-D) will be assembled in the following order:
Fixed Build settings for the whole project as defined in the option-file in the 'sysbuild/target' directory.
As specified by the contents of the flags_sourefiletype.gbs files, if present, in the order as
found in the following directories, if present:
$GBS_ROOT_PATH/sysbuild
$GBS_ROOT_PATH/sysbuild/$GBS_TARGET
$GBS_SUBSYS_PATH/build
$GBS_SUBSYS_PATH/build/$GBS_TARGET
$GBS_COMPONENT_PATH/opt
$GBS_COMPONENT_PATH/opt/$GBS_TARGET
If present: Build-time options as specified in the command-line
This means that options specified on the command-line will win.
To be able to implement these rules and to take care of any limitations of a building step (like a compiler) scripts are used. I.e.:
A compiler is never invoked directly, but always via its (dedicated) script. These scripts must reside in 'SYSGEN/target'.
For building a library, a 'glb-file' acts as the 'src' representative for the 'bld' library.
The glb-file contains a list of all object-files that will make up the library.
The glb-file also gives a name to the library. E.g.:
name.glb → name.lib
Using the rules as mentioned above, a script generates the library-build command needed to create the library, taking the object-files as specified in the glb-file.
A #include statement allows grouping of object-file-names.
The search-path is the same as for other #includes
Note that the glb-file may also contain specific archiver options.
More info: glb/glk/glt Files and
Generating Code
Linking
For linking, a 'glk-file' acts as the 'src' representative for the 'bld' executable.
The glk-file contains a list of all objects and libraries that will make up the executable.
The glk-file also gives a name to the executable. E.g.:
name.glk → name.exe
Using the rules as mentioned above, a script generates the link command needed to link the executable, taking the object-files as specified in the glk-file.
A #include statement allows grouping of file-names.
The search-path is the same as for other #includes
Note that the glk-file may also contain linker-options like -L.
More info: glb/glk/glt Files and
Generating Code
Testing
For (unit-)testing, a 'glt-file' acts as the 'src' representative for the test.
The glt-file contains the command-line with the name of the test-executable.
Results go to a log-file in the 'bld'
The glt-file also gives a name to the log-file. E.g.:
name.glt → name.log
Using the rules as mentioned above, a script generates the test command needed to run the executable, taking the executable name as specified in the glt-file.
Note that the glt-file may also contain execution options
More info: glb/glk/glt Files and
Generating Code
Generation by means of 'make'
With the information as supplied above 'make' files can now be generated and executed.
Typical commands are: gbsmakemake gbsmaketarget-file-name-list and
gbssysmakeSubSystem-list
To generate a single executable with 'make', enter:
gbsmakemyfile.exe
or, if the .glk file is in a different Component than the current-Component:
gbsmakeother_component:myfile.exe
For more information see: Generating Code
Exporting deliverables
Each Component has an optional export.gbs file in the Component-directory.
It specifies for each file in the Component that has to be exported, to which export directory it has to be exported, relative to the 'export'-directory
and/or the 'res/SubSystem'-directory.
The command is: gbsexport
Target-streams
Code may be generated for more than one target: Simulator testing and one or more target platforms.
Sometimes a single source-file generates for more than one target
A sequence of compilations for a specific target, with a specific compiler using the same set of compile-options, possibly followed by linking, resulting in a set of deliverables is called a stream or target-stream.
A total generation of the software-system requires the generation of all streams.
Streams can run in parallel and can so reduce generation throughput time.
Builders and File-types
Two mechanisms are used in order to prevent name-clashes (and overwriting of objects/executables):