GBS Logo






Release 4.00
(2016-02-18)








Randy Marques
Randy Marques Consultancy
Randy@RandyMarques.com.nl


GBS Logo HOME Generic Build Support (GBS) - User Manual
GBS User Guide - Home Bottom Doc. Button
Randy Marques Consultancy Logo Thank you for using Generic Build Support (GBS), the generic build environment created by Randy Marques of Randy Marques Consultancy, Netherlands.

Generic Build Support is a way of setting up a directory structure combined with generic scripts to accommodate Build Automation for almost any kind of software project.
Building information is kept in dedicated files enabling automatic generation of make files, independent of platform or SCM System.

The key aspect of GBS is the directory structure.
Its rigid and strict[1] nature makes sure that everything has its place so that it can be easily retrieved and it is assured that any GBS command will run on any SubSystem created according to the GBS Directory Structure rules.
This directory structure makes it possible to swap and/or share software between projects (interchange ability) ensures an unified way of working.
And yes: where needed there is all the freedom you need!
You can run GBS parallel on Win XP, Windows 7 and Linux systems, sharing the same physical directory structure.
Although not tested: There is no reason why GBS should not run on Unix, Vista or Windows 8

For a simple project you can start using GBS quickly and keep in mind that everything has its place.
I strongly suggest reading the 'Getting Started' part of the documentation.
Following the instructions in Create a GBS-WA/System will quickly set you on track.

The power of GBS lies in its concept.
So on the long run this means that in order for you to use GBS to its full extent, you must understand the concept of GBS and use it As Intended.
Understand GBS by: OR
You are not allowed to change and/or distribute any part of GBS without permission of the owner.

GBS is Freeware with the following conditions:
This free version of GBS is not compatible with previous releases (pre 3.00)

Before you start using GBS, please take a moment to read the Terms and Conditions
[1] Rigid and strict really means that no deviations are allowed.

Important Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

This document is just what it is named. A User Manual.
It does not describe the background, concepts or philosophy of GBS.
It therefore cannot be used to determine whether GBS is usable in a particular environment or project.
It certainly cannot be used to assess the full potential and usability of GBS.
For above purposes the interested user should attend the GBS Concepts presentation as given by Randy Marques.

Features Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

Documentation Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

General

GBS Release Notes
Contains up-to-the-minute release information about GBS.

GBS FAQ
Frequently Asked Questions

Installation Notes

Unix and Windows


GBS Logo HOME Generic Build Support (GBS) - User Manual
Quick Start Bottom Doc. Button

Contents Bottom Doc. Button Top Document Button Down Section Button Blank

Description
Environment| Install| Setup| Startup| Getting Started| Commands| General notes on the GBS command-line environment

Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Environment Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

OS / Shell

GBS runs on:

Perl

GBS is based on Perl-scripts.
Perl must be installed and the perl command must be either in the PATH or specified via an Environment-Variable (GBS_PERL_PATH).
You need at least Perl version 5.16.3.
More information on installing Perl for GBS can be found in Install Notes→Environment

Install Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

If GBS is pre-installed (local or on a network drive) your GBS Administrator will be able to tell you where GBS is installed.
You will then only need to do the Setup as explained below.

If you need to install GBS yourself: More info on Install: Install Notes→Install

Setup Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

To setup GBS:
If setup was not started by Install: When in gbssetup: What happens on Windows: What happens on Linux: Note that a beta version will install red shortcuts. The regular versions will install yellow shortcuts.
More info on Setup: Install Notes→Setup

Startup Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

Startup GBS

Enter:
gbs

The first time you startup GBS you must give it some information:
The Root (System) you are going to use: e.g.: ~/Development/GBSProjects/hello (may take a single root as default)
The SubSystem you are going to use: e.g. main

GBS Manual Page

To obtain current information on all implemented GBS commands enter:
gbsman

GBS Help

To obtain extensive Help in HTML format (including this page) enter:
gbshelp

Getting Started Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

Organising your GBS-WAs / Systems

You can place a GBS-WA/System anywhere you want. You can also have them all on totally different locations. They do not need to be grouped in one directory, although that is a good idea.
It is recommended to relate the name of the GBS Root directory to the SystemName.
You may also give the GBS LogDir directory a place:

    ... Development -+- Projects -+- systemname1
                     |            +- systemname2
                     |            +- systemname2_3.2
                     |
                     +- GBSLogs
Remember that GBS does not like spaces in directory and filenames and that they are case sensitive!

Connect to an existing GBS System

Create a new GBS-WA/System

You enter swr --new.
Creating a new GBS-WA is serious business.
You can find out how to do it in Create a GBS-WA/System
A good understanding of the concept and principles of GBS is needed.
Once done however, things get extremely simple, convenient and fast.

Commands Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

Use GBS to navigate through your directories

After you have once set them GBS 'remembers' the following 'currencies'

Displaying Currencies

To display your currencies just enter:
gbs

Currency commands

swr Switch Root: set/change the current Root (and SubSystem (and Component))
sws Switch SubSystem: set/change the current SubSystem (and Component)
swc Switch Component: To set/change the current Component. This command ends with an explicit cdsrc
swt Switch Target: set/change the current Target

Basic commands

gbsedit Create/Edit a file (you can define your own editor with gbssetup )
gbsgen Compile, Link, etc. one or more files
gbssysgen Compile, Link, etc. the whole System (Runs in batch - with logfile)

Navigation commands

cdlogcd to the log directory as specified by GBS_LOG_PATH (or $HOME)
 
cdrootcd to current Root
cddoccd to the doc of the current Root
cddevcd to the dev of the current Root
cdextcd to the ext of the current Root
cdrescd to the res of the current Root
cdsyscd to the sys of the current Root
cdsysbuildcd to the sysbuild of the current Root
cdsysauditcd to the sysaudit of the current Root
cdsystoolscd to the systools of the current Root
cdsilocd to the silo of the current Root
cdtmpcd to the tmp of the current Root
 
cdsubcd to the current SubSystem directory
cdbuildcd to the gen of the current SubSystem
cdauditcd to the audit of the current SubSystem
cdcompcd to the comp of the current SubSystem
cdimportcd to the import of the current SubSystem
cdexportcd to the export of the current SubSystem
 
cdappcd to the app directory of the current Non GBS SubSystem
 
cdsrccd to the src directory of the current Component
cdinccd to the inc directory of the current Component
cdloccd to the loc directory of the current Component
cdbldcd to the bld directory of the current Component
cdtargetcd to the bld/Target directory of the current Component / Target
cdaudcd to the aud directory of the current Component
cdoptcd to the opt directory of the current Component
cddatcd to the dat directory of the current Component
cdsavcd to the sav directory of the current Component

Other GBS commands

Note that all gbs-commands accept --h for short help and --help for long help

gbsgen, gbssysgen

Commands to compile, link, etc directly

gbsmake, gbssysmake

Commands to compile, link, etc using 'make'

gbsaudit, gbssysaudit

Commands to run Audit programs like QAC and QAC++

gbsmaint

This command enables you to select and execute a number of GBS maintenance functions.
Like:

gbssetup

This command enables you to define your customizations. (Beeps on/off, Define Editor, etc.)

gbsscm

This command enables you to select and execute SCM-related functions in GBS.

There are a lot more command in GBS. They can be found at All Commands.

General notes on the GBS command-line environment Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

In a prompt, possible values are embedded in parenthesis
e.g.:
GBS: Are you sure? (y/n):

In a prompt, the default value is embedded in square brackets
e.g.:
GBS: Are you sure? (y/n)[y]:

Entering a single '!' will quit the script.
Entering a single '?' will give you some additional help (if available)

In general, options for GBS-commands start with -- (double hyphens).
This is to be able to discern options for GBS and options for applications (like QAC)
All GBS-commands accept --h for short help and --help for long help
More in The Command-line Interface

GBS Logo HOME Generic Build Support (GBS) - User Manual
GBS Release Notes Bottom Doc. Button

Contents Bottom Doc. Button Top Document Button Down Section Button Blank

Release Notes for GBS 4.00
Interface changes since 3.01| Build 4.00: 2016-02-18| Build 4.00: 2015-03-10| Build 4.00: 2015-02-17
Release Notes for GBS 3.01
Interface changes since 3.00| Build 3.01: 2014-07-08
Release Notes for GBS 3.00
Build 3.00: 2014-03-18| Build 3.00: 2013-12-13| Build 3.00: Beta 2013-10-02
Release Notes for Previous Releases

Release Notes for GBS 4.00 Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Interface changes since 3.01 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

The following must be implemented before switching to this version.
  1. Upgraded to the last build of GBS 3.01 (2014-07-08)
The following must done immediately after switching to this version.
  1. Upgrade to your directory structure with gbsmaint 7 9 (Upgrade).
  2. Check gbsexport functionality (because of rename of SubSystem gen directory)
The following major changes were implemented:
  1. The gbssysgen directory on Root level has been renamed to gbssysbuild.
  2. The gen directories on SubSystem level have been renamed to build.

Build 4.00: 2016-02-18 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. steps.gbs: Layout changed. Refer to steps.gbs
  2. gbssystool: New GBS command
  3. New EnvVar $GBS_LOG_ROOT
    gbsswr: Will set $GBS_LOG_PATH to $GBS_LOG_ROOT/$GBS_ROOT_PARENT unless it was set in switch.gbs
    gbssys* Log files and gbsaudit .html files are now written to a different $GBS_LOG_PATH
  4. gbssetup: GBS_LOG_PATH replaced by GBS_LOG_ROOT
  5. gbsmaint: New Entry 5: User Tools
  6. gbsmaint: New Entry 5 1: User Tools → Fix Log Files & Directories:
    - Repair/Fix Log files
    - Prune Log files
    - Distribute files in $GBS_LOG_ROOT to the various RootParents
  7. Improved layout of HTML files. E.g: gbshelp, gbssilo, gbsstats, gbsaudit, etc
  8. Added general --verbose option
    Foreground logging of gbsgen and gbsaudit reduced
  9. All occurrences of 'allways' replaced by 'always'
    Also in steps.gbs!
  10. The commands cp find gawk rm sed and tar were added to win32utils so they are all available to GBS-make on Windows
    More info here.
  11. Improvements in handling of SVN repositories (Repositories are 'remembered')
  12. New command gbsuninstall
  13. New Shortcuts in Startmenu for gbssetup and gbsuninstall
  14. audit.gbs, target.gbs and tool.gbs now have a new sub-section in INIT: BIN_DIR.
    'GBSEXT_<plugin>_BIN_PATH' is now defined prior to executing a plugin.
  15. New command gbsstart_here which is a simplified version of gbsstart.
    Prefered command for IDE/Editor integration of GBS
    See also: Integration with other Tools

Problems solved

  1. None

Important Notice

Support for MS VisualSourceSafe and CVS will not be available anymore in the next build of GBS
Please let me know if you have a problem with this.

Build 4.00: 2015-03-10 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. gbsaudit: QAC and QACPP will now run a user_check script if present:
    $GBS_ROOT_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE
  2. gbshelp: New Page EnvVars added. It contains an overview of all GBS EnvVars
  3. gbssilo: Now also generates a Targets/Audits overview
  4. gbsinit: You can now specify --rel=? and get a list of available versions to select from
  5. gbsstats: Now generates a HTML file in the silo. You can also view it with the gbssilo command
    More items were added to the Statistics overview.

Problems solved

  1. Some SubSystem GBS_..._PATH EnvVars were defined incorrectly
  2. gbsmaint: Upgrade: Plugin-names have changed. target.gbs is now properly updated (Linux only)

Build 4.00: 2015-02-17 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. Added support for Git.
  2. The gbssysgen directory on Root level has been renamed to gbssysbuild.
  3. The gen directories on SubSystem level have been renamed to build.
  4. gbsaudit: SCA: Now all messages (warnings) are stored. Only enabled messages are displayed and counted.
  5. gbsaudit: SCA: Improved performance and layout
  6. gbsmaint: SCA: Added functionality to:
    - Show the SCA messages (warnings) documentation file (Help file)
    - Convert SCA warning settings file to GBS SCA settings file
  7. gbsaudit: SCA: Reduce the effort to implement a new SCA
  8. sca_*.gbs: Allow proper includes and allow sca_*.gbs files on SubSystem level
  9. gbsedit: SCA: proper support for sca_*.gbs files
  10. gbsedit: Improved handling of variable name .gbs files (like flags_*.gbs files)
    If not specified you will be prompted for the variable part. (e.g.: gbsedit flags.gbs → flags_c.gbs)
  11. gbsmaint: CLEANUP: Added Cleanup Silo Cache function
  12. Build Plugin unix and linux removed (Use lgnu_gcc or lgnu_cpp)
  13. Build Plugin lgnu replaced by lgnu_gcc and lgnu_cpp
  14. swr: Now asks to Create or Add a Root if none is defined.
  15. sws: Now asks to Create a Subsystem if none is defined.
  16. swc: Now asks to Create a Component if none is defined.
  17. swt: Now asks to Define a Target if none is defined.
  18. Plugins handling (gbsmaint and swt --new) will now offer the option to immediately edit the switch.gbs file

Problems solved

  1. gbsaudit: prqa (QAC & QAC++) calculated file and function metric totals incorrectly

Release Notes for GBS 3.01 Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Interface changes since 3.00 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

The following must be implemented before switching to this version.
  1. Upgraded to the last build of GBS 3.00 (2014-03-18)
The following must done immediately after switching to this version.
  1. Upgrade to your directory structure with gbsmaint 7 9 (Upgrade).
  2. If you have Non-Full GBS SubSystems: Merge the non-GBS SubSystem action script files: (gbssubcleanup_bld, gbssubgen, gbssubmake, etc) into gbssub.
The following major changes were implemented:
  1. Introduction of multiple types of Non-Full GBS SubSystems. Refer to Handling SubSystems & Steps.
  2. The non-GBS SubSystem action script files: (gbssubcleanup_bld, gbssubgen, gbssubmake, etc) have been merged into one script-file: gbssub.
  3. Directory structure: Non GBS SubSystems now require the subdirectories gen and audit.
    Execution of a Non GBS SubSystem step is now controlled the same way as for Full GBS SubSystems. E.g.: The gen directory must contain a target directory to be selected for execution.
  4. gbsaudit and gbssysaudit Now require an Audit/Target combination in the SubSys audit directory to select the proper Audit/Target combination.

Build 3.01: 2014-07-08 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. SubSystems are now presented in the order as defined in steps.gbs, if present.
  2. gbsaudit and gbssysaudit Now require an Audit/Target combination in the SubSys audit directory to select the proper Audit/Target combination.
  3. The non-GBS SubSystem action script files: (gbssubcleanup_bld, gbssubgen, gbssubmake, etc) have been merged into one script-file: gbssub.
  4. Added distinction / support of multiple non-GBS SubSystem types.(MSVS, make and Other)
  5. gbsbldcheck Replaces gbsbldaudit. (Just a name-change)
  6. target.gbs and audit.gbs now support conditional execution (pre-condition) in COMMAND item
  7. target.gbs and audit.gbs special COMMANDs ECHO and SET are now implemented
  8. gbsexport, gbsmakemake and gbswhich do not support the --target option anymore
  9. New Environment Variables: TARGET_PLUGIN and AUDIT_PLUGIN
  10. Directory structure: Non GBS SubSystems now require the subdirectories gen and audit.
    Execution of a Non GBS SubSystem step is now controlled the same way as for Full GBS SubSystems. E.g.: The gen directory must contain a target directory to be selected for execution.

Problems solved

  1. target.gbs, audit.gbs and tool.gbs: Proper user-plugin handling (.plugin)

Release Notes for GBS 3.00 Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Build 3.00: 2014-03-18 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

New/Changed Functionality

  1. target.gbs and audit.gbs: Added VIA_FORMAT and changed behaviour of FLAG_FORMAT, SYSFLAG_FORMAT, INC_FORMAT, SYSINC_FORMAT and GLKB.
  2. target.gbs and audit.gbs: You can now have multiple COMMANDs and you can also specify a list of valid exit-codes for each command
  3. GBS Files: The .end directive was added.
  4. target.gbs and audit.gbs: Added FLAG_FORMAT and SYSFLAG_FORMAT
  5. target.gbs: GBS_glkb_type_LINES and GBS_glkb_type_FILE have been replaced by GBS_GLKB_LINES and GBS_GLKB_FILE.
  6. The detab command which allows for recursive directory processing has replaced the retab command.
  7. audit.gbs: Added mandatory item OUT_TYPES
  8. target.gbs: The P_COMMAND is no longer supported
  9. The --target option is not longer supported in the commands: gbsgen, gbsmake and gbsaudit.

Problems solved

  1. gbsmakemake generated 'file not found' messages for the Visual Studio plugin: msvs2012_cons
    The GBSEXT_ EnvVars for 'Windows Kit' (WK) have been replaced by those for 'Windows SDK' (SDK)
    This reflects on the switch.gbs.

Build 3.00: 2013-12-13 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. This Release-version is not fully compatible with the Beta-version. Please mail me if you encounter problems.
  2. target.gbs: Plugin-names changed: mingw became mingw_cpp or mingw_c.
    Also changes for this in the GBSEXT_ names in the switch.gbs file.
  3. gbsaudit: Now remembers the last executed Audit and takes it as default for the next execution. GBS_AUDIT is now also shown in gbsshow and remembered across sessions.
  4. target.gbs was extended with new SRC item: INC_SEARCH_STYLE to facilitate various include-search methods.
    Needed to solve problem as mentioned below.

Problems solved

  1. gbsaudit and gbsmakemake: Not all header-files were found because the 'UNIX'-search method was not used.
    Needed a new target.gbs functionality as mentioned above.

Build 3.00: Beta 2013-10-02 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

New/Changed Functionality

  1. gbsmaint: New entry 7 4 (SCMS Tools)
    Moved all gbsmaint SCMS related stuff to new entry.
    Added: Modify SCMS Settings
  2. New EnvVar: GBS_ROOT_PARENT (switch.gbs)

Problems solved

  1. Dependency on Perl smart-match (~~) removed.
  2. swr: Select SCMS: PATH can now contain non-existing Paths with GBS crashing.
  3. gbshelp: Documentation on Install and Setup improved
  4. Performance issues (minor)(Perl regular expressions usage)
  5. gbsmaint 3: Map Network Drives. Handling improved.
  6. Improved SCSM handling when creating a new Root

Release Notes for Previous Releases Bottom Doc. Button Top Document Button Blank Up Section Button



GBS Logo HOME Generic Build Support (GBS) - User Manual
Install Notes Bottom Doc. Button

Contents Bottom Doc. Button Top Document Button Down Section Button Blank

Description
Environment| Install| Setup

Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Environment Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

OS / Shell

GBS runs on:

Perl

GBS is based on Perl-scripts.
Perl must be installed and the perl command must be either in the PATH or specified via an Environment-Variable (GBS_PERL_PATH).
You need at least Perl version 5.16.3

If Perl (or the proper Perl version) is not in the PATH, define an environment variable GBS_PERL_PATH to point to the top-level directory where the proper Perl is installed.
e.g.: export GBS_PERL_PATH=/opt/ActivePerl-5.16

Perl can be obtained for free via GBS was developed and tested with the Perl Distributions from ActiveState

Install

After download From ActiveState: More information: Installing ActivePerl 5.16.x

Note: There is a bug in core Perl on Windows that doesn't set up @INC correctly if Perl is installed into a directory that starts with the letter '5'. Your problem should go away if you install into something like C:\MyPrograms\perl\v5.10 instead.
This bug is at least 10 years old and somewhat related to finding additional site_lib directories when you are using the versioned directory layout scheme where multiple Perl versions share site_lib directories.
Found in Perl Monks

Install Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

Pre-Installed

If GBS is pre-installed (local or on a network drive) your GBS Administrator will be able to tell you where GBS is installed.
You will then only need to do the Setup as explained below.

Need to Install

Several versions of GBS can be installed in a GBS_SCRIPTS_ROOT directory.
They are installed using the Hard versioned directories method.
The latest build of a version is always installed under the plain directory. E.g: 2.02
This is called the Current Build of a version. It will be overwritten with every install of the same version.
Specific Builds are installed under version_build directory. E.g.:

                        +- 2.01
                        +- 2.01_2006-11-23
      any_root -+- GBS -+- 2.02
                        +- 2.02_2007-08-05
                        +- 2.02_2007-09-15

<--GBS_SCRIPTS_ROOT-->     <---GBS_SCRIPTS_REL--->

The Install scripts only installs GBS (possibly on a central location).
To be able to use GBS, each user must 'Setup' GBS as explained below.
This tells GBS which of the version to use.
During the Install you have the option to execute the setup immediately after the install.

Prerequisites:
  1. You must have Perl installed and in the PATH
  2. Decide where GBS will be installed (GBS_SCRIPTS_ROOT)
    GBS will provide some nice defaults, but you can also specify you own location
  3. You will need to provide a Site-ID

Instructions for Install:
Notes:
  1. Subsequent installs can be run with -q flag (quiet). This will run the script without human intervention assuming all defaults to be correct.
  2. Using the WinZip Wizard (on Windows):
    1. Double-click on the zip-file
    2. Make sure you run in Wizard mode and Click 'Next'
    3. Choose 'Unzip or Install' and Click 'Next'
    4. Make sure you will not unzip to the directory where you want to install GBS
    5. Enable 'Display file icons after unzipping'
    6. You can use 'View Zip Documentation' to read this text
    7. Click 'Unzip Now'
    8. After the file is unzipped a 'Windows Explorer' window will appear.
    9. Double-click on 'Install.bat' and answer the questions. GBS is installed
    10. Close the WinZip wizard by clicking on 'Finish'

Setup Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

General

To setup GBS: What happens on Windows: What happens on Linux: Note that a beta version will install red shortcuts. The regular versions will install yellow shortcuts.

GBS Logo HOME Generic Build Support (GBS) - User Manual
Create a GBS-WA/System Bottom Doc. Button

Contents Bottom Doc. Button Top Document Button Down Section Button Blank

Description
Before you start| Creating the GBS-WA| Creating a Subsystem| Creating a Component| Getting one file to compile| Creating the executable| Exporting the executable| Generate in the Batch| Adding a Target| Creating a non-GBS SubSystem| Interfacing with the outside-world

Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Creating a new GBS-WA is serious business.
A good understanding of the concept and principles of GBS is needed.
Once done however, things get extremely simple, convenient and fast.

This document will guide you to setup a simple non SCM-controlled 'Hello World' project to give you a taste of GBS.

Before you start Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

Install GBS

Read:

Prepare

After Install it really helps if you have read: If you get stuck, read:
  • Top Level Directory Structure
  • Full Directory Structure
  • Procedures

    The project

    For the explanation below a 'Hello world' implementation is used as example: Linux: We will be using the native C/C++ compiler toolchain
    Windows: We will be using the MinGW toolchain

    Startup GBS

    Creating the GBS-WA Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Make sure your 'Site' is defined in GBS
    We will now proceed to create a SubSystem

    Creating a Subsystem Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    We will now proceed to create a Component

    Creating a Component Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    We will now proceed to create a file and compile it

    Getting one file to compile Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Setup Editor

    You probably want to use your own editor:

    Create and edit the file

    Now we create the file:

    Adjust the Target-environment (if necessary)

    Try to compile the file with gbsgen hello.c.
    It should compile, but if it fails that is probably because the GBSEXT_ EnvVars are not properly set:

    Compile the file

    Repeat until no more errors: Note: You need not be in the src directory when you execute a gbsgen.
    We will now proceed to create the executable

    Creating the executable Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    For linking we need a .glk file in the src directory

    Create the .glk file

    Link and run the .glk file

    We will now proceed to export the executable

    Exporting the executable Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    For the Export we will need an export.gbs file in the component.

    Create export.gbs file

    We will assume that this executable is for a customer called FOO

    Export the file

    Generate in the Batch Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    If at a later stage you want to view your gbssysgen logfiles:

    Adding a Target Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    The previously defined Target will generate our FINAL (non-debug) version.
    But we also want a DEBUG version: It is done now. You can generate single stuff for a single Target with gbsgen and use swt to switch Targets.
    Enter gbssysgen and observe how the system is generated for both Targets in parallel.

    Creating a non-GBS SubSystem Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Create a 'make' Subsystem

    Interfacing with the outside-world Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    System (Root)

    switch.gbs(.bat/.sh)

    This file resides in the $GBS_ROOT_PATH directory.
    It is a script that is executed every time GBS makes a System (Root) current.
    Its purpose is to define the particularities of the general building environment of the selected System.
    e.g.: Here you want to make sure you are using the proper environment for your particular System.
    Have a look at the contents of this file.
    It is maintained by the GBS Administrator and must be under SCM control.
    Note that at the moment of invocation all environment variables for that Root have been set.

    switch.usr(.bat./sh)

    This optional file also resides in the $GBS_ROOT_PATH directory.
    It is an optional script that is executed every time GBS makes a System current.
    And after the switch.gbs mentioned above has been executed.
    Its purpose is to enable a developer to (re-) define the particularities of the general building environment of the selected System.
    It is maintained by the Developer and must never be under SCM control.

    Note: If you change any of these two files you must 'swr .' for them to take effect.

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    FAQ - Frequently Asked Questions Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    General

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    How to create a new Component Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Enter :
    swc --new

    How to create a new SubSystem Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Enter :
    sws --new

    How to create a new System (Root) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Enter :
    swr --new

    How to add an existing System (Root) to my Systems (Roots) list Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Enter :
    swr --add

    How to remove a System (Root) from my Systems (Roots) list Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    Enter :
    swr --remove


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Terms and Conditions Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    SOFTWARE LICENSE Bottom Doc. Button Top Document Button Blank Blank Blank Blank

    BEFORE YOU USE GBS, CAREFULLY READ THE TERMS AND CONDITIONS OF THIS AGREEMENT.
    BY INSTALLING AND USING THE SOFTWARE YOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING A PARTY TO THIS AGREEMENT.
    IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, DO NOT INSTALL OR USE THE SOFTWARE.

    Generic Build Support (GBS)
    Copyright © 2010-2020 by Randy Marques, Randy Marques Consultancy, Netherlands
    All rights reserved.

    SOFTWARE LICENSE
    1. Randy Marques Consultancy, Netherlands grants to you a limited, non-exclusive, non-sub licensable, license to use this version of Generic Build Support (GBS) (the "Software").
    2. RANDY MARQUES CONSULTANCY, NETHERLANDS MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE OR ABOUT ANY CONTENT OR INFORMATION MADE ACCESSIBLE BY THE SOFTWARE, FOR ANY PURPOSE. THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT EXPRESS OR IMPLIED WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. RANDY MARQUES CONSULTANCY, NETHERLANDS SHALL NOT BE LIABLE UNDER ANY THEORY OR ANY DAMAGES SUFFERED BY YOU OR ANY USER OF THE SOFTWARE. RANDY MARQUES CONSULTANCY, NETHERLANDS IS NOT REQUIRED TO SUPPORT OR ISSUE UPDATES TO THIS SOFTWARE.
    3. Title, ownership rights, and intellectual property rights in and to the Software shall remain with Randy Marques Consultancy, Netherlands. You agree to abide by the copyright law and all other applicable laws of the Netherlands including, but not limited to, export control laws. You acknowledge that the Software in source code form remains a confidential trade secret of Randy Marques Consultancy, Netherlands and/or its suppliers and therefore YOU AGREE NOT TO MODIFY THE SOFTWARE OR ATTEMPT TO READ, DECIPHER, DECOMPILE, DISASSEMBLE OR REVERSE ENGINEER THE SOFTWARE, except to the extent applicable laws specifically prohibit such restriction.
    4. This License is personal to you and you agree not to assign your rights herein.
    5. You may not download or otherwise export or re-export the Software or any underlying information or technology except in full compliance with all Dutch and other applicable laws and regulations.
      GBS is Freeware with the following conditions:
      • You are allowed to use it at home and at work for free.
      • You are not allowed to sell GBS as a whole or as part of a product or service.
        Contact the owner if you need this.
    6. GBS Consultants can be appointed by Randy Marques Consultancy only.

    RANDY MARQUES CONSULTANCY, NETHERLANDS OR ITS SUPPLIERS SHALL NOT BE LIABLE FOR (a) INCIDENTAL, CONSEQUENTIAL, SPECIAL OR INDIRECT DAMAGES OF ANY SORT, WHETHER ARISING IN TORT, CONTRACT OR OTHERWISE, EVEN IF RANDY MARQUES CONSULTANCY, NETHERLANDS HAS BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES, OR (b) FOR ANY CLAIM BY ANY OTHER PARTY. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. FURTHERMORE, SOME COUNTRIES/STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT APPLY TO YOU.

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Definitions & Acronyms Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Definitions Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Generic Build Support (GBS)

    The process of building according to strict rules and a strict predefined directory structure.
    This makes building an easy process to use and to handle.
    Make-files can be generated because the directory structure is fixed for all SubSystems.

    RMC

    Randy Marques Consultancy. The owner of GBS.

    GBS-WA or System

    A single, whole GBS directory tree.
    Contains SubSystems.
    GBS-WAs or Systems are identified by their SystemName
    You can have as many GBS-WAs as you want. Even multiple occurrences of the same.
    A GBS-WA will always correspond with a total SCM work area.

    SubSystem

    An independent generation-unit within GBS
    A directory-structure with files that, during generation, produce software that can be delivered (released) to other SubSystems and/or end-customers.
    A GBS SubSystem is not per se an architectural SubSystem.
    SubSystems contain one or more Components
    The number of SubSystems should be limited
    Most Systems will have only one SubSystem

    Component

    A files-container within a GBS SubSystem.
    The lowest level directory-tree in GBS
    Here the source and object files reside.
    A GBS Component is not per se an architectural Component
    GBS Component may very well contain more than one architectural Component and/or parts of architectural Components.
    Files in Components cannot refer to files in Components of other SubSystems

    Deliverable

    The set of files produced by a SubSystem for use in another SubSystem or as final product. Generally speaking the deliverables of a SubSystem will consist of one or more libraries with one or more header-files. In a broader sense, any file that has to be made available to another SubSystem is a deliverable. (final executables, test-scripts, etc)
    You can also have internal deliverables. A SubSystem may 'deliver; to another Subsystem.

    Target or TargetStream

    A sequence of compilations for a specific target, with a specific compiler toolchain, using the same set of compile-options, possibly followed by linking, resulting in a deliverable.

    Auditing

    Actions performed on the code that do not generate executable code.
    Think of Source Code Analysers (SCAs) like PCLint, C++Test or QAC
    Auditing runs on file level, just like compilers
    Note:
    Doxygen runs on System level. It is therefore not considered an Auditing tool but a System Tool

    Archiving

    The process of placing one or more object files into an object library

    GBS Administrator

    Person responsible for the infrastructure of a GBS-WA. Typical GBS responsibilities: This function may very well correspond with that of the SCM Manager

    GBS Integrator

    Person responsible for the execution of Generic functions in a GBS-WA. Typical GBS responsibilities: This function may very well correspond with that of the SCM Manager

    Hard versioned directories

    A method to store multiple versions of something (programs, files, etc.) so that all are available at the same time. This in contrast to Soft versioned directories that are stored inside SCM repositories and need to be checkout before they can be accessed.
    All versions reside under the ROOT directory. The versions are called REL. And the actual location is called PATH.
    3 Environment Variables are used to define the actual location: In the applications and especially switch.gbs you always use app_PATH (and maybe occasionally app_REL)
    This assures that when you want to switch to another version you only need to change the app_REL

  • This method is used heavily throughout GBS

    Builder or Generator

    In the context of this document a Builder or Generator is a program or script that takes care of one step of the build-process of a deliverable. Typical builders are compilers, library-archivers and linkers.

    Acronyms Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    GBS Generic Build Support
    RMC Randy Marques Consultancy
    SCA Source Code Analyser
    SCM Software Configuration Management
    SCMS Software Configuration Management System
    e.g. ClearCase, Continuus, SubVersion, Git
    WA Work Area
     


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Introduction Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    GBS requires a strict and rigid directory structure to facilitate automatic generation and interchange ability between Systems and SubSystems.
    Sometimes separate parts of a system may not be able to use GBS (dedicated environment like Visual Studio, old code, etc.), they can however benefit from parts of the concept of Generic Build Support, like the export mechanism which will be described later.

    One of the advantages of Generic Build Support is that developers need not worry on how to generate the system. Fixed sets of scripts, which work on all parts of the system, take care of this. Because of this, all scripts work in the same way for each component and for each file. This reduces the chance of mistakes considerably. Additionally, because everything is defined, accidental misuse is avoided. GBS gives flexibility where it is really needed. Everything else is fixed.

    GBS provides the functionality to generate the directory-structure or parts of the directory-structure, automatically making sure all directories are properly named.
    Users should never create directories manually.

    Some basic definitions Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    SubSystem

    The basic generation unit of GBS is a SubSystem.
    SubSystems generate autonomously. I.e.: There are never direct references from one SubSystem to another.
    At the end of the SubSystem generation a SubSystem will have generated one or more deliverables.
    These can be executables, header-files, object-libraries, etc.
    In GBS you want to minimise the number of SubSystems.
    Most systems will require only one SubSystem and that is good!

    System

    SubSystems are grouped into a System

    Component

    To be able to handle large amount of files in a SubSystem, files are distributed in containers called Components. Typical population of a Component will be somewhere between 10 to 40 source-files. It is often a good idea to map architectural components on GBS Components.
    A GBS Component however, may very well contain more than one architectural component.

    An executable usually has the following basic Component-structure:

    Simple Component Scope Components COMP1 and COMP2 contain basic functionality.

    Component BASE contains common functions and common header-files. (Or at least one header-file containing types common to COMP1 and COMP2 like 'bool', TRUE and FALSE, NULL, etc.)

    The TOP Component contains the main.c file and the make-file for the executable.

    References are 'downwards' only. There are no references between COMP1 and COMP2.

    No matter how big an executable may become, it will always contain a 'TOP' Component with references 'down-ward', containing the main.c and the make-file for the executable.
    It will also always contain a 'BASE' Component. This is the Component all other Components refer to. (e.g.: dbg-modules, general header-file, etc). It does not refer to other Components.

    referring-to in this context means: including header-files, directly calling functions, directly accessing global variables and including of object-files/libraries during linking.

    Target / TargetStream

    A generation-sequence leading to a specific variant of a deliverable is called a TargetStream.
    The generic name of the variant is the Target.
    In GBS the directory-structure is set up in such a way that multiple TargetStreams generations can run in parallel for a SubSystem.


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Top Level Directory Structure Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    For the build process three areas can be distinguished:
    The above results in a basic directory-structure that looks like this:

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 placed from the other SubSystem in the 'res' area. (How is explained later).
    In a GBS environment a project will be split into SubSystems governed by scope-control.
    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The System-root 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 ROOT directory.

    The 'dev' directory

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

    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.

    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.

    Other Directories

    Although not mentioned before, there are also a number of other top-level directories like 'sysbuild', 'systools, '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: gbssysgen, gbssysmake, gbssysaudit and cleanup.
    The gbsexport functionality to fill res and/.or export directories is also available.

    All in an overview

    (Not complete, just showing the basic idea)
    Note: 'SS_m' stands for 'SubSystem_m', etc)

    Directory Overview

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Full Directory Structure Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    The following diagram gives an overview of the Full-GBS directory structure.
    Reserved (fixed) directory names are specified in bold.

    Full-GBS Complient Directory Overview

    Directory creation Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    Please note that GBS maintains it's own directory structure, assuring consistency.
    Never create GBS directories yourself. Let the GBS commands take care of that.

    The System (Root) directory Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    GBS_ROOT_PATH
    This is the root of the whole directory structure. It contains all that is necessary to build a multi-SubSystem system.
    Nine directories are mandatory for GBS: res, dev, ext, sys, sysbuild, sysaudit, systools, silo and tmp.
    More directories may be added. E.g. doc for documentation, etc.

    The 'res' directory

    GBS_ROOT_PATH/res
    The functionality of this directory is explained in Top Level Directory Structure → res.
    It is used to control the exchange of deliverables between SubSystems.

    The 'dev' directory

    GBS_ROOT_PATH/dev
    This directory contains all and only SubSystems.

    The 'ext' directory

    GBS_ROOT_PATH/ext
    This directory contains the directories of all 3-rd party software that is to be used by all or most of the SubSystems.

    The 'silo' directory

    GBS_ROOT_PATH/silo
    Here data is stored that is generated outside the Component structure and should be kept. E.g. doxygen output. Each Tool has its own directory.
    The command gbssilo will display any content in HTML format in a browser

    The 'sys' directory

    GBS_ROOT_PATH/sys
    This directory contains all common items (scripts, tables, etc) for sysbuild, sysaudit and systools
    e.g.: steps.gbs

    The 'sysbuild' directory

    GBS_ROOT_PATH/sysbuild
    This directory contains all items (scripts, tables, etc) for Generation (building)
    e.g.: gcc, mingw, etc

    The 'sysaudit' directory

    GBS_ROOT_PATH/sysaudit
    This directory contains all items (scripts, tables, etc) for Auditing (SCA)
    e.g.: qac, qac++, pclint, etc

    The 'systools' directory

    GBS_ROOT_PATH/systools
    This directory contains all items (scripts, tables, etc) for additional Tooling (e.g. doxygen)

    The 'tmp' directory

    GBS_ROOT_PATH/tmp
    Here GBS places its temporary files.
    It is always safe to cleanup this directory when no generations are running.
    There is an entry in gbsmaint that will do that.
    When something goes wrong GBS will not delete its tmp files, so you should cleanup this directory on a regular basis.

    The SubSystem directory Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    GBS_ROOT_PATH/dev/GBS_SUBSYS
    This is the top of a basic generation-unit.
    The SubSystem directory may have any number of Sub-Directories and files.
    The directories audit, export, build and tools are mandatory for all types of SubSystems.
    The directory comp is mandatory for Full-GBS SubSystems.
    The directory app is mandatory for Non-Full-GBS SubSystems.
    The following names are reserved for all SubSystems: import, gbs*.* and *.gbs.

    The 'export' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/export
    GBS_ROOT_PATH/dev/GBS_SUBSYS/export/GBS_TARGET

    After the build of the SubSystem, this directory will contain the files and directories that are the end-deliverables of this SubSystem.
    Items in the export directory are always generated/copied items, so they can be deleted at any time.

    The 'import' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/import
    This directory contains directories that hold deliverables from outside the System.
    This is usually 3-rd party software only used by this SubSystem.
    It is used rarely.

    The 'build' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/build
    GBS_ROOT_PATH/dev/GBS_SUBSYS/build/GBS_TARGET
    This directory contains information for the generation of the SubSystem.
    For each TargetStream that this SubSystem generates a sub-directory of the Target-name is required. Else this SubSystem will not generate for that particular TargetStream.
    These directories may contain a number of files that give information on SubSystem level.
    These include: All files and directories in these directories reside under the responsibility of the GBS Administrator in co-ordination with the architect(s) responsible for the SubSystem. They are the only ones allowed to modify these files.

    The 'audit' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/audit
    GBS_ROOT_PATH/dev/GBS_SUBSYS/audit/GBS_AUDIT/GBS_TARGET
    This directory contains information for the Auditing of the SubSystem.
    For each Audit & Target combination that this SubSystem generates a sub-directory of the Audit-name/Target-name is required. Else this SubSystem will not audit for that particular Audit & Target combination.
    All files and directories in these directories reside under the responsibility of the GBS Administrator in co-ordination with the architect(s) responsible for the SubSystem. They are the only ones allowed to modify these files.

    The 'tools' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/tools
    This directory contains information for the Step-Command execution.
    For each Step-Command Tool that this SubSystem runs a sub-directory of the Tool-name is required. Else that particular Step-Command Tool will not run for this SubSystem.
    All files and directories in these directories reside under the responsibility of the GBS Administrator in co-ordination with the architect(s) responsible for the SubSystem. They are the only ones allowed to modify these files.

    The 'comp' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp
    Full GBS only.
    This directory contains the Component directories. The name is reserved and is used only for Full GBS SubSystems.
    The only directories it contains are the Component directories that are to be recognised as under control of GBS.

    The 'app' directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/app
    Non-Full GBS only.
    This directory contains the top of the Non-GBS projects/applications directories. The name is reserved and is used only for Non-Full GBS SubSystems.

    The Component directories (Full GBS only) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT
    These directories contain the Component-Subdirectories. No other directories than the Sub-Directories specified below are allowed here.
    As far as GBS is concerned, Component names are free, except for ALL, EXPORT and RES.
    The project however, will impose rules on names here.
    You can have as many Components as you wish.
    They also contain a number of files that give information on Component level:
    Please bear in mind that a GBS Component is not necessarily an architectural Component.

    The 'src' sub-directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/src
    It contains all files that will lead to the generation of corresponding files in a 'bld' Target-directory.
    Files in this directory form the basis of the generation process. This means that the presence of a file in the src directory indicates that a step of the build-process must be executed with that file as main input.
    As a result of this all files that have to be compiled (or processed) must reside in this directory. If a file is not placed in this directory it will not be a part of the build process (compiled).
    Note that header-files are not compiled. They are included.
    Rules:

    The 'inc' sub-directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/inc
    It contains the files that are needed in the generation process but do not belong in the 'src' directory because their presence does not lead to the invocation of a processor (compiler, linker) in the build-process (and do not lead to a file with the same name in the 'bld' Sub-Directories).
    Files in this directory will be accessible from other Components. (#include)
    This means that all 'included' files like global header-files or API header-files must be placed in this directory.
    Rules:

    The 'loc' sub-directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/loc
    It contains the files that are needed in the generation process but do not belong in the 'src' directory because their presence does not lead to the invocation of a processor (compiler, linker) in the build-process (and do not lead to a file with the same name in the 'bld' Sub-Directories).
    Files in this directory will not be accessible from other Components
    This means that all 'included' files like local header-files must be placed in this directory.
    Rules:

    The 'aud' sub-directory with Autit/Target-directories

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/aud
    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/aud/GBS_AUDIT/GBS_TARGET

    The 'aud' directory acts a placeholder for the Audit-directories.

    The Audit/Target-directories contain the resulting files of Audits triggered by files in the 'src' directory.
    This means that these directories will contain any derived files.
    Rules for Audit/Target-directories:

    The 'opt' sub-directory with optional Target-directories

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/opt
    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/opt/GBS_TARGET

    This directory contains information for the generation of the Component.
    For each TargetStream that this Component generates a sub-directory of the Target-name can be present to specify exceptions. These directories contain a number of files that give information on Component level:

    The 'dat' sub-directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/dat
    It contains all other (developer) files that do not fit in any of the Sub-directories mentioned before.
    Examples are:

    The 'sav' sub-directory

    GBS_ROOT_PATH/dev/GBS_SUBSYS/comp/GBS_COMPONENT/sav
    Contains files that in no way perform a role in the build process, but still have to be kept (saved).
    This is the place to keep obsolete files like test-files that are not maintained anymore.


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Handling SubSystems & Steps Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    SubSystems Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    GBS recognises a number of SubSystem types that can be either Full GBS or Non-Full GBS.
    In general:

    MSVS SubSystem

    You should create/copy your main project of solution file directly in the 'app' directory.
    You will already have a gbssub.bat file appropriate for MSVS, with lots of comments.
    Run 'gbsedit gbssub' to change to the wanted functionality.

    make SubSystem

    You should create/copy your 'make' code tree directly in the 'app' directory.
    Your main 'make' file should be either in the SubSystem directory or the 'app' directory.
    You will already have a gbssub.bat|.sh file appropriate for 'make', with lots of comments.
    Run 'gbsedit gbssub' to change to the wanted functionality.

    Other SubSystem

    You should create/copy your code tree directly in the 'app' directory.
    You will already have a generic gbssub.bat|.sh file, with lots of comments.
    Run 'gbsedit gbssub' to change to the wanted functionality.

    Steps Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    By default SubSystems are handled (gen, make, audit) in Alphabetical order.
    With the definition of Steps in steps.gbs this order can be changed.
    It is also possible to make selections of SubSystems optional in various ways.
    It is also possible to define non-SubSystem steps, called 'Commands' that will allow you to execute commands to e.g.:
    Copy end-results to a specific directory outside then GBS tree, run Doxygen on the whole GBS tree, etc

    More information in steps.gbs.

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Procedures Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Start-up the GBS environment| Navigating the directory structure| Switch Root (System)| Switch Subsystem| Switch Component| Switch Target| Building| Compiling| Building Libraries (Archiving)| Linking| Testing| Generation by means of 'make'| Exporting deliverables| Target-streams| Builders and File-types

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    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:
    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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    To switch to another Root (System) enter:
    swr Root-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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    To switch to another Subsystem enter:
    sws SubSystem-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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    To switch to another Component enter:
    swc Component-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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    To switch to another target enter
    swt Target-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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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:
    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'.

    Typical Build (Generation) commands are:
    gbsgen files-list
    gbssysgen SubSystem-list

    Compiling Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Compiling goes straightforward according to the rules specified above.

    To compile a single file, enter:
    gbsgen file.c
    More info: Generating Code

    Building Libraries (Archiving) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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' Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    With the information as supplied above 'make' files can now be generated and executed.

    Typical commands are:
    gbsmakemake

    gbsmake target-file-name-list
    gbssysmake SubSystem-list

    To generate a single executable with 'make', enter:
    gbsmake myfile.exe
    or, if the .glk file is in a different Component than the current-Component:
    gbsmake other_component:myfile.exe

    For more information see: Generating Code

    Exporting deliverables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    Two mechanisms are used in order to prevent name-clashes (and overwriting of objects/executables):


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Software Configuration Management Support Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    GBS works independently from a Software Configuration Management System (SCMS).

    To ensure however, that GBS-managed files and directories are properly added to the SCMS, GBS provides support for a number of SCMSs:

    SCMSs supported Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    Combining an SCMS with GBS Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    During System (Root) creation (swr --new), one of the above (or 'None') may be selected.
    If 'None' is selected, you are responsible for the proper handling of all SCMS aspects.

    Note that gbsmaint offers a function to check and possibly add GBS-managed files and directories to the selected SCMS.

    How it Fits Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Terms Used

    
        REPOSITORY:--SCMS_ROOT------+              +--ext--
                                     \            /
        DISK:--------GBS_PARENT_PATH--+--SYSTEM--+---dev--
                                                  \
        DISK:<-------GBS_ROOT_PATH-------------->  +--res--
    
    

    Overview

    SCMS Repository Data Data Type
    ClearCase Implicit (VOB) None Irrelevant
    CVS URL SCMS_ROOT Informational
    SVN URL SCMS_ROOT Informational
    Git None SCMS_ROOT Informational
    Synergy EnvVar CCM_ADDR None Irrelevant
    VSS EnvVar SS_DIR SCMS_ROOT Mandatory


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The Command-line Interface Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    GBS is controlled by command-lines in an X-term or DOS-box. Here is the general behaviour of the commands:

    Entering Commands Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    In general: All GBS-commands accept --h for short help and --help for long help
    --inc=filespec will redirect the reading of the command-line arguments to a file.

    Command Syntax Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    All commands have the format: command [ positional-arg | gbs-option | gbs-env-setting ]...

    positional-arg

    Positional arguments are specified in this document as <1>, <2>, <3>
    <*> specifies: Remaining (or all if none other specified)

    gbs-option

    All gbs-options start with --

    Boolean type

    --opt and --opt+ specify value 1
    --opt- Specifies value 0

    String type

    Alphanumeric values
    Specify: --opt=value
    Specify: --opt="value-with-spaces"
    Specify: --opt='value-with-spaces'

    Integer type

    Only numbers allowed
    Specify: --opt=num-value

    Time type

    Delta (+) and Absolute (=). Default is Absolute (=)
    Syntax: [+|=][[H]H:][M]M
    Specify Delta: --opt=+HH:MM
    Specify Absolute--opt=HH:MM

    Array qualifier

    Allows specification of multiple values separated by ',' (comma)

    gbs-env-setting

    By specifying GBS_env-name=value some specific GBS Environment Variables may be given a different value for the duration of the command execution.
    The GBS_ prefix may be omitted.

    Wildcards (globbing) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Wildcards (* and ?) behave in Windows the same as on UNIX.
    This means that wild-card expansion is performed immediately on the current directory. If no match is found, the string will remain as-is.

    Inserting space characters Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The command-line works with elements separated by white-space.
    Sometimes there is a need to embed spaces in line-elements.
    E.g.: -DTEXT=STATUS QUO
    Placing an element between "" or ' ' may not always work.
    The GBS-commands will replace all occurrences of %_ (Unix), $_ (Windows) and %20 (all) in the command-line by one space.
    E.g.: -DTEXT=STATUS%_QUO ⇒ "STATUS QUO"

    Prompts Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    In a prompt, possible values are embedded in parenthesis
    e.g.:
    GBS: Are you sure? (y/n):

    In a prompt, the default value is embedded in square brackets
    e.g.:
    GBS: Are you sure? (y/n)[y]:

    Breaking off during prompt Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Entering a single '!' will quit the script.
    This is safer than the usual CTRL-C.
    All commands can be safely terminated by entering '!' at any prompt. No action will be performed.

    'Help' during prompt Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Entering a single '?' will give you some additional information on the prompt.
    Not always and not excessive.

    Messages Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    All messages generated by GBS are prefixed by the name of the file generating the message in uppercase.
    This distinguishes messages generated by GBS from those generated by the OS and/or called application(s).


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    All Commands Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    General Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    All commands have the format: command [args | gbs-options]...
    gbs-options always start with: -- (hyphen hyphen)
    General options (always available): General options (mostly available):
      command --h   will give you short help
      command --h option...   will give you short help on the specified option(s)
      command --help   will give you more extensive help
      command --help option...   will give you long help on the specified option(s)
      --verbose[+|-]   Extensive logging messages if '' or '+'
    Always '+' in BATCH jobs (gbssys* commands)
      --inc file   will take the contents of file file as if it were typed on the commandline.
    Empty lines and lines starting with '#' are ignored.
    Multiple occurrence and nesting is allowed.

    General Syntax Description

    Refer to The Command Line Interface

    Index

    bgpids, detab, filerep, fixeol, gbs, gbsaudit, gbsbldcheck, gbsedit, gbsexit, gbsexport, gbsgen, gbshelp, gbsinit, gbslocate, gbsmaint, gbsman, gbsscm, gbssetup, gbsshow, gbssilo, gbsstart, gbsstart_here, gbsstats, gbsswc, gbsswr, gbssws, gbsswt, gbssysaudit, gbssysgen, gbssysmake, gbssystool, gbsuninstall, gbswhich, gbsxref, grep, proto, swc, swr, sws, swt, tail, touch, win2unix, wordrep

    bgpids (Non-GBS - Unix only) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Show and/or kill background processes

    Syntax:

    bgpids [ USERS ]...
    [ -a | -a+ | -a- ]
    [ -f | -f+ | -f- ]
    [ -k=process_to_kill ]

    Semantics:

    USERS string
    array optional
    <empty> == current user
    Default=
    -a[+|-] do_all
    boolean
    scalar optional
    Include all processes
    Default=0
    -f[+|-] do_fg
    boolean
    scalar optional
    Include parent (foreground) processes
    Default=0
    -k=process_to_kill integer
    scalar optional
    Kill specified process-tree
    Default=

    gbs Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The gbs command will either startup GBS if not started or show the GBS currencies

    gbsinit (gbs - Before GBS is started ) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Startup GBS

    Syntax:

    gbsinit
    [ --rel=rel ]
    [ --noroot | --noroot+ | --noroot- ]

    Semantics:

    --rel=rel string
    scalar optional
    Specific GBS release. You can also specify 'cur', 'current' or '?'
    Default=.
    --noroot[+|-] noroot
    boolean
    scalar optional
    Do not implicitly swr to current root
    Default=0

    Note:

    Alias for this command is 'gbs'

    gbsaudit Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Perform an AUDIT on one or more files

    Syntax:

    gbsaudit
    [ Environment_Variable=Value ]...

    Semantics:

    None

    Environment Variables:

    (GBS_) LOG_PATH (GBS_) MODE (GBS_) FLAGS_*
    (GBS_) APP_*    

    Note:

    Summary files are written to $GBS_LOG_PATH. View with gbssilo

    gbsbldcheck Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Check if all files have generated

    Syntax:

    gbsbldcheck [ subsystems ]...
    [ --m=max_missing ]
    [ --targets=targets,... ]...

    Semantics:

    subsystems string
    array optional
    Specific SubSystems
    Default=
    --m=max_missing integer
    scalar optional
    Cancel SubSys check after this many missing files
    Default=20
    --targets=targets string
    array optional
    (wild-)Targets to Build-Check. '' or '*' == All, '.' == Current
    Default=

    gbsedit Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Create/edit GBS-files and user-files. GBS-files end with .gbs or .usr
    The switch.gbs, gbssub and gbsall batch files are also considered GBS_files
    Source, Include and glkbt-files are considered user-files
    Relevant templates will be used with file-creation

    Syntax:

    gbsedit file [ editor_opt ]
    [ --nco | --nco+ | --nco- ]

    Semantics:

    file string
    scalar mandatory
    [[[subsys:]component:]subdir:[<subpath>/]]file
    Default=
    editor_opt string
    scalar optional
    Editor option. e.g. Line-nr to jump to
    Default=
    --nco[+|-] no_checkout
    boolean
    scalar optional
    .usr files will always be forced to no_checkout
    Default=0

    gbsexit Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Exit and cleanup the GBS environment

    Syntax:

    gbsexit

    Semantics:

    None

    gbsexport Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Fill the export and/or res directories from the Components and/or Gen or SubSystem by Target

    Syntax:

    gbsexport [ export_file_locations ]...
    [ --i | --i+ | --i- ]
    [ --c | --c+ | --c- ]
    [ --show | --show+ | --show- ]
    [ Environment_Variable=Value ]...

    Semantics:

    export_file_locations string
    array optional
    <Component>... and/or GEN: or SUB:
    . == Current Component. <empty> == <all>
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation after error(s)
    Default=0
    --c[+|-] cleanup_all
    boolean
    scalar optional
    Delete all, independent from target
    Default=0
    --show[+|-] show_actions
    boolean
    scalar optional
    Show all actions
    Default=0

    Environment Variables:

    (GBS_) APP_*    

    gbsgen Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Generate one or more files

    Syntax:

    gbsgen comp_file_opts...
    [ --i | --i+ | --i- ]
    [ --export | --export+ | --export- ]
    [ --mm | --mm+ | --mm- ]
    [ --jobs=jobs ]
    [ Environment_Variable=Value ]...

    Semantics:

    comp_file_opts string
    array mandatory
    src files to generate with 'generate' options
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation regardless of error(s)
    Default=0
    --export[+|-] run_gbsexport
    boolean
    scalar optional
    Run 'gbsexport' on completion
    Default=0
    --mm[+|-] run_makemake
    boolean
    scalar optional
    Run 'makemake' on completion
    Default=0
    --jobs=jobs integer
    scalar optional
    range 1..9
    Max nr parallel jobs
    Default=2

    Environment Variables:

    (GBS_) DEBUGGER (GBS_) MODE (GBS_) OPT
    (GBS_) MAP (GBS_) FLAGS_* (GBS_) APP_*

    gbshelp Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Present help on GBS in HTML browser

    Syntax:

    gbshelp

    Semantics:

    None

    gbslocate Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Locate a file according to include-settings and assigns the location to a specified Environment Variable

    Syntax:

    gbslocate env_name file prefix path-list...

    Semantics:

    env_name string
    scalar mandatory
    Env Variable to contain the filespec
    Default=
    file string
    scalar mandatory
    The file to search
    Default=
    prefix string
    scalar mandatory
    prefix string preceding all path-list elements. e.g: -I
    Default=
    path-list string
    array mandatory
    The directories to search preceded by <prefix>
    Default=

    gbsmaint Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Allow user to execute General Maintenance functions
     1. Audits Handling
     2. Cleanup
     3. Map Network Drives (unix<->win32)
     5. User Tools
     6. Integrator Tools
     7. Administrator Tools
     8. Check/Fix GBS Directory Structure
     9. Owners-file Maintenance

    Syntax:

    gbsmaint [ menu_entry_1 ] [ menu_entry_2 ] [ menu_entry_3 ] [ menu_entry_4 ] [ menu_entry_5 ]

    Semantics:

    menu_entry_1 integer
    scalar optional
    range 1..9
    Primary menu entry for single immediate execution
    Default=0
    menu_entry_2 integer
    scalar optional
    greater 0
    Secondary menu entry for single immediate execution
    Default=0
    menu_entry_3 integer
    scalar optional
    greater 0
    3rd menu entry for single immediate execution
    Default=0
    menu_entry_4 integer
    scalar optional
    greater 0
    4th menu entry for single immediate execution
    Default=0
    menu_entry_5 integer
    scalar optional
    greater 0
    5th menu entry for single immediate execution
    Default=0

    gbsmake Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    gbsmakemake Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    gbsman Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The gbsman command gives a 'more' list of all GBS commands

    Syntax:

    gbsman

    Semantics:

    None

    gbssetup (gbssetup.bat or gbssetup.sh) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Setup/Maintain Basic GBS settings (EnvVars).

    Syntax:

    gbssetup [ menu_entry_1 ]

    Semantics:

    menu_entry_1 integer
    scalar optional
    range 1..7
    Menu entry for immediate execution
    Default=0

    gbsuninstall (gbsuninstall.bat or gbsuninstall.sh) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Uninstall GBS version(s).

    Syntax:

    gbsuninstall [ ?|all|full|versions ] [ versions ]...

    Semantics:

    action string
    scalar optional
    choice: ?,all,full,versions
    Action. Default is interactive ask
    Default=
    versions string
    array optional
    Versions  List
    Default=

    gbsshow (gbs) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Show GBS currencies

    Syntax:

    gbsshow
    [ --brief | --brief+ | --brief- ]

    Semantics:

    --brief[+|-] brief
    boolean
    scalar optional
    Brief (short) listing
    Default=0

    gbssilo Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Generate silo index and show in HTML browser

    Syntax:

    gbssilo
    [ --ci | --ci+ | --ci- ]
    [ --cs | --cs+ | --cs- ]
    [ --vi | --vi+ | --vi- ]
    [ --noc | --noc+ | --noc- ]

    Semantics:

    --ci[+|-] create_index
    boolean
    scalar optional
    Create the HTML Index
    Default=1
    --cs[+|-] create_summaries
    boolean
    scalar optional
    Create the HTML Summaries
    Default=1
    --vi[+|-] view_index
    boolean
    scalar optional
    View index in HTML browser
    Default=1
    --noc[+|-] no_create
    boolean
    scalar optional
    No HTML Creation (forces --ci and --cs to '-')
    Default=0

    Constraints:

    gbssysaudit Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Perform an AUDIT on part of or whole System

    Syntax:

    gbssysaudit [ steps ]...
    [ --i | --i+ | --i- ]
    [ --vs | --vs+ | --vs- ]
    [ --audits=audits,... ]...
    [ --targets=targets,... ]...
    [ --files=files,... ]...
    [ --aud | --aud+ | --aud- ]
    [ --sum | --sum+ | --sum- ]
    [ --fg | --fg+ | --fg- ]
    [ --at=delay ]
    [ --sm | --sm+ | --sm- ]
    [ --n | --n+ | --n- ]
    [ --wait | --wait+ | --wait- ]
    [ --jobs=jobs ]
    [ --c=comment ]
    [ Environment_Variable=Value ]...

    Semantics:

    steps string
    array optional
    Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation after error(s)
    Default=0
    --vs[+|-] view_sum
    boolean
    scalar optional
    View summary at completion
    Default=1
    --audits=audits string
    array optional
    (wild-)Audits to run. '' or '*' == All, '.' == Current
    Default=*
    --targets=targets string
    array optional
    (wild-)Targets to Audit. '' or '*' == All, '.' == Current
    Default=*
    --files=files string
    array optional
    Files to audit
    Default=*:*.*
    --aud[+|-] audit
    boolean
    scalar optional
    Run audit
    Default=1
    --sum[+|-] summary
    boolean
    scalar optional
    Create summary
    Default=1
    --fg[+|-] foreground
    boolean
    scalar optional
    Runs in the foreground if set
    Default=0
    --at=delay time ([+=]hh:mm or [+=]mm)
    scalar optional
    Starting time (10:20), delta (+10:10) or now
    Default=now
    --sm[+|-] mail
    boolean
    scalar optional
    Send mail on completion
    Default=0
    --n[+|-] notify
    boolean
    scalar optional
    Notify user on completion (bg/nowait only)
    Default=1
    --wait[+|-] wait
    boolean
    scalar optional
    Wait for completion of bg jobs
    Default=0
    --jobs=jobs integer
    scalar optional
    range 1..9
    Max nr parallel jobs within a submitted job
    Default=2
    --c=comment string
    scalar optional
    Comments - will be shown in Summary - Specify %20 for space
    Default=

    Constraints:

    Environment Variables:

    (GBS_) LOG_PATH (GBS_) FLAGS_* (GBS_) APP_*

    Note:

    Summary files are written to $GBS_SILO_PATH/audits. View with gbssilo
    See also: The gbssys... commands

    gbssysgen Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Generate part of or whole System

    Syntax:

    gbssysgen [ steps ]...
    [ --i | --i+ | --i- ]
    [ --mm | --mm+ | --mm- ]
    [ --export | --export+ | --export- ]
    [ --targets=targets,... ]...
    [ --fg | --fg+ | --fg- ]
    [ --files=files,... ]...
    [ --at=delay ]
    [ --sm | --sm+ | --sm- ]
    [ --n | --n+ | --n- ]
    [ --wait | --wait+ | --wait- ]
    [ --jobs=jobs ]
    [ --c=comment ]
    [ Environment_Variable=Value ]...

    Semantics:

    steps string
    array optional
    Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation after error(s)
    Default=0
    --mm[+|-] run_makemake
    boolean
    scalar optional
    Run 'gbsmakemake' on completion of Full GBS SubSystems
    Default=1
    --export[+|-] run_export
    boolean
    scalar optional
    Run 'gbsexport' on completion
    Default=1
    --targets=targets string
    array optional
    (wild-)Targets to Build. '' or '*' == All, '.' == Current
    Default=*
    --fg[+|-] foreground
    boolean
    scalar optional
    Runs in the foreground if set
    Default=0
    --files=files string
    array optional
    Files to gen
    Default=*:*.*
    --at=delay time ([+=]hh:mm or [+=]mm)
    scalar optional
    Starting time (10:20), delta (+10:10) or now
    Default=now
    --sm[+|-] mail
    boolean
    scalar optional
    Send mail on completion
    Default=0
    --n[+|-] notify
    boolean
    scalar optional
    Notify user on completion (bg/nowait only)
    Default=1
    --wait[+|-] wait
    boolean
    scalar optional
    Wait for completion of bg jobs
    Default=0
    --jobs=jobs integer
    scalar optional
    range 1..9
    Max nr parallel jobs within a submitted job
    Default=2
    --c=comment string
    scalar optional
    Comments - will be shown in Summary - Specify %20 for space
    Default=

    Constraints:

    Environment Variables:

    (GBS_) LOG_PATH (GBS_) DEBUGGER (GBS_) MODE
    (GBS_) OPT (GBS_) MAP (GBS_) FLAGS_*
    (GBS_) APP_*    
    See also: The gbssys... commands

    gbssysmake Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Generate part of or whole System using 'make'

    Syntax:

    gbssysmake [ steps ]...
    [ --i | --i+ | --i- ]
    [ --smm | --smm+ | --smm- ]
    [ --mm | --mm+ | --mm- ]
    [ --export | --export+ | --export- ]
    [ --targets=targets,... ]...
    [ --files=files,... ]...
    [ --fg | --fg+ | --fg- ]
    [ --at=delay ]
    [ --sm | --sm+ | --sm- ]
    [ --n | --n+ | --n- ]
    [ --wait | --wait+ | --wait- ]
    [ --jobs=jobs ]
    [ --c=comment ]
    [ Environment_Variable=Value ]...

    Semantics:

    steps string
    array optional
    Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation after error(s)
    Default=0
    --smm[+|-] start_makemake
    boolean
    scalar optional
    Pre-generate the make-file
    Default=1
    --mm[+|-] run_makemake
    boolean
    scalar optional
    Run 'gbsmakemake' on completion of Full GBS SubSystems
    Default=1
    --export[+|-] run_export
    boolean
    scalar optional
    Run 'gbsexport' on completion
    Default=1
    --targets=targets string
    array optional
    (wild-)Targets to Build. '' or '*' == All, '.' == Current
    Default=*
    --files=files string
    array optional
    Files to make
    Default=*:*.*
    --fg[+|-] foreground
    boolean
    scalar optional
    Runs in the foreground if set
    Default=0
    --at=delay time ([+=]hh:mm or [+=]mm)
    scalar optional
    Starting time (10:20), delta (+10:10) or now
    Default=now
    --sm[+|-] mail
    boolean
    scalar optional
    Send mail on completion
    Default=0
    --n[+|-] notify
    boolean
    scalar optional
    Notify user on completion (bg/nowait only)
    Default=1
    --wait[+|-] wait
    boolean
    scalar optional
    Wait for completion of bg jobs
    Default=0
    --jobs=jobs integer
    scalar optional
    range 1..9
    Max nr parallel jobs within a submitted job
    Default=2
    --c=comment string
    scalar optional
    Comments - will be shown in Summary - Specify %20 for space
    Default=

    Constraints:

    Environment Variables:

    (GBS_) LOG_PATH (GBS_) DEBUGGER (GBS_) MODE
    (GBS_) OPT (GBS_) MAP (GBS_) FLAGS_*
    (GBS_) APP_*    
    See also: The gbssys... commands

    gbssystool Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Perform TOOL on part of or whole System

    Syntax:

    gbssystool [ steps ]...
    [ --i | --i+ | --i- ]
    [ --vs | --vs+ | --vs- ]
    [ --fg | --fg+ | --fg- ]
    [ --at=delay ]
    [ --sm | --sm+ | --sm- ]
    [ --n | --n+ | --n- ]
    [ --wait | --wait+ | --wait- ]
    [ --jobs=jobs ]
    [ --c=comment ]
    [ Environment_Variable=Value ]...

    Semantics:

    steps string
    array optional
    Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps
    Default=
    --i[+|-] ignore_errors
    boolean
    scalar optional
    Continue generation after error(s)
    Default=0
    --vs[+|-] view_sum
    boolean
    scalar optional
    View summary at completion
    Default=1
    --fg[+|-] foreground
    boolean
    scalar optional
    Runs in the foreground if set
    Default=0
    --at=delay time ([+=]hh:mm or [+=]mm)
    scalar optional
    Starting time (10:20), delta (+10:10) or now
    Default=now
    --sm[+|-] mail
    boolean
    scalar optional
    Send mail on completion
    Default=0
    --n[+|-] notify
    boolean
    scalar optional
    Notify user on completion (bg/nowait only)
    Default=1
    --wait[+|-] wait
    boolean
    scalar optional
    Wait for completion of bg jobs
    Default=0
    --jobs=jobs integer
    scalar optional
    range 1..9
    Max nr parallel jobs within a submitted job
    Default=2
    --c=comment string
    scalar optional
    Comments - will be shown in Summary - Specify %20 for space
    Default=

    Constraints:

    Environment Variables:

    (GBS_) LOG_PATH (GBS_) FLAGS_* (GBS_) APP_*

    Note:

    Output files (Summary files) are written to $GBS_SILO_PATH/audits. View with gbssilo
    See also: The gbssys... commands

    gbsstart (%GBS_BASE_PATH%\gbsstart.bat or $GBS_BASE_PATH/gbsstart.sh) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Startup GBS and execute a (GBS) command. To be used for integration of GBS in other tools

    Syntax:

    gbsstart root [ subsystem ] [ component ]
    [ --target=target ]
    [ --audit=audit ]
    [ --tool=tool ]
    --exec=execute_command
    [ --rel=rel ]

    Semantics:

    root string
    scalar mandatory
    System / Root: '-' == none, '.' == current, '!' == CWD, '!<abs_file/dir_spec>', '!!' == CWD = GBS_ROOT_PATH
    Default=!
    subsystem string
    scalar optional
    SubSystem: '-' == none, '.' or '' == current
    Default=
    component string
    scalar optional
    Component: '-' == none, '.' or '' == current
    Default=
    --target=target string
    scalar optional
    Target: '-' == none, '.' or '' == current
    Default=.
    --audit=audit string
    scalar optional
    Audit: '-' == none, '.' or '' == current
    Default=.
    --tool=tool string
    scalar optional
    Toolt: '-' == none, '.' or '' == current
    Default=.
    --exec=execute_command string
    scalar mandatory
    (GBS-)Command to execute. 'none' = OK
    Default=
    --rel=rel string
    scalar optional
    Specific GBS release.  You can also specify 'cur' or 'current'
    Default=.

    Constraints:

    More info:

    For Tools integration purposes, use the replacing gbsstart_here command.

    gbsstart_here (%GBS_BASE_PATH%\gbsstart_here.bat or $GBS_BASE_PATH/gbsstart_here.sh) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Startup GBS and execute a (GBS) command, using the CWD.
    To be used for integration of GBS in other Development Tools / Editors.
    Replaces 'gbsstart' in most situations

    Syntax:

    gbsstart_here gbs_command [ gbs_command_args ]...

    Semantics:

    gbs_command string
    scalar mandatory
    GBS command. e.g.: gbsgen
    Default=
    gbs_command_args string
    array optional
    GBS command args, including --options
    Default=

    More info:

    Integration with other Tools

    gbsstats Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Show GBS System Statistics

    Syntax:

    gbsstats
    [ --lines | --lines+ | --lines- ]
    [ --cs | --cs+ | --cs- ]
    [ --vi | --vi+ | --vi- ]

    Semantics:

    --lines[+|-] count_lines
    boolean
    scalar optional
    Count lines in src, inc and loc
    Default=0
    --cs[+|-] create_stats
    boolean
    scalar optional
    Create the HTML Statistics
    Default=1
    --vi[+|-] view_index
    boolean
    scalar optional
    View index in HTML browser
    Default=1

    swc (gbsswc) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Set and/or Create new Current Component

    Syntax:

    gbsswc swc [ component ]
    [ --target=target ]
    [ --new | --new+ | --new- ]
    [ --nocd | --nocd+ | --nocd- ]

    Semantics:

    component string
    scalar optional
    Component: '' == ASK, '-' == none, '.' == current
    Default=
    --target=target string
    scalar optional
    Target: '-' == none, '.' == current
    Default=
    --new[+|-] create_new_component
    boolean
    scalar optional
    Create a new Component
    Default=0
    --nocd[+|-] no_cd
    boolean
    scalar optional
    Do not 'cd' to the selected directories
    Default=0

    Constraints:

    swr (gbsswr) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Set a current Root/System or
    Create a new one, Add / Remove one from the Roots List or Show the Roots List

    Syntax:

    gbsswr swr [ root_path ] [ subsystem ] [ component ]
    [ --target=target ]
    [ --audit=audit ]
    [ --tool=tool ]
    [ --new | --new+ | --new- ]
    [ --add | --add+ | --add- ]
    [ --remove | --remove+ | --remove- ]
    [ --show | --show+ | --show- ]
    [ --exec=execute_command ]
    [ --nocd | --nocd+ | --nocd- ]

    Semantics:

    root_path string
    scalar optional
    System / Root: '' == ASK, '-' == none, '.' == current, '!' == CWD, '!<abs_file/dir_spec>', '!!' == CWD = GBS_ROOT_PATH
    Default=
    subsystem string
    scalar optional
    SubSystem: '-' == none, '.' == current
    Default=
    component string
    scalar optional
    Component: '-' == none, '.' == current
    Default=
    --target=target string
    scalar optional
    Target: '-' == none, '.' == current
    Default=.
    --audit=audit string
    scalar optional
    Audit: '-' == none, '.' == current
    Default=.
    --tool=tool string
    scalar optional
    Tool: '-' == none, '.' == current
    Default=.
    --new[+|-] create_new_root
    boolean
    scalar optional
    Create a new System / Root
    Default=0
    --add[+|-] add_root
    boolean
    scalar optional
    Add a Root to the Roots List
    Default=0
    --remove[+|-] remove_root
    boolean
    scalar optional
    Remove a Root from the Roots List
    Default=0
    --show[+|-] show_roots
    boolean
    scalar optional
    Show the Roots List
    Default=0
    --exec=execute_command string
    scalar optional
    (GBS-)Command(s) to execute. 'none' = OK
    Default=
    --nocd[+|-] no_cd
    boolean
    scalar optional
    Do not 'cd' to the selected directories
    Default=0

    Constraints:

    Note:

    You can only '--add' a Root if it was originally created by 'swr --new'

    sws (gbssws) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Set and/or Create new Current SubSystem

    Syntax:

    gbssws sws [ subsystem ] [ component ]
    [ --target=target ]
    [ --new | --new+ | --new- ]
    [ --nocd | --nocd+ | --nocd- ]

    Semantics:

    subsystem string
    scalar optional
    SubSystem. '' == ASK, '-' == none, '.' == current
    Default=
    component string
    scalar optional
    Component. '-' == none, '.' == current
    Default=
    --target=target string
    scalar optional
    Target. '-' == none, '.' == current
    Default=
    --new[+|-] create_new_subsys
    boolean
    scalar optional
    Create a new SubSystem
    Default=0
    --nocd[+|-] no_cd
    boolean
    scalar optional
    Do not 'cd' to the selected directories
    Default=0

    Constraints:

    swt (gbsswt) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Set and/or Create new Current Target

    Syntax:

    gbsswt swt [ target ]
    [ --new | --new+ | --new- ]
    [ --remove | --remove+ | --remove- ]

    Semantics:

    target string
    scalar optional
    Target: '' == ASK, '-' == none, '.' == current
    Default=
    --new[+|-] create_new_target
    boolean
    scalar optional
    Create a new Target
    Default=0
    --remove[+|-] remove_target
    boolean
    scalar optional
    Remove a Target from the Targets List
    Default=0

    Constraints:

    gbswhich Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Lookup header-files, objects, flags

    Syntax:

    gbswhich [ file_or_type_or_comp ] [ search_type ]
    [ Environment_Variable=Value ]...

    Semantics:

    file_or_type_or_comp string
    scalar optional
    filetype or Component or filename or SubDir/filename or */filename
    Default=
    search_type string
    scalar optional
    filetype to search
    Default=

    Environment Variables:

    (GBS_) FLAGS_*    

    gbsxref Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Show cross-references using makefiles and/or scope-files Launcher

    Syntax:

    gbsxref

    Semantics:

    None

    grep tail touch and more... (Non-GBS - Windows Only) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    How any programmer can survive without 'grep' is beyond my understanding...
    Gratefully copied from Karl M. Syring 's UnxUtils (now OpenSource) and (partly) delivered as part of GBS.
    Please read the Standard Disclaimer.
    Some extra help can be found UnxUtils Home Page. Note that not all commands are distributed with GBS. Feel free to request additions.

    The executables are located in '%GBS_SCRIPTS_PATH%/win2utils'.
    You may consider adding the win32utils directory in your PATH.
    In switch.gbs.bat add:
    IF "%WIN32UTILS_IN_PATH%"=="" THEN PATH=%GBS_SCRIPTS_PATH%\win2util;%PATH%
    SET WIN32UTILS_IN_PATH=1

    Syntax and Help:

    On Command Line the following commands are predefined (DosKey):
     grep --help
    egrep --help
    agrep --help
     tail --help
    touch --help
    which --help

    In GBS 'make' or via '%GBS_SCRIPTS_PATH%/win2utils' you can use:
       cp --help
     find --help
     gawk --help
     make --help
       rm --help
      sed --help
      tar --help

    proto (Non-GBS) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Generate function-prototypes for C, C++ and Perl

    Syntax:

    proto [ files ]

    Semantics:

    files string
    scalar optional
    Files to be parsed
    Default=*.c *.cpp *.oc *.pl *.pm

    detab (Non-GBS) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Replace TABs by spaces in files

    Syntax:

    detab [ files ]
    [ -t | -t+ | -t- ]
    [ -r | -r+ | -r- ]
    [ -f=wild_files,... ]...
    [ -m=modulo ]
    [ -s | -s+ | -s- ]

    Semantics:

    files string
    scalar optional
    Files to process or directory in case of -r
    Default=
    -t[+|-] test
    boolean
    scalar optional
    test only - do not make modifications
    Default=0
    -r[+|-] recurse
    boolean
    scalar optional
    recurse directory looking for -f= files
    Default=0
    -f=wild_files string
    array optional
    wild-card files to process
    Default=
    -m=modulo integer
    scalar optional
    The TAB size the file was created with
    Default=8
    -s[+|-] smart_tabs
    boolean
    scalar optional
    retab leading whitespace (modulo 8)
    Default=0

    gbsscm (scm) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Execute basic SCM commands using the current SCMS

    Syntax:

    gbsscm ?|info|state|co|ci|unco|mkdir|mktxt|add|move|ignore|remove|import|connect|stop|select [ files ]...
    [ --r | --r+ | --r- ]

    Semantics:

    command string
    scalar mandatory
    choice: ? info state co ci
            unco mkdir mktxt add move ignore
            remove import connect stop select
    Basic SCM Command
    Default=
    files string
    array optional
    File / Directory  List
    Default=
    --r[+|-] recursive
    boolean
    scalar optional
    Add whole directory tree
    Default=0

    Note:

    info
    state   <file-dir>...
    co      <file-dir>...
    ci      <file-dir>...
    unco    <file-dir>...
    mkdir   <dir>...
    mktxt   <file>...
    add     <file-dir>...
    ignore  <file-dir>...
    remove  <file-dir>...
    import  <from-dir> [<to-dir>]
    connect
    stop
    select

    win2unix (Non-GBS - Unix Only) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The win2unix command will convert Files from Windows-format to Unix-format

    Syntax:

    win2unix files...

    Semantics:

    files string
    array mandatory
    Files to convert
    Default=

    fixeol (Non-GBS) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Fix EndOfLine characters of specified file(s) according to the invoking Operating System

    Syntax:

    fixeol files...

    Semantics:

    files string
    array mandatory
    Files to be fixed
    Default=

    wordrep (Non-GBS) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Replace words/strings in files

    Syntax:

    wordrep command_or_commandsfile [ files ]
    [ -t | -t+ | -t- ]
    [ -r | -r+ | -r- ]
    [ -f=wild-files,... ]...

    Semantics:

    command_or_commandsfile string
    scalar mandatory
    Replace Command or filespec of file containing Replace Commands
    Replace Command: <delim><find><delim><replace><delim>[w|b|e|a|r][i]
    - w = find word, b = find begin word, e = find end word
    - a = find any,  r = find Perl regular expression
    - i = ignore case of search string
    - \s in replace string is converted to single space
    commandsfile:  Empty lines and lines beginning with '#' are ignored
    Default=
    files string
    scalar optional
    Files to process
    Default=
    -t[+|-] test
    boolean
    scalar optional
    test only - do not make modifications
    Default=0
    -r[+|-] recurse
    boolean
    scalar optional
    recurse directory looking for -f= files
    Default=0
    -f=wild-files string
    array optional
    wild-card files to process
    Default=

    Note:

    Directory/Files starting with '.' are skipped

    Note:

    No check-out is performed on file(s)

    filerep (Non-GBS) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Purpose:

    Rename/Delete files

    Syntax:

    filerep command_or_commandsfile [ files ]
    [ -t | -t+ | -t- ]
    [ -r | -r+ | -r- ]
    [ -f=wild-files,... ]...

    Semantics:

    command_or_commandsfile string
    scalar mandatory
    Rename/Delete Command or filespec of file containing Rename/Delete Commands
    Rename/Delete Command: <delim><find><delim><replace><delim>[g|r][i]
    - g = glob rename (default)
    - r = Perl regular expression rename
    - i = ignore case of search string
    Empty <replace> deletes the file
    commandsfile:  Empty lines and lines beginning with '#' are ignored
    Default=
    files string
    scalar optional
    Files to process
    Default=
    -t[+|-] test
    boolean
    scalar optional
    test only - do not make modifications
    Default=0
    -r[+|-] recurse
    boolean
    scalar optional
    recurse directory looking for -f= files
    Default=0
    -f=wild-files string
    array optional
    wild-card files to process
    Default=

    Note:

    Directory/Files starting with '.' are skipped

    Note:

    No check-out is performed on file(s)


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The gbssys... commands Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    gbssysgen, gbssysmake, gbssysaudit and gbssystool Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    The gbssys... commands are used to perform actions involving more than one SubSystem.

    gbssysgen   is used to generate a whole or part of a whole System
    gbssysmake   is used to 'make' a whole or part of a whole System
    gbssysaudit   is used to audit a whole or part of a whole System
    gbssystool   is used run a tool on the whole or part of a whole System

    These commands will perform their functions over various SubSystems in the appropriate order and allows extra steps to be executed.
    It is also possible to generate a number of SubSystems selectively.
    The generations steps, their required order and allowed options are defined in the steps.gbs file (in $GBS_SYS_PATH).
    Execution will be performed in the batch and the output is logged in a log-file.

    Usage

    gbssys...  [ steps ] [ GBS-options ] [ APP-options ] [ GBS-env-variables ] [ other_gbs_options ]
    steps
    Specifies the names of the steps to be executed
    The stepnames are defined in the steps.gbs file.
    If no steps are specified, all steps are assumed.
    The '-' can be used to specify 'from - to' steps. It must be surrounded by spaces.
    An empty 'from' specifies 'from the first'
    An empty 'to' specifies 'to and including the last'
    E.g.: step1 - step3 step6 step8 step9 -
    -→ step1 step2 step3 step6 step8 step9 step10 step11 ... stepnn

    GBS-options
    Contain an '='.
    Standard GBS-options:
    TARGET =...
    DEBUGGER =,YES,NO
    MODE =,FINAL,ASSERT,DEBUG
    OPT =,YES,SPEED,SIZE,NO
    MAP =,NO,YES
    FLAGS_MAKE =...
    FLAGS_src_type =...
    e.g.: TARGET=FINAL MODE=DEBUG

    APP-options
    Contain an '=' As defined in the sys.gbs file
    e.g. PROFILING=YES

    GBS-env-variables
    Any assignment that starts with GBS_ is considered a request to define a (temporary) GBS environment-variable with that value.
    e.g. GBS_FLAGS_MAKE="-u" will set the GBS_FLAGS_MAKE Environment Variable to the specified value for the duration on the command.

    LOG files Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    .log files

    Log files are written to $GBS_LOG_PATH, which unless defined in switch.gbs points to $GBS_LOG_ROOT/$GBS_ROOT_PARENT.
    For each run 2 to 3 files will be generated:

    The logfile_name

    gbssys-command_target-or-tool_audit-or-hyphen_packed-num-date-time
    packed-num-date-time := YYYYMMDD-hhmmss
    E.g.: gbssysaudit_mingw_pclint_20150214-12:00:00

    The .log.sum file

    This file contains a summary of the .log file.
    It is a fixed-format file. One item per line.
    Its layout will never change. Although new items may be added at the end, before the <<EOF>>.
    This file can be used for your own tooling to extract information from the run.
    Format:
    jobname : gbssysgen gbssysmake gbssysaudit gbssystool'
    target_or_tool :
    uname : computer name and id
    os_root_spec : $GBS_ROOT_PATH
    os_logfile_spec : $GBS_LOG_PATH/$jobname_$target_$audit_$datetime.log
    time_start : YYYY-MM-DD hh:mm:ss
    time_end : YYYY-MM-DD hh:mm:ss
    time_diff : hhh:mm:ss
    timer_diff : "$clock $cpu_system $cpu_user $cpu_all" in seconds
    state : NORMAL FAILED KILLED
    rc : Return Code (Numeric. 0 == OK)
    audit : or '-'
    date_time : YYMMDD-hhmmss as used in os_logfile_name
    command_args : From the command-line
    comment : From the command-line (--c=...)
    <<EOF>> :

    .html files

    These are the Summary files resulting from gbsaudit and not from gbssysaudit

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Generating Code Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    The difference between GBSGEN and GBSMAKE Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    gbsgen

    gbsmake

    Specifying Files in GBSGEN, GBSMAKE and GBSAUDIT Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Syntax

    The generic syntax to specify files in GBSGEN, GBSMAKE and GBSAUDIT is:

        [options1]... [ [[Component:][file]... [options2] ]...

    The string is parsed left-to-right, setting the 'current-Component' as specified with Component:
    Both Component and file may contain wild-cards.
    file may be a comma-list, binding it to a possibly prefixed Component

    e.g.: gbsgen *_test:*.c
    Will generate all *.c files in all Components suffixed with '_test'
    e.g.: gbsgen *_test:*.c,*.cpp main: *.glk *.glb
    Will generate all *.c and *.cpp files in all Components suffixed with '_test' then all *.glk in 'main' and then all *.glb in 'main'.
    e.g.: gbsgen *:*.*
    Will generate all files in all Components (within the SubSystem), in the proper order.
    For this particular purpose however you should use gbssysgen SubSystem.

    gbsgen, gbsaudit

    options1 if present, will be passed to all file-generations

    options2 if present, will be passed to all file-generations preceding the options2

    gbsmake

    options1 if present, will be passed to 'make'

    options2 cannot be present in gbsmake. Use the GBS_FLAGS_type to specify options with gbsmake.

    Typical use of GBSGEN:

        gbsgen my_file.c -DTEST comp1.c  comp2:test.c -DTEST2
    

    This results in:

    1. Compile my_file.c in the current Component with options -DTEST
    2. Compile comp1.c in the current Component
    3. Compile test.c in Component comp2 with options -DTEST2

    Specifying FLAGS (-D) Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    There are predefined FLAGS for Debug-Mode, Debugger, Optimizer and Map-files
    - Do not specify -G but DEBUGGER=YES
    - Do not specify -DDEBUG but MODE=DEBUG
    Full list:

    Flags will be placed behind the generation scripts own flags in the following order

    1. (generation-scripts own flags)
    2. Flags in $GBS_BUILD_PATH/flags_type.gbs
    3. Flags in $GBS_BUILD_PATH/$GBS_TARGET/flags_type.gbs
    4. Flags in $GBS_COMPONENT_OPT_PATH/flags_type.gbs
    5. Flags in $GBS_COMPONENT_OPT_PATH/$GBS_TARGET/flags_type.gbs
    6. Flags in Env. variable GBS_FLAGS_TYPE (either pre-set or on command-line)
    7. Flags in GBS Command-line

    Specifying Search Paths (for -I and -L) Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    Include Paths are passed to the generation scripts in the following order

    1. ../loc
    2. ../inc
    3. ../bld/$GBS_TARGET (Only for glkbt builds)
    4. as specified in $GBS_COMPONENT_PATH/scope.gbs:
      Component/inc or
      Component/inc and Component/bld/$GBS_TARGET
    5. as specified in $GBS_COMPONENT_OPT_PATH/$GBS_TARGET/incs_type.gbs
    6. as specified in $GBS_COMPONENT_OPT_PATH/incs_type.gbs
    7. as specified in $GBS_BUILD_PATH/incs_TYPE.gbs
    8. as specified in $GBS_BUILD_PATH/$GBS_TARGET/incs_TYPE.gbs
    9. as specified in $GBS_SYSBUILD_PATH/incs_TYPE.gbs
    10. as specified in $GBS_SYSBUILD_PATH/$GBS_TARGET/incs_TYPE.gbs
    11. as specified in the generation-script

    Note that the contents of the incs_TYPE.gbs files must refer to directories outside the current (Sub)System.

    Do not prefix directories (with -I or -L)


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Generating Libraries & Executables and Testing Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    Archiving Object-files to Libraries Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    The glb extensions are used to build libraries from object files.
    For each library to be built there must be a glb-file in the source-directory, specifying the files to be included in the library.
    The name of the library will be equal to the prefix of the glb-file, suffixed with the proper extension.
        (e.q.: total.glbtotal.lib)
    'glb' Stands for GBS librarian

    Specifying a file to be of the glb type tells GBS that the output files will be eligible for the -L statement while linking.
    Description of the glb files can be found here.

    Linking Object-files and Libraries to Executables Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The .glk extensions are used to build executables from object files and libraries.
    For each executable to be built there must be a glk-file in the source-directory, specifying the files/libraries of the link.
    The name of the executable will be equal to the prefix of the glk-file, suffixed with the proper extension.
        (e.q.: total.glktotal.exe)
    'glk' Stands for GBS linker

    Specifying a file to be of the glk type tells GBS that -L statement will cause searching for libraries as generated by glb.
    Description of the glk files can be found here.

    Testing Executables Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    The .glt extensions are used to test executables.
    For each executable to be tested there must be a glt-file in the source-directory, specifying the executable and its parameters.
    The output of the test (the log) will go to the target-directory. The name of the logfile will be equal to the prefix of the glt-file, suffixed with .log.
        (e.q.: total.glttotal.log)
    'glt' Stands for GBS link test

    Specifying a file to be of the glt type tells GBS that there may be special glt_ keywords in the glt file.
    glt_ keywords must be specified at the top of the file, prefixed with '^',
    followed by the executable-spec on a single line,
    followed by the parameters, each on a single line.
    Note:


    Description of the glt files can be found here.

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Exporting Deliverables Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    The gbsexport command Bottom Doc. Button Top Document Button Blank Blank Blank Blank

    The gbsexport command is used to copy files from Components and/or Gen or SubSystem to the export-directories:

    gbsexport will process the export.gbs files in the Component directories do determine what must be exported (copied to the export and/or res/subsys directory).

    The presence of an export directory determines copy to export.
    The presence of a res/SubSystem directory determines the copy to res.
    Components not containing a bld/$GBS_TARGET directory will be skipped.
    During copy the file dates are preserved.

    The creation of (msi) install programs is also supported in this command
    The syntax of the command can be found here.
    The description of the export.gbs file can be found here.


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Auditing (e.g. QAC, PCLint) Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    gbsaudit| gbssysaudit
    Predefined Audits
    QAC| QAC++| PCLint

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    gbsaudit Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The gbsaudit command will run an audit for one or more files in a Component.
    It will generate a concatenated Audit output file optionally followed by a Summary.
    The Summary is also generated in a separate file.
    Upon completion the output file(s) are presented to the caller in a separate window.

    The syntax of the gbsaudit command can be found here.

    Notes:

    An Audit will only run for SubSystems that

    1. Are Full-GBS and
      Contain an Audit specific directory in the GBS_AUDIT_PATH directory.
    2. Are Non-GBS and
      Contain an audit script in the GBS_SUBSYS_PATH directory

    Predefined audits can be installed with the gbsmaint command.

    gbssysaudit Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Executes the audit on all files in one or more or all SubSystems in a System (provided the SubSystem is enabled for the audit)

    The syntax of the gbssysaudit command can be found here.

    Predefined Audits Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    QAC Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Audit name:

    qac

    Required:

    GBSEXT_QAC_PATH The main directory for QAC
    GBSEXT_QAC_REL The selected QAC release

    Include-file handling

    Same way as for C-compilation
    Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C compliant.

    Handling of compile time options

    Same way as for C compilations

    General Notes:

    QAC++ Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Audit name:

    qacpp

    Required:

    GBSEXT_QACPP_PATH The main directory for QAC++
    GBSEXT_QACPP_REL The selected QAC++ release

    Include-file handling

    Same way as for C++-compilation
    Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C++ compliant.

    Handling of compile time options

    Same way as for C++ compilations

    General Notes:

    PCLint Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Audit name:

    pclint

    Required:

    GBSEXT_PCLINT_PATH The main directory for PCLint
    GBSEXT_PCLINT_REL The selected PCLint release

    Include-file handling

    Same way as for C and C++-compilation
    Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C/ANSI-C++ compliant.

    Handling of compile time options

    Same way as for C and C++ compilations

    General Notes:



    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Customisations (Session) Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    GBS_DEBUGGER| GBS_MAP| GBS_MODE| GBS_OPT| GBS_FLAGS_type

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    A few customisations can be made on the command-line and will only be valid during a Command-Line session and between swr commands.
    They control the behaviour of the build and audit commands (gbsgen, gbsmake, gbsaudit).

    The settings are typically meant to temporary "try something else" without the need to change the target.gbs file.
    More information can be found at target.gbs.
    Order of settings:
    Command-line options override These GBS_EnvVars override Target (target.gbs) settings.
    Index

    GBS_DEBUGGER Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Name:

    GBS_DEBUGGER

    Purpose:

    To predefine the GBS_DEBUGGER (include debugging information) setting during a session

    Possible Values:

    YES NO

    Define:

    Unix
    export GBS_DEBUGGER=value
    Windows
    SET GBS_DEBUGGER=value

    GBS_MAP Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_MAP

    Purpose:

    To predefine the GBS_MAP (generate memory-map) setting during a session

    Possible Values:

    YES NO

    Define:

    Unix
    export GBS_MAP=value
    Windows
    SET GBS_MAP=value

    GBS_MODE Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_MODE

    Purpose:

    To predefine the GBS_MODE settings during a session

    Possible Values:

    FINAL ASSERT DEBUG PROFILING

    Define:

    Unix
    export GBS_MODE=value
    Windows
    SET GBS_MODE=value

    GBS_OPT Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_OPT

    Purpose:

    To predefine the GBS_OPT (optimisation) settings during a session

    Possible Values:

    YES SPEED SIZE DEBUG NO

    Define:

    Unix
    export GBS_OPT=value
    Windows
    SET GBS_OPT=value

    GBS_FLAGS_type Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_FLAGS_type

    Purpose:

    To predefine flags (-options) for a specific type (E.g.: .c or .glk).
    Specify the type without the '.' (dot)

    Possible Values:

    Depend on builder / audit

    Define:

    Unix
    export GBS_FLAGS_type_without_dot=values
    Windows
    SET GBS_FLAGS_type_without_dot=values


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Customisations (User) Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Perl Directory (GBS_PERL_PATH)| gbssetup command| GBS Command Prompt Window (gbscmd.bat / .sh)| Set Window Title (GBS_XTITLE)

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    GBS has a few user customisation possibilities.
    Most are set by the gbssetup command
    Index

    Perl Directory (GBS_PERL_PATH) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Name:

    GBS_PERL_PATH

    Purpose:

    Define an specific directory to find the Perl executable
    To be used when (the wanted) perl is not in the PATH
    Specifies the top-directory of the Perl installation (the directory containing 'bin')

    Default:

    Empty (Find Perl via PATH)

    Where:

    In Registry (Windows) My Computer → Properties → Advanced → Environment Variables
    or ~/.profile (Unix/Linux-ksh) or ~/.bash_profile (Unix/Linux-bash)

    Define:

    Unix
    export GBS_PERL_PATH=your_perl_path
    Windows
    SET GBS_PERL_PATH=your_perl_path

    gbssetup command Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    With the gbssetup command you can set/change:

    Site-ID

    Basic

    Purpose:

    To identify the location where the user works
    It is used in the switch.gbs to cater for different IT infrastructures (e.g. different locations of compilers, network drives, etc)
    You will only really need it if people work from different site-locations on the same code.
    A good name is an abbreviation of the town or site. Just make sure it is unique for the future.
    Keep the name short and in uppercase. Consider using the 3-letter IATA Airport Code of a nearby airport.

    Default:

    HOME

    LogDir

    Basic

    Purpose:

    To define the location of the log files

    Defaults:

    User's Home directory
    Unix
    ~/GBSLogs
    Windows
    %MY_DOCUMENTS%\..\GBSLogs

    Beeps

    General

    Purpose:

    To switch the 'beep' on the command-line on or off

    Default:

    ON

    Editor

    General

    Purpose:

    Define a text-editor (for gbsedit and gbsmaint 9 ('Owners-file' Maintenance)

    Defaults:

    Unix
    $EDITOR, nedit, (gedit)
    Windows
    Notepad

    Browser

    General

    Purpose:

    Define a HTML Browser (for gbshelp and gbsaudit)

    Defaults:

    Unix
    Mozilla/Netscape
    Windows
    Default HTML Browser (Internet Explorer)

    Viewer

    General

    Purpose:

    Define a text-viewer (for viewing batch log-files)

    Defaults:

    Unix
    nedit -read
    Windows
    Notepad

    Administrator

    Special

    Purpose:

    Define/Remove the current user as Administrator for this System
    Administrator privilege is required for all changes to the infrastructure. E.g.: create a new component.
    It is just a token privilege. You will be warned every time you try to do a privileged action. You can always override.
    This is a safety issue, warning you that you are changing something special for which you probably need permission of the System / Code Architect.

    Default:

    None

    Integrator

    Special

    Purpose:

    Define/Remove the current user as Integrator for this System
    Integrator privilege is required for the execution of some special functions ad defined in gbsmaint 6: It is just a token privilege. You will be warned every time you try to do a privileged action. You can always override.
    This is a safety issue, warning you that you are doing something irreversible.

    Default:

    None

    GBS Version

    Purpose:

    Make an other (installed) version of GBS the current GBS version.
    GBS will be restarted.

    Defaults:

    Current

    GBS Command Prompt Window (gbscmd.bat / .sh) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    You can customize your GBS Command Prompt DOS-box/xterm by placing shell commands in a private startup file: 'gbscmd.bat / .sh' in your GBS_BASE_PATH directory:
    Please note the following:
    1. It is only executed in Interactive sessions.
    2. Do not place any GBS-related items in this file.
    3. Placing any GBS-related items in this file may cause GBS to malfunction.
      If not today: probably in the future.

    Set Window Title (GBS_XTITLE) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_XTITLE

    Purpose:

    Allow GBS to set currency information in the window-title

    Default:

    Unix
    xtitle $1
    Windows
    TITLE %1%

    Where:

    Your own scripts

    Define:

    Unix
    export GBS_XTITLE='command to display text in window-title with $1'
    e.g.:
    export GBS_XTITLE="xlabel \"\$1\""
    The $1 will be replaced by the title
    Windows
    SET GBS_XTITLE='command to display text in window-title with %1%'
    The %1% will be replaced by the title


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Customisations (Admin) Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    GBS Startup (gbsall)| User File Templates (GBS_TEMPLATES_PATH)| SCM binary home directory (GBSEXT_scm_PATH)| Make (GBS_MAKE)| Background Processing Invocation (GBS_SUBMIT)| Foreground Processing Invocation (GBS_SUBWIN)| Batch Processing Invocation (GBS_BATCH)| Notify Submit, Start and End of gbssys...-job execution (GBS_BG_NOTIFIER)| ClearCase (Unix)| LSF (Unix Load Sharing Facility)

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    These Customisation must only be set by the GBS Administrator!
    Index

    GBS Startup (gbsall) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    You can define a batch-file that is executed every time before GBS is started.
    Its generic name is gbsall and it must be placed in the GBS_SCRIPTS_ROOT and/or GBS_BASE_PATH directory.
    Typical usage for GBS_SCRIPTS_ROOT is in a shared GBS installation: Typical usage for GBS_BASE_PATH is to define stuff that is valid for all GBS Systems: Depending on presence the files are called in the order above.

    GBS EnvVars defined in the gbsall file must be prefixed GBSALL instead of GBS
    This prevents them to be deleted at root-switch.
    Eligible EnvVars are the EnvVars described in this chapter. (E.g.: GBS_TEMPLATES_PATH)

    Unix
    gbsall.sh
    Windows
    gbsall.bat
    Please note the following:
    1. Do not try to be 'clever' with this file.
    2. Placing any 'clever' stuff this file may cause GBS to malfunction.
      If not today: definitely in the future.

    User File Templates (GBS_TEMPLATES_PATH) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    When gbsedit creates a file, a template is used.
    Standard templates are defined in GBS for GBS-internal files and for most common User files (.c, .glk, etc).
    You can define your own templates in GBS_SYSBUILD_PATH/templates. And/or somewhere central defined by GBS_TEMPLATES_PATH.
    Template-files are named anydot_file_type. E.g.: any.c, any.glk
    Search-order is GBS_TEMPLATES_PATH, GBS_SYSBUILD_PATH/templates, Internal_GBS_directory.

    You can copy existing GBS templates to GBS_SYSBUILD_PATH/templates by using gbsmaint 7 2 and then edit them to suit your taste.
    cdsysbuild, cd templates and then gbsedit any.type
    See below for the customisable items in a template-file.
    Suggestions? Your favourite missing? Let me know!

    Name:

    GBS_TEMPLATES_PATH

    Purpose:

    To define a directory containing external project file-templates

    Default:

    None

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_TEMPLATE_PATH)

    Define:

    Unix
    export GBS_TEMPLATES_PATH=your_template_path
    Windows
    SET GBS_TEMPLATES_PATH=your_template_path

    Semantics:

    Template-files are named anydot_file_type. e.g.: any.c, any.glk
    Search-order is GBS_TEMPLATES_PATH, GBS_SYSBUILD_PATH/templates, Internal_GBS_directory.

    The following tokens used within the Template will be replaced during file-creation by GBS:
        %SYSTEM_NAME% → System
        %SUBSYS% → SubSys
        %COMPONENT% → Component
        %FILE% → File_nameFile_type
        %FILE_NAME% → File_name
        %FILE_TYPE% → File_type
        %UC_FILE% → uc File_nameFile_type
        %UC_FILE_NAME% → uc File_name
        %UC_FILE_TYPE% → uc File_type
        %INCLUDE_GUARD% → uc File_nameFile_type with '.' replaced by '_'

    SCM binary home directory (GBSEXT_scm_PATH) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBSEXT_scm_PATH

    Purpose:

    To define the home directory of the specific SCM execution binary
    This prevents being depended on the individual PATH settings

    Default:

    None

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALLEXT_scm_PATH)

    Define:

    Unix
    export GBSEXT_scm_PATH=your_scm_home_path
    Windows
    SET GBSEXT_scm_PATH=your_scm_home_path

    Semantics:

    The following EnvVars will be recognised by GBS:
       ClearCase GBSEXT_CC_PATH
       IBM Rational Synergy GBSEXT_CCM_PATH
       CVS GBSEXT_CVS_PATH
       Git GBSEXT_GIT_PATH
       Subversion GBSEXT_SVN_PATH
       VisualSourceSafe GBSEXT_VSS_PATH

    Make (GBS_MAKE) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_MAKE and/or
    GBS_MAKE_gbs_target

    Purpose:

    Define a alternate make command and/or specify make-options
    Careful: Incorrect use can damage the build-system!

    Default:

    Unix
    make
    Windows
    nmake

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_MAKE)

    Define:

    Unix
    export GBS_MAKE='Your make command'
    Windows
    SET GBS_MAKE=Your make command

    Background Processing Invocation (GBS_SUBMIT) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_SUBMIT and/or
    GBS_SUBMIT_gbs_target

    Purpose:

    Define a general script to be executed after submitting a job to the background batch and before the job is executed (for implementing things like LSF)
    The batch-job will be executed within the context of this general script
    Affected commands: gbssysgen, gbssysmake, gbssysaudit.
    Careful: Incorrect use can damage the build-system!

    Default:

    Unix
    none
    Windows
    none

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_SUBMIT)

    Define:

    Unix
    export GBS_SUBMIT='command to be executed with $1'
    The $1 will be replaced by the file-name of the scriptfile to be executed (Mandatory!)
    Any $2 will be replaced by the jobname
    Any $3 will be replaced by the logfile specification
    Windows
    SET GBS_SUBMIT=command to be executed with %1%
    The %1% will be replaced by the file-name of the scriptfile to be executed (Mandatory!)
    Any %2% will be replaced by the jobname
    Any %3% will be replaced by the logfile specification

    Foreground Processing Invocation (GBS_SUBWIN) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_SUBWIN and/or
    GBS_SUBWIN_gbs_target

    Purpose:

    Define a general script to be executed after submitting a job for foreground executing in a separate window and before the job is executed (for implementing things like LSF)
    The batch-job will be executed within the context of this general script
    Affected commands: gbssysgen, gbssysmake, gbssysaudit (with --fg)
    Careful: Incorrect use can damage the build-system!

    Default:

    Unix
    none
    Windows
    none

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_SUBWIN)

    Define:

    Unix
    export GBS_SUBWIN='command to be executed with $1'
    The $1 will be replaced by the file-name of the scriptfile to be executed (Mandatory!)
    Any $2 will be replaced by the jobname
    Windows
    SET GBS_SUBWIN=command to be executed with %1%
    The %1% will be replaced by the file-name of the scriptfile to be executed (Mandatory!)
    Any %2% will be replaced by the jobname

    Batch Processing Invocation (GBS_BATCH) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_BATCH and/or
    GBS_BATCH_gbs_target

    Purpose:

    Define a general script to be executed after submitting a batch job and before the job is executed (for implementing things like LSF)
    The batch-job will be executed within the context of this general script
    Affected commands: gbsgen, gbsmake, gbsaudit
    Careful: Incorrect use can damage the build-system!

    Default:

    Unix
    none
    Windows
    none

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_BATCH)

    Define:

    Unix
    export GBS_BATCH='command to be executed with $1'
    The $1 will be replaced by the file-name of the scriptfile to be executed (Mandatory!)
    Windows
    SET GBS_BATCH=command to be executed with %1%
    The %1% will be replaced by the file-name of the scriptfile to be executed (Mandatory!)

    Notify Submit, Start and End of gbssys...-job execution (GBS_BG_NOTIFIER) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Name:

    GBS_BG_NOTIFIER and/or
    GBS_BG_NOTIFIER_gbs-target

    Purpose:

    Define a command to be executed at submit, beginning and at termination of a gbssysgen, gbssysmake or gbssysaudit job (Used by tools like SoftFab, Hudson, BuildForge and CruiseControl)

    The command will be appended with the following information:
    Submit:submitjobname datetime nr_jobs [ target action ]...
    Begin: start jobname datetime pid target action logfile-spec
    End: end jobname datetime pid target action logfile-spec completion-state completion-code
    Where completion-state is one of NORMAL FAILED or KILLED
    More tbs Expect future extensions
    action is either gen make or audit_name (e.g. qac)

    Note that for one submit all jobname and datetime will be the same

    Where:

    In the switch.gbs file and/or gbsall file (as GBSALL_BG_NOTIFIER)

    Define:

    Unix
    export GBS_BG_NOTIFIER='command to be executed'
    Windows
    SET GBS_BG_NOTIFIER=command to be executed

    Note:

    As the GBS_BG_NOTIFIER will be executed from different processes, no assumption can be made on the order in which they are executed!

    ClearCase (Unix) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Define the following Environment Variables in the switch.gbs file:
    export MY_CC_VIEW=`cleartool pwv -short`
    export GBS_SUBMIT="cleartool setview -exec '\$1' $MY_CC_VIEW"
    export GBS_MAKE="clearmake -T"

    At Philips AppTech in combination with LSF

    export MY_CC_VIEW=`cleartool pwv -short`
    export CC_SUBMIT="cleartool setview -exec '\$1' $MY_CC_VIEW"
    export GBS_SUBMIT="/cadappl/gbs/asa/gbssubmit \"$CC_SUBMIT\""
    export GBS_SUBWIN="/cadappl/gbs/asa/gbssubwin \"$CC_SUBMIT\""
    export GBS_BATCH="/cadappl/gbs/asa/gbsbatch \"$CC_SUBMIT\""
    export GBS_MAKE="clearmake -C sun -T"

    LSF (Unix Load Sharing Facility) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    At Philips AppTech

    The following Environment Variables are predefined (in gbsall.sh):
    export GBS_SUBMIT='cd ; export BSUB_QUIET=1 ; bsub -I -q buildq "$1"'
    export GBS_SUBWIN='cd ; bsub -I -q buildq "$1"'
    export GBS_BATCH='cd ; bsub -I -q buildq "$1"'
    export GBS_BATCH_QAC='cd ; bsub -I -q QACq "$1"'
    export GBS_BATCH_QACPP='cd ; bsub -I -q QACPPq "$1"'

    To run an lgcc Target on the Linux cluster, add the following line in your switch.gbs.sh:
    export GBS_BATCH_LGCC='cd ; bsub -I -q linuxq "$1"'


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Integration with other Tools Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    The gbsstart_here Command| The gbsstart Command| Eclipse| Gedit| Crimson Editor| MS Visual Studio

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    It is possible to integrate the execution of GBS commands in development tooling like editors, IDEs and buildmanagers.
    The command that makes this possible is gbsstart_here.
    It is a simplified version of the gbsstart command.
    Typical commands are We suggest you keep this order.

    The following chapters describe the integrations for:
    Eclipse, Crimson Editor, Gedit, MS Visual Studio,

    The gbsstart_here Command Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The purpose of the gbsstart_here command is to be able to execute a GBS command outside of a GBS context.
    For this 2 things are needed: Most Development Environments and/or Editors allow you to specify multiple, named commands that will execute a command-file in which currencies can be set via special codes and/or entries: Because GBS is now invoked from outside a GBS context the gbsstart_here command must be invoked from the generic GBS startup directory GBS_BASE_PATH.
    Unix:
    ~/.gbs/gbsstart_here.sh
    Windows:
    %APPDATA%\.gbs\gbsstart_here.bat

    The gbsstart Command Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    When gbsstart_here cannot be used (because you do not have a CWD), the more complex gbsstart command can be used.

    The purpose of the gbsstart command is to be able to execute a GBS command outside of a GBS context.
    For this 2 things are needed: The positional parameters of gbsstart allow you to specify the GBS context (Root, SubSys, Component and Target).
    Specify '.' to take current (default)
    Specify '-' to take none
    The first parameter also allows for the special '!' and '!!' GBS_ROOT_PATH settings, giving the following possibilities:
    abs_dir_spec
    Means: Take abs_dir_spec as GBS_ROOT_PATH (standard behaviour)
    !
    Means: Search for the GBS_ROOT_PATH from the Current Working Directory upwards.
    !abs_file/dir_spec
    Means: Search for the GBS_ROOT_PATH from abs_file/dir_spec upwards.
    !!
    Means: The Current Working Directory IS the GBS_ROOT_PATH (No need to search)
    The --exec parameter specifies the command that is to be executed.
    No spaces are allowed here so you must use the special space notation ($_, %_ or %20).

    Because GBS is now invoked from outside a GBS context the gbsstart command must be invoked from the generic GBS startup directory GBS_BASE_PATH.
    Unix:
    ~/.gbs/gbsstart.sh
    Windows:
    %APPDATA%\.gbs\gbsstart.bat

    Eclipse Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Location:

    Only System-wide commands can be defined here
    WindowShow ViewMake Targets
    Add Make Target

    Command definitions:

    In Add Make Target Window: gbsstart_parameters:
    gbssysgen
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbssysgen%20--i
    gbssysmake
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbssysmake%20--i
    gbssysaudit
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbssysaudit%20--i
    swt target
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbsswt%20target
    doxygen
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbssysgen%20doxygen
    gbssilo
    ${workspace_loc:/projectname}\root_dirs - - --exec=gbssysgen%20gbssilo
    gbshelp
    - --exec=gbssysgen%20gbshelp

    Notes:

    None

    Gedit Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Enable:

    EditPreferencesPlugins
    Enable 'External Tools'

    Location:

    ToolsExternal Tools

    Command definitions:

    ToolsManage External Tools
    The 'External Tools Manager' is started For a new command click on the 'New' icon, in the lower left corner, just above the 'Help'
    gbsgen
    Command: ~/.gbs/gbsstart_here.sh gbsgen $GEDIT_CURRENT_DOCUMENT_NAME
    gbsmake
    Command: ~/.gbs/gbsstart_here.sh gbsmake $GEDIT_CURRENT_DOCUMENT_NAME --r
    gbsaudit
    Command: ~/.gbs/gbsstart_here.sh gbsaudit $GEDIT_CURRENT_DOCUMENT_NAME
    gbssysgen
    Command: ~/.gbs/gbsstart_here.sh gbssysgen --i
    gbssysmake
    Command: ~/.gbs/gbsstart_here.sh gbssysmake --i
    gbssysaudit
    Command: ~/.gbs/gbsstart_here.sh gbssysaudit --i
    swt target
    Command: ~/.gbs/gbsstart_here.sh gbsswt target
    gbssilo
    Command: ~/.gbs/gbsstart_here.sh gbssilo
    gbshelp
    Command: ~/.gbs/gbsstart_here.sh - --exec=gbsshelp

    Notes:

    None

    Crimson Editor Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Location:

    ToolsConf.User Tools...

    Command definitions:

    Tools On Windows GBS_BASE_PATH points to %APPDATA%\.gbs
    Be sure to mark: Capture output and Save before execute
    gbsgen
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbsgen $(FileName)
    Start in: $(FileDir)
    gbsmake
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbsmake $(FileName) --r
    Start in: $(FileDir)
    gbsaudit
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbsaudit $(FileName)
    Start in: $(FileDir)
    gbssysgen
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbssysgen --i
    Start in: $(FileDir)
    gbssysmake
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbssysmake --i
    Start in: $(FileDir)
    gbssysaudit
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbssysaudit --i
    Start in: $(FileDir)
    swt target
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbsswt target
    Start in: $(FileDir)
    gbssilo
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbssilo
    Start in: $(FileDir)
    gbshelp
    Command: $APPDATA\.gbs\gbsstart_here.bat
    Argument: gbshelp
    Start in: $(FileDir)

    Notes

    None

    MS Visual Studio Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    As a Visual Studio project will be in a non-compliant GBS SubSystem, we cannot use the gbsgen, gbsaudit and gbsmake commands.
    If you are using Visual Studio only as an editor in a Full GBS SubSystem, you can use these commands.

    Location:

    Tools

    Command definitions:

    ToolsExternal Tools...
    On Windows GBS_BASE_PATH points to %APPDATA%\.gbs
    Be sure to mark: Use Output window
    gbsgen
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbsgen $(ItemFileName)$(ItemExt)
    Initial directory: $(ItemDir)
    gbsmake
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbsmake $(ItemFileName)$(ItemExt) --r
    Initial directory: $(ItemDir)
    gbssysgen
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbssysgen --i
    Initial directory: $(ItemDir)
    gbssysmake
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbssysmake --i
    Initial directory: $(ItemDir)
    swt target
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbsswt target
    Initial directory: $(ItemDir)
    gbssilo
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments: gbssilo
    Initial directory: $(ItemDir)
    gbshelp
    Command: %APPDATA%\.gbs\gbsstart_here.bat
    Arguments:- --exec=gbshelp
    Initial directory:

    Notes:

    None

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Plugins Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    Supported plugins.
    GBS Administrator only!!
    Index
    Builds, Audits, Tools, Other

    Build (gen) Plugins Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    Build Plugins are selected with gbsswt --new
    And are updated with gbsmaint 7 1

    Supported Build Plugins:

    See also target.gbs

    Audit Plugins Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Audit Plugins are selected and updated with gbsmaint 7 1

    Supported Audit Plugins:

    See also audit.gbs

    Tool Plugins Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Tool Plugins are selected and updated with gbsmaint 7 1

    Supported Tool Plugins:

    See also tool.gbs


    Doxygen

    Purpose

    Run Doxygen for all SubSystems

    Run

    In steps.gbs:
    
    STEP doxygen_api
        TOOL        = doxygen_api
        BUILD       = NO
        AUDIT	= NO
    
    STEP doxygen
        TOOL        = doxygen
        EXEC        = SPECIFY
        BUILD       = NO
        AUDIT	= NO
    
    

    Requires

    Doxygen via GBSEXT_DOXYGEN_PATH and GBSEXT_DOXYGEN_REL
    and optionally Dot (Graphviz) via PATH

    Notes

    Use gbssilo to view results

    Other Plugins Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    Supported Other Plugins:



    Copy_Export

    Purpose

    Copy the contents of one or more GBS EXPORT directories to a directory outside the GBS WorkArea

    Usage

    Run in steps.gbs

    Syntax

    copy_export >copy_export/bin/copy_export.pl subsys_comma_list export_path to_root
    subsys_comma_list
    From SubSystem(s).
    export_path
    From-export: Relative path from EXPORT-path (may be .).
    to_root
    To-path: Absolute path to output-directory

    Example

    STEP copy_export
        COMMAND    = >copy_export/bin/copy_export.pl superglo $GBS_TARGET $GBSEXT_GBSSHARE/$GBS_TARGET
        AUDIT      = NO
    

    Requires

    None

    Notes

    None

    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Environment Variables (EnvVars) Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    GBS relies heavily on Environment Variables (EnvVars)
    They are all controlled by GBS.
    There is a lot of inter dependency between the GBS EnvVars and they must be set as a group.
    Some EnvVars (most) are intrinsically set by GBS, others (a few) may be set by the User and that has to be done by using the proper GBS functionality that supports that.

    Changing EnvVars by just setting them may lead to unexpected results and may cause GBS to crash or loose integrity
    All GBS EnvVar are prefixed by either GBS_, GBSEXT_ or GBSALLEXT_
    • GBS_... EnvVars are defined by GBS
    • GBSEXT_... EnvVars are defined in switch.gbs
    • GBSALL_... and GBSALLEXT_ EnvVars are defined in gbsall(.bat|.sh) and are renamed during GBS startup to GBS_... and GBSEXT_...

    Index

    GBS_ EnvVars Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    Note that the following table is sortable by the items in the top row.
    Level EnvVar Name Possible Values Usage More
    Info
    Set by Changed
    by
    Remarks
    1 Pre GBS_PERL_PATH directory path Define location of Perl More User User Optional
    1 Pre GBS_BASE_PATH directory path Define location of .gbs   gbsinit N/A Internal
    1 Pre GBS_HOME directory path Define a HOME-path   User User Deprecated
    1 Pre GBS_XTITLE text Define Window Title More User User Deprecated
    2 GBS GBS_RC Number Scripts return status   various scripts  
    2 GBS GBS_SITE Short name in uppercase Name your Site More gbsinit gbssetup  
    2 GBS GBS_LOG_ROOT directory path Log Files Root Location More gbsinit gbssetup Contains GBS_LOG_PATHs per GBS_ROOT_PARENT
    2 GBS GBS_LOG_PATH directory path Log Files Location More gbsinit switch.gbs Set to $GBS_LOG_ROOT/$GBS_ROOT_PARENT
    2 GBS GBS_BEEPS YES NO Beep More gbsinit gbssetup  
    2 GBS GBS_EDITOR command_path Editor to be used More gbsinit gbssetup  
    2 GBS GBS_BROWSER command_path Browser to be used More gbsinit gbssetup  
    2 GBS GBS_VIEWER command_path File viewer to be used More gbsinit gbssetup  
    2 GBS GBS_ADMINISTRATOR System-names List Defines Administrator More gbsinit gbssetup Internal
    2 GBS GBS_INTEGRATOR System-names List Defines Integrator More gbsinit gbssetup Internal
    2 GBS GBS_TEMPLATES_PATH directory path User Templates path (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_MAKE command_path Alternative 'make' (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_SUBMIT command_path Alternative Submit (Background) (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_SUBWIN command_path Alternative Submit (Foreground) (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_BATCH command_path Alternative Batch command (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_BG_NOTIFIER command_path Notifier for Submit completion (OPT) More gbsinit swr gbsall
    switch.gbs
    2 GBS GBS_BUILD RVVYYMMDD Current Release/Build More gbsinit Predefined  
    2 GBS GBS_EXEC_MODE INTERACTIVE FOREGROUND
    BACKGROUND
    Execution Mode   gbsinit gbssys* Internal
    2 GBS GBS_GUI Tkx None Available Perl GUI   gbsinit Predefined Internal
    2 GBS GBS_PERL_CMD perl with or without path Direct Perl execution command   gbsinit Predefined  
    2 GBS GBS_WPERL_CMD perl with or without path Command to start Perl GUI   gbsinit Predefined  
    2 GBS GBS_PID number PID of toplevel process   gbsinit Predefined Internal
    2 GBS GBS_PLATFORM Linux Win32 Current platform More gbsinit Predefined Scripts
    2 GBS GBS_SCRIPTS_ROOT directory path Where GBS versions are installed More gbsinit gbssetup Internal
    2 GBS GBS_SCRIPTS_REL version version_build The current GBS version directory More gbsinit gbssetup Internal
    2 GBS GBS_SCRIPTS_PATH Root/Rel The current GBS scripts location More gbsinit gbssetup  
    2 GBS GBS_SHELL_FILETYPE .bat .sh The current shell filetype   gbsinit gbssetup  
    2 GBS GBS_VERSION version (e.g.: 4.00) The current GBS version number More gbsinit Predefined  
    2 GBS GBS_VERBOSE 0 1 Verbose logging More gbsinit All Commands (Internally) Always 1 in BATCH jobs (gbssys*)
    3 Root GBS_SYSTEM_NAME name Name of the System/Root More swr    
    3 Root GBS_ROOT_PATH directory path Current system root More swr    
    3 Root GBS_ROOT_PARENT directory name Parent dir of current Root More swr    
    3 Root GBS_ALL_AUDITS names list All platform Audits   swr    
    3 Root GBS_AUDITS names list All Audits for this Platform   swr    
    3 Root GBS_AUDIT name Current Audit   swr gbsaudit  
    3 Root GBS_AUDIT_PLUGIN name Current Audit Plugin   swr gbsaudit  
    3 Root GBS_ALL_TARGETS names list All platform Targets   swr    
    3 Root GBS_TARGETS names list All Targets for this Platform   swr    
    3 Root GBS_TARGET name Current Target   swr swt  
    3 Root GBS_TARGET_PLUGIN name Current Target Plugin   swr swt  
    3 Root GBS_ALL_TOOLS names list All platform Tools   swr    
    3 Root GBS_TOOLS names list All Tools for this Platform   swr    
    3 Root GBS_TOOL name Current Tool   swr gbssystool  
    3 Root GBS_TOOL_PLUGIN name Current Tool Plugin   swr gbssystool  
    3 Root GBS_ALL_SUBSYSTEMS names list All SubSystems   swr sws --new  
    3 Root GBS_IS_ADMINISTRATOR 0 1 User is Administrator More swr gbssetup  
    3 Root GBS_IS_INTEGRATOR 0 1 User is Integrator More swr gbssetup  
    3 Root GBS_SKIPTYPES regexp List Filetypes to be skipped   swr   Internal
    3 Root GBS_PLATFORMS Platform list Platforms this root generates for       Internal
    3 Root GBS_SCMS None Subversion Git CVS ... Current SCMS More swr   Internal
    3 Root GBS_SCMS_DATA path Internal Path More swr   Internal
    3 Root GBS_SCMS_REPOSITORY file/directory path/URL SCMS Repository location More swr   Internal
    3 Root GBS_SCM_SKIPTYPES Regexp List Filetypes for Current SCMS More swr   Internal
    3 Root GBS_DEV_PATH directory path ROOT/dev More swr    
    3 Root GBS_EXT_PATH directory path ROOT/ext More swr    
    3 Root GBS_RES_PATH directory path ROOT/res More swr    
    3 Root GBS_SILO_PATH directory path ROOT/silo More swr   Internal
    3 Root GBS_SYS_PATH directory path ROOT/sys More swr    
    3 Root GBS_SYSAUDIT_PATH directory path ROOT/sysaudit More swr    
    3 Root GBS_SYSBUILD_PATH directory path ROOT/sysbuild More swr    
    3 Root GBS_SYSTOOLS_PATH directory path ROOT/systools More swr    
    3 Root GBS_TMP_PATH directory path ROOT/tmp More swr   Internal
    4 Sub GBS_SUBSYS name Current SubSys More sws    
    4 Sub GBS_SSTYPE GBS make MSVS Other Current SubSystem Type More sws    
    4 Sub GBS_SUBSYS_PATH directory path ROOT/dev/SUBSYS More sws    
    4 Sub GBS_AUDIT_PATH directory path ROOT/dev/SUBSYS/audit More sws    
    4 Sub GBS_BUILD_PATH directory path ROOT/dev/SUBSYS/build More sws    
    4 Sub GBS_TOOLS_PATH directory path ROOT/dev/SUBSYS/tools More sws    
    4 Sub GBS_EXPORT_PATH directory path ROOT/dev/SUBSYS/export (OPT) More sws    
    4 Sub GBS_IMPORT_PATH directory path ROOT/dev/SUBSYS/import (OPT) More sws    
    4 Sub GBS_COMP_PATH directory path ROOT/dev/SUBSYS/comp More sws   SSTYPE==GBS
    4 Sub GBS_APP_PATH directory path ROOT/dev/SUBSYS/app More sws   SSTYPE!=GBS
    5 Cmp GBS_COMPONENT name Current Component More swc   SSTYPE==GBS
    4 Cmp GBS_COMPONENT_PATH directory path ROOT/dev/SUBSYS/comp/COMPONENT More swc   SSTYPE==GBS
    5 Ses GBS_DEBUGGER YES NO Include Debugger (build) More User User Scripts
    5 Ses GBS_MAP YES NO Produce a memory map (linking) More User User Scripts
    5 Ses GBS_MODE FINAL ASSERT DEBUG PROFILING Override Build mode More User User Scripts
    5 Ses GBS_OPT YES SPEED SIZE DEBUG NO Override Optimisation More User User Scripts
    5 Ses GBS_FLAGS_type flags Predefine flags (-D...) More User User Scripts
    6 Exe GBS_BLD_src_type File type Derived Object filetype More gbsgen gbsmake   Scripts
    6 Exe GBS_IGNORE_ERRORS 0 1 --i was specified More gbssysgen gbssysmake   Scripts
    6 Exe GBS_FLAGS_type flags or flags_file ref Flags (-D...) More gbssys* gbsgen gbsaudit   Scripts
    6 Exe GBS_SYSFLAGS_type flags or flags_file ref System Flags (-D...) More gbssys* gbsgen gbsaudit   Scripts
    6 Exe GBS_INCS_type includes or includes_file ref Include Flags (-I...) More gbssys* gbsgen gbsaudit   Scripts
    6 Exe GBS_SYSFLAGS_type includes or includes_file ref System Include Flags (-I...) More gbssys* gbsgen gbsaudit   Scripts
    6 Exe GBS_MAKE_FLAGS -i or empty -i if GBS_IGNORE_ERRORS == 1 More gbssysgen   Scripts
    SSTYPE==make
    6 Exe GBS_MSBUILD_CONFIG Debug Release or empty Depends on GBS_MODE More gbssysgen   Scripts
    SSTYPE==MSVS

    GBSEXT_ EnvVars For SCMS Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    The value must be either the directory where the SCMS is installed or PATH if the SCMS command(s) are in the PATH.

    Note that the following table is sortable by the items in the top row.
    EnvVar Name Required for
    GBSEXT_CC_PATH ClearCase
    GBSEXT_CCM_PATH IBM Rational Synergy
    GBSEXT_CVS_PATH CVS
    GBSEXT_GIT_PATH Git
    GBSEXT_SVN_PATH Subversion
    GBSEXT_VSS_PATH Visual Source Safe

    GBSEXT_ EnvVars For Plugins Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    GBSEXT_... EnvVars define the location of external stuff (Plugins and External Data).
    Usually 3 EnvVars are defined (Hard versioned directories):
    • GBSEXT_name_ROOT: Site dependent location
    • GBSEXT_name_REL: Release/version
    • GBSEXT_name_PATH: GBSEXT_name_ROOT/GBSEXT_name_REL
    Just before executing the plugin the following GBSEXT_ EnvVar will be defined:
    • GBSEXT_name_BIN_PATH: GBSEXT_name_PATH/optional_bin_dir

    Note that the following table is sortable by the items in the top row.
    Type Plugin EnvVar Required Platform Remarks
    Builder MinGW C GBSEXT_MINGW_GCC REL and PATH Win32  
    Builder MinGW C/C++ GBSEXT_MINGW_CPP REL and PATH Win32  
    Builder Microsoft Visual Studio 2012 - Simple Console C/C++ GBSEXT_MSVS2012_CONS REL and PATH Win32  
    Builder Green Hills - BlackFin C/C++ GBSEXT_GHSBF REL and PATH Win32  
    Builder GNU C GBSEXT_LGNU_GCC REL and PATH Linux  
    Builder GNU C/C++ GBSEXT_LGNU_CPP REL and PATH Linux  
    Audit PC-Lint C/C++ GBSEXT_PCLINT REL and PATH Win32  
    Audit QAC GBSEXT_QAC REL and PATH Both  
    Audit QAC++ GBSEXT_QACPP REL and PATH Both  
    Tool Doxygen GBSEXT_DOXYGEN REL and PATH Both  


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The glk/glb/glt files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a glb file
    Example of a glk file
    Example of a glt file

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    The glkbt files (.glb, .glk, .glt and others) are located in the src, loc and/or inc directories and are used to specify the behaviour of builders that traditionally do not have 'source'-files, like Linkers and Archivers.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    General considerations:
    • Trailing white-space is ignored.
    • Empty lines are ignored
    • Lines starting with '#' are considered comments and are ignored.
    • The syntax is line-oriented.
    • Leading white-space is significant.
    • The .targets directive can be used to skip execution and generate a dummy-file

    Syntax Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    [ special_char ] content [ target_line_selector ]
    special_char := . | $ | % | - | / | ^ | + | =
    Lines can be appended with a Target Selector enabling skipping of the line dependent on the current Target.
    Refer to GBS-files: General for explanation of the target_line_selector mechanism.
    The first (special-)character on a line specifies it's function:
    Lines starting with '.':
    Directives for the glkbt pre-processor:
    .include file | "file" | 'file' | <file>
    Lines starting with '$' or '%'
    Specify absolute files-specs via Environment Variables
    Passed as-is
    Lines starting with '-' or '/' (Windows only)
    Specify options for the post-processor (builder)
    Passed as-is
    Words with a dot will be passed to gbsmakemake for dependencies
    Lines starting with '^'
    Are passed as-is without the leading '^'
    No further actions
    Lines starting with '+'
    Specify libraries or files to be found via the incs_type.gbs search path
    Passed without the '+'
    Lines with a dot will be passed to gbsmakemake for dependencies
    Lines starting with '='
    Specify config-type files found via the .include search path
    Passed without the '='
    Words with a dot will be prefixed with the found relative path and will be passed to gbsmakemake for dependencies
    Other lines:
    Specify files from the Component-build-target directories:
    Same Component: file-comma-list
    Other Component: Component:file-comma-list
    Any line can be appended with a Target selector enabling skipping of the line dependent on the current Target. Refer to GBS-files: General for explanation of the target-line-selection mechanism.

    Semantics: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Include:
    No path specification allowed
    Files will be searched in inc and loc directories
    File extensions:
    During processing all the GBS_BLD_src_type environment variables for the current Target are set.
    You should create generic glk/glb/glt files suitable for various Targets by using these variables instead of the fixed text.
    i.e.:
    file1$GBS_BLD_C → file1.o or file1.obj
    file2$GBS_BLD_ASM → file2.o or file2.obj
    file3$GBS_BLD_GLB → file3.a or file3.lib

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a glb file: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    #======================================
    #   Src-File:   software.glb
    #   Component:  software
    #   SubSys:     product_s
    #======================================
    root$GBS_BLD_C
    
    #======================================
    #   Other Components
    #======================================
    otv_arm:arm1$GBS_BLD_C
    otv_arm:arm2$GBS_BLD_C
    
    
    ###EOF###
    
    

    Example of a glk file: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    #======================================
    #   Src-File:   total_cze.glk
    #   Component:  software
    #   SubSys:     product_s
    #======================================
    root$GBS_BLD_C
    root_country_cze$GBS_BLD_C
    rom_cze_gnu$GBS_BLD_C            = gnu
    rom_cze_arm$GBS_BLD_C            = arm
    
    software.lib
    
    #======================================
    #   Other Components
    #======================================
    obs:occ$GBS_BLD_C
    obs:saoc$GBS_BLD_GLK
    
    #======================================
    #   Externals
    #======================================
    .include total_libs.glk
    
    +rmgr_upc$GBS_BLD_GLB
    +country_czech$GBS_BLD_C
    +caxxconfiguration_cze$GBS_BLD_C
    +dvbst_stub$GBS_BLD_GLB
    
    ###EOF###
    

    Example of a glt file: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================
    #   File:       hello.glt
    #   Component:  test
    #   SubSystem:  superglo
    #   System:     SuperGlo_OK
    #========================================
    .targets=mingw,mingwd
    ^call
    hello$GBS_BLD_GLK
    -par1 PAR2
    
    ##EOF##
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The .gbs files - General Bottom Doc. Button

    Description Bottom Doc. Button Top Document Button Down Section Button Blank

    Usage Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Blank

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    • 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

    End-Of-Line Comments Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

        .plugin     .include     .eol_comment     .targets     .exit     .end

    .plugin Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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

    .eol_comment Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Down Section Button Blank Down Chapter Button Up Chapter Button

    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 Bottom Doc. Button Top Document Button Blank Blank Blank Up Chapter Button

    1. Skip empty lines and lines starting with '#'
    2. Remove EOL-Comments if enabled
      Skip possibly resulting empty line
    3. Perform Target-Line-Selection and remove target-selection part
    4. Execute Directive / Line


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The audit.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Examples of audit.gbs files

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The audit.gbs files are located in the GBS_SYSAUDIT_PATH/audit directories and are used to associate file-extensions with audit-tools (QAC, QAC++ etc) for a specific audit.
    Also the particularities of the auditing tools are defined.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space (called header-lines) define an item.
    • Following lines with leading white-space (called sub-lines) define the parameters for that item.
    • Reserved words (keywords) are case sensitive
    • The search path for the .include Directive is:
      - $GBS_SYSAUDIT_PATH/$GBS_AUDIT
      - $GBS_SYSAUDIT_PATH

    Contents Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    SETUP definition
    INIT definition
    SRC definitions (multiple)
    ...
    SUMMARY definition
    MAINT definition

    SETUP Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define general stuff, valid for the whole definition set.

    Syntax:

    SETUP
    NICE_NAME = nice_name
    VIA_FORMAT = via_format

    Semantics:

    NICE_NAME
    Specifies a more descriptive name of the Audit. It is used in messages.
    nice_name
    Free format (just do not make it too long)
    VIA_FORMAT
    Specifies format/syntax of file-inclusion on the command-line.
    via_format
    Specifies the printf format for command-line file-inclusion
    It must contain a %s
    It may contain a .file_type
    If a .file_type is not specified .gbs will be used.
    e.g.: -via %s for QAC,
    %s.lnt for PC-Lint,
    @%s for MVS or
    %s (default)

    INIT Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define derived Target dependent Environment Variables
    Note that all references to the 'outside-world' must be specified in the switch.gbs.
    On Windows it can be used to (re)define an EnvVar with spaces removed. (Converted to ShortPathName)

    Syntax:

    INIT
    SET_W = envvar_name => envvar_value
    ...
    SET_X = envvar_name => envvar_value
    ...
    SET = envvar_name => envvar_value
    ...
    SETPATH = path_envvar_name => envvar_value-list
    ...
    BIN_DIR = bin_dir

    Semantics:

    SET_W, SET_X & SET
    Specifies an Environment Variable.
    envvar_name
    Uppercase please
    envvar_value
    If placed between quotes (") it will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    SET_W is executed for Windows only.
    SET_X is executed for Unix and Linux only.
    SET is executed for all platforms
    and must be specified after SET_W and SET_X
    SETPATH
    Specifies a PATH Environment Variable.
    path_envvar_name
    Case dependent on OS
    envvar_value-list
    If placed between quotes (") items will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    Items will be properly joined (';' on Windows, ':' on Linux)
    Must be specified after SET_W, SET_X & SET
    BIN_DIR
    Specifies the directory in which the executables of the plugin reside, relative to GBSEXT_<plugin>_PATH.
    It is used to assemble GBSEXT_<plugin>_BIN_PATH which must be used in the COMMAND sub-section.
    bin_dir
    One or more directories, separated by '/'

    SRC Definitions Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To associate a file-extensions with an audit program (like SCA) and provide the necessary information in order to be able to execute that audit program (executable or script).

    Syntax:

    SRC src_type-list
    OUT_TYPES = out_type-list
    INC_FORMAT = [ env_type ] printf-format
    SYSINC_FORMAT = [ env_type ] printf-format
    FLAG_FORMAT = [ env_type ] printf-format
    SYSFLAG_FORMAT = [ env_type ] printf-format
    COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition
    ...

    Semantics:

    OUT_TYPES
    List of mandatory output-types
    The first one is considered the primary output-type
    The primary output-type must start with a '.' (dot)
    Secondary output-type(s) must contain a '.' (dot).
    Note that if output-types do not start with '.' you may get name-clashes in Target-directory.
    Files of these type(s) will be deleted before builder starts.
    INC_FORMAT
    Specifies information on the presentation of include-options (-I)
    env_type
    VARIABLE | FILE
    Specifies how the include-options will presented on the command-line.
    VARIABLE: In Environment Variable GBS_INCS
    FILE: In a temporary file specified via EnvVar GBS_INCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for include-options
    It must contain a %s
    e.g: -I %s for QAC.
    SYSINC_FORMAT
    Specifies information on the presentation of SYSTEM include-options (-I)
    Items are taken from sysbuild/target/bld_incs_src_type.gbs only.
    env_type
    VARIABLE | FILE
    Specifies how the include-options will presented on the command-line.
    VARIABLE: In Environment Variable GBS_SYSINCS
    FILE: In a temporary file specified via EnvVar GBS_SYSINCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for include-options
    It must contain a %s
    e.g: -SI %s for QAC++.
    FLAG_FORMAT
    Specifies information on the presentation of flags (-D)
    env_type
    VARIABLE | FILE
    Specifies how the flags will presented on the command-line.
    VARIABLE: In Environment Variable GBS_FLAGS
    FILE: In a temporary file specified via EnvVar GBS_FLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for flags
    It must contain a %s
    e.g: -D %s for QAC++.
    SYSFLAG_FORMAT
    Specifies information on the presentation of SYSTEM flags (-D)
    Items are taken from sysbuild/target/bld_flags_src_type.gbs only.
    env_type
    VARIABLE | FILE
    Specifies how the flags will presented on the command-line.
    VARIABLE: In Environment Variable GBS_SYSFLAGS
    FILE: In a temporary file specified via EnvVar GBS_SYSFLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for flags
    It must contain a %s
    e.g: -SD %s for QAC++
    COMMAND
    Command to invoke the audit program.
    pre_condition
    file_exists_condition | env_value_condition
    The command will only be executed if the condition is true.
    file_exists_condition
    [ ! ] exists file_spec
    env_value_condition
    variable_name_in_uppercase =|==|!= value
    ok_exit_values-comma-list
    Specifies the exit values for the command that are considered OK.
    Range specification (3-5) allowed. Default is 0.
    command-definition
    build_command | @user_script | >gbs_audit_script | .gbs_script | echo_command | set_command
    build_command
    Single line command
    You may want to use GBSEXT_<plugin>_BIN_PATH
    user_script
    Search for in User-Audit and then GBS-Audit
    gbs_audit_script
    Relative from the GBS plugin/audit directory
    gbs_script
    Take from GBS_SCRIPTS_PATH
    echo_command
    ECHO any_text
    Prints any_text. EnvVars and positional parameters are replaced
    set_command
    SET variable_name_in_uppercase = any_value
    Sets the EnvVar. In any_value EnvVars and positional parameters are replaced
    Note that you can continue a long line on the next line by adding ' \' at the end.

    The command is called with the following positional parameters:
    • $1 filename
      Without the file-type
    • $2 in_file_spec
      Relative path
    • $3 out_file_spec
      Relative path
    • $4 out_file_path
      Relative path
    • $5 out_file_type
      Including the dot
    • $6-$n ($*) Command-line flags
    The following additional Environment Variables are set and may be used:
    • GBS_INCS
      Contains the include-statements specification as defined by INC_FORMAT
    • GBS_SYSINCS
      Contains the include-statements specification as defined by SYSINC_FORMAT
    • GBS_FLAGS
      Contains the flags specification as defined by FLAG_FORMAT Including:
      - Results of MODE, DEBUGGER, OPT and MAP
      - Values of flags_type.gbs files
      - Values in GBS_FLAGS_type
      Note that only the -D flags are included.
    • GBS_SYSFLAGS
      Contains the flags specification as defined by SYSFLAG_FORMAT
    • GBS_AUDIT_FLAGS
      Contains the content of EnvVar GBS_FLAGS_audit
    • GBS_APP_name... and GBS_APP_name_VALUE...
      As specified in the sys.gbs file

    SUMMARY Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To provide information on how to run the summary program (executable or script)

    Syntax:

    SUMMARY
    COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition
    ...

    Semantics:

    COMMAND
    Command to invoke the audit summary program.
    It is not used if the Audit is an SCA Audit.
    pre_condition
    file_exists_condition | env_value_condition
    The command will only be executed if the condition is true.
    file_exists_condition
    [ ! ] exists file_spec
    env_value_condition
    variable_name_in_uppercase =|==|!= value
    ok_exit_values-comma-list
    Specifies the exit values for the command that are considered OK.
    Range specification (3-5) allowed. Default is 0.
    command-definition
    command | @user_script | >gbs_audit_script | .gbs_script echo_command | set_command
    command
    Single line command
    user_script
    Search for in User-Audit and then GBS-Audit
    gbs_audit_script
    Relative from the GBS plugin/audit directory
    gbs_script
    Take from GBS_SCRIPTS_PATH
    echo_command
    ECHO any_text
    Prints any_text. EnvVars and positional parameters are replaced
    set_command
    SET variable_name_in_uppercase = any_value
    Sets the EnvVar. In any_value EnvVars and positional parameters are replaced
    Note that you can continue a long command on the next line by adding ' \' at the end.

    The command is called with the following positional parameters:
    • $1 sum_file_spec
      Specifies the .html output filespec
    The following additional Environment Variables are set and may be used:
    • GBS_APP_name... and GBS_APP_name_VALUE...
      As specified in the sys.gbs file

    MAINT Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To provide the interface of an audit-related program that can be executed from the gbsmaint command

    Syntax:

    MAINT
    COMMAND = [ ok_exit_values-comma-list ; ] command-definition

    Semantics:

    COMMAND
    Command to invoke the audit program.
    ok_values-comma-list
    Specifies the exit values for the command that are considered OK.
    Range specification (3-5) allowed. Default is 0.
    command-definition
    command | @user_script | >gbs_audit_script | .gbs_script
    command
    Single line command
    user_script
    Search for in User-Audit and then GBS-Audit
    gbs_audit_script
    Relative from the GBS plugin/audit directory
    gbs_script
    Take from GBS_SCRIPTS_PATH
    Note that you can continue a long command on the next line by adding ' \' at the end.

    The command is called with the following positional parameters:
    • None
    The following additional Environment Variables are set and may be used:
    • None

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Examples of audit.gbs files: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    File 1 (Basic reference) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    #========================================================
    #   [qac] audit.gbs
    #========================================================
    .plugin qac
    .include <audit.gbs>
    
    ##EOF##
    

    File 2 (Full specification) Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    #========================================================
    #   [qacpp] audit.gbs
    #========================================================
    
    SETUP
        NICE_NAME       = QAC++
        VIA_FORMAT	    = -via %s
    
    INIT
        SET_W   = QAC_EXEC => qacpp
        SET_X   = QAC_EXEC => qac++
        SET	    = QACPPHELPFILES => $GBSEXT_QACPP_PATH/help
        BIN_DIR =
    
    SRC .cpp
        OUT_TYPES	    = .gout .met .err
        INC_FORMAT	    = -I %s
        SYSINC_FORMAT   = -SI %s
        FLAG_FORMAT	    = -D %s
        SYSFLAG_FORMAT  = FILE -SD %s
        COMMAND	    = 0,1 ; \
    		      $GBSEXT_QACPP_BIN_PATH/$QAC_EXEC $GBS_INCS $GBS_SYSINCS $GBS_AUDIT_FLAGS $GBS_SYSFLAGS $GBS_FLAGS \
    		          $2 $GBS_QACPP_FLAGS $* -outputpath $4 -n 1599
        COMMAND	    = exists $GBS_ROOT_PATH/sysaudit/$GBS_AUDIT/style_ALL.nrf; ; \
                          $GBSEXT_QACPP_BIN_PATH/pal qacpp $2 $GBS_PAL_FLAGS -outputpath $4
        COMMAND	    = exists $GBS_ROOT_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE ; ; \
    		      $GBS_ROOT_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE qacpp $2 \
    		          $GBS_INCS $GBS_SYSINCS $GBS_AUDIT_FLAGS $GBS_SYSFLAGS $GBS_FLAGS $*
        COMMAND	    = 0,1-9,99; \
    		      $GBSEXT_QACPP_BIN_PATH/errdsp qacpp $2 $GBS_ERRDSP_FLAGS -outputpath $4 -file $2$5
    
    SUMMARY
        COMMAND = ECHO SCA
    
    MAINT
        COMMAND = >qac/bin/prqamaint.pl QACPP
    
    
    ##EOF##
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The export.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of an export.gbs
    Example of an export.gbs using INSTALL

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The export.gbs files are used to fill the res/subsys and subsys/export directories.
    They (the export.gbs files) can reside in 3 locations:
    • Full-GBS SubSystems:
      1. Component - From Component res and/or export
      2. SubSystem/Gen - From res to res and/or export and from ext to export
    • Non-GBS SubSystems:
      1. Subsystem - From SubSystem to res and/or export

    The export.gbs files located in the GBS_COMPONENT directories are used to specify which files of the Component are to be exported to a relative directory in RES/$GBS_SUBSYS and/or EXPORT when using the gbsexport command.

    The export.gbs files located in the GBS_GEN directories are used to specify which files of any RES or EXT are to be exported to a relative directory in RES/$SUBSYS and/or EXPORT when using the gbsexport command.

    The export.gbs files located in the GBS_SUBSYS directories (Non-GBS) are used to specify which files of the SubSystem, any RES and/or EXT are to be exported to a relative directory in RES/$SUBSYS and/or EXPORT when using the gbsexport command.

    Files can be exported to $GBS_RES_PATH/$GBS_SUBSYS and/or to $GBS_EXPORT_PATH depending on the existence of these directories or selective by means if the to_base prefix.

    Besides copying files it is also possible to create (msi) install programs.

    By default:
    Exported directories are created with mode: u=rwx,go=rx,o=x
    Exported files are created with mode: ugo:r

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space define the destination (output_directory)
    • Following lines with leading white-space define the source (from_file)
    • Keywords are case sensitive
    • The .include directive is not allowed
    The combination of 1 destination-line flowed by a number of source-lines is called a destination-set.

    Contents: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Syntax:

    destination_line
    source_line
    ...
    destination_line := [to_base:]to_path['|'chmods] [target-line-selection]

    source_line := copy_line | install_line

    copy_line := [from_base:][from_path]from_file [to_file['|'chmods]]

    install_line := INSTALL:command [args...] to_file['|'chmods]
    Destination lines (to_path) can be appended with a Target Selector enabling skipping of the whole destination_set dependent on the current Target. Refer to GBS-files: General for explanation of the target-line-selection mechanism.

    Semantics:

    to_base := EXPORT | RESSUB | ANY
    Specifies explicit output location.
    ANY: Default. Export to RESSUB and/or EXPORT depending on their existence
    RESSUB: Base is GBS_RES_PATH/SUBSYS
    EXPORT: Base is to GBS_EXPORT_PATH
    to_path
    Relative to to_base
    ../ or '*' not allowed

    from_base := CMP | EXT | RES | SILO | SUB | GBSEXT_name_PATH | INSTALL
    Specifies explicit input location.
    CMP: Base is GBS_COMPONENT_PATH
    CMP: is the default for Component export.gbs and should not be specified (custom)
    CMP: may only be specified in a Component export.gbs
    EXT: Base is GBS_EXT_PATH. Files MUST exist
    RES: Base is GBS_RES_PATH
    SILO: Base is GBS_SILO_PATH
    SUB: Base is GBS_SUBSYS_PATH
    SUB: is the default for Gen and Non-Full-GBS Subsystem export.gbs
    SUB: Only specific directories can be selected (audit, export, build, comp, tools)
    GBSEXT_name_PATH: Base is the directory defined by that Environment Variable
    INSTALL: cannot be specified in a Component export.gbs
    INSTALL: Base is the same location as the export.gbs file
    from_path
    Relative to from_base
    ../ or '*' not allowed
    Default is from_base
    from_file
    ../ or '*' not allowed
    Use $GBS_BLD_src_type to specify Target specific generated file-types
    to_file
    Optional. Mandatory for INSTALL:
    Specifies a (different) output name for the file.
    A dot indicates the same as the input file name
    chmods
    chmod_comma-list
    Use to change the default file/directory permissions
    chmod := unix_symbolic_mode_notation>
    For the chmod notation refer to Wikipedia chmod
    command
    Command that will invoke the (msi) install create program
    Before execution the CWD will be set to the same locations as the export.gbs file
    Best way to work is to use the copy_lines to create a directory/file structure and then use an install_line to create an installer using that directory/file structure
    args
    Argument(s) for command
    Optional

    General:
    Paths containing non-current Target Target-names will be skipped for the current Target.

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    • No wild-cards allowed (e.g.: *.h)
    • file/directory specifications containing spaces are supported:
      All occurrences of %_ (Unix), $_ (Win32) and %20 (all) are replaced by spaces.

    Example of an export.gbs: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    #===============================
    #  [otv_al_s:ocs] export.gbs
    #===============================
    RESSUB:inc/$GBS_TARGET                     == mingw
        inc/http_init.h
        inc/lsm.h
        inc/oco.h
        inc/ocs.h
        inc/ocs_cfg.h
    RESSUB:lib/$GBS_TARGET                     == mingw
        bld/$GBS_TARGET/ocs$GBS_BLD_GLB
    EXPORT:bin                                 == mingw
        bld/$GBS_TARGET/ocs$GBS_BLD_GLBK|ugo:x
    
    ## EOF ##
    

    Example of an export.gbs using INSTALL: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================================
    #   [profielsw] export.gbs
    #========================================================
    base
    base/bin
        app\Task24Profiel\bin\Release\Task24Profiel.exe
    base/bin/DUT
        data\bin\DUT\_NL%20Profiel%20Leesmij.txt
        data\bin\DUT\CV%20TemplateB.dotm
        data\bin\DUT\leegcv.ini
        data\bin\DUT\wizard.ini
    base/bin/ENG
        data\bin\ENG\_English%20Profile%20ReadMe.txt
        data\bin\ENG\CV%20TemplateB.dotm
        data\bin\ENG\leegcv.ini
        data\bin\ENG\wizard.ini
    base/Doc
        data\Doc\Help.html
        data\Doc\userguide.doc
    base/Doc/Images
        data\Doc\Images\Balkknop.jpg
        data\Doc\Images\CVWizardMain.jpg
        data\Doc\Images\image002.jpg
        data\Doc\Images\TASK24.ico
    install
        INSTALL:%GBSEXT_ADVANCED_INSTALLER_PATH%\AdvancedInstaller.com /build Task24Profiel.aip setup.msi
    ###EOF###
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The flags_*.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a flags_*.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The flags_type.gbs files are used to specify builder-specific flags.
    The type specifies the associated source-file type (without the DOT)

    The flags_type.gbs files may be placed in the following locations:

    • $GBS_SYSBUILD_PATH
    • $GBS_SYSBUILD_PATH/$target
    • $GBS_BUILD_PATH
    • $GBS_BUILD_PATH/$target
    • $GBS_COMPONONENT_PATH/opt
    • $GBS_COMPONONENT_PATH/opt/$target
    And will be read in the specified order, overriding possible values of a higher level.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • The .include directive is not allowed

    Contents: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Syntax:

    One flag per line
    A line containing spaces will be quoted unless the line also contains quotes (")
    To prevent this, place elements on separate lines

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Flags may not be include-paths like -I and/or -L
    These should be specified in the incs_*.gbs files.

    Example of a flags_*.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================================
    #   [superglo::test]FLAGS_C.GBS
    #========================================================
    -DTESTFLAG=1
    
    
    ###EOF###
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The gbssub batch file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a gbssub.bat

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The gbssub batch file is used only for Non-GBS SubSystems, is located in the GBS_SUBSYS_PATH directory and is used for the building or auditing of these Subsystems.
    It is used by gbssysgen, gbssysmake, gbssysaudit and for Cleanup functions in gbsmaint.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Special considerations:
    • These files are operating-system dependent batch files and have the appropriate file-extension for that particular operating-system. e.g.:
      • gbssub.sh for Unix-type operating-systems
      • gbssub.bat for MSWindows operating-systems

    Calling Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    The gbssub file is called:
    When you build or audit a SubSystem with one of the gbssys.. commands:
    With one of the arguments cleaunp_bld, gen, make, cleanup_aud or audit
    When Cleanup a SubSystem with gbsmaint:
    With one of the arguments cleaunp_bld or cleanup_aud

    Environment Variables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Before execution a vast amount of EnvVars is set so you can make your proper selections.
    Some EnvVars will be dependent on the SubSystem type.
    Refer to example below.

    Layout Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    For every Non-GBS SubSystem type there is a slightly different gbssub file.
    The 'switch' on action (cleaunp_bld, gen, make, cleanup_aud or audit) is the same for all, but the contents of the 'cases' will differ.
    Refer to example below.

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a gbssub.bat: Bottom Doc. Button Top Document Button Blank Up Section Button

    @ECHO OFF
    ::=============================================================================
    ::  [%SUBSYS%] gbssub.bat
    ::	Requires 1 parameter: action
    ::	Called to cleanup, gen, make or audit a non-GBS SubSystem
    ::	For 'make' SubSystems
    ::=============================================================================
    ::
    ::  Currently in $GBS_ROOT_PATH/dev/$GBS_SUBSYS
    ::  Applicable EnvVars:
    ::	GBS_TARGET
    ::	GBS_TARGET_PLUGIN
    ::	GBS_TARGET_PLUGIN_PATH				('make' or 'Other')
    ::	GBS_TARGET_PLUGIN_BIN_PATH			('make' or 'Other')
    ::	GBS_AUDIT_PLUGIN	    (for Audit only)
    ::	GBS_AUDIT_PLUGIN_PATH	    (for Audit only)    ('make' or 'Other')
    ::	GBS_AUDIT_PLUGIN_BIN_PATH   (for Audit only)	('make' or 'Other')
    ::
    ::  Availabe EnvVars:
    ::      GBS_ROOT_PATH
    ::      GBS_SUBSYS
    ::      GBS_SUBSYS_PATH
    ::      GBS_AUDIT_PATH
    ::      GBS_BUILD_PATH
    ::      GBS_APP_PATH
    ::
    ::	GBS_MAKE		
    ::      GBS_IGNORE_ERRORS       0 | 1
    ::      GBS_MODE                FINAL | ASSERT | DEBUG | PROFILING
    ::      GBS_OPT                 YES | SPEED | SIZE | DEBUG | NO
    ::      GBS_DEBUGGER            NO | YES
    ::      GBS_MAP                 NO | YES
    ::
    ::      GBS_BLD_      
    ::      GBS_SYSFLAGS_
    ::      GBS_FLAGS_    also contains flags resulting from MODE, OPT, DEBUGGER and MAP
    ::      GBS_SYSINCS_
    ::      GBS_INCS_
    ::
    ::      GBS_MAKE_FLAGS		'-i' if GBS_IGNORE_ERRORS == TRUE
    ::
    ::=============================================================================
    setlocal
    set rc=0
    
    set action=%1
    
    ::
    ::  Adjust for proper actions
    ::  Just one to a few lines per action. Keep it simple. Do not try to be clever.
    ::  Do not forget to set rc to proper exit value (0=success, >0=fail)
    ::
    
    if [%action%] == [cleanup_bld] goto CASE_CLEANUP_BLD
    if [%action%] == [gen]         goto CASE_GEN
    if [%action%] == [make]        goto CASE_MAKE
    if [%action%] == [cleanup_aud] goto CASE_CLEANUP_AUD
    if [%action%] == [audit]       goto CASE_AUDIT
    goto CASE_DEFAULT
    ::
    ::  CLEANUP_BLD
    ::
    :CASE_CLEANUP_BLD
        echo GBSSUB_: ** SubSys=%GBS_SUBSYS% - Target=%GBS_TARGET% - Action=%action%
        :: <== add your command(s) to execute the bld_cleanup here and remove these lines.
        ::     Do not forget to set rc to proper exit value (0=success, >0=fail)
        :: <== Probably something like:
        %GBS_MAKE% clean -f Makefile.mk -i
        set rc=%ERRORLEVEL%
        goto CASE_END
    :CASE_GEN
        ::
        ::	GEN
        ::
        echo GBSSUB_: ** SubSys=%GBS_SUBSYS% - Target=%GBS_TARGET% - Action=%action%
        :: <== add your command(s) to execute the gen here and remove these lines.
        ::	   Do not execute the 'clean' in this command.
        ::     Do not forget to set rc to proper exit value (0=success, >0=fail)
        :: <== Probably something like:
        %GBS_MAKE% -f Makefile.mk -B -k %GBS_MAKE_FLAGS%
        set rc=%ERRORLEVEL%
        goto CASE_END
    :CASE_MAKE
        ::
        ::	MAKE
        ::
        echo GBSSUB_: ** SubSys=%GBS_SUBSYS% - Target=%GBS_TARGET% - Action=%action%
        :: <== add your command(s) to execute the make here and remove these lines.
        ::     Do not forget to set rc to proper exit value (0=success, >0=fail)
        :: <== Probably something like:
        %GBS_MAKE% -f Makefile.mk %GBS_MAKE_FLAGS%
        set rc=%ERRORLEVEL%
        goto CASE_END
    :CASE_CLEANUP_AUD
        ::
        ::	CLEANUP_AUD
        ::
        echo GBSSUB_: ** SubSys=%GBS_SUBSYS% - Target=%GBS_TARGET% - Audit=%GBS_AUDIT% - Action=%action%
        :: <== add your command(s) to execute the audit_cleanup here and remove these lines.
        ::     Do not forget to set rc to proper exit value (0=success, >0=fail)
        :: <== Probably something like:
        %GBS_MAKE% clean -f Makefile_aud.mk -i
        set rc=%ERRORLEVEL%
        goto CASE_END
    :CASE_AUDIT
        ::
        ::	AUDIT
        ::
        echo GBSSUB_: ** SubSys=%GBS_SUBSYS% - Target=%GBS_TARGET% - Audit=%GBS_AUDIT% - Action=%action%
        :: <== add your command(s) to execute the gbssubaudit.bat here and
        ::     remove these lines.
        ::     Do not forget to set rc to proper exit value (0=success, >0=fail)
        :: <== Probably something like:
        :: %GBS_MAKE% -f Makefile_aud.mk -B -k %GBS_MAKE_FLAGS%
        echo GBSSUB_: No audits for non-GBS SubSystems
        set rc=%ERRORLEVEL%
        goto CASE_END
    :CASE_DEFAULT
        ::
        ::	DEFAULT
        ::
        echo GBSSUB_: ***FATAL ERROR***
        echo - Invalid action '%action%'. Must be one of (cleaunp_bld gen make cleanup_aud audit)
        set rc=9
        goto CASE_END
    :CASE_END
    
    endlocal & set rc=%rc%
    exit /B %rc%
    :::EOF:::
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The incs_*.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a incs_*.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The incs_type.gbs files are used to extend the search paths for builders beyond the Components.
    The type specifies the associated source-file type (without the DOT)
    They will specify directories in

    • 'res' area: $GBS_RES_PATH/$GBS_SUBSYS/...
    • 'ext' area: $GBS_EXT_PATH/yourdirectory
    • Directories outside the GBS directory structure, as specified in switch.gbs.

    The incs_type.gbs files may be placed in the following locations:

    • $GBS_SYSBUILD_PATH
    • $GBS_SYSBUILD_PATH/$target
    • $GBS_BUILD_PATH
    • $GBS_BUILD_PATH/$target
    • $GBS_COMPONONENT_PATH/opt
    • $GBS_COMPONONENT_PATH/opt/$target
    And will be read in reverse order.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • The .include directive is not allowed

    Contents: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Syntax:

    One directory per line.

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a incs_*.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================================
    #   [superglo]INCS_C.GBS
    #========================================================
    $GBSEXT_DMF_PATH/include
    $GBSEXT_MARAP_PATH/inc
    
    ###EOF###
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The owners.gbs file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a owners.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The owners.gbs file is located in the GBS_SYS_PATH directory is used to maintains 'owners' of SubSystems and Components.
    'Owners' have no meaning within GBS. It is offered as a convenience to be able to trace the responsible person for a SubSystem or Component.

    It has a specific internal structure and editing of the file is done via gbsmaint 9: 'Owners-file' Maintenance

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    This file will NOT be superseded by a .usr file

    Example of a owners.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    
    * UserId    Email                               Phone          Owner-Name
    + uida1179  Paul.Lieverse@siemens.com           +31-40-1234567 Paul Lieverse
    + uida1393  Leon.Bouwmeester@SiemensVDO.com     +31-40-1234567 Leon Bouwmeester
    + uida1473  Datta.Inamdar@siemensvdo.com        +31-40-1234567 Datta Inamdar
    + uida1641  Marcel.vanderVelden@siemensvdo.com  +31-40-1234567 Marcel van der Velden
    + uida1667  Reinier.Kleefman@siemensvdo.com     +31-40-1234567 Reinier Kleefman
    + uida1685  Martin.Smits.ext@siemens.com        +31-40-1234567 Martin Smits
    *
    * SubSystem  Component                       UserId
    = booter     drv_flash                       uida1641
    = booter     -                               uida1641
    = booter     booter                          uida1641
    = booter     i_infolog                       uida1641
    = main       -                               uida1667
    = main       c_trusted_device_database       uida1667
    = main       test_trace_mgr                  uida1685
    = main       most_fb_bluetooth_gateway       uida1667
    = main       drv_iis                         uida1641
    = main       i_tracer                        uida1641
    = main       i_infolog                       uida1641
    = main       test_booter                     uida1641
    = main       c_phonebook_manager             uida1667
    = main       a_ec_nr                         uida1179
    = main       zzz_comp2                       uida1685
    = main       appl_p2er5                      uida1685
    = main       a_mediarecorder                 uida1179
    = main       test_src                        uida1179
    = main       a_audiorouter                   uida1179
    = main       test_logger                     uida1641
    = main       c_bluetooth_phone               uida1667
    = main       hal                             uida1641
    = main       base                            uida1393
    = main       i_logger                        uida1641
    = main       a_speechrecognition_lib         uida1179
    = main       i_xtp                           uida1641
    = main       most_fb_speechrecognition       uida1179
    = main       most_fb_linkcontrol             uida1179
    = main       i_rtp                           uida1641
    = main       drv_sport                       uida1641
    = main       c_bluetooth_transfer_manager    uida1667
    = main       test_autotests                  uida1473
    = main       test_most_stack                 uida1641
    = main       bsp_bf532dev                    uida1641
    = main       i_lifesign                      uida1641
    = main       a_speechrecognition             uida1179
    = main       a_ec_nr_lib                     uida1179
    = main       i_ffs                           uida1641
    = main       h_flash_mgr                     uida1473
    = main       a_mediaplayer                   uida1179
    = main       most_fb_lifecycle               uida1641
    = main       dq_mgr                          uida1641
    = main       zzz_comp1                       uida1685
    
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The sca_*.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a sca_*.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The sca_*.gbs files are used to define the behaviour of SCA Audits.
    There are two types of sca_*.gbs files:

    • The sca_target.gbs file
      - Primary file
      - Specifies the associated Target
    • The sca_uppercase_name.gbs file
      - Include file
      - Can be included by the sca_target.gbs (and also by other sca_uppercase_name.gbs files.

    The sca_*.gbs files can be placed in the following locations:

    • $GBS_SUBSYS_PATH/audit/$audit
    • $GBS_SYSAUDIT_PATH/$audit
    The sca_target.gbs file is first searched in the current SubSystem/audit directory.
    If not found it is searched in the SYSAUDIT directory

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • The .include directive is allowed.
      If the sca_target.gbs was found in the SubSystem the Include-path is:
      - $GBS_SUBSYS_PATH/audit/$audit
      - $GBS_SYSAUDIT_PATH/$audit
      If the sca_target.gbs was found in the SYSAUDIT the Include-path is:
      - $GBS_SYSAUDIT_PATH/$audit (same directory) only

    Contents: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Syntax:

    +|-flag value | value-list

    The file is basically a 'flags' file.
    Flags are switched on and off by placing a '+' or '-' in front
    One flag per line
    Possible flags are: E F Q T

    Semantics:

    E value-list
    Enables/Disables Warnings/Errors from the sca tool.
    value-list
    ALL | warning/error-number
    F value
    Specifies the Format of the warning/error message on stdout.
    value
    NONE | DEFAULT | PCLINT | VISUAL_C | GNU_C | ECLIPSE
    Q path
    Ignore (Quiet) warnings/errors in the specified path / file-spec.
    path
    File or Directory Path
    Note that system header-files and files in GBS_EXT_PATH are Quieted by default.
    T threshold_expression
    Override Threshold setting for a Metric.
    threshold_expression
    Syntax:
    metric_name=[min_value][,max_value][:msg_nr]
    Either min_value or max_value must be specified, or both.
    msg_nr: Specifies a use-defined message to be output after file-analysis.
    Not implemented yet.

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a sca_*.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================================
    #   [SYSAUDIT:pclint[mingw]] sca_mingw.gbs
    #========================================================
    
    .include sca_ALL.gbs
    
    ###EOF###
    
    
    and...
    
    #========================================================
    #   [SYSAUDIT:pclint[ALL]] sca_ALL.gbs
    #========================================================
    
    +E ALL
    +E 537           # Repeated include file name
    -E 1042          # At least one class-like operand is required with operator 
    
    +Q $GBSEXT_MINGW_CPP_PATH
    
    +F NONE
    
    +T TLN=20,400:6001
    
    ###EOF###
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The scope.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a scope.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The scope.gbs files are located in the GBS_COMPONENT_PATH directory and are used to specify which Components are in scope.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    Contents: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Syntax:

    component_name [ target-line-selection ]

    Semantics:

    component_name
    The Component to included in the scope

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a scope.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    #========================================================
    #   [OMS::test_no_unix:main]SCOPE.GBS
    #========================================================
    superglo
    test_all                                = gnu
    
    ###EOF###
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The steps.gbs file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a steps.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The steps.gbs file is located in the GBS_SYS_PATH directory is used to define the order in which SubSystems are built or audited, Commands are executed or Tools are run.

    Non-SubSystem steps, called 'Commands' allow you to execute commands to e.g.:
    Copy end-results to a specific directory outside then GBS tree.

    Tools run on the whole GBS tree and are not dependent on Audit or Target. E.g.: Doxygen, etc.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space (called header-lines) define an item.
    • Following lines with leading white-space (called sub-lines) define the parameters for that item.
    • Reserved words (keywords) are case sensitive
    • The .include directive is not allowed

    Definitions Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    STEP ALIAS

    STEP-definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define the order in which SubSystems must be generated

    Syntax:

    STEP step_name
    EXEC = SELECT | SPECIFY | ALWAYS | FORCE
    TOOL = tool_name
    COMMAND = command [command_arguments...]
    BUILD = YES | NO
    AUDIT = YES | NO

    Semantics:

    The order in which the STEP definitions appear specifies the order in which the steps must be executed. Cyclic references are not possible.
    step_name
    SubSystem, Command or Tool
    The step_name may not be ALL
    If the step_name is a SubSystem-name then it refers to that SubSystem.
    Else, there must be a COMMAND or a TOOL line immediately following this line to specify the action to be taken

    Each Non-GBS SubSystem must have a set of gbssub... 'generate' scripts in the top-directory of that SubSystem.
    These scripts are:
    gbssubgen.batch_type
    gbssubmake.batch_type
    gbssubaudit.batch_type
    gbssubcleaup_bld.batch_type
    gbssubcleanup_aud.batch_type
    These scripts do not take arguments from the command line, only EnvVars:
    GBS_IGNORE_ERRORS (bool)
    GBS_MAKE ('make' command)
    GBS_FLAGS_type
    GBS_BLD_type
    GBS_MODE, GBS_OPT, GBS_DEBUGGER and GBS_MAP
    EXEC
    Single, Optional
    SELECT == Include this step if specified in command-line (default)
    SPECIFY == Only include this step if explicitly specified in command-line
    ALWAYS == Include this step even if not specified in command-line
    FORCE == Never skip, Same as ALWAYS, even if job fails.
    TOOL
    Single
    May not be specified for SubSystem STEP or Command STEP
    Must be specified for Tool STEP
    COMMAND
    Single
    May not be specified for SubSystem STEP or Tool STEP
    Must be specified for Command STEP
    command
    If preceded by '@' or '>' or '.' and no .type: assume .bat on Win32 else .sh

    If preceded by '@', find command_file relative to $GBS_SYS_PATH
    If preceded by '>', find command_file relative to $GBS_SCRIPTS_PATH/plugins
    If preceded by '.', find command_file relative to $GBS_SCRIPTS_PATH
    BUILD
    Single, Optional, Boolean
    If NO the Step will not be selected for gbssysgen or gbssysmake
    May not be specified for Tool Step
    AUDIT
    Single, Optional, Boolean
    If NO the Step will not be selected for gbssysaudit
    May not be specified for Tool Step

    ALIAS-definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To group step_names and optionally associate a Target

    Syntax:

    ALIAS alias_name
    TARGET = target-name
    STEPS = steps-list

    Semantics

    ALIAS
    Must be specified after the STEP-definitions
    alias_name
    It is good practice to specify the alias_name in uppercase
    The alias_name may not be ALL
    TARGET
    Single, Optional
    Specifies associated Target
    STEPS
    Single, Mandatory
    steps-list
    '-' (hyphen) may be used to specify 'from' - 'to' sequences

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a steps.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    
    #
    #   STEPS.GBS
    #
    
    #
    #   STEPS
    #
    STEP begin
        COMMAND     = @begin
        AUDIT       = NO
    
    STEP superglo
    
    STEP bart
    
    STEP non_gbs
    
    STEP visualstudio
    
    STEP copy_export
        COMMAND     = >copy_export/bin/copy_export.pl superglo $GBS_TARGET $GBSEXT_GBSSHARE/$GBS_TARGET
        AUDIT       = NO
    
    STEP prqa
        EXEC        = SPECIFY
    
    STEP doxygen
        TOOL        = >doxygen/bin/doxygen.pl full
        BUILD       = NO
        AUDIT	= NO
    
    STEP doxygen_api
        TOOL        = >doxygen/bin/doxygen.pl api
        EXEC        = SPECIFY
        BUILD       = NO
        AUDIT	= NO
    
    #
    #   ALIASES
    #
    ALIAS SUBSET
        STEPS = superglo bart
    
    ALIAS PRQA
        STEPS = prqa
    
    ALIAS FULL
        STEPS = superglo bart prqa
    
    ALIAS ALL
        STEPS = begin - doxygen_api
    
    ALIAS LGCC
        TARGET = lgcc
    
    ALIAS MINGW
        TARGET = mingw
    
    ##EOF##
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The switch.gbs batch file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a switch.gbs.bat
    Example of a switch.gbs.sh

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The switch.gbs batch file is located in the GBS_ROOT_PATH directory and is used to define the environment in which the System has to function.
    Here all external items must be defined. e.g.:

    • Compiler-locations
    • 3rd party software located outside the Root
    • etc
    In GBS the switch.gbs file is the only file allowed to contain absolute disk-addresses

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Special considerations:
    • These files are operating-system dependent batch files and have the appropriate file-extension for that particular operating-system. e.g.:
      • switch.gbs.sh and switch.usr.sh for Unix-type operating-systems
      • switch.gbs.bat and switch.usr.bat for MS Windows operating-systems
    • If a file exists with the same name and with extension .usr instead of .gbs then that file will be taken after execution on the .gbs file.
      Never, ever check-in a .usr file.

    Calling Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    The switch.gbs file is called:
    When you enter a System (swr or startup)
    GBS_ROOT_PATH:switch.gbs is called with parameter entry
    When you leave a System (swr)
    GBS_ROOT_PATH:switch.gbs is called with parameter exit

    Environment Variables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Environment Variables defined in the switch.gbs file should be in uppercase.
    When referring to external data (directories/files) they should be prefixed with GBSEXT_. (Not GBS_EXT_)
    When exiting a Root (System) GBS will unset all Environment Variables starting with GBSEXT_.
    This is done before the switch.gbs is called with the 'exit' parameter. Note that at the moment of invocation all GBS internal Environment Variables for that Root have been set.

    Additional Available Environment Variables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    These are defined before execution of the switch.gbs file and can be used to control additional settings.
    They should not be changed!
    GBS_SITE
    Preset by user (Install or gbssetup)
    Specifies the site where this user is working
    More info in Install Notes
    GBS_BUILD
    A full numeric value that identifies the current build of GBS
    A combination of the GBS version and version_date
    GBS_PLATFORM
    Use to distinguish on which platform GBS is running. e.g.:
        linux, MSWin32, etc
    GBS_ROOT_PARENT
    The name of the parent directory (not the path) of the Root.
    It can be used to define a Log-directory dependent on the Root. E.g.:
    SET GBS_LOG_PATH=\%GBS_ROOT_PARENT%
    GBS_IS_INTEGRATOR
    0 or 1
    Specifies that the user has GBS Integrator privileges
    GBS_IS_ADMINISTRATOR
    0 or 1
    Specifies that the user has GBS Administrator privileges

    Layout Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    The file consists of two mayor parts:
    • Entry: The part that is executed with parameter 'entry'
      • The Root / Site sub-part
      • The general sub-part
    • Exit: The part that is executed with parameter 'exit;

    Entry

    This part is executed when you 'enter' a Root / System (make it current)
    It consists of 2 sub-parts

    Root / Site sub-part

    This sub-part is where you have the Site dependent stuff.
    Here you will typically set GBSEXT_..._ROOT EnvVars to their Site-dependent locations

    General sub-part

    This sub-part is where you set the GBSEXT_..._REL
    And the assembly of GBSEXT_..._ROOT and GBSEXT_..._REL to GBSEXT_..._PATH

    Exit

    This part is executed when you 'exit' a Root / System (un-current it)
    Here you cleanup all non GBSEXT_ stuff

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a switch.gbs.bat: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    
    @ECHO OFF
    ::========================================
    ::    %FILE% [%SYSTEM_NAME%]
    ::========================================
    if NOT [%1] == [entry] goto :exit
        ::
        ::    set items
        ::
    
        if NOT [%GBS_SITE%] == [%SITE%] goto :NOT_%SITE%
            ::
            ::  %SITE%
            ::
    
    	::
    	::  Version Control
    	::
    	::set GBSEXT_CC_PATH=PATH
    	::set GBSEXT_CCM_PATH=PATH
    	::set GBSEXT_CVS_PATH=PATH
    	::set GBSEXT_GIT_PATH=PATH
    	::set GBSEXT_SVN_PATH=PATH
    	::set GBSEXT_VSS_PATH=PATH
    
    	::
    	::  Targets
    	::
            ::set GBSEXT_MSVS2012_ROOT=C:\Program Files (x86)\Microsoft Visual Studio 11.0
            ::set GBSEXT_MSVS2012_SDK_ROOT=C:\Program Files (x86)\Microsoft SDKs\Windows
            ::set GBSEXT_MSBUILD_ROOT=C:\Windows\Microsoft.NET\Framework
    
    	::set GBSEXT_MINGW_ROOT=C:\MinGW
    
    	::
    	::  Audits
    	::
    	::set GBSEXT_QAC_ROOT=C:\MyPrograms\PRQA\QAC
    
    	::set GBSEXT_QACPP_ROOT=C:\MyPrograms\PRQA\QACPP
    
    	::set GBSEXT_PCLINT_ROOT=C:\MyPrograms\PC-Lint
    
    	::
    	::  Tools
    	::
    	::set GBSEXT_DOXYGEN_ROOT=C:\MyPrograms\doxygen
    
    	::
    	::  GBS Settings
    	::
    
            goto :end_site
        :NOT_%SITE%
        if NOT [%GBS_SITE%] == [OTHER] goto :NOT_OTHER
            ::
            ::      OTHER
            ::
            goto :end_site
        :NOT_OTHER
        	echo *******
        	echo **  Unknown site '%GBS_SITE%'
        	echo **  Must be one of [ %SITE% OTHER ]
    	echo *******
    	::false
    	goto :error_exit
        :end_site
    
        ::
        ::	Version Control
        ::
        ::set GBSEXT_SVN_PATH="C:\Program Files\TortoiseSVN\bin"
        ::set GBSEXT_SVN_PATH=PATH
    
        ::
        ::  Targets
        ::
        ::set GBSEXT_MSVS2012_CONS_REL=2012
        ::set GBSEXT_MSVS2012_CONS_PATH=%GBSEXT_MSVS2012_ROOT%
        ::set GBSEXT_MSVS2012_SDK_REL=v7.1A
        ::set GBSEXT_MSVS2012_SDK_PATH=%GBSEXT_MSVS2012_SDK_ROOT%\%GBSEXT_MSVS2012_SDK_REL%
        ::set GBSEXT_MSBUILD_REL=v4.0.30319
        ::set GBSEXT_MSBUILD_PATH=%GBSEXT_MSBUILD_ROOT%\%GBSEXT_MSBUILD_REL%
    
        ::set GBSEXT_MINGW_BASE_REL=2013072200
        ::set GBSEXT_MINGW_GCC_PATH=%GBSEXT_MINGW_ROOT%\%GBSEXT_MINGW_BASE_REL%
        ::set GBSEXT_MINGW_GCC_REL=4.8.1
    
        ::set GBSEXT_MINGW_BASE_REL=2013072200
        ::set GBSEXT_MINGW_CPP_PATH=%GBSEXT_MINGW_ROOT%\%GBSEXT_MINGW_BASE_REL%
        ::set GBSEXT_MINGW_CPP_REL=4.8.1
    
        ::
        ::  Audits
        ::
        ::set GBSEXT_QAC_REL=8.1-R
        ::set GBSEXT_QAC_PATH=%GBSEXT_QAC_ROOT%-%GBSEXT_QAC_REL%
    
        ::set GBSEXT_QACPP_REL=3.0-R
        ::set GBSEXT_QACPP_PATH=%GBSEXT_QACPP_ROOT%-%GBSEXT_QACPP_REL%
    
        ::set GBSEXT_PCLINT_REL=8.00x
        ::set GBSEXT_PCLINT_PATH=%GBSEXT_PCLINT_ROOT%\%GBSEXT_PCLINT_REL%
    
        ::
        ::	Tools
        ::
        ::set GBSEXT_DOXYGEN_REL=3.5
        ::set GBSEXT_DOXYGEN_PATH=%GBSEXT_DOXYGEN_ROOT%
    
        ::
        ::	Audit Tools
        ::
        ::set QAC_REL=%GBSEXT_QAC_REL%
        ::set QACROOT=%GBSEXT_QAC_PATH%
    
        ::set QACPP_REL=%GBSEXT_QACPP_REL%
        ::set QACPPROOT=%GBSEXT_QACPP_PATH%
    
        goto end_entry_exit
    :exit
    if NOT [%1] == [exit] goto :no_entry_exit
        ::
        ::	unset items
        ::	(GBSEXT_... are all unset by GBS)
        ::
        set QAC_REL=
        set QACROOT=
    
        set QACPP_REL=
        set QACPPROOT=
    
        goto :end_entry_exit
    :no_entry_exit
        echo *****
        echo ** SYSTEM/switch.gbs: Usage = call switch.gbs.bat [ entry ^| exit ]
        echo *****
        goto :error_exit
    :end_entry_exit
    :: true
    goto :EOF
    
    :error_exit
    ::
    ::  Error-exit
    ::
    set GBS_RC=1
    goto :EOF
    
    :::EOF:::
    
    

    Example of a switch.gbs.sh: Bottom Doc. Button Top Document Button Blank Up Section Button

    
    #========================================
    #   %FILE% [%SYSTEM_NAME%]
    #========================================
    SWITCH_RC=0
    if [[ $1 = "entry" ]]
    then
        #
        #	set items
        #
    
        if [[ $GBS_SITE = "%SITE%" ]]
        then
    	#
    	#   %SITE%
    	#
    
    	#
    	#   Version Control
    	#
            #export GBSEXT_CC_PATH=PATH
    	#export GBSEXT_CCM_PATH=PATH
    	#export GBSEXT_CVS_PATH=PATH
    	#export GBSEXT_GIT_PATH=PATH
    	#export GBSEXT_SVN_PATH=PATH
    
    	#
    	#   Targets
    	#
    	#export GBSEXT_LGNU_GCC_ROOT=/usr/lib/gcc/x86_64-linux-gnu
    	#export GBSEXT_LGNU_CPP_ROOT=/usr/lib/gcc/x86_64-linux-gnu
    
    	#
    	#   Audits
    	#
    	#export GBSEXT_QAC_ROOT=/apl/cadappl_linux_ia32/qac
    	#export GBSEXT_QACPP_ROOT=/apl/cadappl_linux_ia32/qac++
    
    	#
    	#   Tools
    	#
    
    	#
    	#   GBS Settings
    	#
    
    	true
    
        elif [[ $GBS_SITE = "OTHER" ]]
        then
    	#
    	#   OTHER
    	#
    
        	true
        else
        	echo "SWITCH.GBS: *****"
        	echo "SWITCH.GBS: ** Unknown Site $GBS_SITE"
    	echo "SWITCH.GBS: ** Must be one of '%SITE% OTHER'"
        	echo "SWITCH.GBS: *****"
        	SWITCH_RC=1
        fi
        #
        #	Targets
        #
        if [[ $SWITCH_RC = 0 ]]
        then
        	#
    	#   Targets
    	#
    	#export GBSEXT_LGNU_GCC_REL=4.4.5
    	#export GBSEXT_LGNU_GCC_PATH=$GBSEXT_LGNU_GCC_ROOT/$GBSEXT_LGNU_GCC_REL
    
    	#export GBSEXT_LGNU_CPP_REL=4.4.5
    	#export GBSEXT_LGNU_CPP_PATH=$GBSEXT_LGNU_CPP_ROOT/$GBSEXT_LGNU_CPP_REL
    
    	#
    	#   Audits
    	#
            #set GBSEXT_QAC_REL=8.1-R
            #set GBSEXT_QAC_PATH=$GBSEXT_QAC_ROOT-$GBSEXT_QAC_REL
    
            #set GBSEXT_QACPP_REL=3.0-R
            #set GBSEXT_QACPP_PATH=$GBSEXT_QACPP_ROOT-$GBSEXT_QACPP_REL
    
    	#
    	#   Tools
    	#
    
    	true
        fi
    elif [[ $1 = "exit" ]]
    then
        #
        #	unset items
        #	(GBSEXT_... are all unset by GBS)
        #
    
        true
    else
        echo "SWITCH.GBS: *****"
        echo "SWITCH.GBS: ** switch.gbs.sh: Usage = . switch.gbs.sh [ entry | exit ]"
        echo "SWITCH.GBS: *****"
        SWITCH_RC=1
    fi
    
    [[ $SWITCH_RC = 1 ]] && export GBS_RC=1
    unset SWITCH_RC
    
    ##EOF##
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The sys.gbs file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a sys.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The sys.gbs file is located in the GBS_SYS_PATH directory is used to define general settings for generation and auditing.
    Before GBS 3.00 this file was named sysbuild.gbs.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space (called header-lines) define an item.
    • Following lines with leading white-space (called sub-lines) define the parameters for that item.
    • Reserved words (keywords) are case sensitive
    • The .include directive is not allowed

    Definitions Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    VARIABLE EXCLUDE

    VARIABLE-definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    Allows environment-variables to be set while calling a GBS command on the command-line.
    These environment-variables can then be used by the generation/audit scripts.
    For each variable a selection of value_names and optionally a value_string can be set
    They will be made available with GBS_APP_value_name and optionally GBS_APP_value_name_VALUE

    Syntax:

    VARIABLE variable_name
    DEFAULT = value_name
    VALUE = value_name => value_string

    Semantics:

    variable_name
    Preferably in uppercase
    DEFAULT
    Single Occurrence. Single value, Optional
    Specifies the default value_name
    If omitted, the first value_name if the following list will be taken as default
    VALUE
    Multiple occurrence, at least one (or VALUES) must be specified

    EXCLUDE-definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    Specify files in the src directories that are to be ignored during generation.

    Syntax:

    EXCLUDE regular-expression-list

    Semantics:

    EXCLUDE
    May be specified more than once
    regular_expression-list
    Perl regular-expressions specifying files to be skipped
    e.g.
      \.tst$ == all filenames ending with '.tst'
      ^MEM == all filenames starting with 'MEM'

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a sys.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    #
    #   SYS.GBS
    #
    
    #
    #   ENVIRONMENT VARIABLES
    #
    VARIABLE PROFILING
        VALUE       = NO  => NO
        VALUE       = YES => YES
    
    VARIABLE COMPILER
        DEFAULT     = GHS
        VALUE       = GHS  => -ghs
        VALUE       = DIAB => -dia
    
    #
    #   SRC EXCLUDES
    #
    EXCLUDE \.mcp$ \.cvs$
    
    ##EOF##
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The system.gbs file Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a system.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The system.gbs file is located in the GBS_ROOT_PATH directory is used to define primary settings for a ROOT.

    It is a very delicate file and any manual modifications should be left to a GBS specialist.

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    This file will NOT be superseded by a .usr file

    Example of a system.gbs: Bottom Doc. Button Top Document Button Blank Up Section Button

    
    #
    #   SYSTEM.GBS
    #
    id=system
    system_name=SuperGlo
    root_version=2.04
    build_start=202061212
    build_end=
    scms-MSWin32=SubVersioN
    scms-linux=No_SCMS
    scms_data=trunk
    scms_repository-linux=
    scms_repository-MSWin32=svn://vhvfsnt10/SuperGlo
    targets-MSWin32=dos
    targets-MSWin32=dosd
    targets-MSWin32=mingw
    targets-MSWin32=mingwd
    targets-MSWin32=mvs
    targets-MSWin32=mvsd
    targets-linux=lgcc
    ###EOF###
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The target.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Examples of target.gbs files

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The target.gbs files are located in the GBS_SYSBUILD_PATH/target directories and is used to associate file-extensions with builders (compilers, linkers, etc) for a specific target.
    Also the particularities of the builders are defined.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space (called header-lines) define an item.
    • Following lines with leading white-space (called sub-lines) define the parameters for that item.
    • The search path for the .include Directive is:
      - $GBS_SYSBUILD_PATH/$GBS_TARGET
      - $GBS_SYSBUILD_PATH

    Contents Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    SETUP definition
    DEFAULTS definition
    INIT definition
    SRC definitions (multiple)
    ...

    SETUP Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define general stuff, valid for the whole definition set.

    Syntax:

    SETUP
    NICE_NAME = nice_name
    VIA_FORMAT = via_format

    Semantics:

    NICE_NAME
    Specifies a more descriptive name of the Target. It is used in messages.
    nice_name
    Free format (just do not make it too long)
    VIA_FORMAT
    Specifies format/syntax of file-inclusion on the command-line.
    via_format
    Specifies the printf format for command-line file-inclusion
    It must contain a %s
    It may contain a .file_type
    If a .file_type is not specified .gbs will be used.
    e.g.: @%s for MVS or
    %s (default)

    DEFAULTS definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To set Target dependent defaults, overriding the GBS defaults

    Syntax:

    DEFAULTS
    MODE = mode-definition
    OPT = opt-definition
    DEBUGGER = debugger-definition
    MAP = map-definition

    Semantics:

    Refer to SRC semantics below.

    INIT definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define derived Target dependent Environment Variables
    Note that all references to the 'outside-world' must be specified in the switch.gbs.
    On Windows it can be used to (re)define an EnvVar with spaces removed. (Converted to ShortPathName)

    Syntax:

    INIT
    SET_W = envvar_name => envvar_value
    ...
    SET_X = envvar_name => envvar_value
    ...
    SET = envvar_name => envvar_value
    ...
    SETPATH = path_envvar_name => envvar_value-list
    ...
    BIN_DIR = bin_dir

    Semantics:

    SET_W, SET_X & SET
    Specifies an Environment Variable.
    envvar_name
    Uppercase please
    envvar_value
    If placed between quotes (") it will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    SET_W is executed for Windows only.
    SET_X is executed for Unix and Linux only.
    SET is executed for all platforms
    and must be specified after SET_W and SET_X
    SETPATH
    Specifies a PATH Environment Variable.
    path_envvar_name
    Case dependent on OS
    envvar_value-list
    If placed between quotes (") items will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    Items will be properly joined (';' on Windows, ':' on Linux)
    Must be specified after SET_W, SET_X & SET
    BIN_DIR
    Specifies the directory in which the executables of the plugin reside, relative to GBSEXT_<plugin>_PATH.
    It is used to assemble GBSEXT_<plugin>_BIN_PATH which must be used in the COMMAND sub-section.
    bin_dir
    One or more directories, separated by '/'

    SRC definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To associate a file-extensions with a builder and provide the necessary information in order to be able to execute the builder.

    Syntax:

    SRC src_type-list
    TYPE = generic_type [ include_re [ comment_re | c ] ]
    ORDER = order-number
    SRC_ABS_PATH = 0 | 1
    INC_TYPES = inc_type-list
    OUT_TYPES = out_type-list
    OPT_OUT_TYPES = out_type-list
    OUT_FILES = out_name-list
    GLKB = env_type [ lib_spec ]
    INCLUDE_INC = 0 | 1
    INCLUDE_BLD = 0 | 1
    INC_FORMAT = [ env_type ] printf-format
    SYSINC_FORMAT = [ env_type ] printf-format
    INC_ABS_PATH = 0 | 1
    INC_SEARCH_STYLE = UNIX | PLAIN
    FLAG_FORMAT = [ env_type ] printf-format
    SYSFLAG_FORMAT = [ env_type ] printf-format
    MODE = mode-definition
    OPT = opt-definition
    DEBUGGER = debugger-definition
    MAP = map-definition
    COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition
    ...

    Semantics:

    SRC
    Specifies the input-type.
    May not be equal to '.glkb'
     
    TYPE
    Specifies the generic type of the builder.
    Has consequences on how comments and includes are handled.
    generic-type
    gen | asm | c | glb | glk | glt
    include_re
    Regular expression specifying how include-statements are recognised
    E.g.: For c the default is: ^\s*#include\s+[<"]\s*([^>"]+?)\s*[>"]
    comment_re
    Regular expression specifying how comments are recognised
    E.g.: For asm the default is: ^\s*[;*/].*
    Must be the first item in the list
    ORDER
    The Generation order
    SRC_ABS_PATH
    Some debuggers require an absolute src path to be able to find the source during debugging.
    INC_TYPES
    List of optional include-types
    Used to determine the proper Template/Comment_char when creating a User-file with gbsedit
    The SRC_TYPE is implicitly added to this list.
    OUT_TYPES
    List of mandatory output-types
    The first one is considered the primary output-type
    The primary output-type must start with a '.' (dot)
    Secondary output-type(s) must contain a '.' (dot).
    Note that if output-types do not start with '.' you may get name-clashes in Target-directory.
    Files of these type(s) will be deleted before builder starts.
    OPT_OUT_TYPES
    Additional (optional) output-types.
    Must contain a '.' (dot).
    Note that if output-types do not start with '.' you may get name-clashes in Target-directory.
    Files of these type(s) will be deleted before builder starts.
    OUT_FILES
    List of (mandatory) output-files
    These files will be deleted before builder starts.
    This is a very tricky option because you can have only one source file of this type per Component and GBS will not check on this...
    GLKB
    Specifies additional information on glb, glk and glt processing.
    env_type
    VARIABLE | FILE
    Specifies how the GLKB output will be presented.
    VARIABLE: In Environment Variable GBS_GLKB
    FILE: In a temporary file specified via EnvVar GBS_GLKB. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    lib-spec
    empty | UNIXLIB
    Specifies Unix-type library specification i.e.:
    -llibname searches for all liblibname.glb_out_types
    INCLUDE_INC
    Specifies that Component INC-directories must be included in the include-path search.
    Default = 1 for non GLKB types
    INCLUDE_BLD
    Specifies that Component BLD-directories must be included in the include-path search.
    INC_FORMAT
    Specifies information on the presentation of include-options (-I)
    env_type
    VARIABLE | FILE
    Specifies how the include-options will presented on the command-line.
    VARIABLE: In Environment Variable GBS_INCS
    FILE: In a temporary file specified via EnvVar GBS_INCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for include-options
    It must contain a %s
    e.g: -I%s for the C compiler.
    SYSINC_FORMAT
    Specifies information on the presentation of SYSTEM include-options (-I)
    Used in those cases where the compiler headerfiles must be specified explicitly.
    Items are taken from sysbuild/target/bld_incs_src_type.gbs only.
    env_type
    VARIABLE | FILE
    Specifies how the include-options will presented on the command-line.
    VARIABLE: In Environment Variable GBS_SYSINCS
    FILE: In a temporary file specified via EnvVar GBS_SYSINCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for include-options
    It must contain a %s
    e.g: -I%s for the C compiler.
    INC_ABS_PATH
    Specifies that the include-search-path must be an absolute address
    INC_SEARCH_STYLE
    Specifies the order in which the Include-Paths are searched:
    UNIX
    The order in which the paths are specified, unless it is a it is a quotes-type include:
    then first look in the directory of the including file
    PLAIN
    The order in which the paths are specified
    FLAG_FORMAT
    Specifies information on the presentation of flags (-D)
    env_type
    VARIABLE | FILE
    Specifies how the flags will presented on the command-line.
    VARIABLE: In Environment Variable GBS_FLAGS
    FILE: In a temporary file specified via EnvVar GBS_FLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for flags
    It must contain a %s
    e.g: -D%s for the C compiler.
    SYSFLAG_FORMAT
    Specifies information on the presentation of SYSTEM flags (-D)
    Used in those cases where the standard compiler flags must be specified explicitly.
    Note that is normally not the case!
    Items are taken from sysbuild/target/bld_flags_src_type.gbs only.
    env_type
    VARIABLE | FILE
    Specifies how the flags will presented on the command-line.
    VARIABLE: In Environment Variable GBS_SYSFLAGS
    FILE: In a temporary file specified via EnvVar GBS_SYSFLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.
    printf_format
    Specifies the printf format for flags
    It must contain a %s
    e.g: -D%s for the C compiler.
    MODE
    Specifies the options for FINAL, ASSERT, DEBUG and PROFILING
    Useful for types: c
    mode-definition
    mode-definition := mode_name... => option
    mode_name := FINAL | ASSERT | DEBUG | PROFILING
    E.g.: MODE = DEBUG => -DDEBUG
    OPT
    Specifies the optimization
    Useful for types: c
    opt-definition
    opt-definition := optimize_name... => option
    optimize_name := YES | SPEED | SIZE | DEBUG | NO
    E.g: OPT = YES SPEED SIZE => -O9
    DEBUGGER
    Specifies if debugging information must be included
    Useful for types: c glb and glk
    debugger-definition
    NO => option (default)
    YES => option
    MAP
    Specifies if a memory-map must be created
    Useful for types: glk
    map-definition
    YES => option (default)
    NO => option
    In the option: any %1 (MSWin) or $1 (Unix) will be replaced by the file-spec of the map-file.
    COMMAND
    Command to invoke the builder.
    pre_condition
    file_exists_condition | env_value_condition
    The command will only be executed if the condition is true.
    file_exists_condition
    [ ! ] exists file_spec
    env_value_condition
    variable_name_in_uppercase =|==|!= value
    ok_exit_values-comma-list
    Specifies the exit values for the command that are considered OK.
    Range specification (3-5) allowed. Default is 0.
    command-definition
    command | @user_script | >gbs_audit_script | .gbs_script echo_command | set_command
    command
    Single line command
    You may want to use GBSEXT_<plugin>_BIN_PATH
    user_script
    Search for in User-Audit and then GBS-Audit
    gbs_audit_script
    Relative from the GBS plugin/audit directory
    gbs_script
    Take from GBS_SCRIPTS_PATH
    echo_command
    ECHO any_text
    Prints any_text. EnvVars and positional parameters are replaced
    set_command
    SET variable_name_in_uppercase = any_value
    Sets the EnvVar. In any_value EnvVars and positional parameters are replaced
    Note that you can continue a long command on the next line by adding ' \' at the end.

    The command is called with the following positional parameters
    • $1 filename
      Without the file-type
    • $2 in_file_spec
      May be absolute depending on SRC_ABS_PATH
    • $3 out_file_spec
      Relative path
    • $4 out_file_path
      Relative path
    • $5 out_file_type
      Including the dot.
    • $6-$n ($*) Command-line flags.
    The following additional Environment Variables are set and may be used:
    • GBS_INCS
      Contains the include-statements specification as defined by INC_FORMAT
    • GBS_SYSINCS
      Contains the include-statements specification as defined by SYSINC_FORMAT
    • GBS_FLAGS
      Contains the flags specification as defined by FLAG_FORMAT Including:
      - Results of MODE, DEBUGGER, OPT and MAP
      - Values of flags_type.gbs files
      - Values in GBS_FLAGS_type
    • GBS_SYSFLAGS
      Contains the flags specification as defined by SYSFLAG_FORMAT
    • GBS_GLKB
      For GLKB types
      Contains the GLKB lines
    • GBS_APP_name... and GBS_APP_name_VALUE...
      As specified in the sys.gbs file

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Examples of target.gbs files: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    File 1 (final target) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    #========================================================
    #   [mingw] target.gbs
    #========================================================
    
    SETUP
        NICE_NAME	= MinGW_cpp
    
    INIT
        SET_W       = TEST => WIN32
        SET_X       = TEST => LUNIX
        BIN_DIR	= bin
        SETPATH     = PATH => GBSEXT_MINGW_CPP_BIN_PATH% PATH
    
    SRC .c
        TYPE	= c
        ORDER	= 1
        INC_TYPES	= .h
        OUT_TYPES	= .o
        INCLUDE_BLD = 1
        INC_FORMAT	= -I%s
        INC_SEARCH_STYLE = UNIX
        FLAG_FORMAT = -D%s
        MODE    	= ASSERT    => -DASSERT
        MODE    	= DEBUG     => -DDEBUG
        MODE        = PROFILING => -DPROFILING
        DEBUGGER	= YES       => -g
        OPT     	= NO	    => -O0
        OPT     	= SIZE	    => -Os
        OPT     	= SPEED	YES => -O3
        COMMAND	= GBSEXT_MINGW_CPP_BIN_PATH%\gcc -c -Wall -ansi %GBS_INCS% %GBS_FLAGS% %* %2 -o %3
    
    SRC .cpp
        TYPE	= c
        ORDER	= 1
        INC_TYPES	= .hpp
        OUT_TYPES	= .o
        INCLUDE_BLD = 0
        INC_FORMAT	= -I%s
        INC_SEARCH_STYLE = UNIX
        FLAG_FORMAT = -D%s
        MODE    	= ASSERT    => -DASSERT
        MODE    	= DEBUG     => -DDEBUG
        MODE        = PROFILING => -DPROFILING
        DEBUGGER	= YES       => -g
        DEBUGGER    = NO        =>
        OPT     	= NO	    => -O0
        OPT     	= SIZE	    => -Os
        OPT     	= SPEED	YES => -O3
        COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\g++ -c -Wall %GBS_INCS% %GBS_FLAGS% %* %2 -o %3
    
    SRC .s
        TYPE	= asm ^\.include\s+(")(.*?)" ^\s*#.*
        ORDER	= 1
        INC_TYPES	= .inc
        OUT_TYPES	= .o
        INC_FORMAT	= -I%s
        FLAG_FORMAT = -D%s
        COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\as --warn --fatal-warnings %GBS_INCS% %GBS_FLAGS% %* %2 -o %3
    
    SRC .glb
        TYPE	= glb
        ORDER	= 2
        INC_TYPES	= .glb
        OUT_TYPES	= .a
        GLKB	= VARIABLE
        COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\ar -rvs %* %3 %GBS_GLKB%
    
    SRC .glk
        TYPE	= glk
        ORDER	= 4
        INC_TYPES	= .glk
        OUT_TYPES	= .exe
        GLKB	= VARIABLE UNIXLIB
        INC_FORMAT	= -L%s
        MAP     	= YES => -Wl,-Map -Wl,%1
    #    DEBUGGER	= NO  => "Wl,-s"
        COMMAND	= @mingw_glk.bat
    
    SRC .glt
        TYPE	= glt
        ORDER	= 5
        INC_TYPES	= .glt
        OUT_TYPES	= .log
        COMMAND	= >ALL/gbstest.pl
    
    ##EOF##
    
    

    File 2 (debug target) Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    #========================================================
    #   [mingwd] target.gbs
    #========================================================
    .plugin mingw_gcc
    
    .include <target.gbs>
    
    DEFAULTS
        MODE     = DEBUG
        DEBUGGER = YES
        OPT      = DEBUG
    
    ##EOF##
    
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    The tool.gbs files Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Description
    Example of a tool.gbs

    Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    Purpose Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    The tool.gbs files are located in the GBS_SYSTOOLS_PATH/tool directories and are used to define the particularities of a Tool.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Please refer to .gbs files: General information

    Additional for this file:

    • Lines with no leading white-space (called header-lines) define an item.
    • Following lines with leading white-space (called sub-lines) define the parameters for that item.
    • Reserved words (keywords) are case sensitive
    • The search path for the .include Directive is:
      - $GBS_SYSTOOLS_PATH/$GBS_TOOL
      - $GBS_SYSTOOLS_PATH

    Contents Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    SETUP definition
    DEFAULTS definition
    INIT definition
    RUN definition

    SETUP Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define general stuff, valid for the whole definition set.

    Syntax:

    SETUP
    NICE_NAME = nice_name

    Semantics:

    NICE_NAME
    Specifies a more descriptive name of the Tool. It is used in messages.
    nice_name
    Free format (just do not make it too long)

    DEFAULTS definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To set Tool dependent defaults, overriding the GBS defaults

    Syntax:

    DEFAULTS
    ACTION = action-definition

    Semantics:

    Refer to RUN semantics below.

    INIT definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To define derived Tool dependent Environment Variables
    Note that all references to the 'outside-world' must be specified in the switch.gbs.
    On Windows it can be used to (re)define an EnvVar with spaces removed. (Converted to ShortPathName)

    Syntax:

    INIT
    SET_W = envvar_name => envvar_value
    ...
    SET_X = envvar_name => envvar_value
    ...
    SET = envvar_name => envvar_value
    ...
    SETPATH = path_envvar_name => envvar_value-list
    ...
    BIN_DIR = bin_dir

    Semantics:

    SET_W, SET_X & SET
    Specifies an Environment Variable.
    envvar_name
    Uppercase please
    envvar_value
    If placed between quotes (") it will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    SET_W is executed for Windows only.
    SET_X is executed for Unix and Linux only.
    SET is executed for all platforms
    and must be specified after SET_W and SET_X
    SETPATH
    Specifies a PATH Environment Variable.
    path_envvar_name
    Case dependent on OS
    envvar_value-list
    If placed between quotes (") items will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
    Items will be properly joined (';' on Windows, ':' on Linux)
    Must be specified after SET_W, SET_X & SET
    BIN_DIR
    Specifies the directory in which the executables of the plugin reside, relative to GBSEXT_<plugin>_PATH.
    It is used to assemble GBSEXT_<plugin>_BIN_PATH which must be used in the COMMAND sub-section.
    bin_dir
    One or more directories, separated by '/'

    RUN Definition Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Purpose:

    To provide information on how to run the Tool program (executable or script)

    Syntax:

    RUN
    ACTION = actiondefinition
    ...
    COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition
    ...

    Semantics:

    ACTION
    Specifies possible actions of the Tool. To be used as pos-arg, option or EnvVar
    action-definition
    action-definition := action_name... => option
    E.g.:
    ACTION = API => api
    ACTION = FULL => full
    Default is the first in the list
    COMMAND
    Command to invoke the Tool program.
    pre_condition
    file_exists_condition | env_value_condition
    The command will only be executed if the condition is true.
    file_exists_condition
    [ ! ] exists file_spec
    env_value_condition
    variable_name_in_uppercase =|==|!= value
    ok_exit_values-comma-list
    Specifies the exit values for the command that are considered OK.
    Range specification (3-5) allowed. Default is 0.
    command-definition
    command | @user_script | >gbs_audit_script | .gbs_script echo_command | set_command
    command
    Single line command
    You may want to use GBSEXT_<plugin>_BIN_PATH
    user_script
    Search for in User-Audit and then GBS-Audit
    gbs_audit_script
    Relative from the GBS plugin/audit directory
    gbs_script
    Take from GBS_SCRIPTS_PATH
    echo_command
    ECHO any_text
    Prints any_text. EnvVars and positional parameters are replaced
    set_command
    SET variable_name_in_uppercase = any_value
    Sets the EnvVar. In any_value EnvVars and positional parameters are replaced
    Note that you can continue a long command on the next line by adding ' \' at the end.

    The command is called with the following positional parameters:
    • $1 selected_action
      The option value of the DEFAULT ACTION
    • $2 subsys_def_list
      A comma-list of selected SubSystem definitions
      subsys_def := subsystem:subsystem_type
      subsystem_type := GBS | MSVS | make | Other
      E.g.: subsys1:GBS,subsys2:make,subsys3:GBS
    • $3 out_file_spec
      $GBS_SILO_PATH/tools/$GBS_TOOL/index.html
    • $4 out_file_path
      $GBS_SILO_PATH/tools/$GBS_TOOL
    The following additional Environment Variables are set and may be used:
    • GBS_APP_name... and GBS_APP_name_VALUE...
      As specified in the sys.gbs file

    Notes: Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    None

    Example of a tool.gbs: Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    File 1 (Basic reference - implicit default) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    #========================================================
    #   doxygen_api [doxygen] tool.gbs
    #========================================================
    .plugin doxygen
    
    .include <tool.gbs>
    
    ###EOF###
    

    File 2 (Basic reference - explicit default) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    #========================================================
    #   [doxygen] tool.gbs
    #========================================================
    .plugin doxygen
    
    .include <tool.gbs>
    
    DEFAULTS
        ACTION = FULL
    
    ###EOF###
    

    File 3 (Full specification) Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    #========================================================
    #   %TOOL% [doxygen] tool.gbs
    #========================================================
    
    SETUP
        NICE_NAME	= DoxyGen
    
    INIT
        BIN_DIR	= bin
    
    RUN
        ACTION = API    => api
        ACTION = FULL   => full
        COMMAND = >doxygen/bin/doxygen.pl %1 %2 %3 %4
    
    ##EOF##
    


    GBS Logo HOME Generic Build Support (GBS) - User Manual
    Metrics Help Bottom Doc. Button

    Contents Bottom Doc. Button Top Document Button Down Section Button Blank

    Metrics Overview
    Function-Based Metrics
    File-Based Metrics
    Project-Wide Metrics
    Class-Based Metrics
    General

    Metrics Overview Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    The Calculation of Metrics Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    QAC calculates metrics in three groups.
    Function metrics are generated for all functions with a full definition.
    File metrics are generated for each file analyzed.
    Project metrics are calculated once per complete project, and are generated from cross-module analysis.

    QAC++ calculates metrics in three groups.
    Function metrics are generated for all functions with a full definition.
    Class metrics are generated for each defined class.
    File metrics are generated for each file analyzed.

    All metrics, except LIN and TPP, ignore code that is disabled on evaluation of pre-processor directives.
    That is, both the code in the source file and the #include'd files inside conditional pre-processor directives are ignored for all metrics except LIN and TPP.

    For example:

    
        #define A 10
        #if 0
        #include <stdio.h>      /* Ignored by all except LIN, TPP */
        int i;                  /* Ignored by all except LIN, TPP */
        #else
        long i;
        #endif
    

    Function-Based Metrics Overview Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    These metrics are all calculated for the source code of an individual function. Some metrics are used in the definition of others, but there is no obvious sequence. They are described here in alphabetical order, for ease of reference. The complete list is as follows:

    AKIAkiyama's Criterion
    AV1Average Size of Statement in Function (variant 1)
    AV2Average Size of Statement in Function (variant 2)
    AV3Average Size of Statement in Function (variant 3)
    BAKNumber of Backward Jumps
    CALNumber of Functions Called from Function
    CYCCyclomatic Complexity
    ELFNumber of Dangling Else-Ifs
    FN1Number of Operator Occurrences in Function
    FN2Number of Operand Occurrences in Function
    GTONumber of Goto statements
    KDNKnot Density
    KNTKnot Count
    LCTNumber of Local Variables Declared
    LINNumber of Code Lines
    LOPNumber of Logical Operators
    M07Essential Cyclomatic Complexity
    M19Number of Exit Points
    M29Number of Functions Calling this Function
    MCCMyer's Interval
    MIFDeepest Level of Nesting
    PARNumber of Function Parameters
    PBGResidual Bugs (PTH-based est.)
    PDNPath Density
    PTHEstimated Static Program Paths
    RETNumber of Return Points in Function
    ST1Number of Statements in Function (variant 1)
    ST2Number of Statements in Function (variant 2)
    ST3Number of Statements in Function (variant 3)
    SUBNumber of Function Calls
    UNRNumber of Unreachable Statements
    UNVUnused or Non-Reused Variables
    XLNNumber of Executable Lines

    File-Based Metrics Overview Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    These metrics are all calculated for the source code in a complete translation unit (TU). They are listed alphabetically here for convenience. They are not calculated in this sequence. because of their derivation from each other:

    BMEEmbedded Programmer Months
    BMOOrganic Programmer Months
    BMSSemi-detached Programmer Months
    BUGResidual Bugs (token-based estimate)
    CDNComment to Code Ratio
    DEVEstimated Development (programmer-days)
    DIFProgram Difficulty
    ECTNumber of External Variables Declared
    EFFProgram Effort
    FCOEstimated Function Coupling
    FNCNumber of Functions in File
    HALHalstead Prediction of TOT
    M20Number of Operand Occurrences
    M21Number of Operator Occurrences
    M22Number of Statements
    M28Number of Non-Header Comments
    M33Number of Internal Comments
    OPNNumber of Distinct Operands
    OPTNumber of Distinct Operators
    SCTNumber of Static Variables Declared
    SHNShannon Information Content
    TDEEmbedded Total Months
    TDOOrganic Total Months
    TDSSemi-detached Total Months
    TLNTotal Preprocessed Source Lines
    TOTTotal Number of Tokens Used
    TPPTotal Unpreprocessed Code Lines
    VARTotal Number of Variables
    VOLProgram Volume
    ZIPZipf Prediction of TOT
      
    CCATotal Number of Characters
    CCBTotal Number of Code Characters
    CCCTotal Number of Comment Characters

    Class-Based Metrics Overview Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    These metrics are calculated for the classes in your source code. To calculate some of these metrics you must also have run the relevant cross-module analysis program. See Cross-Module Analysis in Chapter 4: Analysing Source Code. Class-based metrics are described here in alphabetical order for ease of reference:

    CBOCoupling between objects
    DITDeepest level of inheritance
    LCMLack of cohesion of methods within a class
    MTHNumber of methods available in class
    NOCNumber of immediate children
    NOPNumber of immediate parents
    RFCResponse for class
    WMCWeighted methods per class

    Project-Wide Metrics Overview Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    These metrics are calculated once per complete project. The complete list is as follows:

    NRANumber of Recursions Across Project
    NEANumber of Entry Points Across Project
    NFANumber of Functions Across Project
    CYACyclomatic Complexity Across Project

    Function-Based Metrics Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    AKI - Akiyama's Criterion Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Function-Based Metric

    This metric is the sum of the Cyclomatic complexity (CYC) and the number of function calls (SUB). Although this is not an independent metric, it is included on account of its use in documented case histories. See Akiyama[1] and Shooman[2] for more details. The metric is calculated as:

    AKI = CYC + SUB

    [1] Akiyama, F. (1971) An Example of Software System Debugging, Proc. IFIP Congress 1971, Lbujlana, Yugoslavia, American Federation of information Processing Societies, Montvale, New Jersey.

    [2] Shooman, M.L. (1983) Software Engineering, McGraw-Hill, Singapore.

    AV1 - Average Size of Statement in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    AV2 - Average Size of Statement in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    AV3 - Average Size of Statement in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    AVx - Average Size of Statement in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metrics

    These metrics (AV1, AV2, and AV3) measure the average number of operands and operators per statement in the body of the function. They are calculated as follows:

    AVx = (N1 + N2) / number of statements in the function

    where:
    N1 is Halstead's number of operator occurrences.
    N2 is Halstead's number of operand occurrences.

    The AVx metrics are computed using ST1, ST2 and ST3 to represent the number of statements in a function. Hence there are three variants: AV1, AV2 and AV3 relating to the respective statement count metrics.

    This metric is used to detect components with long statements. Statements comprising a large number of textual elements (operators and operands) require more effort by the reader in order to understand them. This metric is a good indicator of the program's readability.

    Metric values are computed as follows:

    AV1 = (FN1 + FN2) / ST1
    AV2 = (FN1 + FN2) / ST2
    AV3 = (FN1 + FN2) / ST3

    BAK - Number of Backward Jumps Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    Jumps are never recommended and backward jumps are particularly undesirable. If possible, the code should be redesigned to use structured control constructs such as while or for instead of goto.

    
        main()
        {
        Backward:
            switch (n)
            {
            case 0:
                printf( stdout, "zero\n");
                break;
            case 1:
                printf( stdout, "one\n");
                goto Backward;                  /* 1 */
                break;
            case 2:
                printf( stdout, "two\n");
                break;
            default: printf( stdout, "many\n");
                break;
            }
        }
    

    The above code sample has a BAK value of 1.

    CAL - Number of Functions Called from Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric counts the number of function calls in a function.

    It differs from the metric SUB, in that only distinct functions are counted (multiple instances of calls to a particular function are counted as one call), and also that functions called via pointers are not counted.

    CYC - Cyclomatic Complexity Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    Cyclomatic complexity is calculated as the number of decisions plus 1.

    High cyclomatic complexity indicates inadequate modularization or too much logic in one function. Software metric research has indicated that functions with a cyclomatic complexity greater than 10 tend to have problems related to their complexity.

    McCabe[3] gives an essential discussion of this issue as well as introducing the metric.

    Example 1:

    
        int divide( int x, int y)
        {
            if (y != 0)                     /* 1 */
            {
                return x / y;
            } else if (x == 0)              /* 2 */
            {
                return 1;
            } else
            {
                printf( "div by zero\n");
                return 0;
            }
        }
    

    The above code sample has a cyclomatic complexity of 3 as there are two decisions made by the function. Note that correctly-indented code does not always reflect the nesting structure of the code. In particular, the use of the construct 'else if' always increases the level of nesting, but it is conventionally written without additional indentation and so the nesting is not visually apparent.

    Example 2:

    
        void how_many(int n)
        {
            switch (n)
            {
            case 0:
                printf( "zero");            /* 1 */
                break;
            case 1:
                printf( "one");             /* 2 */
                break;
            case 2:
                printf( "two");             /* 3 */
                break;
            default:
                printf( "many");
                break;
            }
        }
    

    The above code sample has a cyclomatic complexity of 4, as a switch statement is equivalent to a series of decisions.

    Some metrication tools include use of the ternary operator ? : when calculating cyclomatic complexity. It could also be argued that use of the && and || operators should be included. Instead, CYC calculation is based on statements alone.

    CYC is one of the three standard metrics used by QAC for demographic analysis.

    [3] McCabe, T. J. (1976) A Complexity Measure, IEEE Transactions on Software Engineering, SE-2, pp. 308-320.

    ELF - Number of Dangling Else-Ifs Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the number of if-else-if constructs that do not end in an else clause. This metric is calculated by counting all if statements that do not have a corresponding else and for which QAC issues a warning 2004. ELF provides a quick reference allowing monitoring of these warnings. The code sample below has an ELF value of 1.

    
        int divide(int x, int y)
        {
            if (y != 0)
            {
                return x/y;
            } else if (x == 0)
            {
                return 1;
            }
        }
    

    FN1 - Number of Operator Occurrences in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is Halstead's operator count on a function basis (N1). FN1 is related to OPT and M21: all of these metrics count 'operators', the difference is summarized as:

    FN1Counts ALL operators in the function body
    M21Counts ALL operators in the file
    OPTCounts DISTINCT operators in the file

    See OPT for the definition of an operator.

    FN2 - Number of Operand Occurrences in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is Halstead's operand count on a function basis (N2). FN2 is related to OPN and M20: all of these metrics count 'operands', the difference is summarized as:

    FN2Counts ALL operands in the function body
    M20Counts ALL operands in the file
    OPNCounts DISTINCT operands in the file

    See OPN for the definition of an operand.

    GTO - Number of Goto statements Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    Some occurrences of goto simplify error handling. However, they should be avoided whenever possible. According to the Plum Hall Guidelines, goto should not be used.

    KDN - Knot Density Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the number of knots per executable line of code. The metric is calculated as:

    KDN = KNT / XLN

    The value is computed as zero when XLN is zero.

    KNT - Knot Count Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the number of knots in a function. A knot is a crossing of control structures, caused by an explicit jump out of a control structure either by break, continue, goto, or return. KNT is undefined for functions with unreachable code.

    This metric measures knots, not by counting control structure crossings, but by counting the following keywords:

    • goto statements,
    • continue statements within loop statements
    • break statements within loop or switch statements, except those at top switch level,
    • all return statements except those at top function level.

    The function below has an KNT value of 1.

    
        void fn( int n, int array[], int key )
        {
            while ( array[ n ] != key )
            {
                if ( array[ n ] == 999 )
                {
                    break;
                } else
                {
                    ++n;
                }
            }
        }
    

    LCT - Number of Local Variables Declared Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the number of local variables of storage class auto, register, or static declared in a function. These are variables that that have no linkage. The function below has an LCT value of 2.

    
        int other_result;
        extern int result;
    
        int test()
        {
            int x;                                  /* 1 */
            int y;                                  /* 2 */
    
            return (x + y + other_result);
        }
    

    LIN - Number of Code Lines Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the total number of lines, including blank and comment lines, in a function definition between (but excluding) the opening and closing brace of the function body. It is computed on raw code. LIN is undefined for functions which have #include'd code or macros which include braces in their definition.

    The function below has an LIN value of 5.

    
        int fn()
        {
            int x;                  /* 1 */
            int y;                  /* 2 */
                                    /* 3 */
            return (x + y);         /* 4 */
            /* Comment Here */      /* 5 */
        }
    

    Long functions are difficult to read, as they do not fit on one screen or one listing page. An upper limit of 200 is recommended.

    LOP - Number of Logical Operators Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the total number of logical operators (&&, ||) in the conditions of do-while, for, if, switch, or while statements in a function. The example function below has a LOP value of 2.

    
        void fn( int n, int array[], int key )
        {
            while (( array[n] != key ) && ( n > 0 ))
            {
                if (( array[n] == 999) || ( array[n] == 1000 ))
                {
                    break;
                } else
                {
                    ++n;
                }
            }
        }
    

    M07 - Essential Cyclomatic Complexity Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    The essential cyclomatic complexity is obtained in the same way as the cyclomatic complexity but is based on a 'reduced' control flow graph. The purpose of reducing a graph is to check that the component complies with the rules of structured programming.

    A control graph that can be reduced to a graph whose cyclomatic complexity is 1 is said to be structured. Otherwise reduction will show elements of the control graph which do not comply with the rules of structured programming.

    The principle of control graph reduction is to simplify the most deeply nested control subgraphs into a single reduced subgraph. A subgraph is a sequence of nodes on the control flow graph which has only one entry and exit point. Four cases are identified by McCabe[4] which result in an unstructured control graph. These are:

    • a branch into a decision structure,
    • a branch from inside a decision structure,
    • a branch into a loop structure,
    • a branch from inside a loop structure.

    However, if a subgraph possesses multiple entry or exit points then it cannot be reduced. The use of multiple entry and exit points breaks the most fundamental rule of structured programming.

    The example below has a M07 value of 4.

    
        void g( int n, int pos, int force )  /* M07 = 4
                                                Cannot reduce control graph to
                                                Cyclomatic Complexity of 1 */
        {
            int nlines = 0;
    
            while ( --n >= 0 )
            {
                pos = back_line( pos );
                if ( pos == 0 )
                {
                    if ( ! force )
                    {
                        break;
                    }
                    ++nlines;
                }
            }
        }
    

    [4] McCabe, T. J. (1976) A Complexity Measure, IEEE Transactions on Software Engineering, SE-2, pp. 308-320.

    M19 - Number of Exit Points Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a measure of the number of exit points in a software component and is calculated by counting the number of return statements. A function that has no return statements will have an M19 value of zero even though it will exit when falling through the last statement. This is regardless of whether the function is declared to have a return value or not (i.e. returns void). Calls to non-returning functions such as exit() or abort() are ignored by this metric.

    The example below has an M19 value of 3.

    
        void f( int a )
        {
            return;             /* 1 */
            if ( a )
                return;         /* 2 */
            a++;
            return;             /* 3 */
        }
    

    M29 - Number of Functions Calling this Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is defined as the number of functions calling the designated function. The number of calls to a function is an indicator of criticality. The more a function is called, the more critical it is and, therefore, the more reliable it should be.

    MCC - Myer's Interval Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is an extension to the cyclomatic complexity metric. It is expressed as a pair of numbers, conventionally separated by a colon. Myer's Interval is defined as CYC : CYC + L

    Cyclomatic complexity (CYC) is a measure of the number of decisions in the control flow of a function. L is the value of the QAC LOP metric which is a measure of the number of logical operators (&&, ||) in the conditional expressions of a function. A high value of L indicates that there are many compound decisions, which makes the code more difficult to understand. A Myer's interval of 10 is considered very high.

    The example below has a MCC value of 3:4 because the cyclomatic complexity is 3 and there is one connective (&&) used in the conditions.

    
        int divide( int x, int y)
        {
            if (y != 0)                     /* Condition 1 */
            {
                return x / y;
            } else if (x == 0 && y > 2)     /* Condition 2 */
                                            /* Conditional expr 1 */
            {
                return 1;
            } else
            {
                printf( "div by zero\n");
                return 0;
            }
        }
    

    Note:

    In the calculation of MCC, the ternary operator (?:) is ignored.

    When exporting metric values or displaying in the Metrics Browser, rather than attempting to display a value pair, the value of L is chosen for MCC.

    MIF - Deepest Level of Nesting Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a measure of the maximum control flow nesting in your source code.

    You can reduce the value of this metric by turning your nesting into separate functions. This will improve the readability of the code by reducing both the nesting and the average cyclomatic complexity per function.

    The code example below has an MIF value of 3.

    
        int divide( int x, int y)
        {
            if (y != 0)                         /* 1 */
            {
                return (x/y);
            } else if (x == 0)                  /* 2 */
            {
                return 1;
            } else
            {
                printf( "Divide by zero\n");
                while (x > 1)                   /* 3 */
                    printf( "x = %i", x);
                return 0;
            }
        }
    

    MIF is incremented in switch, do, while, if and for statements. The nesting level of code is not always visually apparent from the indentation of the code. In particular, an else if construct increases the level of nesting in the control flow structure but is conventionally written without additional indentation.

    MIF is one of the three standard metrics used by QAC for demographic analysis.

    PAR - Number of Function Parameters Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric counts the number of declared parameters in the function argument list. Note that ellipsis parameters are ignored.

    PBG - Residual Bugs (PTH-based est.) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    Hopkins, in Hatton & Hopkins[5] investigated software with a known audit history and observed a correlation between Static Path Count (PTH) and the number of bugs that had been found. This relationship is expressed as PBG.

    PBG = log10 ( PTH )

    [5] Hatton, L., Hopkins, T.R., (1989) Experiences With Flint, a Software Metrication Tool for Fortran 77, Symposium on Software Tools, Napier Polytechnic, Edinburgh, Scotland.

    PDN - Path Density Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is a measure of the number of paths relative to the number of executable lines of code.

    PDN = PTH / XLN
    PDN is computed as zero when XLN is zero.

    PTH - Estimated Static Program Paths Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is similar to Nejmeh's[6] NPATH statistic and gives an upper bound on the number of possible paths in the control flow of a function. It is the number of non-cyclic execution paths in a function.

    The NPATH value for a sequence of statements at the same nesting level is the product of the NPATH values for each statement and for the nested structures. NPATH is the product of:

    • NPATH( sequence of non control statements ) = 1
    • NPATH(if) = NPATH(body of then) + NPATH( body of else)
    • NPATH(while) = NPATH( body of while) + 1
    • NPATH(do while) = NPATH(body of while) + 1
    • NPATH(for) = NPATH(body of for) + 1
    • NPATH(switch) = Sum( NPATH(body of case 1) ... NPATH(body of case n) )

    Note:

    else and default are counted whether they are present or not.

    In switch statements, multiple case options on the same branch of the switch statement body are counted once for each independent branch only. For example:

    
        switch( n )
        {
        case 0 :
            break;          /* NPATH of this branch is 1                */
        case 1 :
        case 2 :
            break;          /* NPATH for case 1 &amp; case 2 combined is 1  */
        default:
            break;          /* NPATH for this default is 1              */
        }
    

    Since NPATH cannot be reliably computed if there are goto statements in the function, they are ignored by QAC for the purposes of calculating NPATH.

    The following code example has a static path count of 26.

    
        int n;
        if ( n )
        {
        } /* block 1, paths 1 */
        else if ( n )
        {
            if ( n )
            {
            } /* block 2, paths 1 */
    
            else
            {
            } /* block 3, paths 1 */
    
            /* block 4, paths block2+block3 = 2 */
    
            switch ( n )
            {
            case 1 : break;
            case 2 : break;
            case 3 : break;
            case 4 : break;
            default: break;
            } /* block 5, paths = 5 */
    
        } /* block 6, paths block4*block5 = 10 */
        else
        {
            if ( n )
            {
            } /* block 7, paths 1 */
    
            else
            {
            } /* block 8, paths 1 */
        } /* block 9, paths block7+block8 = 2 */
        /* block 10, paths block1+block6+block9 = 13 */
    
        if ( n )
        {
        } /* block 11, paths 1 */
    
        else
        {
        } /* block 12, paths 1 */
        /* block 13, paths block11+block12 = 2 */
    
        /* outer block, paths block10*block13 = 26 */
    

    Each condition is treated as disjoint. In other words, no conclusions are drawn about a condition that is tested more than once.

    The true path count through a function usually obeys the inequality:

    cyclomatic complexity <= true path count <= static path count

    Static path count is one of the three standard metrics used by QAC for demographic analysis.

    [6] Nejmeh, B.A. (1988), NPATH: A Measure of Execution Path Complexity and its Applications, Comm ACM, 31, (2), p. 188-200.

    RET - Number of Return Points in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    RET is the count of the reachable return statements in the function, plus one if there exists a reachable implicit return at the } that terminates the function.

    The following example shows an implicit return:

    
        void foo( int x, int y )
        {
            printf( "x=%d, y=%d\n", x, y );
            /* Here with implicit return. Hence RET = 1*/
        }
    

    Structured Programming requires that every function should have exactly one entry and one exit. This is indicated by a RET value of 1. RET is useful when the programmer wants to concentrate on the functions that do not follow the Structured Programming paradigm. For example, those with switch statements with returns in many or every branch.

    ST1 - Number of Statements in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    ST2 - Number of Statements in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    ST3 - Number of Statements in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    STx - Number of Statements in Function Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metrics

    These metrics count the number of statements in the function body. There are 3 variants on the metric:

    ST1 is the base definition and counts all statements tabulated below.
    ST2 is ST1 except block, empty statements and labels are not counted.
    ST3 is ST2 except declarations are not counted.

    The following chart shows the statements counted by the STST metrics:

    Statement KindST1ST2ST3
    blockyesignoreignore
    simple statement followed by ;yesyesyes
    empty statementyesignoreignore
    declaration statementyesyesignore
    labelyesignoreignore
    breakyesyesyes
    continueyesyesyes
    doyesyesyes
    foryesyesyes
    gotoyesyesyes
    ifyesyesyes
    returnyesyesyes
    switchyesyesyes
    whileyesyesyes

    The following example shows statements counted by ST1, which for this function yields a value of 10:

    
        void stst( void )
        {
            int i;          /* 1 */
        label_1:            /* 2 */
        label_2:            /* 3 */
            switch ( 1 )    /* 4 */
            {               /* 5 */
            case 0:         /* 6 */
            case 1:         /* 7 */
            case 2:         /* 8 */
            default:        /* 9 */
                break;      /* 10 */
            }
        }
    

    This metric indicates the maintainability of the function. Number of statements also correlates with most of the metrics defined by Halstead. The greater the number of statements contained in a function, the greater the number of operands and operators, and hence the greater the effort required to understand the function. Functions with high statement counts should be limited. Restructuring into smaller sub-functions is often appropriate.

    SUB - Number of Function Calls Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    The number of function calls within a function. Functions with a large number of function calls are more difficult to understand because their functionality is spread across several components. Note that the calculation of SUB is based on the number of function calls and not the number of distinct functions that are called, see CAL.

    A large SUB value may be an indication of poor design; for example, a calling tree that spreads too rapidly.
    See Brandl (1990)[7] for a discussion of design complexity and how it is highlighted by the shape of the calling tree.

    The following code example has an SUB value of 4.

    
        extern dothis(int);
        extern dothat(int);
        extern dotheother(int);
    
        void test()
        {
            int a, b;
            a = 1;
            b = 0;
    
            if (a == 1)
            {
                dothis(a);                  /* 1 */
            } else
            {
                dothat(a);                  /* 2 */
            }
            if (b == 1)
            {
                dothis(b);                  /* 3 */
            } else
            {
                dotheother(b);              /* 4 */
            }
        }
    

    [7] Brandl, D.L. (1990), Quality Measures in Design, ACM Sigsoft Software Engineering Notes, vol 15, 1.

    UNR - Number of Unreachable Statements Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the count of all statements within the function body that are guaranteed never to be executed. UNR uses the same method for identifying statements as metric ST1. Hence UNR counts the following as statements if unreachable.

    Statement Kind Counted
    block
    simple statement followed by ;
    empty statement
    declaration statement
    label
    break
    continue
    do
    for
    goto
    if
    return
    switch
    while

    Example yielding UNR = 4

    
    void stunr( unsigned i )
    {
        if ( i >= 0 )
        {
            if ( i >= 0 )
            {
                while ( i >= 0 )
                    return;
            } else
            /* unreachable */
            {
                while ( i >= 0 )
                    return;
            }
        }
        return; /* unreachable */
    }
    

    UNV - Unused or Non-Reused Variables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    An unused variable is one that has been defined but which is never referenced. A non-reused variable is a variable that has a value by assignment but which is never used subsequently.

    Such variables are generally clutter and are often evidence of 'software ageing', which is the effect of a number of programmers making changes. The code below has an UNV value of 2.

    
        int other_result;
        extern int result;
    
        int test()
        {
            int y;                      /* Unused */
            int z;
    
            z = 1;                      /* Non-Reused */
    
            return (result + other_result);
        }
    

    XLN - Number of Executable Lines Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Function-Based Metric

    This is a count of lines in a function body that have code tokens. Comments, braces, and all tokens of declarations are not treated as code tokens. The function below has an XLN value of 9.

    
        void fn( int n )
        {
            int x;
            int y;
    
            if ( x )                        /* 1 */
            {
                x++;                        /* 2 */
                for (;;)                    /* 3 */
                    /* Ignore comments */
                    /* Ignore braces */
                {
                    switch ( n )            /* 4 */
                    {
                        case 1 : break;     /* 5 */
                        case 2 :            /* 6 */
                        case 3 :            /* 7 */
                            break           /* 8 */
                                    ;       /* 9 */
                    }
                }
            }
        }
    

    This metric is used in the computation of the KDN and PDN metrics.

    File-Based Metrics Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    BMO - Organic Programmer Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    BMS - Semi-detached Programmer Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    BME - Embedded Programmer Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metrics

    The COCOMO metrics are produced for each source code file. You can display an estimate of development costs for a whole project by choosing the COCOMO Cost Model option from the Reports menu. See Chapter 6: Reports for a discussion of the COCOMO cost model and an explanation of the three programming modes: Organic, Semi-detached, and Embedded.

    These metrics estimate the number of programmer-months required to create the source code in the respective environments.

    BME = 3.6 * ( TPP / 1000 ) 1.20
    BMO = 2.4 * ( TPP / 1000 ) 1.05
    BMS = 3.0 * ( TPP / 1000 ) 1.12

    BUG - Residual Bugs (token-based estimate) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    BUG = 0.001 * EFF2/3

    This is an estimate of the number of bugs in the file, based on the number of estimated tokens. Its value would normally be lower than the sum of the function-based PBG values. For a more detailed discussion of software bug estimates, see Hatton and Hopkins,[8].

    [8] Hatton, L., Hopkins, T.R., (1989) Experiences With Flint, a Software Metrication Tool for Fortran 77, Symposium on Software Tools, Napier Polytechnic, Edinburgh, Scotland.

    CDN - Comment to Code Ratio Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is defined to be the number of visible characters in comments, divided by the number of visible characters outside comments. Comment delimiters are ignored. Whitespace characters in strings are treated as visible characters.

    A large value of CDN indicates that there may be too many comments, which can make a module difficult to read. A small value indicates that there may not be enough comments, which can make a module difficult to understand.

    The code below has 28 visible characters in comments and 33 visible characters in the code. The resulting CDN value is 0.85.

    
        int test()
        /* This is a test */
        {
            int x;
            int y;
        /* This is another test */
            return (x + y);
        }
    

    The value of CDN is affected by how QAC counts the comments. QAC can count comments in three possible ways:

    • all comments, (a),
    • all comments except for those from headers, (n),
    • inline or internal comments (i). These are comments within functions and comments that annotate a line of code (comments that are on the same line as code at file scope).

    DEV - Estimated Development (programmer-days) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is an estimate of the number of programmer days required to develop the source file. Unlike COCOMO statistics, which are based solely on the number of lines of code, this estimate is derived from the file's difficulty factor. It is a more accurate measure of the development time, especially after the scaling factor has been adjusted for a particular software environment.

    DEV = EFF / dev_scaling

    where dev_scaling is a scaling factor defined in qac.cfg. The default is 6000.

    DIF - Program Difficulty Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is a measure of the difficulty of a translation unit. An average C program has a difficulty of around 12. Anything significantly above this has a rich vocabulary and is potentially difficult to understand.

    DIF = VOL / ( (2 + VAR) * log2 (2 + VAR) )

    ECT - Number of External Variables Declared Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is a measure of the number of data objects (not including functions) declared with external linkage. It is an indication of the amount of global data being passed between modules. It is always desirable to reduce dependence on global data to a minimum.

    
        extern int result;
        int other_result;
    
        main()
        {
            result = 20 + 30;
            other_result = result * 2;
        }
    

    The above code sample has an ECT value of 2.

    EFF - Programmer Effort Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a measure of the programmer effort involved in the production of a translation unit. It is used to produce a development time estimate.

    EFF = VOL * DIF

    FNC - Number of Functions in File Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a count of the number of function definitions in the file.

    FCO - Estimated Function Coupling Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    See Brandl[9]. Since the actual value of Brandl's metric requires a full, well-structured calling tree, FCO can only be an estimate. A high figure indicates a large change of complexity between levels of the calling tree. The metric is computed from FNC and the SUB values of the component functions in the translation unit:

    FCO = ∑(SUB) - FNC + 1

    The code example below has an FCO value of 1 (2 - 2 + 1).

    
        BOOL isActive(CHANNEL c);
    
        BOOL okToRead(TEXTCHANNEL c)
        {
            return !isActive(c);
        }
    
        BOOL okToPrint(PRINTCHANNEL c)
        {
            return !isActive(c);
        }
    
    [9] Brandl, D.L. (1990), Quality Measures in Design, ACM Sigsoft Software Engineering Notes, vol 15, 1.

    HAL - Halstead Prediction of TOT Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric and also ZIP are predictions derived from the vocabulary analysis metrics OPN and OPT of what the value of TOT should be. If they differ from TOT by more than a factor of 2, it is an indication of an unusual vocabulary. This usually means that either the source code contains sections of rather repetitive code or it has an unusually rich vocabulary. The two metrics are computed as follows:

    ZIP = ( OPN + OPT ) * ( 0.5772 + ln (OPN + OPT) )
    HAL = OPT * log2 ( OPT ) + OPN * log2 ( OPN )

    M20 - Number of Operand Occurrences Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the number of operands in a software component and is one of the Halstead vocabulary analysis metrics. Halstead considered that a component is a series of tokens that can be defined as either operators or operands.

    Unlike OPN, this metric is the count of every instance of an operand in a file, regardless of whether or not it is distinct. OPN only counts the operands that are distinct. The code example below has a M20 value of 8.

    
        void f( int a )             /* 1,2 -> f, a  */
        {
            if ( a > 1 )            /* 3,4 -> a, 1  */
            {
                ++a;                /* 5 -> a       */
                while ( a > 1 )     /* 6,7 -> a, 1  */
                {
                    --a;            /* 8 -> a       */
                }
            }
        }
    

    M21 - Number of Operator Occurrences Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the number of operators in a software component and is one of the Halstead vocabulary analysis metrics. Halstead considered that a component is a series of tokens that can be defined as either operators or

    operands.

    Unlike OPT, this metric is the count of every instance of an operator in a file, regardless of whether or not it is distinct. OPT only counts the operators that are distinct. The code example below has a M21 value of 22.

    
        void f( int a )             /* 1,2,3,4 -> void, (, int, )       */
        {                           /* 5 -> {                           */
            if ( a > 1)             /* 6,7,8,9 -> if, (, >, )           */
            {                       /* 10 ->{                           */
                ++a;                /* 11,12 -> ++, ;                   */
                while (a > 1)       /* 13,14,15,16 -> while, (, >, )    */
                {                   /* 17 -> {                          */
                    --a;            /* 18,19 -> --, ;                   */
                }                   /* 20 -> }                          */
            }                       /* 21 -> }                          */
        }                           /* 22 -> }                          */
    

    M22 - Number of Statements Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the number of statements in a software component. This is a count of semicolons in a file except for the following instances:

    • within for expressions,
    • within struct or union declarations/definitions,
    • within comments,
    • within literals,
    • within preprocessor directives,
    • within old-style C function parameter lists.

    The code example below has a M22 value of 5.

    
        void f( int a )
        {
            struct { int i;
                     int j; }
                ij;                 /* 1    */
            a = 1;                  /* 2    */
            a = 1; a = 2;           /* 3,4  */
            if
                ( a >
                        1 )
            {
                return;             /* 5    */
            }
        }
    

    M28 - Number of Non-Header Comments Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a count of the occurrences of C or C++ style comments in a source file except for those that are within the header of a file. A file header is defined as tokens preceeding the first code token or preprocessor directive token.

    M28 is based on the method used to compute CDN but differs from CDN in that CDN counts the visible characters within comments, whereas M28 counts the occurrences of comments. The code example below has a M28 value of 2.

    
        /* Header comment 1             Count = 0 */
        /* Header comment 2             Count = 0 */
    
        /* Last header comment          Count = 0
           code follows */
    
        #define CENT 100
    
        /* Non header comment           Count = 1 */
        void f( int a )
        {
            /* Block scope comment      Count = 2 */
            a = CENT;
            return;
        }
    

    M33 - Number of Internal Comments Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a count of C style or C++ comments in a source file that are within functions or annotate a line of code at file scope. Comments within functions are all comments at block scope. Comments that annotate code are ones that start or end on the same line as code.

    M33 is based on the method used to compute CDN but differs from CDN in that CDN counts the visible characters within comments, whereas M33 counts the occurrences of comments. The code example below has a M33 value of 5.

    
        /* Header comment 1         Count = 0 */
        /* Header comment 2         Count = 0 */
    
        /* Last header comment      Count = 0
           code follows */
    
        #define CENT 100    /* Annotating comment   M33 = 1 */
    
        int                 /* Annotating comment   M33 = 2 */
            i;
        /* Annotating comment M33 = 3 */ int j; /*
           Annotating comment M33 = 4 */
        /* Non internal comment                     M33 = 0 */
        void f( int a )
        {
            /* Block scope comment                  M33 = 5 */
            a = CENT;
            return;
        }
    

    OPN - Number of Distinct Operands Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is the number of distinct operands used in the file. Distinct operands are defined as unique identifiers and each occurrence of a literal.

    Most literals, except 0 and 1, are usually distinct within a program. Since macros are usually used for fixed success and failure values (such as TRUE and FALSE), the differences in counting strategies are fairly minimal. The code below has an OPN value of 11.

    
        extern int result;              /* 1 -> result */
        static int other_result;        /* 2 -> other_result */
    
        main()                          /* 3 -> main */
        {
            int x;                      /* 4 -> x */
            int y;                      /* 5 -> y */
            int z;                      /* 6 -> z */
    
            x = 45;                     /* 7 -> 45 */
            y = 45;                     /* 8 -> 45 */
            z = 1;                      /* 9 -> 1 */
            result = 1;                 /* 10 -> 1 */
            other_result = 0;           /* 11 -> 0 */
    
            return (x + other_result);
        }
    

    OPT - Number of Distinct Operators Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This covers any source code tokens not supplied by the user, such as keywords, operators, and punctuation. OPT is used in the calculation of a number of other metrics.

    The code below has an OPT value of 11.

    
        extern int result;              /* 1,2,3 -> extern, int, ; */
        static int other_result;        /* 4 -> static */
    
        main()                          /* 5,6 -> ()*/
        {                               /* 7 -> { */
            int x;
            int y;
            int z;
    
            x = 45;                     /* 8 -> = */
            y = 45;
            z = 1;
            result = 1;
            other_result = 0;
    
            return (x + other_result);  /* 9,10 -> return, + */
        }                               /* 11 -> } */
    

    SCT - Number of Static Variables Declared Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is computed as the number of variables and functions declared static at file scope. The code example below has an SCT value of 2.

    
        static int other_result;                /* 1 */
        int result;
    
        static int test()                       /* 2 */
        {
            int x;
            int y;
            int z;
    
            z = 1;
    
            return (x + other_result);
        }
    

    SHN - Shannon Information Content Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    Also known as the "entropy" H, this metric is a widely recognized algorithm for estimating the program space required to encode the functions in a source file. SHN is measured in bits and is calculated as follows:

    SHN = ZIP * log2 (√(OPN + OPT) + ln (OPN + OPT))

    TDE - Embedded Total Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    TDO - Organic Total Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    TDS - Semi-detached Total Months Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metrics

    The COCOMO metrics are produced for each source code file. You can display an accurate estimate of development costs for a whole project by choosing the COCOMO Cost Model option from the Reports menu. Refer to Chapter 6: Reports for a discussion of the COCOMO cost model and an explanation of the three programming modes: Organic, Semi-detached, and Embedded.

    These metrics are a measure of elapsed time in months required to develop the source code in the respective environments.

    TDE = 2.5 * BME 0.32
    TDO = 2.5 * BMO 0.38
    TDS = 2.5 * BMS 0.35

    TLN - Total Preprocessed Code Lines Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a count of the total amount of lines in the translation unit after pre-processing. The pre-processed file will reflect the processing of include files, pre-processor directives and the stripping of comment lines.

    TOT - Total Number of Tokens Used Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the total number of tokens, not distinct tokens, in the source file. The code example below has an TOT value of 19.

    
        int test()                  /* 1,2,3,4 */
        {                           /* 5 */
            int x;                  /* 6,7,8
            int y;                  /* 9,10,11 */
            /*Excluded Comment*/
            return (x + y);         /* 12,13,14,15,16,17,18 */
        }                           /* 19 */
    

    TPP - Total Unpreprocessed Code Lines Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is a count of the total number of source lines in the file before pre-processing.

    VAR - Total Number of Variables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    The metric represents the total number of distinct identifiers. The code below has an VAR value of 5.

    
        int other_result;           /* 1 */
        extern int result;          /* 2 */
    
        int test()                  /* 3 */
        {
            int x;                  /* 4 */
            int y;                  /* 5 */
    
            return (x + y + other_result);
        }
    

    VOL - Program Volume Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This is a measure of the number of bits required for a uniform binary encoding of the program text. It is used to calculate various Halstead vocabulary metrics.

    The following is the calculation for the program volume:

    VOL = TOT * log 2 ( OPN + OPT )

    ZIP - Zipf Prediction of TOT Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    ZIP = ( OPN + OPT ) * ( 0.5772 + ln (OPN + OPT) )

    See HAL.

    CCA - Total Number of Characters Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the total number of characters in the file. Only visible characters are counted, except in string or character literals, in which case all characters are counted and tabs are treated as one character. When counting comment characters, the comment delimiter characters are counted.

    CCB - Total Number of Code Characters Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Function-Based Metric

    This metric is the total number of code characters in the file. Only visible characters are counted, except in string or character literals, in which case all characters are counted and tabs are treated as one character. Characters comprising comments are not counted, this includes the comment delimiter characters.

    CCC - Total Number of Comment Characters Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Function-Based Metric

    This metric is the total number of visible comment characters in the file. The comment delimiter characters are not counted.

    Project-Wide Metrics Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    NRA - Number of Recursions Across Project Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Project-Wide Metric

    This metric is defined to be the number of recursive paths in the call graph of the project's functions. A recursive path can be for one or more functions. The minimum, and often desirable, value of this metric is zero. Values greater than zero indicate the number of distinct loops in the call graph.

    NEA - Number of Entry points Across Project Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Project-Wide Metric

    This metric is the number of functions that are not called in the project. It is the number of nodes in the call graph which are not themselves called. For example, main() is not called; hence the minimum (target) value of 1.

    NFA - Number of Functions Across Project Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Project-Wide Metric

    This metric is the number of function definitions in the project. Note that this metric is the sum of QAC's FNC metric values for each source file included in the project.

    CYA - Cyclomatic Complexity Across Project Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Project-Wide Metric

    This metric is the sum of cyclomatic complexity values for each function definition in the project. Note that this metric is the sum of QAC CYC metric values for each source file included in the project.

    Class-Based Metrics Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    CBO - Coupling between objects Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Class-Based Metric

    This is a count of the number of methods (member functions) or member objects of other classes accessed by a class. Only classes outside the inheritance hierarchy are considered because you would expect interaction with base and derived classes. Coupling to classes outside the inheritance tree should be viewed with suspicion as it makes the class less independent and less re-usable. This is one of Chidamber & Kemerer's[10] suite of object oriented metrics.

    [10] Chidamber, S.R. and Kemerer, C.F. (1991). Towards a Metrics Suite for Object Oriented Design, Proceedings of OOPSLA, '91, Sigplan notices, vol.26, no. 11, ACM Press.

    DIT - Deepest level of inheritance Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    This represents the number of derivations from the furthest base class down to this class. A high figure may indicate that the class depends on accumulated functionality, which makes understanding the class potentially difficult. This is one of the metrics defined by Chidamber & Kemerer.

    LCM - Lack of cohesion of methods within a class Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    Methods within a class are partitioned into sets that access independent sets of member objects. The LCM metric is a count of sets of unrelated members for a type.

    For example (default):

    
        class cohesive
        {
        private:
            int i1;
            int i2;
            int i3;
        public:
            void m1(int a) { i1 = a + i2; }
            void m2(int a) { i2 = a; }
            void m3(int a) { if (a > i3) ++i3; }
        };
    

    This above code sample has a LCM value of 2 because methods m1 and m2 access the set of member objects i1 and i2. Method m3 accesses only i3 and can be viewed as independent of m1 and m2. (m3 is not cohesive with the other two methods).

    Similarly, where one method calls another, the set used for inclusion in LCM is the union of the sets from each method.

    Variations of the calculation of LCM may explicitly exclude constructors, so the default behavior of CMA is that constructors are excluded when calculating this metric. To include constructors, enable the configuration option "-ProdOption LCM::include_constructor".

    If constructors are included, and the constructor for such a type initializes all the members, then the value of LCM is guaranteed to be '1'.

    This is one of the metrics defined by Chidamber & Kemerer.

    MTH - Number of methods declared in class Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    The number of methods declared within a class. This does not include methods declared in base classes. Classes with a large number of methods will be difficult to understand.

    NOC - Number of immediate children Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    This is the number of classes for which this class is an immediate base class. A high figure for this metric indicates greater dependence on the functionality of this class, and more potential knock-on effects from changes to it. This is one of the metrics defined by Chidamber & Kemerer.

    NOP - Number of immediate parents Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    This metric indicates the number of inheritances for a class. Root base classes have a value of 0 while classes derived with a single inheritance have a value of 1. Classes that have multiple inheritance are prohibited by some programming standards.

    RFC - Response for class Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    Class-Based Metric

    This indicates how functions can potentially be called directly from the class. The response set is calculated as the number of distinct class methods and functions called from the definitions of those methods. This is one of the metrics defined by Chidamber & Kemerer.

    WMC - Weighted methods per class Bottom Doc. Button Top Document Button Down Section Button Up Section Button Blank Up Chapter Button

    Class-Based Metric

    This is the sum of cyclomatic complexities (See Cyclomatic complexity (CYC) in Function-Based Metrics section of this document) for all the methods in the class. In the same way that cyclomatic complexity gives an indication of the amount of testing required for an individual function, this metric gives an indication of the amount of testing required for a whole class. This is one of the metrics defined by Chidamber & Kemerer.

    General Bottom Doc. Button Top Document Button Down Section Button Up Section Button

    The Components of Function Structure Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

    Function structure diagrams show the control flow structures within source code. Decisions (if, switch, and the condition part of a loop) are displayed as forks in the structure. The corresponding join, further to the right, indicates where the paths rejoin. Backward arcs, caused by loops, are shown as dotted lines.

    The function structure diagrams show the following code structures:

    • straight code
    • if
    • if else
    • switch
    • while loop
    • for loop
    • nested structures
    • break in a loop
    • return in a loop
    • continue in a loop
    • unreachable code

    Each component progresses from the left to the right as the control flow would progress through the source code.

    Straight code Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcStraight( void)
        {
            code = 1;
        }
    

    There is only one path through this particular function, which is represented as lying along the x-axis.

    If Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcIf( void)
        {
            if (code > 0)
            {
                code = 1;
            }
        }
    

    This function has two paths. The first path is through the if statement and is shown by the raised line. The second path is where the if condition is false and is represented by the x-axis.

    If-Else Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcIfElse( void)
        {
            if (code > 0)
            {
                code = 3;
            } else
            {
                code = 4;
            }
        }
    

    This function has two execution paths. The first path is the if sub-statement represented by the raised line. The second path is the else sub-statement represented by the x-axis.

    Note that the body of this structure is longer than the body of the if statement. If the two arms of the if-else were not straight line code, the body of the if branch would appear at the left hand end of the raised line and the body of the else branch would appear to the right of the lower line.

    Switch Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

        static int code = 0;
    
        void funcSwitch( void)
        {
            switch (code)
            {
            case 1:
                if (code == 1)
                {
                    /* block of code */
                }
                break;
            case 2:
                break;
            case 3:
                if (code == 3)
                {
                    /* block of code */
                }
                break;
            default:
                break;
            }
        }
    

    In the switch statement, the x-axis represents the default action, and each case statement is shown by a raised line. The two briefly raised lines represent the if statements within case 1 and case 3.

    The diagram shows how the if statements are staggered. The if of case 1 is shown on the left and the if of case 3 is shown on the right.

    While loop Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcWhile( void)
        {
            while (code > 0)
            {
                --code;
            }
        }
    

    In the while loop, the x-axis represents the path straight through the function as though the while loop had not been executed. The solid raised line shows the path of the while body. The dotted line shows the loop to the beginning of the while statement.

    For loop Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
        void doSomethingWith(int);
    
        void funcFor( void)
        {
            int i;
            for (i = 0; i > code; ++i)
            {
                doSomethingWith( i);
            }
        }
    

    The for loop is similar to the while loop as for loops can be rewritten as while loops. For example, funcFor in the above example could be written as:

    
        void funcFor( void)
        {
            int i = 0;
            while (i > code)
            {
                /* body */
                ++i;
            }
        }
    

    Nested Structures Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcWhileIfElse( void)
        {
            while (code > 0)
            {
                if (code == 1)
                {
                    code = 0;
                } else
                {
                    code--;
                }
            }
        }
    

    This is an if-else contained within a while loop. The first solid raised line represents the while loop while the inner raised solid line represents the if-else loop. Other function structure components can be similarly nested.

    Break in a loop Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcWhileIfBreak( void)
        {
            while (code > 0)
            {
                if (code == 3)
                {
                    break;
                }
                code--;
            }
            if (code == 0)
            {
                code++;
            }
        }
    

    The break jumps to the end of the while statement and causes a knot. A knot is where the control flow crosses the boundary of another statement block and indicates unstructured code. In this case, break jumps to the end of the while statement and the next part of the program, the if statement, is executed.

    Return in a loop Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
    
        void funcWhileIfReturn( void)
        {
            while (code > 0)
            {
                if (code == 3)
                {
                    return;
                }
                code--;
            }
            if (code == 0)
            {
                code++;
            }
        }
    

    The return statement causes the program to jump to the end of the function. This jump breaks the control flow and causes a knot in the code.

    Continue in a loop Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

    
        static int code = 0;
        void funcWhileIfContinue( void)
        {
            while (code > 0)
            {
                if (code == 3)
                {
                    continue;
                }
                code--;
            }
            if (code == 0)
            {
                code++;
            }
        }
    

    The continue statement causes the program to jump back to the beginning of the while loop.

    Unreachable code Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

    
        static void funcUnReach( int i)
        {
            if (i)
            {
                i = 1;
            }
    
            goto Bad;
    
    if (i) { i = 2; }
    Bad: if (i) { i = 3; } return; }

    The raised red section represents code that is unreachable.

    The structure and approximate position of the unreachable code is shown. It occurs after the first if condition and before the last if condition. Its position above the main structure shows that the control flow misses the middle if condition.


     All Manual Pages