Release RMC-06.02
(2024-04-29)
|
Contents
Description
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
Startup GBS
- DoubleClick the 'GBS Startup [cur]' 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 Config settings →
Edit Editor
More info: Define your own editor
Use a different Terminal type
You may also want to use a different Terminal type.
gbssettings → Change Config settings →
Edit Terminal
More info: Use a different Terminal type
Creating the GBS-WA
Make sure your 'Site' is defined in GBS
- Enter: swr --new
(switch System)
- Select: 'Create in User's GBSWA (MyDocuments/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 created and made current.
We will now proceed to define a Build
Defining a Build
- Enter: swb --new
(switch Build)
- 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 to your situation E.g.: Location and/or version-number.
- 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 → Program 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' (2) 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)
Note: If you should not be in the current src directory you can also enter:
gbsedit src:hello.c
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 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
Windows: Enter: cd mingw
Linux : Enter: cd gnuc
This places you in the output-directory for gbsbuild.
- The output of the test is placed in
hello.log
Using 'make'
Until now we have used gbsbuild
to generate the code, specifying explicitly the file(s) we want to 'build'.
Of course GBS offers a 'make' facility ('incremental build', 'selective build', 'dependency build'):
gbsmake.
Before you run gbsmake
for the first time you have to run gbsmakemake
to create a Component and Build specific make-file.
Enter: gbsmakemake
If you get errors or warnings refer to: Generating Code.
You can proceed with the next step if there are only warnings, but the 'make' will not be safe.
Enter: gbsmake
If you have not done so, this is a good time to read Generating Code.
More info: Generating Libraries & Executables and Testing
We will now proceed to export the executable
Exporting the executable
For the Export we will need an
export.gbs file in the component.
We will assume that this executable is for a customer called FOO
Export the file
- Enter: gbsexport
- Enter: cdexport and see what has happened.
- You may want to do this with a Navigator
(Enter: gbsnav)
For more info: Exporting Deliverables
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
More info: The gbssys... commands
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!
- Build the stream:
Enter: gbsbuild .:*.*
- All files (*.*) of the current Component (.:)
- 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 cdapp and then cd src (note the space!)
- 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
You will need Perl Tkx installed.
- Enter: gbsgui
If it does not startup properly, try: gbsgui --t
- Have fun
Interfacing with the outside-world
System
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
|
HELP HOME
Generic Build Support (GBS) - User Manual