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.
Creating the GBS-WA
Make sure your 'Site' is defined in GBS
- Enter:
swr --add
(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 root is now created.
A GBS-Root needs at least one Target so GBS will now proceed to execute an implicit
'swt --new'
- 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 lines), uncomment and
possibly adjust.
- Save the file!
- Back to the GBS window: Confirm 'Press <ENTER> to continue . . '
The Target is now created.
- 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
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.
We will now proceed to create a Component
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.
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:
- Enter gbssetup
- Select: '2. General Settings (Beeps, Editor, ...)'
- Change the Beeps if you whish
- Change the Editor
- Enter 'e' (end) with 'Change? (y/n/e/q)[n]:'
- Enter empty line in the main-menu (0. Exit)
- Enter 'y' with '*** Implement Changes? (y/n)[n]:'
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 a Template-File ending with 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
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 (.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 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 the 'Summary for new SubSys ...'
- Confirm: 'OK? (y/n/q)[y]:'
The SubSystem is created.
- cd to app/src
- Create a 'main.c' file with 'gbsedit main.c'
- Edit the makefile with 'gbsedit Makefile.mk'
- Run the makefile with 'gbssysgen .'
- 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
|