GBS Logo GBS DEV HELP HOME Generic Build Support (GBS)
GBS Development Documentation Bottom Doc. Button Blank Blank Blank

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

  1. Welcome
  2. Install
  3. The Directory Structure
  4. The Code Structure
  5. Special Files and Directories
  6. Generating Deliverables
  7. Tools
  8. Design Considerations
  9. FAQ
  10. Release Notes

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

Welcome to the wonderful world of GBS internals, you daredevil!
This document describes how to maintain GBS.

Note that development and execution directories are the same.
So you can edit and execute immediately.

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

Prerequistes

Unzip the Install-file

After the Install

You are now ready to go.

The build.dat file

If for some reason the 'Version' (Line 3) in your build.dat still ends with '?', you must edit it.
The build.dat file resides in the main directory.

Edit line 3: Version.
The format is Project-RR.VV(-patch) where:

The Perl regular expression is: /^[A-Z_]+-\d\d\.\d\d(|-\w+)$/

The Directory Structure Bottom Doc. Button Top Document Button Down Section Button Up Section Button

GBS DEV

The 'GBS DEV' directory

This the Top directory.

It has a space in its name on purpose.
Regrettably Windows often has spaces in paths.
This makes sure that the code will always run with one or more spaces in the Root path.

It contains the major GBS directories and a few files:

The 'build' directory

Contains 2 directories: gbs and dev
They contain the primary results of the buildgbs and builddev commands.
They form the basis of the created GBS Zip files.

The 'export' directory

Contains 2 directories: gbs and dev
They contain the final results (.zip files) of the buildgbs and builddev commands.
Each directory also contains a Release directory.
Here the actually released .zip files are copied to.

The 'WA' directory

Is actualy the GBS_SCRIPTS_ROOT for development.
It contains:

The 'main' directory

Besides all the directories to generate GBS it also contains the toplevel code files.
E.g.: the .sh, .bat and .pl files.
It also contains the build.dat and development.dat files which will be explained later.

The 'cpan, func, glo, gui, Install, gbsglo and setup' directories

These contain the actual code and will be explained later

The 'devdoc' directory

Contains the Development Documentation
E.g.: This document

Not delivered with GBS-export

The 'doc' directory

Contains the 'sources' for genhelp which generates and checks the Help files.
Results go to the doc directory.

Not delivered with GBS-export

The 'doc' directory

Contains the results of genhelp. Sub-direcories are images, pdfs and scripts.

The files in this directory should not be under source-control

The 'plugins' directory

Contains the code for the various plugins.
TBS

The 'StandAlone' directory

Contains 'standalone' functions like wordrep, pgrep, etc.
They are fully independed of GBS

The 'STUBS' directory

Contains 'dummy' code that is used for SCA simulation and could be used for non-SCA Audit, Build and Tools simulation

Not delivered with GBS-export

The 'templates' directory

Contains the file-templates for gbsedit

The 'Tools' directory

Contains the tools to manage GBS development

Not delivered with GBS-export

The 'win32utils' directory

Contains a set of Unix (Linux) tools for Windows. Like grep, find, sed, etc

The Code Structure Bottom Doc. Button Top Document Button Down Section Button Up Section Button

This chapter is about the main, cpan, func, glo, gui, Install, gbsglo and setup directories. They contain the actual GBS code.

Scoping

The GBS code adheres to strict scope control.
Basically:
    main → gui → func → gbsglo → glo + cpan (→ PerlLibs)
    Install → func → gbsglo → glo + cpan (→ PerlLibs)
    setup (→ PerlLibs)
Examples:

main

This is the toplevel.
Contains scripts and toplevel (.pl) files.
No modules (.pm files) reside here.

gui

Contains GBS GUI specific modules

func

Contains GBS specific funcionality modules

gbsglo

Contains GBS specific general modules

glo

This is the lowest level.
Contains non-GBS specific modules.

The lowest level module is env.pm which contains basic functions like trace, dump, try, string manipulation, etc.
It is 'used' by (almost) all files and modules.
You want to be very familiar with this file!

cpan

Contains modules copied from CPAN
Only used by corresponding modules in glo.

Install

Contains 2 subdirectories:

The contents is copied to top of ZipFile during buildgbs and builddev

setup

Contains MAIN scripts and icons for GBS startup.
Subdirectory subs contains sub scripts and programs for the MAIN scripts.

Copied to GBS_BOOT_PATH during GBS Setup and when executing gbssettings 4

Special Files and Directories Bottom Doc. Button Top Document Button Down Section Button Up Section Button

build.dat

Resides in main
It defines the application (GBS), current Version, current Version Date and a long name for the Application.
For compatibility reasons its name or layout may never be changed.
No comment lines!

Note that in pre 5.01 versions there were two extra lines (6 & 7) containing licensing information.

build.dat example

GBS

PROJ-06.02
2023-08-12
Generic Build Support

development.dat

Resides in main
It defines:

development.dat example

Note that not all specified files/directories will be in the delivered ZIP 
#
#   Development.dat
#
gbs-exclude-dirs
    .svn
    devdoc
    doc
    Install
    MOCKS
    MyStuff
    SCM
    STUBS
    Test
    tmp
    Tools
    util
    WebTools
gbs-exclude-files
    batchfix.dat
    development.dat
    test_cond_use.pl
    Thumbs.db
help-exclude-dirs
    .svn
    devdoc
    doc
    glo
    MOCKS
    MyStuff
    plugins
    SCM
    setup
    STUBS
    Test
    tmp
    Tools
    util
    WebTools
help-exclude-commands
    DevInstall.pl
    gbsguiinit.pl
    gbsnew.pl
dev-exclude-dirs
    .svn
    MyStuff
    Test
    tmp
    WebTools
dev-exclude-files
    ActionList.xlsx
    HowTo.docx
    Thumbs.db

The GBS_BOOT directory

This directory is the 'starting-point' for GBS.
From here all other GBS directories can be found.
Hence a fixed location on all platforms:

Note that it is hidden directory.
It is identified by the EnvVar GBS_BOOT_PATH
It is created during the first setup of GBS

It contains: All files needed to startup GBS
No data is kept here. No need to backup.

There is one special file: bootstrap.bat or bootstrap.sh
It contains a single line that defines an EnvVar for the GBS_BASE directory (see next chapter)
Default:

The GBS_BASE directory

This directory contains the basic data files for running GBS
It is found via the bootstrap.bat or bootstrap.sh file in the GBS_BOOT directory (see previous chapter)
You can change the location with the gbsmanage 7 command.
You definitely want to backup this directory. That is why it is separated from the GBS_BOOT directory.

It is identified by the EnvVar GBS_BASE_PATH
It is created during the first setup of GBS.

Some of the files it contains follow:

profile.bat/.sh

This file contains EnvVar settings as you can define and change with:
gbssettings 1 (Change Profile Settings)

Most importantly it contains the definitions of GBS_SCRIPTS_ROOT, GBS_SCRIPTS_REL and the combination of the former: GBS_SCRIPTS_PATH.
So when GBS is started it finds:

Presto!

Other settings in profile.(sh|bat):

Values can be set and changed with gbssettings 1

config.ini

This file contains internal settings as you can define and change with gbssettings 2 (Change Config Settings)

Settings in config.ini:

Values can be set and changed with gbssettings 2

Generating Deliverables Bottom Doc. Button Top Document Button Down Section Button Up Section Button

On-the-fly testing

The GBS Development environment contains all the ingredients of 'build' so you can test immediately after you change something.
It is good practice to run the following tools so now and then to make sure that you are still on track. (Full explanation in 'Tools' section)

Do not forget to update the help files in case of relevant changes and update the release Notes.

Preparing for Release

Step by step: All in one command:

Releasing

After all of the above:

New Version or Release

Release and Version are identified by PROJ-RR.VV (Previously R.VV was allowed)
Both R and V must be numbers. E.g: 06.01.
Version may be postfixed with a patch or beta indication. E.g.: PROJ-RR.VV-beta

New Version

A new Version is required if the execution of Upgrade in gbsmaint 7 9 is required because of a minor change in the user directory structure (directories and/or files). Also in case a development version was downloaded from the GBS SourceForgs page.

New Release

A new Release is required if the execution of Upgrade in gbsmaint 7 9 is required because of a major change in the user directory structure and/or commands.
Backwards compatibility may be questionable.

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

Type toolsman to get overview of GBS development tools

All commands accept --h and --help as parameter

Windows and Linux

buildgbs

'build' a GBS version and create export ZIP-file (Needs Perl Package Archive::Zip)

builddev

'build' a GBS Development WorkArea and create export ZIP-file (Needs Perl Package Archive::Zip)

cleanup

Removes trailing spaces and optimises leading spaces with Tabs

exportgbs

Performs all the generation steps for a complete build of GBS and GBSDEV:
Terminates if an error occured.

genhelp

Generates the help files from the docgen directory to the doc directory

perlchange

Run the temporary perlchange.pl for automated changes in the GBS code. Caution!
This is just a wrapper for any one-time action you would like to perform on the code.

perlcheck

General checks for Perl files

perlcritic

Static Analysis for Perl files according to the O'Reilly book: Perl Best Practices

perlxref

Creates cross references for Perl files. External Functions and 'use'.

testall

Runs all perl scripts and shell scripts with argument --help

Windows

batchfix

Fixes the file-format for batch-files (.bat and .sh)

copy_mocks

Copy output-files from the current Root to the MOCKS directory in the same root

Linux

None

Design Considerations Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Main requisites

Choice of Language

GBS is written in Perl.
I needed a language that will execute exactly the same on various computers (at that time Windows and UNIX), without being depended on installed libraries, etc.
When I started developing GBS in 2001 the best choice was Perl.
Should I start developing now I would probably chose Python. (But there is nothing wrong with Perl!)

Background

One of the main requisites of GBS is that it must be fast.
Hence command-line interface and no frills.

GBS runs on the command-line. So when you are in command-line you are not 'inside' GBS.
This ensures that you have the full potential of the command-line at your disposal.
GBS keeps track by means of Environment Variables (EnvVars), all starting with 'GBS_'
Every time you enter a GBS command, the Perl code is loaded, precompiled and executed (interpreted).

Most PerlLib modules are re-implemented in GBS.
This is because the PerlLib modules are large (and slightly slower) because they cater for most Operating Systems and often do not offer the required functionality or too much functionality.
This also ensures constant functionality as in the past functionality was changed between Perl releases.
We want to keep the footprint of the resulting 'executable' as small as reasonably possible.

Since the start of GBS (2001) a lot has changed in Perl. Not all nice new features (like autoload) were implemented. Who knows in the future.
There are also be some odd things that cannot be changed for historical reasons and choices made in the past.
I.e.: build.gbs was originally called target.gbs (for target-stream), controlled my module build.pm. This conflicts with the name of build.dat, which cannot be changed. Hence build.dat is controlled by module version.pm

Object oriented approach

The code is basically Object Oriented but without blessing.

All GBS data-files are controlled by a module of the same name.
E.g.: audit.gbs is controlled by audit.pm.

Windows AND Linux

The requirement to run under both Windows and Linux poses a number of restrictions:

Communicating with the user

Messages to the user are always prefixed with:

You must use the following functions for User I/O:

They allow redirection to and from other devices, like a GUI window.
The output functions also take care of window width (wrapping).
The ASK_... functions guarantee a standard look-and-feel for user input

Debugging

You may want to look at the following functions:

Errors and Condition Handling

You may want to look at the following functions:

Command arguments

All command arguments are handled by one of the two packages:

Paths

GBS works with paths in Perl (Unix) format and are case-sensitive.
As soon as a path 'enters' GBS it is converted to Perl format (Windows only).
The functions ENV_getenv and ENV_setenv consider EnvVars ending with _PATH, _ROOT or _CMD to be paths and will automatically do the proper conversions.
E.g.: my $this_perl_path = ENV_getenv( $GBS_SCRIPTS_PATH);
It remains so until it has to 'exit' GBS (E.g.: execute a shell command). Then it is converted to a different variable prefixed with os_.
E.g.: my $os_this_path = ENV_os_path( $this_path);

Nomenclature

Naming Conventions

System Global Variables

Between execution of GBS commands, information is maintained in Environment Variables (EnvVars).
They are full uppercase and start with GBS_.

When a GBS command starts, it will read all the GBS EnvVars and place them in System Global Variables, all starting with GBS::
So GBS_SCRIPTS_PATH goes to GBS::SCRIPTS_PATH.
These EnvVars are controlled by the gbsglo::gbs_pre.pm and gbsglo::gbs.pm packages.

When a GBS command starts, glo::env.pm will also define some basic system globals:

A few are copied to $GBS::...

There are also some constants defined in glo::scm.pm:

Some GBS commands change these EnvVars.
So at the end of the execution of a command, the changed EnvVars are written to a batchfile that is executed after the Perl code exits, updating the EnvVars in the command-line environment.
You are not allowed to change a System Global Variable directly. You must use the GBSENV_setenv function in gbsglo::gbsenv.pm.
The function controlling the export to a batch file is RESULT_write_script.

Coding and Style Standard

The code adheres to the GBS Coding and Style Standard

About TABs and SPACEs

The GBS sources use the physical TAB character (HT, X09).
The physical TAB character is interpreted as modulo 8.
This is the standard interpretation as used by most tools and the command line of most OS.
Something different is how the pressing of the TAB key is interpreted.
On OS command-lines it often invokes auto-completion.
In Editors it usually invokes indentation, often modulo 4 spaces
It is not wise to change the interpretatiom of the TAB character to anything other than 8: You will have to change all tools and even the OS if you want to keep your layout when using commands like more, type or cat.
Proper modern editors will allow definition of hard-tabs (do notchange) and soft-tabs (indentation - set as you please).
Some even allow definition of 'intelli-tabs' creating a proper mix of TABs and SPACEs.

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

TBS

Release Notes Bottom Doc. Button Top Document Button Down Section Button Up Section Button

Build RMC-06.02: 2024-04-29

New/Changed Functionality

  1. Brand new. So none

Problems solved

  1. Brand new. So none

Generic Build Support (GBS) - GBS Development Documentation Blank Top Document Button
GBS_Development.html
Copyright 2021 © Randy Marques, Netherlands