HOME Generic Build Support (GBS) - User Manual
Create a GBS-WA/System

Description

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

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

Before you start

Install GBS

Read:

Prepare

After Install it really helps if you have read:

If you get stuck, read:

The project

For the explanation below a 'Hello world' implementation is used as example:

SystemName: HelloWorld
Builds: Linux: gnuc and gnucd. Windows: mingw and mingwd
SubSystem: main
Component: hello

Linux: We will be using the native C/C++ compiler toolchain
Windows: We will be using the MinGW toolchain

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.

Startup GBS

DoubleClick the 'GBS Startup [xxx]' shortcut.
A command-line window is opened and you are presented a list of possible GBS commands.
Enter: gbsbash if you are in Windows CMD and want to use GBS in a WSL bash environment.
Enter: gbs
Answer the questions if it is the first time.

Setup Editor

Now is a good time to setup your editor if you have not yet done so. (Not required):
gbssettings → Change Profile settings → General Settings
More info: Define your own editor

Creating the GBS-WA

Make sure your 'Site' is defined in GBS

Enter: swr --new
(switch System)
- Select: 'Create in User's GBSWA (~/GBSWA)'
- Enter: 'New System Parent': HelloWorld
- Confirm create
- Confirm 'Enter New System Name [HelloWorld]:' with <enter>
- Select: 'No_SCMS'
- Confirm 'OK? (y/n/q)[y]:' with <enter>
An empty System is now created and made current.

A GBS-System needs at least one Build so GBS will now proceed to execute an implicit 'swb --new' to create a Build for the System
- Enter mingw (Windows) or gnuc (Linux) with 'Enter new Build-name []:'
- Select: 'Associate with an existing Build Plugin'
- Select Plugin:
  'mingw_cpp: MINGW: GNU C' (Windows) or
  'lgnu_gcc: LGNU_GCC: GNU C' (Linux)
- Confirm 'OK? (y/n/q)[y]:'
- Confirm 'Do you want to edit switch.gbs now?:'
  - In the editor-window find all occurrences of the missing EnvVars (3-4 lines), uncomment and possibly adjust.
    - Windows:
      - GBSEXT_MINGW_ROOT
        -
      - GBSEXT_MINGW_BASE_REL
      - GBSEXT_MINGW_GCC_PATH
      - GBSEXT_MINGW_GCC_REL
    - Linux:
      - GBSEXT_LGNU_GCC_ROOT
        -
      - GBSEXT_LGNU_GCC_REL
      - GBSEXT_LGNU_GCC_PATH
  - Save the file!
- Back to the GBS window: Confirm 'Press <ENTER> to continue . . '
The Build is now created in the current System and made current.
- Enter: swr .' to effectuate the edited switch.gbs
If you got errors (from the execution of switch.gbs) you will have to fix switch.gbs.
- If the switch.gbs is not still open in an editor, start the edit with 'gbsedit switch.gbs'.
  Note that gbsedit knows where the switch.gbs file resides and that it ends with .bat (Windows) or .sh (Linux)
- Find and fix problem(s) with the GBSEXT_... EnvVars
- Save the file (keep editor open)
- Repeat until all errors solved.
Optionally enter gbs to see what you have achieved

We will now proceed to create a SubSystem in the current System.

Creating a Subsystem

Enter: sws --new
(switch SubSystem)
- Enter the name of the New Subsystem: main
- Select: SubSystem type: 'GBS' (default)
- Keep confirming (defaults) till you get 'Summary for new SubSys ...'
- Confirm: 'OK? (y/n/q)[y]:'
The SubSystem is created in the current System and made current.

We will now proceed to create a Component in the current SubSystem.

Creating a Component

Enter: swc --new
(switch Component)
- Enter the name of the New Component: hello
- Keep confirming (defaults) till you get 'Summary for new Component ...'
The Component is created in the current SubSystem and made current.

We will now proceed to create a file in the current Component and compile it.

Getting one file to compile

Setup Editor

If you have not setup your own editor, now is really the time to do so. (But you do not have to):
gbssettings → Change Profile settings → General Settings
More info: Define your own editor

Create and edit the file

Now we create the file:

Make sure you are in the src directory
If not: Enter: cdsrc
Enter: gbsedit hello.c
Enter 'y' when asked 'Create? (y/n/q)[y]:'
Select Template-File 'main_slash_star.c' (4) when asked
The file is created in the src directory and opened in your editor
Edit the file to implement the 'hello world' application
and save the file (keep open in editor)

Adjust the Build-environment (if necessary)

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

Enter: gbswhich to get an overview of building (and auditing)
Note the src_types on top
And the GBSEXT_ Paths, which should reflect the Plugin you selected
Enter: gbswhich build .c to get information on .c -files processing
Note: In gbswhich: an 'x' before a PATH means that it was not found
Edit the switch.gbs, fix, swr . and try again.

Compile the file

Enter: gbsbuild hello.c
Repeat until no more errors:

Edit hello.c and save
Enter: gbsbuild hello.c

Note: You need not be in the src directory when you execute a gbsbuild.
We will now proceed to create the executable

Where am I?

At any time you can enter gbs on the commandline. It will show you all currencies.

Creating the executable

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

Create the .glk file

Enter: cdsrc
Enter: gbsedit src:hello.glk
'y' to create the file
- Immediately below the main banner enter:
  hello$GBS_BLD_C
- Save the file
  Note: During processing the $GBS_BLD_C will be replaced by the resulting file-type of a C compilation for this platform (.obj or .o)
'cd' to the current bld/$GBS_BUILD directory:
Enter: cdbld
For Windows Enter: cd mingw (The current Build)
For Linux Enter: cd gnuc (The current Build)
This places you in the output-directory for gbsbuild.

Link and run the .glk file

Enter: gbsbuild hello.glk
Stay in the bld/Build directory
Run the executable:
For Windows Enter: hello.exe
For Linux Enter: ./hello.e

Note that all files in GBS must have a type. Hence .e for Linux
The .e can be removed when exporting the file with gbsexport.
If you need to change stuff:
- Stay in the bld/Build directory.
- Do your edits
- Build all with gbsbuild .:*.*
  Not with gbsbuild *.*'. That will cause UNIX globbing to take the files in the current (Build) directory.
- Run the executable

Creating automated testing

For testing we need a .glt file in the src directory

Create the .glt file

Stay in the bld/Build directory
Enter: gbsedit src:hello.glt
'y' to create the file
- Immediately below the main banner enter:
  hello$GBS_BLD_GLK
- Save the file
  Note: During processing the $GBS_BLD_GLK will be replaced by the resulting file-type of a .glk (linking) operation for this platform (.exe or .e)

Run the .glt file

Enter: gbsbuild hello.glt
'cd' to the bld/$GBS_BUILD directory
Enter: cdbld
Enter: cd GBS_BUILD
This places you in the output-directory for gbsbuild.
The output of the test is placed in hello.log

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

Enter: gbsedit export.gbs
As we can have various types of export.gbs files we must specify which. The default (Component) is what we want.
Add the following lines:
Windows:
```
FOO
    bld/$GBS_BUILD/hello$GBS_BLD_GLK
```
Linux:
```
FOO
    bld/$GBS_BUILD/hello$GBS_BLD_GLK            hello|ug+x
```
The hello at the end of the line renames the file (removes the .e)
The |ug+x chmods the file (Just an example. Not realy needed)
Beware: No spaces before FOO and at least one space before bld/$GBS...
Notes:
The $GBS_BUILD specifies the current Build
The $GBS_BLD_GLK specified the output-type of the .glk gbsbuild. (i.e.: .exe (Windows) or .e (Linux)

Export the file

Enter: gbsexport
Enter: cdexport and see what has happened.
- You may want to do this with a Navigator (Enter:gbsnav)

Generate in the Batch

Enter: gbssysbuild
A batch job is started.
When it is done, a Notify popup-box will appear.
In the popup-box Select: (click) 'View Log & Exit'
View the logfile

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

Enter: gbssilo
A page is generated in your browser
Select: 'gbsssysbuild (.log)' under 'GBS Log Overviews'
Select: VIEW of the Logfile you want to view

Adding a Build (Debug)

The previously defined Build will generate our FINAL (non-debug) version.
But we also want a DEBUG version:

Enter: swb --new
- Enter mingwd (Windows) or gnucd (Linux) with 'Enter new Build-name []:'
- Select: 'Refer to an existing Build'
- Select Build:
  'mingw' (Windows) or
  'gnuc' (Linux)
- Confirm 'OK? (y/n/q)[y]:'
The new Build is created and will be (almost) equal to mingw/gnuc ('FINAL').
So we will have to set it to 'DEBUG'
Note that it is now also the Current Build.
Set the current Build to 'DEBUG':
Enter: gbsedit build.gbs.
- Change MODE into DEBUG
- Change DEBUGGER into YES
- Change OPT into DEBUG
- Save the file!
We do not want to export the DEBUG version so we have to edit the export.gbs:
Enter: gbsedit export.gbs
Select 'Component'
- Append FOO with a few TABs and then '== mingw' or '== gnuc'
  This will cause the destination-line and the following source-lines to be executed only for the mingw/gnuc Build.
- Save the file!
- Test with gbsexport

It is done now. You can generate single stuff for a single Build with gbsbuild and use swb to switch Builds.
Enter: gbssysbuild and observe how the system is generated for both Builds in parallel.

Creating a non-GBS SubSystem

Create a 'make' Subsystem

Enter: sws --new
(switch SubSystem)
- Enter the name of the New Subsystem: make_ss
- Select: SubSystem type: 'make'
- Keep confirming (defaults) till you get 'Create App Sub directories (app/src, app/inc...'
- Enter 'y'
- Confirm: 'Summary for new SubSys ...'
The SubSystem is created with a standard Makefile.mk in SubSys directory.
cd to app/src with cd app and then cd src
Create a 'main.c' file with gbsedit main.c
The file is created in the current subsys/app/src directory
Edit the makefile with gbsedit Makefile.mk
The uppercase 'M' makes it a GBS makefile and takes it from the SubSys directory.
Run the makefile with gbssysbuild .
Wait for OK completion
cd ../bld/<build>
Run the generated executable

Try the GUI

Enter: gbsgui
If it does not startup properly, try: gbsgui --t
Have fun

Interfacing with the outside-world

System

switch.gbs(.bat/.sh)

This file resides in the $GBS_SYSTEM_PATH directory.
It is a script that is executed every time GBS makes a System 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 System have been set.

The file consists of two parts:

The SITE part
Here you define the GBSEXT_plugin_ROOT Envvars to define the locations of your plugins.
They may vary per Site (PC/Location).
Then REL/PATH part.
Here you define the GBSEXT_plugin_REL and GBSEXT_plugin_PATH EnvVars using the abovementioned Roots This is - of course - fixed per System.

Because the SITE part is always the same on a specific PC you can also put your Root definitions in a central file called site.gbs

Generic Build Support (GBS) - User Manual - Create a GBS-WA/System

create_system.html

Contents

Description

Before you start

Install GBS

Prepare

The project

Startup GBS

Setup Editor

Creating the GBS-WA

Creating a Subsystem

Creating a Component

Getting one file to compile

Setup Editor

Create and edit the file

Adjust the Build-environment (if necessary)

Compile the file

Where am I?

Creating the executable

Create the .glk file

Link and run the .glk file

Creating automated testing

Create the .glt file

Run the .glt file

Exporting the executable

Create export.gbs file

Export the file

Generate in the Batch

Adding a Build (Debug)

Creating a non-GBS SubSystem

Create a 'make' Subsystem

Try the GUI

Interfacing with the outside-world

System

switch.gbs(.bat/.sh)