Procedures
The project
For the explanation below a 'Hello world' implementation is used as example:
- SystemName: HelloWorld
- Targets: 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 [xxx]' shortcut.
A command-line window is opened
- 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):
gbssetup → 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 Root)
- Select: 'Create in User's GBSWA (~/GBSWA)'
- Enter: 'New Root Dir': 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-Root needs at least one Target so GBS will now proceed to execute an implicit
'swt --new' to create a Target for the System
- Enter mingw (Windows) or gnuc (Linux) with 'Enter new Target-name []:'
- Select: 'Create a Reference to a Target Plugin'
- Select Plugin:
'mingw: MINGW: GNU C/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_REL and GBSEXT_MINGW_PATH
- Linux:
GBSEXT_LGNU_GCC_ROOT, GBSEXT_LGNU_GCC_REL and GBSEXT_LGNU_GCC_PATH
- Save the file!
- Back to the GBS window: Confirm 'Press <ENTER> to continue . . '
The Target is now created in the current System and made current.
- Enter: swr .' to effectuate the edited switch.gbs
If you get 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)
- Enter: swr .
- 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 the '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 'Add another Component'. Reply with 'n'
The Component is created in the current SubSystem and made current.
We will now proceed to create a file in the current Compionent 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):
gbssetup → 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 'slash_star_main.c' 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 Target-environment (if necessary)
Try to compile the file with gbsgen hello.c
It should compile, but if it fails that is probably because the GBSEXT_ EnvVars are not properly set:
- 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 .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
Repeat until no more errors:
- Enter: gbsgen hello.c
- Edit hello.c and save
Note: You need not be in the src directory when you execute a gbsgen.
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 (probably already in src)
- 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)
- Enter: cdtarget
This places you in the output-directory for gbsgen.
Link and run the .glk file
- Enter: gbsgen hello.glk
- Stay in the bld-Target directory (with cdtarget)
- Enter: hello.exe (Windows) or
./hello.e (Linux) to run the executable
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 cdtarget.
- Do your edits
- Build all with gbsgen .:*.*
Not with gbsgen *.*'.
That will cause Unix globbing
to take the files in the current (Target) directory.
- Run the executable
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 GUI)
Generate in the Batch
- Enter: gbssysgen
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 gbssysgen 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 Target
The previously defined Target will generate our FINAL (non-debug) version.
But we also want a DEBUG version:
- Enter: swt --new
- Enter mingwd (Windows) or gnucd (Linux) with 'Enter new Target-name []:'
- Select: 'Create a Reference to a Target Plugin'
- Select Plugin:
'mingw: MINGW: GNU C/C++' (Windows) or
'lgnu_gcc: LGNU_GCC: GNU C' (Linux)
- Confirm 'OK? (y/n/q)[y]:'
- Negate 'Do you want to edit switch.gbs now?:' (no changes in switch.gbs necessary)'
The new Target is created and will be equal to mingw/gnuc ('FINAL').
So we will have to set it to 'DEBUG'
Note that it is now also the Current Target.
- Set the current Target to 'DEBUG':
Enter: gbsedit target.gbs.
Confirm file creation.
- 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 Target.
- Save the file!
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
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 gbssysgen .
- Wait for OK completion
- cd ../bld/<target>
- Run the generated executable
Interfacing with the outside-world
System (Root)
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.
Copyright © Randy Marques of Randy Marques Consultancy - All rights reserved
|