GBS Logo






Release 4.00
(2015-03-10)








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


GBS User Guide -- Home

GBS Logo Generic Build Support (GBS) - User Manual HOME
GBS User Guide - Home
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

The power of GBS lies in its concept.
This means that in order for you to use GBS you must understand the concept and use GBS 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

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

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

Documentation

General

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

GBS FAQ
Frequently Asked Questions

Installation Notes

Unix and Windows

Quick Start

GBS Logo Generic Build Support (GBS) - User Manual HOME
Quick Start
Environment| Install| Setup| Startup| Getting Started| Commands

Environment

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

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

To setup GBS:
If setup was not started by Install: When in gbssetup: What happens on Windows: What happens on Unix/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

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

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

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

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

Release Notes

GBS Logo Generic Build Support (GBS) - User Manual HOME
GBS Release Notes

Release Notes for GBS 4.00

Interface changes since 3.01

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: 2015-03-10

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 Satistics 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

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

Interface changes since 3.00

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

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

Build 3.00: 2014-03-18

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 prorcessing 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

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

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


Install Notes

GBS Logo Generic Build Support (GBS) - User Manual HOME
Install Notes
Environment| Install| Setup|

Environment

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

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

General

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

FAQ

GBS Logo Generic Build Support (GBS) - User Manual HOME
FAQ - Frequently Asked Questions

Index

How to create a new Component

Enter :
swc --new

How to create a new SubSystem

Enter :
sws --new

How to create a new System (Root)

Enter :
swr --new

How to add an existing System (Root) to my Systems (Roots) list

Enter :
swr --add

How to remove a System (Root) from my Systems (Roots) list

Enter :
swr --remove

Terms and Conditions (The Fine Print)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Terms and Conditions
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.

Definitions & Acronyms

GBS Logo Generic Build Support (GBS) - User Manual HOME
Definitions & Acronyms

Definitions

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 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

cadenv

A centrally controlled set of version-controlled repositories for general software like QAC, Perl, nedit, Continuus, etc…, as used at various Philips development-sites

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

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
 

Introduction

GBS Logo Generic Build Support (GBS) - User Manual HOME
Introduction
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

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.

Top Level Directory Structure

GBS Logo Generic Build Support (GBS) - User Manual HOME
Top Level Directory Structure
The rigid and strict nature of the GBS directory structure allows interchange ability between Systems and SubSystems.
GBS will generate the directory-structure automatically making sure all directories are properly named and added to any specified SCM System.

General overview

For the build process three areas can be distinguished:
The 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

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

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 like 'cadenv'.

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

Full Directory Structure

GBS Logo Generic Build Support (GBS) - User Manual HOME
Full Directory Structure
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

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

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

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)

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.

Handling SubSystems & Steps

GBS Logo Generic Build Support (GBS) - User Manual HOME
Handling SubSystems & Steps

SubSystems

GBS recognises a numer 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 treedirectly 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 to change to the wanted functionality.

Steps

By default SubStems 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-SubSytem 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.

Procedures

GBS Logo Generic Build Support (GBS) - User Manual HOME
Procedures
In this section the essentials of some GBS procedures are described.
This is in no way a specification, final document or manual.
It shows the basic idea of what is possible in GBS.

Start-up the GBS environment

The 'gbs' command sets up the GBS environment.
The first time it is called, it will prompt the user for things like System Root directory and a SubSystem name. This information is remembered between logins.
Four main Environment Variables are defined:
These Environment Variables form the basics of the GBS build-environment.
All GBS actions involve the currencies as indicated by these Environment Variables.
GBS maintains the contents of these variables.
Never change these Environment Variables yourself. Use the GBS commands to do that.

Navigating the directory structure

GBS is based on a system of currencies: current-Root, current-SubSystem, current-Component, and current-Target. Whenever you make another Root, SubSystem, Component or Target current (switch) the appropriate Environment Variables are set accordingly.
Targets are always current for a whole Root.

Switch Root (System)

To switch to another Root (System) enter:
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

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

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

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

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

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)

For building a library, a 'glb-file' acts as the 'src' representative for the 'bld' library.
The glb-file contains a list of all object-files that will make up the library.
The glb-file also gives a name to the library. E.g.:
name.glb → name.lib
Using the rules as mentioned above, a script generates the library-build command needed to create the library, taking the object-files as specified in the glb-file.
A #include statement allows grouping of object-file-names. The search-path is the same as for other #includes
Note that the glb-file may also contain specific archiver options.
More info: glb/glk/glt Files and Generating Code

Linking

For linking, a 'glk-file' acts as the 'src' representative for the 'bld' executable.
The glk-file contains a list of all objects and libraries that will make up the executable.
The glk-file also gives a name to the executable. E.g.:
name.glk → name.exe
Using the rules as mentioned above, a script generates the link command needed to link the executable, taking the object-files as specified in the glk-file.
A #include statement allows grouping of file-names. The search-path is the same as for other #includes
Note that the glk-file may also contain linker-options like -L.
More info: glb/glk/glt Files and Generating Code

Testing

For (unit-)testing, a 'glt-file' acts as the 'src' representative for the test.
The glt-file contains the command-line with the name of the test-executable. Results go to a log-file in the 'bld'
The glt-file also gives a name to the log-file. E.g.:
name.glt → name.log
Using the rules as mentioned above, a script generates the test command needed to run the executable, taking the executable name as specified in the glt-file.
Note that the glt-file may also contain execution options
More info: glb/glk/glt Files and Generating Code

Generation by means of 'make'

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

Typical commands are:
gbsmakemake

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

Each Component has an optional export.gbs file in the Component-directory.
It specifies for each file in the Component that has to be exported, to which export directory it has to be exported, relative to the 'export'-directory and/or the 'res/SubSystem'-directory.
The command is:
gbsexport

Target-streams

Code may be generated for more than one target: Simulator testing and one or more target platforms.
Sometimes a single source-file generates for more than one target
A sequence of compilations for a specific target, with a specific compiler using the same set of compile-options, possibly followed by linking, resulting in a set of deliverables is called a stream or target-stream.
A total generation of the software-system requires the generation of all streams.
Streams can run in parallel and can so reduce generation throughput time.

Builders and File-types

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

Software Configuration Management Support

GBS Logo Generic Build Support (GBS) - User Manual HOME
Software Configuration Management Support

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

Combining an SCMS with GBS

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

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

Create a GBS-WA/System

GBS Logo Generic Build Support (GBS) - User Manual HOME
Create a GBS-WA/System
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.

Before you start

Make sure you have read and understood the items as mentioned under "basics':
Have the following information ready at hand: See the sections below on how to decide on the names mentioned above.

Example

For the explanation below a 'Hello world' implementation is used as example: We will be using the MinGW environment under Windows.
You can obtain MinGW via SourceForge/MinGW
Be sure you install it in a Hard Versioned Directory e.g: C:\WinGW\2013072200.
You only need to install Basic Setup: mingw32-base for this exercise.

Creating the GBS-WA

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

Creating a Subsystem

We will now proceed to create a Component

Creating a Component

We will now proceed to create a file and compile it

Getting one file to compile

Setup Editor

You probably want to use your own editor:

Create and edit the file

Now we create the file:

Adjust the Target-environment

You can try to compile the file with gbsgen hello.c, but that will fail

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

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

Create the .glk file

Link the .glk file

We will now proceed to export the executable

Exporting the executable

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

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

Adding a Target

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

TBS

Interfacing with the outside-world

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.

The Command-Line Interface

GBS Logo Generic Build Support (GBS) - User Manual HOME
The Command-line Interface
GBS is controlled by command-lines in an X-term or DOS-box. Here is the general behaviour of the commands:

Entering Commands

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

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)

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

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

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

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

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

Messages

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).

All Commands

GBS Logo Generic Build Support (GBS) - User Manual HOME
All Commands
All commands have the format: command [args | gbs-options]...
gbs-options always start with: -- (hyphen hyphen)
General options (always 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)
  --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
agrep, bgpids, detab, egrep, filerep, fixeol, gbs, gbsaudit, gbsbldcheck, gbsedit, gbsexit, gbsexport, gbsgen, gbshelp, gbsinit, gbslocate, gbsmaint, gbsmake, gbsmakemake, gbsman, gbsscm, gbssetup, gbsshow, gbssilo, gbsstart, gbsstats, gbsswc, gbsswr, gbssws, gbsswt, gbssysaudit, gbssysgen, gbssysmake, gbswhich, gbsxref, grep, proto, swc, swr, sws, swt, tail, touch, win2unix, wordrep

bgpids (Non-GBS - Unix only)

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=

fixeol (Non-GBS)

Purpose:

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

Syntax:

fixeol files...

Semantics:

files string
array mandatory
Files to process
Default=

gbs

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

gbsinit (gbs - Before GBS is started )

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

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_*    

gbsbldcheck

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

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

Purpose:

Exit and cleanup the GBS environment

Syntax:

gbsexit

Semantics:

None

gbsexport

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- ]
[ --verbose | --verbose+ | --verbose- ]
[ 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
--verbose[+|-] verbose
boolean
scalar optional
Extensive messaging
Default=0

Environment Variables:

(GBS_) APP_*    

gbsgen

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

Purpose:

Present help on GBS in HTML browser

Syntax:

gbshelp

Semantics:

None

gbslocate

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

Purpose:

Allow user to execute General Maintenance functions
1. Audits Handling
2. Cleanup
3. Map Network Drives (unix<->win32)
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

Purpose:

'make' one or more files

Syntax:

gbsmake [ comp_file_opts ]...
[ --r | --r+ | --r- ]
[ --i | --i+ | --i- ]
[ --smm | --smm+ | --smm- ]
[ --export | --export+ | --export- ]
[ --mm | --mm+ | --mm- ]
[ --jobs=jobs ]
[ Environment_Variable=Value ]...

Semantics:

comp_file_opts string
array optional
bld files to make with 'make' options
Default=
--r[+|-] reverse_type
boolean
scalar optional
Specify source-types instead of build-types
Default=0
--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=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_*

gbsmakemake

Purpose:

Make make-file(s) for the current SubSystem

Syntax:

gbsmakemake [ components ]...
[ --i | --i+ | --i- ]

Semantics:

components string
array optional
. == current component, <empty> == all
Default=
--i[+|-] ignore_errors
boolean
scalar optional
Continue generation after error(s)
Default=0

gbsman

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

Syntax:

gbsman

Semantics:

None

gbssetup (gbssetup.bat or gbssetup.sh)

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

gbsshow (gbs)

Purpose:

Show GBS currencies

Syntax:

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

Semantics:

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

gbssilo

Purpose:

Generate silo index and show in HTML browser

Syntax:

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

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

gbssysaudit

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, '-' == NonSpecific
Default=-,*
--targets=targets string
array optional
(wild-)Targets to Audit. '' or '*' == All, '.' == Current, '-' == NonSpecific
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_*

gbssysgen

Purpose:

Generate part of or whole System

Syntax:

gbssysgen [ steps ]...
[ --i | --i+ | --i- ]
[ --mm | --mm+ | --mm- ]
[ --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
--targets=targets string
array optional
(wild-)Targets to Audit. '' or '*' == All, '.' == Current, '-' == NonSpecific
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_*    

gbssysmake

Purpose:

Generate part of or whole System using 'make'

Syntax:

gbssysmake [ steps ]...
[ --i | --i+ | --i- ]
[ --smm | --smm+ | --smm- ]
[ --mm | --mm+ | --mm- ]
[ --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
--targets=targets string
array optional
(wild-)Targets to Audit. '' or '*' == All, '.' == Current, '-' == NonSpecific
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_*    

gbsstart (%GBS_BASE_PATH%\gbsstart.bat or $GBS_BASE_PATH/gbsstart.sh)

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 ]
--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=.
--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:

Integration with other Tools

gbsstats

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)

Purpose:

Set and/or Create new Current Component

Syntax:

gbsswc [ 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)

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 [ root_path ] [ subsystem ] [ component ]
[ --target=target ]
[ --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=.
--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)

Purpose:

Set and/or Create new Current SubSystem

Syntax:

gbssws [ 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)

Purpose:

Set and/or Create new Current Target

Syntax:

gbsswt [ 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

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
file_type or Component or filename or SubDir/filename or */filename
Default=
search_type string
scalar optional
file_type to search
Default=

Environment Variables:

(GBS_) FLAGS_*    

gbsxref

Purpose:

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

Syntax:

gbsxref

Semantics:

None

grep agrep egrep, tail & touch (Non-GBS - Windows Only)

How any programmer can survive without 'grep' is beyond my understanding...
Gratefully copied from Karl M. Syring 's UnxUtils and delivered as part of GBS

Syntax and Help:

grep --help
egrep --help
agrep --help
tail --help
touch --help

proto (Non-GBS)

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)

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)

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)

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)

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)

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)

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)

Generating Code

GBS Logo Generic Build Support (GBS) - User Manual HOME
Generating Code

The difference between GBSGEN and GBSMAKE

gbsgen

gbsmake

Specifying Files in GBSGEN, GBSMAKE and GBSAUDIT

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)

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)

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)


Libraries & Executables and Testing

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

Archiving Object-files to Libraries

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

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

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.

Exporting Deliverables

GBS Logo Generic Build Support (GBS) - User Manual HOME
Exporting Deliverables

The gbsexport command

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.

Auditing

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

gbsaudit

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

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

QAC

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++

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

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:


The gbssys... Commands

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

gbssysgen, gbssysmake and gbssysaudit

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

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 $GBS_SYS_PATH/steps.gbs file.
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.

Customisations (Session)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Customisations (Session)
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 ment to temporary "try someting 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

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

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

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

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

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_withot_dot=values

Customisations (User)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Customisations (User)
GBS has a few user customisation possibilities.
Most are set by the gbssetup command
Index

Perl Directory (GBS_PERL_PATH)

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

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)

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)

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

Customisations (Admin)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Customisations (Admin)
These Customisation must only be set by the GBS Administrator!
Index

GBS Startup (gbsall)

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.
Eligble 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)

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)

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)

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)

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)

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)

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)

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)

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)

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"'

Integration with other Tools

GBS Logo Generic Build Support (GBS) - User Manual HOME
Integration with other Tools
It is possible to integrate the execution of certain GBS commands in development tooling like editors, IDEs and buildmanagers.
The command that makes this possible is gbsstart

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 Command

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: Most tools in this context 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: 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

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

Location:

TBS

Command definitions:

TBS

Notes:

None

Crimson Editor

Location:

ToolsConf.User Tools...

Command definitions:

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

Notes

MS Visual Studio

Location:

TBS

Command definitions:

TBS

Notes:

None

Plugins (Admin)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Plugins
Supported plugins.
GBS Administrator only!!
Index
Builds, Audits, Tools,

Build (gen) Plugins

Supported Build Plugins:

Audit Plugins

Supported Audit Plugins:

Tool Plugins

Doxygen

Purpose

Run Doxygen for all Full-GBS SubSystems

Install

In steps.gbs:
STEP doxygen    >doxygen/bin/doxygen.pl full
    EXEC        = SPECIFY
    TARGETS     = -
    AUDITS      = -

STEP doxygen_api >doxygen/bin/doxygen.pl api
    EXEC        = SPECIFY
    TARGETS     = -
    AUDITS      = -

Requires

Doxygen via GBSEXT_DOXYGEN_PATH
and optionally Dot (Graphviz) via PATH

Notes

Use gbssilo to view results


Copy_Export

Purpose

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

Install

In steps.gbs:

STEP 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
e.g.:
STEP copy_export >copy_export/bin/copy_export.pl superglo $GBS_TARGET D:/GBSSHARE/$GBS_TARGET

Requires

None

Notes

None

Environment Variables (EnvVars)

GBS Logo Generic Build Support (GBS) - User Manual HOME
Environment Variables (EnvVars)
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 functionaliy 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 EbvVar are prefixed by either GBS_, GBSEXT_ or GBSALLEXT_
Index

GBS_ EnvVars

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_PATH directory path Log Files Location More gbsinit gbssetup  
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 Curent Release/Build More gbsinit Predefined  
2 GBS GBS_EXEC_MODE INTERACTIVE FOREGROUND
BACKGROUND
Exeution 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 excution 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  
3 Root GBS_SYSTEM_NAME name Name of the System/Root More swr    
3 Root GBS_ROOT_PATH directory path Currrent 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 TBS  
3 Root GBS_TOOL_PLUGIN name Current Tool Plugin   swr TBS  
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 Oject 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

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

GBSEXT_... EnvVars define the location of external stuff (Plugins and External Data).
Usually 3 EnvVars are defined (Hard versioned directories):
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  

The GLKBT (glk/glb/glt) Files

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

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

General considerations:

Syntax

[ 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:

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:

None

Example of a glb file:

#======================================
#   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:

#======================================
#   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:

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

##EOF##


GBS Files - General

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

Usage

If a file exists with the same name and with extension .usr instead of .gbs then that file will be taken instead of the .gbs file.
Never, ever check-in a .usr file.

General Syntax

End-Of-Line Comments

The usage of End-Of-Line Comments can be enabled and disabled by means of the .eol_comment directive.
Enabling the EOL Comments slows down parsing and should therefore be enabled with care.
It works similar as C and C++ // comments.

Syntax:

line # comments

Semantics:

#
The # must be surrounded by at least 1 white-space on both sides
The # , any characters following the # and any whitespace preceding the # will be removed.
Possibly remaining empty line will be skipped

Example

ENABLE = AKI # "Akiyama's criterion"
results in:
ENABLE = AKI

target-line-selection

The target-line-selection mechanism allows lines to be skipped depending on the current Target.
This mechanism is not enabled for all .gbs files.

Syntax:

line operator wild-target-list

Semantics:

line
The line that will candidate for the selection
operator
== | !=
wild-target-list
The Target(s) for which the scope is valid (==) or not (!=)
Wildcards are honoured

Example

comp1:file.o      != gnu
Means: line will be skipped for Target gnu
comp2:file.o      = gnu
Means: line will be included only for Target gnu

Note

It is practice to align the Target selections to the right of the lines.

Directives

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

.plugin

Purpose:

To define the plugin.
The plugin-directory associated with the defined plugin will be added to a possible include-path.
It is used to find the plugin directory with .include

Syntax:

.plugin plugin_name

Semantics:

plugin_name
The plugin-directory must exist

.include

Purpose:

To include text from another .gbs file

Syntax:

.include gbs_file
.include "gbs_file"
.include <plugin_gbs_file>

Semantics:

gbs_file
Absolute filepath is not allowed
'../' is not allowed
The file must be a .gbs file
The search-path depends on the type of the .gbs file
plugin_gbs_file
Absolute filepath is not allowed
'../' is not allowed
The file must be a .gbs file
The file will be taken from the plugin directory as specified by the .plugin directive

.eol_comment

Purpose:

To enable/disable EOL (End-Of-Line) Comments

Syntax:

.eol_comment enable
.eol_comment disable

Semantics:

General
The state (enabled/disabled) is propagated through includes.
Each main file starts in the disabled state.

.targets

Purpose:

To exclude generation of SRC files depending on the current Target
Only for glkbt files

Syntax:

.targets[!]=wild-target-comma-list

Semantics:

General
glkbt files only
The directive must be the first item in the file (after comments)
The build step will not be executed if the condition is false. A dummy output file will be created.
This is useful when a build step (like testing) should not be executed for specific Targets
Note
This mechanism works very similar to the target-line-selection, except no spaces are allowed.

.exit

Purpose:

To prematurely exit from a (included) file

Syntax:

.exit

Semantics:

General
The rest of the file will be skipped
This may be useful when testing a setup of a file and you do not want to comment out the rest of the file
You will get a warning.

.end

Purpose:

To prematurely exit from a (included) file

Syntax:

.end

Semantics:

General
The rest of the file will be skipped
This may be useful when you want to add extensvie 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

  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

audit.gbs

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

Purpose

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

Please refer to .gbs files: General information

Additional for this file:

Contents

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

SETUP Definition

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

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

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 Lunix)
Must be specified after SET_W, SET_X & SET

SRC Definitions

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 inly 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
user_script
Search for in 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

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.
pre_condition
file_exists_condition | env_value_condition
The command will inly 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 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
    TBS
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

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

None

Examples of audit.gbs files:

File 1 (Basic reference)

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

##EOF##

File 2 (Full specification)

#========================================================
#   [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

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	    = $GBSEXT_QACPP_BIN_PATH/%QAC_EXEC% %GBS_INCS% %GBS_SYSINCS% %GBS_AUDIT_FLAGS% %GBS_SYSFLAGS% %GBS_FLAGS% %2 %GBS_QACPP_FLAGS% %* -outpath %4
    COMMAND	    = $GBSEXT_QACPP_BIN_PATH/pal qacpp %2 %GBS_PAL_FLAGS% -outpath %4
    COMMAND	    = 0,1-9,99; \
		      $GBSEXT_QACPP_BIN_PATH/errdsp qacpp %2 %GBS_ERRDSP_FLAGS% -outpath %4 -file %2%5

SUMMARY
    COMMAND = .scasum.pl

MAINT
    COMMAND = >qac/bin/prqamaint.pl QACPP


##EOF##

export.gbs

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

Purpose

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:

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

Please refer to .gbs files: General information

Additional for this file:

The combination of 1 destination-line flowed by a number of source-lines is called a destination-set.

Contents:

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:

Example of an export.gbs:

#===============================
#  [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:

#========================================================
#   [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###

flags_*.gbs

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

Purpose

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:

And will be read in the specified order, overriding possible values of a higher level.

General

Please refer to .gbs files: General information

Additional for this file:

Contents:

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:

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:

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


###EOF###

gbssub(.bat/.sh)

GBS Logo Generic Build Support (GBS) - User Manual HOME
The gbssub batch file

Purpose

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

Special considerations:

Calling

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

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

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:

None

Example of a gbssub.bat:

@ECHO OFF
::=============================================================================
::  [%SUBSYS%] gbssub.bat
::	Requires 1 parameter: action
::	Called to cleanup, gen, make or audit a non-GBS SubSystem
::	For 'MSVS' (MicroSoft Visual Studio) SubSystems
::=============================================================================
::
::  Currently in $GBS_ROOT_PATH/dev/$GBS_SUBSYS
::  Applicable EnvVars:
::      GBS_TARGET
::      GBS_AUDIT (for Audit only)
::
::  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_
::      GBS_SYSINCS_
::      GBS_INCS_
::
::      GBS_MSBUILD_CONFIG	if MODE==DEBUG: Debug. If MODE==FINAL: release. Else: Empty
::
::=============================================================================
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)
::

cd app

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:
    %GBSEXT_MSBUILD_PATH%\msbuild /m /property:Configuration=%GBS_MSBUILD_CONFIG% /target:Clean
    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:
    %GBSEXT_MSBUILD_PATH%\msbuild /m /property:Configuration=%GBS_MSBUILD_CONFIG%
    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:
    %GBSEXT_MSBUILD_PATH%\msbuild /m /property:Configuration=%GBS_MSBUILD_CONFIG%
    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:
    echo GBSSUB_: No audits for non-GBS SubSystems
    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:
    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:::


incs_*.gbs

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

Purpose

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

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

And will be read in reverse order.

General

Please refer to .gbs files: General information

Additional for this file:

Contents:

Syntax:

One directory per line.

Notes:

None

Example of a incs_*.gbs:

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

###EOF###

owners.gbs

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

Purpose

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:

This file will NOT be superseded by a .usr file

Example of a owners.gbs:


* 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



sca_*.gbs

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

Purpose

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

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

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

Please refer to .gbs files: General information

Additional for this file:

Contents:

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:

None

Example of a sca_*.gbs:

#========================================================
#   [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###


scope.gbs

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

Purpose

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

General

Please refer to .gbs files: General information

Additional for this file:

Contents:

Syntax:

component_name [ target-line-selection ]

Semantics:

component_name
The Component to included in the scope

Notes:

None

Example of a scope.gbs:

#========================================================
#   [OMS::test_no_unix:main]SCOPE.GBS
#========================================================
superglo
test_all                                = gnu

###EOF###

steps.gbs

GBS Logo Generic Build Support (GBS) - User Manual HOME
The steps.gbs file

Purpose

The steps.gbs file is located in the GBS_SYS_PATH directory is used to define the order and conditions in which SubSystems are generated or audited.

It is also possible to define non-SubSytem 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.

General

Please refer to .gbs files: General information

Additional for this file:

Definitions

STEP ALIAS

STEP-definition

Purpose:

To define the order in which SubSystems must be generated

Syntax:

STEP step_name
EXEC = SELECT | SPECIFY | ALLWAYS | FORCE
TARGETS = [ ! ] [ targets-list | - ]
AUDITS = [ ! ] [ audits-list | - ]
COMMAND = command [command_arguments...]

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 or Command
If the step_name is a SubSystem-name then it refers to that SubSystem.
Else, there must be a COMMAND 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 the SubSystem.
  These scripts are:
    gbssubgenbatch_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
ALLWAYS == Include this step even if not specified in command-line
FORCE == Never skip, Same as ALLWAYS, even if job fails.
TARGETS
Single, Optional
targets-list
Specifies the Targets for which the step must be executed.
Default == all Targets.
If the list is preceded by the optional '!' all non-specified Targets are assumed
A value of '-' specifies a non-specific Target
AUDITS
Single, Optional
audits-list
Specifies the Audits for which the step must be executed.
Default == all Audits.
If the list is preceded by the optional '!' all non-specified Audits are assumed
A value of '-' specifies a non-specific Audit
COMMAND
Single
May not be specified for SubSystem 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

ALIAS-definition

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
TARGET
Single, Optional
Specifies associated Target
STEPS
Single, Mandatory
steps-list
'-' (hyphen) may be used to specify 'from' - 'to' sequences

Notes:

None

Example of a steps.gbs:


#
#   STEPS.GBS
#

#
#   STEPS
#
STEP begin
    COMMAND     = @begin

STEP superglo

STEP bart
    TARGETS     = *

STEP non_gbs
    AUDITS      = ! *

STEP visualstudio
    AUDITS      = ! *

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

STEP prqa
    EXEC        = SPECIFY

STEP doxygen
    COMMAND     = >doxygen/bin/doxygen.pl full
    EXEC        = SPECIFY
    TARGETS     = -
    AUDITS	= -

STEP doxygen_api
    COMMAND     = >doxygen/bin/doxygen.pl api
    EXEC        = SPECIFY
    TARGETS     = -
    AUDITS	= -

#
#   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##


switch.gbs(.bat/.sh)

GBS Logo Generic Build Support (GBS) - User Manual HOME
The switch.gbs batch file

Purpose

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

In GBS the switch.gbs file is the only file allowed to contain absolute disk-addresses

General

Special considerations:

Calling

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

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

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

The file consists of two mayor parts:

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:

None

Example of a switch.gbs.bat:


@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:


#========================================
#   %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##

sys.gbs

GBS Logo Generic Build Support (GBS) - User Manual HOME
The sys.gbs file

Purpose

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

Please refer to .gbs files: General information

Additional for this file:

Definitions

VARIABLE EXCLUDE

VARIABLE-definition

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

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:

None

Example of a sys.gbs:

#
#   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##

system.gbs

GBS Logo Generic Build Support (GBS) - User Manual HOME
The system.gbs file

Purpose

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:

This file will NOT be superseded by a .usr file

Example of a system.gbs:


#
#   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###


target.gbs

GBS Logo Generic Build Support (GBS) - User Manual HOME
The target.gbs files

Purpose

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

Please refer to .gbs files: General information

Additional for this file:

Contents

SETUP definition
DEFAULTS definition
INIT definition
SRC definitions (multiple)
...

SETUP Definition

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

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

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

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 Lunix)
Must be specified after SET_W, SET_X & SET

SRC definition

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 inly 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 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:

None

Examples of target.gbs files:

File 1 (final target)

#========================================================
#   [mingw] target.gbs
#========================================================

SETUP
    NICE_NAME	= MinGW_cpp

INIT
    SET_W       = TEST => WIN32
    SET_X       = TEST => LUNIX
    SETPATH     = PATH => %GBSEXT_MINGW_CPP_PATH%\bin 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_PATH%\bin\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_PATH%\bin\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_PATH%\bin\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_PATH%\bin\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)

#========================================================
#   [mingwd] target.gbs
#========================================================
.plugin mingw_gcc

.include <target.gbs>

DEFAULTS
    MODE     = DEBUG
    DEBUGGER = YES
    OPT      = DEBUG

##EOF##


tool.gbs

GBS Logo Generic Build Support (GBS) - User Manual HOME
The tool.gbs files

Purpose

The tool.gbs files are located in the GBS_SYSTOOLS_PATH/tool directories and are used to define the particularities of a Tool.

General

Please refer to .gbs files: General information

Additional for this file:

Contents

INIT definition

INIT definition

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

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 Lunix)
Must be specified after SET_W, SET_X & SET

Notes:

None

Example of a tool.gbs:

#
#   TOOL.GBS
#   doxygen
#
.plugin doxygen

INIT
    SET = DOXY_BIN => %GBSEXT_DOXYGEN_PATH%/bin

##EOF##

 All Manual Pages