HOME
Generic Build Support (GBS) - User Manual
The .gbs files - General
Description
Usage
If a file exists with the same name and with extension .usr instead of .gbs then that file will be
taken instead of the .gbs file.
Never, ever check-in a .usr file.
General Syntax
- Trailing white-space is ignored.
- Empty lines are ignored
- Lines beginning with '#' are considered comments and are ignored.
- The syntax is line-oriented.
- Leading white-space is significant.
- Lines ending with ' \' will be spliced with the next line.
WhiteSpace before the '\' and at the beginning of the next line will be
replaced by a single space.
- End-Of-Line Comment may be enabled/disabled using directives (see below)
- Lines may be skipped by the target-line-selection mechanism (see below)
- Lines starting with '.' are Directives (see below)
- Reserved words (keywords) are case sensitive
The usage of End-Of-Line Comments can be enabled and disabled by means of the .eol_comment directive.
Enabling the EOL Comments slows down parsing and should therefore be enabled with care.
It works similar as C and C++ // comments.
Syntax:
- line # comments
Semantics:
- #
- The # must be surrounded by at least 1 white-space on both sides
- The # , any characters following the # and any whitespace preceding the # will be removed.
- Possibly remaining empty line will be skipped
Example
- ENABLE = AKI # "Akiyama's criterion"
- results in:
- ENABLE = AKI
target-line-selection
The target-line-selection mechanism allows lines to be skipped depending on the current Target.
This mechanism is not enabled for all .gbs files.
Syntax:
- line operator wild-target-list
Semantics:
- line
- The line that will candidate for the selection
- operator
- == | !=
- wild-target-list
- The Target(s) for which the scope is valid (==) or not (!=)
- Wildcards are honoured
Example
- comp1:file.o != gnu
- Means: line will be skipped for Target gnu
- comp2:file.o = gnu
- Means: line will be included only for Target gnu
Note
It is practice to align the Target selections to the right of the lines.
Directives
.plugin
.include
.eol_comment
.targets
.exit
.end
.plugin
Purpose:
To define the plugin.
The plugin-directory associated with the defined plugin will be added to a possible include-path.
It is used to find the plugin directory with .include
Syntax:
- .plugin plugin_name
Semantics:
- plugin_name
- The plugin-directory must exist
.include
Purpose:
To include text from another .gbs file
Syntax:
- .include gbs_file
- .include "gbs_file"
- .include <plugin_gbs_file>
Semantics:
- gbs_file
- Absolute filepath is not allowed
- '../' is not allowed
- The file must be a .gbs file
- The search-path depends on the type of the .gbs file
- plugin_gbs_file
- Absolute filepath is not allowed
- '../' is not allowed
- The file must be a .gbs file
- The file will be taken from the plugin directory as specified by the .plugin directive
Purpose:
To enable/disable EOL (End-Of-Line) Comments
Syntax:
- .eol_comment enable
- .eol_comment disable
Semantics:
- General
- The state (enabled/disabled) is propagated through includes.
- Each main file starts in the disabled state.
.targets
Purpose:
To exclude generation of SRC files depending on the current Target
Only for glkbt files
Syntax:
- .targets[!]=wild-target-comma-list
Semantics:
- General
- glkbt files only
- The directive must be the first item in the file (after comments)
- The build step will not be executed if the condition is false. A dummy output file will be created.
- This is useful when a build step (like testing) should not be executed for specific Targets
- Note
- This mechanism works very similar to the target-line-selection, except no spaces are allowed.
.exit
Purpose:
To prematurely exit from a (included) file
Syntax:
- .exit
Semantics:
- General
- The rest of the file will be skipped
- This may be useful when testing a setup of a file and you do not want to comment out
the rest of the file
- You will get a warning.
.end
Purpose:
To prematurely exit from a (included) file
Syntax:
- .end
Semantics:
- General
- The rest of the file will be skipped
- This may be useful when you want to add extensive documentation and do not want it to slow down processing
of the file.
It also gives you the possibility of free-format text (without leading '#')
Order of actions
- Skip empty lines and lines starting with '#'
- Remove EOL-Comments if enabled
Skip possibly resulting empty line
- Perform Target-Line-Selection and remove target-selection part
- Execute Directive / Line
Copyright © Randy Marques of Randy Marques Consultancy - All rights reserved