Release RMC-06.02
(2024-04-29)
Randy Marques, Netherlands
|
Thank you for using Generic Build Support (GBS), the generic build environment created by Randy Marques, Netherlands. Generic Build Support is a way of setting up a directory structure combined with generic scripts to accommodate Build Automation for almost any kind of software project. Building information is kept in dedicated files enabling automatic generation of make files, independent of platform or SCMS. The key aspect of GBS is the directory structure. Its strict[1] nature makes sure that everything has its place so that it can be easily retrieved and it is assured that any GBS command will run on any SubSystem created according to the GBS Directory Structure rules. This directory structure makes it possible to swap and/or share software between projects (interchange ability) and ensures an unified way of working. And yes: where needed there is all the freedom you need! You can run GBS parallel on Windows 10, Windows 10 WSL and Linux systems, sharing the same physical directory structure. GBS depends only on Perl (Version 5.16.3 or later, preferably with PerlTkx). No extra packages are required when using ActiveState Perl This version was developed on Windows 10 using Perl 5.16.3 from ActiveState (with PerlTkx) It was tested on Windows 10, Windows 10 WSL 1 and Ubuntu 22.04 - GNOME. (On VirtualBox 7.0) Many thanks to Martin Smiths of the Netherlands who did the beta-testing on Manjaro 18.04 - Xfce. Although not tested: There is no reason why GBS should not run on Unix or Windows 7 No clue if it works on Windows 11. For a simple project you can start using GBS quickly and keep in mind that everything has its place. I strongly suggest reading the 'Getting Started' part of the documentation. Following the instructions in Create a GBS-WA/System will quickly set you on track. The power of GBS lies in its concept. So on the long run this means that in order for you to use GBS to its full extent, you must understand the concept of GBS and use it as intended. Rest assured: it is very simple. Understand GBS by:
GBS is OpenSource under the MIT License and as such free to use:
Note: The free and OpenSource versions of GBS are not compatible with pre version 2.00 releases Before you start using GBS, please take a moment to read the Terms and Conditions
[1]
Strict really means that no deviations are allowed.
Important
This document is just what it is named. A User Manual. |
Contents
Description | ||
| cdlog | cd to the log directory as specified by GBS_LOG_PATH (or $HOME) | |
| cdsystem | cd to current System | |
| cddoc | cd to the doc of the current System | |
| cddev | cd to the dev of the current System | |
| cdext | cd to the ext of the current System | |
| cdres | cd to the res of the current System | |
| cdsys | cd to the sys of the current System | |
| cdsysbuild | cd to the sysbuild of the current System | |
| cdsysaudit | cd to the sysaudit of the current System | |
| cdsystool | cd to the systool of the current System | |
| cdsilo | cd to the silo of the current System | |
| cdtmp | cd to the tmp of the current System | |
| cdsub | cd to the current SubSystem directory | |
| cdbuild | cd to the build directory of the current SubSystem | |
| cdaudit | cd to the audit directory of the current SubSystem | |
| cdtool | cd to the tool directory of the current SubSystem | |
| cdcomp | cd to the comp of the current SubSystem | |
| cdimport | cd to the import of the current SubSystem | |
| cdexport | cd to the export of the current SubSystem | |
| cdapp | cd to the app directory of the current Non GBS SubSystem | |
| cdsrc | cd to the src directory of the current Component | |
| cdinc | cd to the inc directory of the current Component | |
| cdloc | cd to the loc directory of the current Component | |
| cdbld | cd to the bld directory of the current Component | |
| cdbuild | cd to the bld/Build directory of the current Component / Build | |
| cdaud | cd to the aud directory of the current Component | |
| cdopt | cd to the opt directory of the current Component | |
| cddat | cd to the dat directory of the current Component | |
| cdsav | cd to the sav directory of the current Component | |
Contents
Release Notes for GBS 6.00 |
Contents
Description |
Contents
Description |
Contents
General |
Description
|
Contents
Description |
| GBS | Generic Build Support | |
| RMC | Randy Marques Consultancy | |
| SCA | Source Code Analyser | |
| SCM | Software Configuration Management | |
| SCMS | Software Configuration Management System e.g. SubVersion, Git | |
| WA | Work Area | |
Description
The strict nature of the GBS directory structure allows interchange ability
between Systems and SubSystems. |
| - doc | for documentation at system-level |
Description
Reserved (fixed) directory names are specified in a blue background. |
Description
|
Contents
Description |
Description
|
| SCMS | Repository | Data | Data Type |
|---|---|---|---|
| SVN | URL | SCMS_ROOT | Informational |
| Git | None | SCMS_ROOT | Informational |
Description
|
| command --h | will give you short help | ||
| command --h option... | will give you short help on the specified option(s) | ||
| command --help | will give you more extensive help | ||
| command --help option... | will give you long help on the specified option(s) | ||
| --verbose[+|-] | Extensive logging messages if '' or '+' Always '+' in BATCH jobs (gbssys* commands) | ||
| --inc file | will take the contents of file file as if it were typed on the commandline. Empty lines and lines starting with '#' are ignored. Multiple occurrence and nesting is allowed. |
Components COMP1 and COMP2 contain basic functionality.
Install.bat,
_gbssetup.bat,
bgpids,
detab,
filerep,
fixeol,
gbs,
gbsaudit,
gbsbash,
gbsbg,
gbsbldcheck,
gbsbuild,
gbsdebug,
gbsedit,
gbsexit,
gbsexport,
gbsgui,
gbshelp,
gbsinit,
gbslocate,
gbsmaint,
gbsmake,
gbsmakemake,
gbsman,
gbsmanage,
gbsnav,
gbsscm,
gbssettings,
gbsshow,
gbssilo,
gbsstart,
gbsstart_here,
gbsstats,
gbssudo,
gbsswa,
gbsswb,
gbsswc,
gbsswr,
gbssws,
gbsswt,
gbssysall,
gbssysaudit,
gbssysbuild,
gbssysmake,
gbssystool,
gbswhich,
gbswsl,
gbsxref,
grep,
pgrep,
proto,
swa,
swb,
swc,
swr,
sws,
swt,
tail,
touch,
win2unix,
wordrep,
wsudo
<*>
| USERS string array optional | <empty> == current user Default= |
-a[+|-]
| do_all boolean scalar optional | Include all processes Default=0 |
-f[+|-]
| do_fg boolean scalar optional | Include parent (foreground) processes Default=0 |
-k=process_to_kill
| process_to_kill integer scalar optional | Kill specified process-tree Default= |
--nos[+|-]
| noswitch boolean scalar optional | Do not implicitly swr to current System Default=0 |
<*>
| comp_file_opts string array mandatory | src-files and AUDIT-options. ALL = *:*.* Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue auditing after error(s) Default=0 |
--stdout[+|-]
| show_stdout boolean scalar optional | Show errorlines (0 when not interactive) Default=1 |
--vs[+|-]
| view_sum boolean scalar optional | View summary at completion Default=1 |
--aud[+|-]
| run_audit boolean scalar optional | Run audit Default=1 |
--sum[+|-]
| run_summary boolean scalar optional | Create summary Default=1 |
--caller=caller
| caller string scalar optional choice: gbsaudit gbssysaudit | Internal use. Default=gbsaudit |
--threads=threads
| threads integer scalar optional range: 1..9 | Max. nr. parallel threads Default=2 |
| (GBS_) LOG_PATH | (GBS_) MODE | (GBS_) FLAGS_* |
| (GBS_) APP_* |
gbsbash
<*>
| subsystems string array optional | Specific SubSystems Default= |
--m=max_missing
| max_missing integer scalar optional | Cancel SubSys check after this many missing files Default=20 |
--builds=builds
| builds string array optional | (wild-)Builds to Build-Check. '' or '*' == All, '.' == Current Default= |
<*>
| menu_entries integer array optional greater: 0 | Menu entries for immediate execution Default= |
<1>
| selector string scalar optional choice: 1 2 show enable disable | Menu entry or show/enable/disable Default= |
<2>
| debug_name string scalar optional | Menu entry or EnvName to enable/disable Default= |
--app=application
| application string scalar optional choice: GBS TOOLS PRQA CPPTEST | Application to debug. E.g.: GBS TOOLS Default=GBS |
<1>
| basic_filespec string scalar mandatory | file, ./file, rel_filespec, filespec or subdir:file Default= |
<2>
| editor_opt string scalar optional | Editor option. e.g. Line-nr to jump to Default= |
--nco[+|-]
| no_checkout boolean scalar optional | By default files will also be added if non-exist Default=0 |
--quit[+|-]
| quit boolean scalar optional | Do not setup the basic GBS functions Default=0 |
--restart[+|-]
| restart boolean scalar optional | Restart GBS after exit Default=0 |
| --quit+ | AND | --restart+ |
<*>
| export_file_locations string array optional | <Component>... and/or SUBSYS: . == Current Component. <empty> == <all> Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--c[+|-]
| cleanup_all boolean scalar optional | Delete all, independent from build Default=0 |
--show[+|-]
| show_actions boolean scalar optional | Show all actions Default=0 |
| (GBS_) APP_* |
<*>
| comp_file_opts string array mandatory | src files to generate with 'generate' options. ALL = *:*.* Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation regardless of error(s) Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads Default=2 |
| (GBS_) DEBUGGER | (GBS_) MODE | (GBS_) OPT |
| (GBS_) MAP | (GBS_) FLAGS_* | (GBS_) APP_* |
--t[+|-]
| test_mode boolean scalar optional | Run in test-mode Default=0 |
--geo=geo
| geo string scalar optional | Start geometry - Internal use (width, height, x, y) Default=. |
<1>
| env_name string scalar mandatory | Env Variable to contain the filespec Default= |
<2>
| file string scalar mandatory | The file to search Default= |
<3>
| prefix string scalar mandatory | prefix string preceding all path-list elements. e.g: -I Default= |
<*>
| path-list string array mandatory | The directories to search preceded by <prefix> Default= |
<*>
| menu_entries integer array optional greater: 0 | Menu entries for immediate execution Default= |
<*>
| comp_file_opts string array optional | bld files to make with 'make' options. ALL = *:*.* Default= |
--r[+|-]
| reverse_type boolean scalar optional | Specify source-types instead of build-types Default=0 |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--mo[+|-]
| make_only boolean scalar optional | Run 'make' only (show make results) Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads Default=2 |
| (GBS_) DEBUGGER | (GBS_) MODE | (GBS_) OPT |
| (GBS_) MAP | (GBS_) FLAGS_* | (GBS_) APP_* |
<*>
| components string array optional | . == current component, <empty> == all Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
gbsman
<1>
| dir_path string scalar optional | Existig directory path or '.' Default= |
<1>
| command string scalar mandatory choice: ? info state co ci unco mkdir mktxt add move get_ignore set_ignore remove import connect select | Basic SCM Command Default= |
<*>
| files string array optional | File / Directory List Default= |
--r[+|-]
| recursive boolean scalar optional | Add whole directory tree Default=0 |
--c[+|-]
| use_cache boolean scalar optional | Use cache Default=0 |
<*>
| menu_entries integer array optional greater: 0 | Menu entries for immediate execution Default= |
<*>
| menu_entries integer array optional greater: 0 | Menu entries for immediate execution Default= |
--brief[+|-]
| brief boolean scalar optional | Brief (short) listing Default=0 |
--ci[+|-]
| create_index boolean scalar optional | Create the HTML Index Default=1 |
--cs[+|-]
| create_summaries boolean scalar optional | Create the HTML Summaries Default=1 |
--vi[+|-]
| view_index boolean scalar optional | View index in HTML browser Default=1 |
--noc[+|-]
| no_create boolean scalar optional | No HTML Creation (forces --ci and --cs to '-') Default=0 |
| --noc+ | AND | --ci+ or --cs+ |
<*>
| steps string array optional | Steps and/or Aliases. <empty> == all select steps, 'CUR', 'ALL' == force all steps, 'CUR', '?' == show steps Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--vs[+|-]
| view_sum boolean scalar optional | View summary at completion Default=1 |
--audits=audits
| audits string array optional choice: . $GBS_AUDITS | (wild-)Audits to run. '' or '*' == All, '.' == Current Default=* |
--builds=builds
| builds string array optional choice: . $GBS_BUILDS | (wild-)Builds to Build. '' or '*' == All, '.' == Current Default=* |
--files=files
| files string array optional | Files to audit Default=*:*.* |
--aud[+|-]
| run_audit boolean scalar optional | Run audit Default=1 |
--sum[+|-]
| run_summary boolean scalar optional | Create summary Default=1 |
--fg[+|-]
| foreground boolean scalar optional | Runs in the foreground if set Default=0 |
--at=delay
| delay time ([+=]hh:mm or [+=]mm) or now) scalar optional | Starting time (10:20), delta (+10:10) or now Default=now |
--n[+|-]
| notify boolean scalar optional | Notify user on completion (bg/nowait only) Default=$notify |
--wait[+|-]
| wait boolean scalar optional | Wait for completion of bg threads Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads within a submitted job Default=2 |
--c=comment
| comment string scalar optional | Comments - will be shown in Summary - Specify %20 for space Default= |
| <*> = ALL | AND | <*> |
| <*> = CUR | AND | <*> or --audits or --builds |
| <*> = ? | AND | <*> |
| --fg+ | AND | --at or --n+ or --wait+ |
| --wait+ | AND | --n+ |
| --sum- | AND | --vs+ |
| (GBS_) LOG_PATH | (GBS_) FLAGS_* | (GBS_) APP_* |
<*>
| steps string array optional | Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--mm[+|-]
| run_makemake boolean scalar optional | Run 'gbsmakemake' on completion of Full GBS SubSystems Default=1 |
--export[+|-]
| run_export boolean scalar optional | Run 'gbsexport' on completion Default=1 |
--builds=builds
| builds string array optional choice: . $GBS_BUILDS | (wild-)Builds to Build. '' or '*' == All, '.' == Current Default=* |
--files=files
| files string array optional | Files to build Default=*:*.* |
--fg[+|-]
| foreground boolean scalar optional | Runs in the foreground if set Default=0 |
--at=delay
| delay time ([+=]hh:mm or [+=]mm) or now) scalar optional | Starting time (10:20), delta (+10:10) or now Default=now |
--n[+|-]
| notify boolean scalar optional | Notify user on completion (bg/nowait only) Default=$notify |
--wait[+|-]
| wait boolean scalar optional | Wait for completion of bg threads Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads within a submitted job Default=2 |
--c=comment
| comment string scalar optional | Comments - will be shown in Summary - Specify %20 for space Default= |
| <*> = ALL | AND | <*> |
| <*> = CUR | AND | <*> or --builds |
| <*> = ? | AND | <*> |
| --fg+ | AND | --at or --n+ or --wait+ |
| --wait+ | AND | --n+ |
| (GBS_) LOG_PATH | (GBS_) DEBUGGER | (GBS_) MODE |
| (GBS_) OPT | (GBS_) MAP | (GBS_) FLAGS_* |
| (GBS_) APP_* |
<*>
| steps string array optional | Steps and/or Aliases. <empty> == all select steps, 'CUR', 'ALL' == force all steps, '?' == show steps Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--smm[+|-]
| start_makemake boolean scalar optional | Pre-generate the make-file Default=1 |
--mm[+|-]
| run_makemake boolean scalar optional | Run 'gbsmakemake' on completion of Full GBS SubSystems Default=1 |
--export[+|-]
| run_export boolean scalar optional | Run 'gbsexport' on completion Default=1 |
--builds=builds
| builds string array optional choice: . $GBS_BUILDS | (wild-)Builds to Build. '' or '*' == All, '.' == Current Default=* |
--files=files
| files string array optional | Files to make Default=*:*.* |
--fg[+|-]
| foreground boolean scalar optional | Runs in the foreground if set Default=0 |
--at=delay
| delay time ([+=]hh:mm or [+=]mm) or now) scalar optional | Starting time (10:20), delta (+10:10) or now Default=now |
--n[+|-]
| notify boolean scalar optional | Notify user on completion (bg/nowait only) Default=$notify |
--wait[+|-]
| wait boolean scalar optional | Wait for completion of bg threads Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads within a submitted job Default=2 |
--c=comment
| comment string scalar optional | Comments - will be shown in Summary - Specify %20 for space Default= |
| <*> = ALL | AND | <*> |
| <*> = CUR | AND | <*> or --builds |
| <*> = ? | AND | <*> |
| --fg+ | AND | --at or --n+ or --wait+ |
| --wait+ | AND | --n+ |
| (GBS_) LOG_PATH | (GBS_) DEBUGGER | (GBS_) MODE |
| (GBS_) OPT | (GBS_) MAP | (GBS_) FLAGS_* |
| (GBS_) APP_* |
<*>
| steps string array optional | Steps and/or Aliases. <empty> == all select steps, 'CUR', 'ALL' == force all steps, '?' == show steps Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--vs[+|-]
| view_sum boolean scalar optional | View summary at completion Default=1 |
--tools=tools
| tools string array optional choice: . $GBS_TOOLS | (wild-)Tools to execute. '' or '*' == All, '.' == Current Default=* |
--fg[+|-]
| foreground boolean scalar optional | Runs in the foreground if set Default=0 |
--at=delay
| delay time ([+=]hh:mm or [+=]mm) or now) scalar optional | Starting time (10:20), delta (+10:10) or now Default=now |
--n[+|-]
| notify boolean scalar optional | Notify user on completion (bg/nowait only) Default=$notify |
--wait[+|-]
| wait boolean scalar optional | Wait for completion of bg threads Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads within a submitted job Default=2 |
--c=comment
| comment string scalar optional | Comments - will be shown in Summary - Specify %20 for space Default= |
| <*> = ALL | AND | <*> |
| <*> = CUR | AND | <*> or --tools |
| <*> = ? | AND | <*> |
| --fg+ | AND | --at or --n+ or --wait+ |
| --wait+ | AND | --n+ |
| (GBS_) LOG_PATH | (GBS_) FLAGS_* | (GBS_) APP_* |
<*>
| steps string array optional | Steps and/or Aliases. <empty> == all select steps, 'ALL' == force all steps, '?' == show steps Default= |
--i[+|-]
| ignore_errors boolean scalar optional | Continue generation after error(s) Default=0 |
--vs[+|-]
| view_sum boolean scalar optional | View summary at completion Default=1 |
--audits=audits
| audits string array optional choice: . $GBS_AUDITS | (wild-)Audits to run. '' or '*' == All, '.' == Current Default=* |
--builds=builds
| builds string array optional choice: . $GBS_BUILDS | (wild-)Builds to Build. '' or '*' == All, '.' == Current Default=* |
--tools=tools
| tools string array optional choice: . $GBS_TOOLS | (wild-)Tools to Execute. '' or '*' == All, '.' == Current, '-' == None Default=* |
--current[+|-]
| current boolean scalar optional | Sets --audits, --builds and --tools to '.' (current) Default=0 |
--files=files
| files string array optional | Files to audit Default=*:*.* |
--make[+|-]
| make boolean scalar optional | Run gbssysmake instead of gbssysbuild Default=0 |
--fg[+|-]
| foreground boolean scalar optional | Runs in the foreground if set Default=0 |
--at=delay
| delay time ([+=]hh:mm or [+=]mm) or now) scalar optional | Starting time (10:20), delta (+10:10) or now Default=now |
--n[+|-]
| notify boolean scalar optional | Notify user on completion (bg/nowait only) Default=$notify |
--wait[+|-]
| wait boolean scalar optional | Wait for completion of bg threads Default=0 |
--threads=threads
| threads integer scalar optional range: 1..9 | Max nr parallel threads within a submitted job Default=2 |
--c=comment
| comment string scalar optional | Comments - will be shown in Summary - Specify %20 for space Default= |
| <*> = ALL | AND | <*> |
| <*> = CUR | AND | <*> or --audits or --builds or --tools |
| <*> = ? | AND | <*> |
| --current+ | AND | --audits or --builds or --tools |
| --fg+ | AND | --at or --n+ or --wait+ |
| --wait+ | AND | --n+ |
| (GBS_) LOG_PATH | (GBS_) FLAGS_* | (GBS_) APP_* |
<1>
| system_spec string scalar mandatory | System: '-' == none, '.' == current, '!' == CWD, '!<abs_file/dir_spec>', '!!' == CWD = GBS_SYSTEM_PATH Default=! |
<2>
| subsystem string scalar optional | SubSystem: '-' == none, '.' or '' == current Default= |
<3>
| component string scalar optional | Component: '-' == none, '.' or '' == current Default= |
--build=build
| build string scalar optional | Build: '-' == none, '.' or '' == current Default=. |
--audit=audit
| audit string scalar optional | Audit: '-' == none, '.' or '' == current Default=. |
--tool=tool
| tool string scalar optional | Toolt: '-' == none, '.' or '' == current Default=. |
--exec=execute_command
| execute_command string scalar mandatory | (GBS-)Command to execute. 'none' = OK Default= |
| <1> = - | AND | <2> |
| <1> = - | AND | <3> |
| <2> = - | AND | <3> |
<1>
| gbs_command string scalar mandatory | GBS command. e.g.: gbsbuild Default= |
<*>
| gbs_command_args string array optional | GBS command args, including --options Default= |
--lines[+|-]
| count_lines boolean scalar optional | Count lines in src, inc and loc Default=0 |
--cs[+|-]
| create_stats boolean scalar optional | Create the HTML Statistics Default=1 |
--vi[+|-]
| view_index boolean scalar optional | View index in HTML browser Default=1 |
<1>
| component string scalar optional | Component: '' == ASK, '-' == none, '.' == current Default= |
--build=build
| build string scalar optional | Build: '-' == none, '.' == current Default= |
--audit=audit
| audit string scalar optional | Audit. '-' == none, '.' == current Default= |
--new[+|-]
| create_component boolean scalar optional | Create a new Component Default=0 |
--delete[+|-]
| delete_component boolean scalar optional | Delete a Component Default=0 |
--nocd[+|-]
| no_cd boolean scalar optional | Do not 'cd' to the selected directories Default=0 |
| --new+ | AND | --delete+ or --build or --audit |
| --delete+ | AND | --new+ or --build or --audit |
| <1> = - | AND | --new+ or --delete+ or --build or --audit |
<1>
| system_spec string scalar optional | System: <abs_or_relspec>, '' == ASK, '-' == none, '.' == current, '!' == CWD, '!<abs_or_relspec>' (search), '!!' == current GBS_SYSTEM_PATH Default= |
<2>
| subsystem string scalar optional | SubSystem: '-' == none, '.' == current Default= |
<3>
| component string scalar optional | Component: '-' == none, '.' == current Default= |
--build=build
| build string scalar optional | Build: '-' == none, '.' == current Default= |
--audit=audit
| audit string scalar optional | Audit: '-' == none, '.' == current Default= |
--tool=tool
| tool string scalar optional | Tool: '-' == none, '.' == current Default= |
--new[+|-]
| create_system boolean scalar optional | Create a new System Default=0 |
--add[+|-]
| add_system boolean scalar optional | Add a System to the Systems-List Default=0 |
--remove[+|-]
| remove_system boolean scalar optional | Remove a System from the Systems-List - do not Delete Default=0 |
--delete[+|-]
| delete_system boolean scalar optional | Remove and Delete a System from the Systems-List Default=0 |
--show[+|-]
| show_systems boolean scalar optional | Show the Systems-List Default=0 |
--exec=execute_command
| execute_command string scalar optional | (GBS-)Command(s) to execute. 'none' = OK Default= |
--nocd[+|-]
| no_cd boolean scalar optional | Do not 'cd' to the selected directories Default=0 |
| --new+ | AND | --add+ or --remove+ or --delete+ or --show+ or --exec or <2> or --build or --audit or --tool |
| --add+ | AND | --new+ or --remove+ or --delete+ or --show+ or --exec or <2> or --build or --audit or --tool |
| --remove+ | AND | --new+ or --add+ or --delete+ or --show+ or --exec or <2> or --build or --audit or --tool |
| --delete+ | AND | --new+ or --add+ or --remove+ or --show+ or --exec or <2> or --build or --audit or --tool |
| --show+ | AND | --new+ or --add+ or --remove+ or --delete+ or --exec or <2> or --build or --audit or --tool |
| <1> = - | AND | --new+ or --add+ or --remove+ or --delete+ or --show+ or --exec or <2> or --build or --audit or --tool |
| <2> = - | AND | <3> |
| <1> | AND | <2> or <3> or --build or --audit or --tool |
<1>
| subsystem string scalar optional | SubSystem. '' == ASK, '-' == none, '.' == current Default= |
<2>
| component string scalar optional | Component. '-' == none, '.' == current Default= |
--build=build
| build string scalar optional | Build. '-' == none, '.' == current Default= |
--audit=audit
| audit string scalar optional | Audit. '-' == none, '.' == current Default= |
--new[+|-]
| create_subsys boolean scalar optional | Create a new SubSystem Default=0 |
--delete[+|-]
| delete_subsys boolean scalar optional | Delete a SubSystem Default=0 |
--nocd[+|-]
| no_cd boolean scalar optional | Do not 'cd' to the selected directories Default=0 |
| --new+ | AND | <2> or --delete+ or --build or --audit |
| --delete+ | AND | <2> or --new+ or --build or --audit |
| <1> = - | AND | --new+ or --delete+ or <2> or --build or --audit |
<1>
| build string scalar optional | Build: '' == ASK, '-' == none, '.' == current Default= |
--new[+|-]
| create_build boolean scalar optional | Create a new Build Default=0 |
--remove[+|-]
| remove_build boolean scalar optional | Remove a Build from the Builds List Default=0 |
--delete[+|-]
| delete_build boolean scalar optional | Delete a Build Default=0 |
| --new+ | AND | --remove+ or --delete+ |
| --remove+ | AND | --new+ or --delete+ |
| --delete+ | AND | --new+ or --remove+ |
<1>
| audit string scalar optional | Audit: '' == ASK, '-' == none, '.' == current Default= |
--new[+|-]
| create_audit boolean scalar optional | Create a new Audit Default=0 |
--remove[+|-]
| remove_audit boolean scalar optional | Remove an Audit from the Audits List Default=0 |
--delete[+|-]
| delete_audit boolean scalar optional | Delete an Audit Default=0 |
| --new+ | AND | --remove+ or --delete+ |
| --remove+ | AND | --new+ or --delete+ |
| --delete+ | AND | --new+ or --remove+ |
<1>
| tool string scalar optional | Tool: '' == ASK, '-' == none, '.' == current Default= |
--new[+|-]
| create_tool boolean scalar optional | Create a new Tool Default=0 |
--remove[+|-]
| remove_tool boolean scalar optional | Remove a Tool from the Tools List Default=0 |
--delete[+|-]
| delete_tool boolean scalar optional | Delete a Tool Default=0 |
| --new+ | AND | --remove+ or --delete+ |
| --remove+ | AND | --new+ or --delete+ |
| --delete+ | AND | --remove+ or --new+ |
<1>
| command string scalar mandatory choice: edit manage | GBS command to execute Default= |
<*>
| command_args string array optional | Arguments for <command> Default= |
<1>
| what string scalar optional choice: ? subsys comp component build audit tool find search | Specify Default= |
<*>
| what_args string array optional | 'what'-dependent Default= |
| (GBS_) FLAGS_* |
--t[+|-]
| test_mode boolean scalar optional | Run in test-mode - Internal use Default=0 |
<1>
| install_root string scalar optional path: syntax check only | Install-Root. Remembered Default= |
--q[+|-]
| quiet_mode boolean scalar optional | Run in Quiet-Mode (No prompts) Default=0 |
--setup[+|-]
| setup boolean scalar optional | Call gbssetup after install. Not if Multi-User. Remembered Default= |
--site=site
| site string scalar optional word: Min. length = 3 Max. length = 20 | Default Site. Remembered and passed to gbssetup Default= |
--company=company
| company string scalar optional text: Min. length = 2 Max. length = 40 | Default Company Default= |
--log_root=log_root
| log_root string scalar optional path: syntax check only | Default Log-Root. Passed to gbssetup. Not if Multi-User. Default= |
--q[+|-]
| quiet_mode boolean scalar optional | Run in Quiet-Mode (No prompts) Default=0 |
--site=site
| site string scalar optional word: Min. length = 3 Max. length = 20 | Default Site Default= |
--company=company
| company string scalar optional text: Min. length = 2 Max. length = 40 | Default Company Default= |
--log_root=log_root
| log_root string scalar optional path: syntax check only | Default Log-Root Default= |
<*>
| files string scalar optional | Files to process or directory in case of -r Default= |
-t[+|-]
| test boolean scalar optional | test only - do not make modifications Default=0 |
-r[+|-]
| recurse boolean scalar optional | recurse directory looking for -f= files Default=0 |
-f=wild_files
| wild_files string array optional | wild-card files to process Default= |
-m=modulo
| modulo integer scalar optional | The TAB size the file was created with Default=8 |
-s[+|-]
| smart_tabs boolean scalar optional | retab leading whitespace (modulo 8) Default=0 |
fixeol files...
files
| string array mandatory | Files to be fixed Default= |
<1>
| command_or_commandsfile string scalar mandatory | Rename/Delete Command or @filespec of file containing Rename/Delete Commands Rename/Delete Command: <delim><find><delim><replace><delim>[g|r][i] - g = glob rename (default) - r = Perl regular expression rename - i = ignore case of search string Empty <replace> deletes the file commandsfile: Empty lines and lines beginning with '#' are ignored Default= |
<*>
| files string scalar optional | (wild-)Files and.or Dirs to process Default= |
-t[+|-]
| test boolean scalar optional | test only - do not make modifications Default=0 |
-r=recurse
| recurse string array optional | recurse direcory using comma-separated wild files Default= |
-R=recurse_group
| recurse_group string array optional | recurse direcory using comma-separated file-groups. e.g.: perl Default= |
<1>
| rexexp_or_file string scalar mandatory | Perl regexp or @filespec of file containing Perl regexps regexp-file: Empty lines and lines beginning with '#' are ignored Default= |
<*>
| files string scalar optional | (wild-)Files and.or Dirs to process Default= |
-w[+|-]
| word boolean scalar optional | find word (no regexp) Default=0 |
-b[+|-]
| begin boolean scalar optional | find begin word (no regexp) Default=0 |
-e[+|-]
| end boolean scalar optional | find end word (no regexp) Default=0 |
-a[+|-]
| any boolean scalar optional | find any (no regexp) Default=0 |
-i[+|-]
| ignore_case boolean scalar optional | ignore case of search string Default=0 |
-n[+|-]
| print_linenr boolean scalar optional | print linenumber Default=1 |
-B=before_context
| before_context integer scalar optional | print <num> lines of leading context Default=0 |
-A=after_context
| after_context integer scalar optional | print <num> lines of trailing context Default=0 |
-C=context
| context integer scalar optional | print <num> lines of output context (-A=<num> and -B=<num>) Default=0 |
-r=recurse
| recurse string array optional | recurse direcory using comma-separated wild files Default= |
-R=recurse_group
| recurse_group string array optional | recurse direcory using comma-separated file-groups. e.g.: perl Default= |
-s[+|-]
| supress_msg boolean scalar optional | Suppress non-error messages Default=0 |
<*>
| files string scalar optional | Files to be parsed Default=*.c,*.cpp,*.oc,*.pl,*.pm |
win2unix files...
files
| string array mandatory | Files to convert Default= |
<1>
| command_or_commandsfile string scalar mandatory | Replace Command or @filespec of file containing Replace Commands Replace Command: <delim><find><delim><replace><delim>[w|b|e|a|r][i] - w = find word, b = find begin word, e = find end word - a = find any, r = find Perl regular expression - i = ignore case of search string - \s in replace string is converted to single space commandsfile: Empty lines and lines beginning with '#' are ignored Default=1 |
<*>
| files string scalar optional | (wild-)Files and.or Dirs to process Default= |
-t[+|-]
| test boolean scalar optional | test only - do not make modifications Default=0 |
-r=recurse
| recurse string array optional | recurse direcory using comma-separated wild files Default= |
-R=recurse_group
| recurse_group string array optional | recurse direcory using comma-separated file-groups. e.g.: perl Default= |
wsudo [ command_sequence ]
command_sequence
| string array optional | Command(s) to be executed If omitted a CMD Window will be started in Elevated Mode. |
IF "%WIN32UTILS_IN_PATH%"=="" THEN PATH=%GBS_SCRIPTS_PATH%\win2util;%PATH%
SET WIN32UTILS_IN_PATH=1
grep --help
egrep --help
agrep --help
tail --help
touch --help
which --help
cp --help
find --help
gawk --help
make --help
rm --help
sed --help
tar --help
Description
|
| gbssysbuild | is used to generate a whole or part of a whole System |
| gbssysmake | is used to 'make' a whole or part of a whole System |
| gbssysaudit | is used to audit a whole or part of a whole System |
| gbssystool | is used run a tool on the whole or part of a whole System |
| |
| gbssysall | is used run all of the above |
These commands will perform their functions over various SubSystems in the appropriate order and allows extra steps to be executed.
It is also possible to generate a number of SubSystems selectively.
The generations steps, their required order and allowed options are defined in the
steps.gbs file (in $GBS_SYS_PATH).
Execution will be performed in the batch and the output is logged in a log-file.
| gbssys... | [ steps | CUR | ALL ] [ GBS-options ] [ APP-options ] [ GBS-env-variables ] [ other_gbs_options ] |
| BUILD | =... |
| DEBUGGER | =,YES,NO |
| MODE | =,FINAL,ASSERT,DEBUG |
| OPT | =,YES,SPEED,SIZE,NO |
| MAP | =,NO,YES |
| FLAGS_MAKE | =... |
| FLAGS_src_type | =... |
| jobname | : gbssysbuild gbssysmake gbssysaudit gbssystool' |
| build_or_tool | : |
| uname | : computer name and id |
| os_root_spec | : $GBS_SYSTEM_PATH |
| os_logfile_spec | : $GBS_LOG_PATH/$jobname_$build_$audit_$datetime.log |
| time_start | : YYYY-MM-DD hh:mm:ss |
| time_end | : YYYY-MM-DD hh:mm:ss |
| time_diff | : hhh:mm:ss |
| timer_diff | : "$clock $cpu_system $cpu_user $cpu_all" in seconds |
| state | : NORMAL FAILED KILLED |
| rc | : Return Code (Numeric. 0 == OK) |
| audit | : or '-' |
| date_time | : YYMMDD-hhmmss as used in os_logfile_name |
| command_args | : From the command-line |
| comment | : From the command-line (--c=...) |
| <<EOF>> | : |
Contents
Description |
Description
|
Description
|
Contents
Description |
| GBSEXT_QAC_PATH | The main directory for QAC |
| GBSEXT_QAC_REL | The selected QAC release |
Same way as for C-compilation
Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C compliant.
Same way as for C compilations
qacpp
| GBSEXT_QACPP_PATH | The main directory for QAC++ |
| GBSEXT_QACPP_REL | The selected QAC++ release |
Same way as for C++-compilation
Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C++ compliant.
Same way as for C++ compilations
pclint
| GBSEXT_PCLINT_PATH | The main directory for PCLint |
| GBSEXT_PCLINT_REL | The selected PCLint release |
Same way as for C and C++-compilation
Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C/ANSI-C++ compliant.
Same way as for C and C++ compilations
cpptest
| GBSEXT_CPPTEST_PATH | The main directory for C++test |
| GBSEXT_CPPTEST_REL | The selected C++test release |
Same way as for C and C++-compilation
Note: #include "../../../file.h" notations are not handled correctly as they are not ANSI-C/ANSI-C++ compliant.
Same way as for C and C++ compilations
Contents
Description |
Contents
Description |
Contents
Description |
| %SYSTEM_NAME% | → System | |
| %SUBSYS% | → SubSys | |
| %COMPONENT% | → Component | |
| %FILE% | → File_nameFile_type | |
| %FILE_NAME% | → File_name | |
| %FILE_TYPE% | → File_type | |
| %UC_FILE% | → uc File_nameFile_type | |
| %UC_FILE_NAME% | → uc File_name | |
| %UC_FILE_TYPE% | → uc File_type | |
| %INCLUDE_GUARD% | → uc File_nameFile_type with '.' replaced by '_' |
| Git | → GBSEXT_GIT_PATH | |
| Subversion | → GBSEXT_SVN_PATH |
--fg)
| Submit: | submit | jobname datetime nr_jobs [ build action ]... |
| Begin: | start | jobname datetime pid build action logfile-spec |
| End: | end | jobname datetime pid build action logfile-spec completion-state completion-code Where completion-state is one of NORMAL FAILED or KILLED |
| More | TBS | Expect future extensions |
Contents
Description |
Description
Supported plugins. |
Description
GBS relies heavily on Environment Variables (EnvVars) |
| Level | EnvVar Name | Possible Values | Usage | More Info | Set by | Changed by | Remarks |
|---|---|---|---|---|---|---|---|
| 0 Adm | GBS_PERL_PATH | directory path | Define location of Perl | More | User | User | Optional. In: Windows System Variables or .profile |
| 1 Pre | GBS_BOOT_PATH | directory path %APPDATA%\.gbs or ~/.gbs | Define location of Boot .gbs | define GBS | N/A | Internal | |
| 1 Pre | GBS_BASE_PATH | directory path %MyDocuments%/.gbs or ~/.gbs/base | Define location of User .gbs/base | define GBS | N/A | Internal | |
| 1 Pre | GBS_PLATFORM | MSWin32 or Linux | Current platform | More | Define GBS | Predefined | Internal |
| 1 Pre | GBS_SHELL_FILETYPE | .bat or .sh | Commandfile-type for current platform | Define GBS | N/A | Internal | |
| 1 Pre | GBS_PERL_CMD | command | Full Perl command | Define GBS | N/A | Internal | |
| 1 Pre | GBS_WSL_DISTRO | Empty, none or distro | Current Distro if in WSL | Define GBS | N/A | Internal | |
| 2 GBS | GBS_RC | Number | Scripts return status | various | scripts | ||
| 2 GBS | GBS_SITE | Short name in uppercase | Name of your Site | More | gbsinit | gbssettings | |
| 2 GBS | GBS_LOG_ROOT | directory path | Log Files Root Location | More | gbsinit | gbssettings | Contains GBS_LOG_PATHs per GBS_SYSTEM_PARENT |
| 2 GBS | GBS_LOG_PATH | directory path | Log Files Location | More | gbsinit | switch.gbs | Set to $GBS_LOG_ROOT/$GBS_SYSTEM_PARENT |
| 2 GBS | GBS_HOME_PATH | directory path MyDocuments or ~/Documents | CWD when no System is current and default Root for GBS user directories | More | gbsinit | gbssettings | |
| 2 GBS | GBS_TEMPLATES_PATH | directory path | External Templates path (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_MAKE | command_spec | Alternative 'make' for Non-GBS Makefiles (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_SUBMIT | command_spec | Alternative Submit (Background) (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_SUBWIN | command_spec | Alternative Submit (Foreground) (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_BATCH | command_spec | Alternative Batch command (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_BG_NOTIFIER | command_spec | Notifier for Submit completion (OPT) | More | gbsinit | swr | site.gbs switch.gbs |
| 2 GBS | GBS_BUILD | RVVYYMMDD | Current Release/Build | More | gbsinit | Predefined | |
| 2 GBS | GBS_EXEC_MODE | DEFINED INTERACTIVE FOREGROUND BACKGROUND | Execution Mode | define gbsinit | gbssys* | Internal | |
| 2 GBS | GBS_GUI | Tkx None | Available Perl GUI | gbsinit | Predefined | Internal | |
| 2 GBS | GBS_PERL_CMD | perl with or without path | Direct Perl execution command | gbsinit | Predefined | ||
| 2 GBS | GBS_WPERL_CMD | perl with or without path | Command to start Perl GUI | gbsinit | Predefined | ||
| 2 GBS | GBS_PID | number | PID of toplevel process | gbsinit | Predefined | Internal | |
| 2 GBS | GBS_SCRIPTS_ROOT | directory path | Where GBS versions are installed | More | gbsinit | gbssettings | Internal |
| 2 GBS | GBS_SCRIPTS_REL | version version_build | The current GBS version directory | More | gbsinit | gbssettings | Internal |
| 2 GBS | GBS_SCRIPTS_PATH | Root/Rel | The current GBS scripts location | More | gbsinit | gbssettings | |
| 2 GBS | GBS_SHELL_FILETYPE | .bat .sh | The current shell filetype | gbsinit | gbssettings | ||
| 2 GBS | GBSDEBUG_VERBOSE | 0 1 | Verbose logging | More | gbsinit | All Commands (Internally) | Always 1 in BATCH jobs (gbssys*) |
| 3 System | GBS_SYSTEM_NAME | name | Name of the System | More | swr | ||
| 3 System | GBS_SYSTEM_PATH | directory path | Current System path | More | swr | ||
| 3 System | GBS_SYSTEM_PARENT | directory name | Parent dir of current System | More | swr | ||
| 3 System | GBS_ALL_AUDITS | names list | All platform Audits | swr | |||
| 3 System | GBS_AUDITS | names list | All Audits for this Platform | swr | |||
| 3 System | GBS_AUDIT | name | Current Audit | swr | gbsaudit | ||
| 3 System | GBS_AUDIT_PLUGIN | name | Current Audit Plugin | swr | gbsaudit | ||
| 3 System | GBS_ALL_BUILDS | names list | All platform Builds | swr | |||
| 3 System | GBS_BUILDS | names list | All Builds for this Platform | swr | |||
| 3 System | GBS_BUILD | name | Current Build | swr | swb | ||
| 3 System | GBS_BUILD_PLUGIN | name | Current Build Plugin | swr | swb | ||
| 3 System | GBS_ALL_TOOLS | names list | All platform Tools | swr | |||
| 3 System | GBS_TOOLS | names list | All Tools for this Platform | swr | |||
| 3 System | GBS_TOOL | name | Current Tool | swr | gbssystool | ||
| 3 System | GBS_TOOL_PLUGIN | name | Current Tool Plugin | swr | gbssystool | ||
| 3 System | GBS_ALL_SUBSYSTEMS | names list | All SubSystems | swr | sws --new | ||
| 3 System | GBS_IS_ADMINISTRATOR | 0 1 | User is Administrator | More | swr | gbssettings | |
| 3 System | GBS_IS_INTEGRATOR | 0 1 | User is Integrator | More | swr | gbssettings | |
| 3 System | GBS_IGNORES | regexp List | Filetypes to be skipped | swr | Internal | ||
| 3 System | GBS_PLATFORMS | Platform list | Platforms this System generates for | Internal | |||
| 3 System | GBS_SCMS | None Subversion Git ... | Current SCMS | More | swr | Internal | |
| 3 System | GBS_SCMS_DATA | path | Internal Path | More | swr | Internal | |
| 3 System | GBS_SCMS_REPOSITORY | file/directory path/URL | SCMS Repository location | More | swr | Internal | |
| 3 System | GBS_DEV_PATH | directory path | SystemPath/dev | More | swr | ||
| 3 System | GBS_EXT_PATH | directory path | SystemPath/ext | More | swr | ||
| 3 System | GBS_RES_PATH | directory path | SystemPath/res | More | swr | ||
| 3 System | GBS_SILO_PATH | directory path | SystemPath/silo | More | swr | Internal | |
| 3 System | GBS_SYS_PATH | directory path | SystemPath/sys | More | swr | ||
| 3 System | GBS_SYSAUDIT_PATH | directory path | SystemPath/sysaudit | More | swr | ||
| 3 System | GBS_SYSBUILD_PATH | directory path | SystemPath/sysbuild | More | swr | ||
| 3 System | GBS_SYSTOOL_PATH | directory path | SystemPath/systool | More | swr | ||
| 3 System | GBS_TMP_PATH | directory path | SystemPath/tmp | More | swr | Internal | |
| 3 System | GBS_DEBUGGER | YES NO | Include Debugger (build) | More | swb | User gbsbuild gbsmake | Scripts |
| 3 Systems | GBS_MAP | YES NO | Produce a memory map (linking) | More | swb | User gbsbuild gbsmake | Scripts |
| 3 System | GBS_MODE | FINAL ASSERT DEBUG PROFILING | Build mode | More | swb | User gbsbuild gbsmake | Scripts |
| 3 System | GBS_OPT | YES SPEED SIZE DEBUG NO | Build Optimisation | More | swb | User gbsbuild gbsmake | Scripts |
| 3 System | GBS_BLD_src_type | File type | Derived Object filetype | swb | Scripts | ||
| 4 Sub | GBS_SUBSYS | name | Current SubSys | More | sws | ||
| 4 Sub | GBS_SSTYPE | GBS make MSVS Other | Current SubSystem Type | More | sws | ||
| 4 Sub | GBS_SUBSYS_PATH | directory path | SystemPath/dev/SUBSYS | More | sws | ||
| 4 Sub | GBS_AUDIT_PATH | directory path | SystemPath/dev/SUBSYS/audit | More | sws | ||
| 4 Sub | GBS_BUILD_PATH | directory path | SystemPath/dev/SUBSYS/build | More | sws | ||
| 4 Sub | GBS_TOOL_PATH | directory path | SystemPath/dev/SUBSYS/tool | More | sws | ||
| 4 Sub | GBS_EXPORT_PATH | directory path | SystemPath/dev/SUBSYS/export (OPT) | More | sws | ||
| 4 Sub | GBS_IMPORT_PATH | directory path | SystemPath/dev/SUBSYS/import (OPT) | More | sws | ||
| 4 Sub | GBS_COMP_PATH | directory path | SystemPath/dev/SUBSYS/comp | More | sws | SSTYPE==GBS | |
| 4 Sub | GBS_APP_PATH | directory path | SystemPath/dev/SUBSYS/app | More | sws | SSTYPE!=GBS | |
| 4 Cmp | GBS_COMPONENT_PATH | directory path | SystemPath/dev/SUBSYS/comp/COMPONENT | More | swc | SSTYPE==GBS | |
| 5 Cmp | GBS_COMPONENT | name | Current Component | More | swc | SSTYPE==GBS | |
| 5 Ses | GBS_FLAGS_type | flags | Predefine flags (-D...) | More | User | User | Scripts |
| 6 Exe | GBS_IGNORE_ERRORS | 0 1 | --i was specified | More | gbssysbuild gbssysmake | Scripts | |
| 6 Exe | GBS_FLAGS_type | flags or flags_file ref | Flags (-D...) | More | gbssys* gbsbuild gbsaudit | Scripts | |
| 6 Exe | GBS_SYSFLAGS_type | flags or flags_file ref | System Flags (-D...) | More | gbssys* gbsbuild gbsaudit | Scripts | |
| 6 Exe | GBS_INCS_type | includes or includes_file ref | Include Flags (-I...) | More | gbssys* gbsbuild gbsaudit | Scripts | |
| 6 Exe | GBS_BUILD_type | Command | Command to execute Build | More | gbssysbuild | Scripts SSTYPE== make or Other | |
| 6 Exe | GBS_AUDIT_type | Command | Command to execute Audit | More | gbssysbuild | Scripts SSTYPE== make or Other | |
| 6 Exe | GBS_MAKE_FLAGS | -i or empty | -i if GBS_IGNORE_ERRORS == 1 | More | gbssysbuild | Scripts SSTYPE==make | |
| 6 Exe | GBS_MSBUILD_CONFIG | Debug Release or empty | Depends on GBS_MODE | More | gbssysbuild | Scripts SSTYPE==MSVS |
| EnvVar Name | Required for |
|---|---|
| GBSEXT_GIT_PATH | Git |
| GBSEXT_SVN_PATH | Subversion |
| Type | Plugin | EnvVar | Required | Platform | Remarks |
|---|---|---|---|---|---|
| Builder | MinGW C | GBSEXT_MINGW_GCC | REL and PATH | Win32 | |
| Builder | MinGW C/C++ | GBSEXT_MINGW_CPP | REL and PATH | Win32 | |
| Builder | Microsoft Visual Studio 2012 - Simple Console C/C++ | GBSEXT_MSVS2012_CONS | REL and PATH | Win32 | |
| Builder | Green Hills - BlackFin C/C++ | GBSEXT_GHSBF | REL and PATH | Win32 | |
| Builder | GNU C | GBSEXT_LGNU_GCC | REL and PATH | Linux | |
| Builder | GNU C/C++ | GBSEXT_LGNU_CPP | REL and PATH | Linux | |
| Audit | PC-Lint C/C++ | GBSEXT_PCLINT | REL and PATH | Win32 | |
| Audit | QAC | GBSEXT_QAC | REL and PATH | Both | |
| Audit | QAC++ | GBSEXT_QACPP | REL and PATH | Both | |
| Tool | Doxygen | GBSEXT_DOXYGEN | REL and PATH | Both |
Contents
Description |
Contents
General |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
Description |
Contents
History |
Contents
Metrics Overview |
| AKI | Akiyama's Criterion |
| AV1 | Average Size of Statement in Function (variant 1) |
| AV2 | Average Size of Statement in Function (variant 2) |
| AV3 | Average Size of Statement in Function (variant 3) |
| BAK | Number of Backward Jumps |
| CAL | Number of Functions Called from Function |
| CYC | Cyclomatic Complexity |
| ELF | Number of Dangling Else-Ifs |
| FN1 | Number of Operator Occurrences in Function |
| FN2 | Number of Operand Occurrences in Function |
| GTO | Number of Goto statements |
| HLB | Number of Halstead's delivered bugs (B) |
| KDN | Knot Density |
| KNT | Knot Count |
| LCT | Number of Local Variables Declared |
| LIN | Number of Code Lines |
| LOP | Number of Logical Operators |
| M07 | Essential Cyclomatic Complexity |
| M19 | Number of Exit Points |
| M29 | Number of Functions Calling this Function |
| MCC | Myer's Interval |
| MIF | Deepest Level of Nesting |
| PAR | Number of Function Parameters |
| PBG | Residual Bugs (PTH-based est.) |
| PDN | Path Density |
| PTH | Estimated Static Program Paths |
| RET | Number of Return Points in Function |
| ST1 | Number of Statements in Function (variant 1) |
| ST2 | Number of Statements in Function (variant 2) |
| ST3 | Number of Statements in Function (variant 3) |
| SUB | Number of Function Calls |
| UNR | Number of Unreachable Statements |
| UNV | Unused or Non-Reused Variables |
| XLN | Number of Executable Lines |
These metrics are all calculated for the source code in a complete translation unit (TU). They are listed alphabetically here for convenience. They are not calculated in this sequence. because of their derivation from each other:
| BME | Embedded Programmer Months |
| BMO | Organic Programmer Months |
| BMS | Semi-detached Programmer Months |
| BUG | Residual Bugs (token-based estimate) |
| CDN | Comment to Code Ratio |
| DEV | Estimated Development (programmer-days) |
| DIF | Program Difficulty |
| ECT | Number of External Variables Declared |
| EFF | Program Effort |
| FCO | Estimated Function Coupling |
| FNC | Number of Functions in File |
| HAL | Halstead Prediction of TOT |
| M20 | Number of Operand Occurrences |
| M21 | Number of Operator Occurrences |
| M22 | Number of Statements |
| M28 | Number of Non-Header Comments |
| M33 | Number of Internal Comments |
| OPN | Number of Distinct Operands |
| OPT | Number of Distinct Operators |
| SCT | Number of Static Variables Declared |
| SHN | Shannon Information Content |
| TDE | Embedded Total Months |
| TDO | Organic Total Months |
| TDS | Semi-detached Total Months |
| TLN | Total Preprocessed Source Lines |
| TOT | Total Number of Tokens Used |
| TPP | Total Unpreprocessed Code Lines |
| VAR | Total Number of Variables |
| VOL | Program Volume |
| ZIP | Zipf Prediction of TOT |
| CCA | Total Number of Characters |
| CCB | Total Number of Code Characters |
| CCC | Total Number of Comment Characters |
These metrics are calculated for the classes in your source code. To calculate some of these metrics you must also have run the relevant cross-module analysis program. See Cross-Module Analysis in Chapter 4: Analysing Source Code. Class-based metrics are described here in alphabetical order for ease of reference:
| CBO | Coupling between objects |
| DIT | Deepest level of inheritance |
| LCM | Lack of cohesion of methods within a class |
| MTH | Number of methods available in class |
| NOC | Number of immediate children |
| NOP | Number of immediate parents |
| RFC | Response for class |
| WMC | Weighted methods per class |
These metrics are calculated once per complete project. The complete list is as follows:
| NRA | Number of Recursions Across Project |
| NEA | Number of Entry Points Across Project |
| NFA | Number of Functions Across Project |
| CYA | Cyclomatic Complexity Across Project |
Function-Based Metric
This metric is the sum of the Cyclomatic complexity (CYC) and the number of function calls (SUB). Although this is not an independent metric, it is included on account of its use in documented case histories. See Akiyama[1] and Shooman[2] for more details. The metric is calculated as:
[1] Akiyama, F. (1971) An Example of Software System Debugging, Proc. IFIP Congress 1971, Lbujlana, Yugoslavia, American Federation of information Processing Societies, Montvale, New Jersey.
[2] Shooman, M.L. (1983) Software Engineering, McGraw-Hill, Singapore.
Function-Based Metrics
These metrics (AV1, AV2, and AV3) measure the average number of operands and operators per statement in the body of the function. They are calculated using Halstead's[1] calculations as follows:
AVx = (N1 + N2) / number of statements in the function
where:
N1 is Halstead's number of operator occurrences.
N2 is Halstead's number of operand occurrences.
The AVx metrics are computed using ST1, ST2 and ST3 to represent the number of statements in a function. Hence there are three variants: AV1, AV2 and AV3 relating to the respective statement count metrics.
This metric is used to detect components with long statements. Statements comprising a large number of textual elements (operators and operands) require more effort by the reader in order to understand them. This metric is a good indicator of the program's readability.
Metric values are computed as follows:
AV1 = (FN1 + FN2) / ST1
AV2 = (FN1 + FN2) / ST2
AV3 = (FN1 + FN2) / ST3
[1] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
Jumps are never recommended and backward jumps are particularly undesirable. If possible, the code should be redesigned to use structured control constructs such as while or for instead of goto.
Living in Eindhoven - The Netherlands, from Curaçao - South Caribbean
main()
{
Backward:
switch (n)
{
case 0:
printf( stdout, "zero\n");
break;
case 1:
printf( stdout, "one\n");
goto Backward; /* 1 */
break;
case 2:
printf( stdout, "two\n");
break;
default: printf( stdout, "many\n");
break;
}
}
The above code sample has a BAK value of 1.
Function-Based Metric
This metric counts the number of function calls in a function.
It differs from the metric SUB, in that only distinct functions are counted (multiple instances of calls to a particular function are counted as one call), and also that functions called via pointers are not counted.
Function-Based Metric
Cyclomatic complexity is calculated as the number of decisions plus 1.
High cyclomatic complexity indicates inadequate modularization or too much logic in one function. Software metric research has indicated that functions with a cyclomatic complexity greater than 10 tend to have problems related to their complexity.
McCabe[1] gives an essential discussion of this issue as well as introducing the metric.
int divide( int x, int y)
{
if (y != 0) /* 1 */
{
return x / y;
} else if (x == 0) /* 2 */
{
return 1;
} else
{
printf( "div by zero\n");
return 0;
}
}
The above code sample has a cyclomatic complexity of 3 as there are two decisions made by the function. Note that correctly-indented code does not always reflect the nesting structure of the code. In particular, the use of the construct 'else if' always increases the level of nesting, but it is conventionally written without additional indentation and so the nesting is not visually apparent.
void how_many(int n)
{
switch (n)
{
case 0:
printf( "zero"); /* 1 */
break;
case 1:
printf( "one"); /* 2 */
break;
case 2:
printf( "two"); /* 3 */
break;
default:
printf( "many");
break;
}
}
The above code sample has a cyclomatic complexity of 4, as a switch statement is equivalent to a series of decisions.
Some metrication tools include use of the ternary operator ? : when calculating cyclomatic complexity. It could also be argued that use of the && and || operators should be included. Instead, CYC calculation is based on statements alone.
CYC is one of the three standard metrics used by QAC for demographic analysis.
[1] McCabe, T. J. (1976) A Complexity Measure, IEEE Transactions on Software Engineering, SE-2, pp. 308-320.
Function-Based Metric
This is the number of if-else-if constructs that do not end in an else clause. This metric is calculated by counting all if statements that do not have a corresponding else and for which QAC issues a warning 2004. ELF provides a quick reference allowing monitoring of these warnings. The code sample below has an ELF value of 1.
int divide(int x, int y)
{
if (y != 0)
{
return x/y;
} else if (x == 0)
{
return 1;
}
}
Function-Based Metric
This metric is Halstead's[1] operator count on a function basis (N1). FN1 is related to OPT and M21: all of these metrics count 'operators', the difference is summarized as:
| FN1 | Counts ALL operators in the function body |
| M21 | Counts ALL operators in the file |
| OPT | Counts DISTINCT operators in the file |
See OPT for the definition of an operator.
[1] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
This metric is Halstead's[1] operand count on a function basis (N2). FN2 is related to OPN and M20: all of these metrics count 'operands', the difference is summarized as:
| FN2 | Counts ALL operands in the function body |
| M20 | Counts ALL operands in the file |
| OPN | Counts DISTINCT operands in the file |
See OPN for the definition of an operand.
[1] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
Some occurrences of goto simplify error handling. However, they should be avoided whenever possible. According to the Plum Hall Guidelines, goto should not be used.
Function-Based Metric
The metric is an estimate for the number of errors in the implementation.
High values of Halstead's[1] delivered bugs (B) metrics
indicate possibility of high number of bugs.
The value of this metric is highly correlated to the size of a function.
The metric is defined in following way:
B = V / 3000
where:
int foo( int i) /* Violation: B = 0.09 */
{
int a;
int b;
a = i + (2 * (i + 1)) + (3 * (i + 2));
b = (i + (2 * (i + 1)) + (3 * (i + 2))) * 2;
if (i >= 3)
return a;
if (i >= 2)
return b;
}
[1] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
This is the number of knots per executable line of code. The metric is calculated as:
The value is computed as zero when XLN is zero.
Function-Based Metric
This is the number of knots in a function. A knot is a crossing of control structures, caused by an explicit jump out of a control structure either by break, continue, goto, or return. KNT is undefined for functions with unreachable code.
This metric measures knots, not by counting control structure crossings, but by counting the following keywords:
The function below has an KNT value of 1.
void fn( int n, int array[], int key )
{
while ( array[ n ] != key )
{
if ( array[ n ] == 999 )
{
break;
} else
{
++n;
}
}
}
Function-Based Metric
This is the number of local variables of storage class auto, register, or static declared in a function. These are variables that have no linkage. The function below has an LCT value of 2.
int other_result;
extern int result;
int test()
{
int x; /* 1 */
int y; /* 2 */
return (x + y + other_result);
}
Function-Based Metric
This is the total number of lines, including blank and comment lines, in a function definition between (but excluding) the opening and closing brace of the function body. It is computed on raw code. LIN is undefined for functions which have #include'd code or macros which include braces in their definition.
The function below has an LIN value of 5.
int fn()
{
int x; /* 1 */
int y; /* 2 */
/* 3 */
return (x + y); /* 4 */
/* Comment Here */ /* 5 */
}
Long functions are difficult to read, as they do not fit on one screen or one listing page. An upper limit of 200 is recommended.
Function-Based Metric
This is the total number of logical operators (&&, ||) in the conditions of do-while, for, if, switch, or while statements in a function. The example function below has a LOP value of 2.
void fn( int n, int array[], int key )
{
while (( array[n] != key ) && ( n > 0 ))
{
if (( array[n] == 999) || ( array[n] == 1000 ))
{
break;
} else
{
++n;
}
}
}
Function-Based Metric
The essential cyclomatic complexity is obtained in the same way as the cyclomatic complexity but is based on a 'reduced' control flow graph. The purpose of reducing a graph is to check that the component complies with the rules of structured programming.
A control graph that can be reduced to a graph whose cyclomatic complexity is 1 is said to be structured. Otherwise reduction will show elements of the control graph which do not comply with the rules of structured programming.
The principle of control graph reduction is to simplify the most deeply nested control subgraphs into a single reduced subgraph. A subgraph is a sequence of nodes on the control flow graph which has only one entry and exit point. Four cases are identified by McCabe[1] which result in an unstructured control graph. These are:
However, if a subgraph possesses multiple entry or exit points then it cannot be reduced. The use of multiple entry and exit points breaks the most fundamental rule of structured programming.
The example below has a M07 value of 4.
void g( int n, int pos, int force ) /* M07 = 4
Cannot reduce control graph to
Cyclomatic Complexity of 1 */
{
int nlines = 0;
while ( --n >= 0 )
{
pos = back_line( pos );
if ( pos == 0 )
{
if ( ! force )
{
break;
}
++nlines;
}
}
}
[1] McCabe, T. J. (1976) A Complexity Measure, IEEE Transactions on Software Engineering, SE-2, pp. 308-320.
Function-Based Metric
This metric is a measure of the number of exit points in a software component and is calculated by counting the number of return statements. A function that has no return statements will have an M19 value of zero even though it will exit when falling through the last statement. This is regardless of whether the function is declared to have a return value or not (i.e. returns void). Calls to non-returning functions such as exit() or abort() are ignored by this metric.
The example below has an M19 value of 3.
void f( int a )
{
return; /* 1 */
if ( a )
return; /* 2 */
a++;
return; /* 3 */
}
Function-Based Metric
This metric is defined as the number of functions calling the designated function. The number of calls to a function is an indicator of criticality. The more a function is called, the more critical it is and, therefore, the more reliable it should be.
Function-Based Metric
This is an extension to the cyclomatic complexity metric. It is expressed as a pair of numbers, conventionally separated by a colon. Myer's Interval is defined as CYC : CYC + L
Cyclomatic complexity (CYC) is a measure of the number of decisions in the control flow of a function. L is the value of the QAC LOP metric which is a measure of the number of logical operators (&&, ||) in the conditional expressions of a function. A high value of L indicates that there are many compound decisions, which makes the code more difficult to understand. A Myer's interval of 10 is considered very high.
The example below has a MCC value of 3:4 because the cyclomatic complexity is 3 and there is one connective (&&) used in the conditions.
int divide( int x, int y)
{
if (y != 0) /* Condition 1 */
{
return x / y;
} else if (x == 0 && y > 2) /* Condition 2 */
/* Conditional expr 1 */
{
return 1;
} else
{
printf( "div by zero\n");
return 0;
}
}
Note:
In the calculation of MCC, the ternary operator (?:) is ignored.
When exporting metric values or displaying in the Metrics Browser, rather than attempting to display a value pair, the value of L is chosen for MCC.
Function-Based Metric
This metric is a measure of the maximum control flow nesting in your source code.
You can reduce the value of this metric by turning your nesting into separate functions. This will improve the readability of the code by reducing both the nesting and the average cyclomatic complexity per function.
The code example below has an MIF value of 3.
int divide( int x, int y)
{
if (y != 0) /* 1 */
{
return (x/y);
} else if (x == 0) /* 2 */
{
return 1;
} else
{
printf( "Divide by zero\n");
while (x > 1) /* 3 */
printf( "x = %i", x);
return 0;
}
}
MIF is incremented in switch, do, while, if and for statements. The nesting level of code is not always visually apparent from the indentation of the code. In particular, an else if construct increases the level of nesting in the control flow structure but is conventionally written without additional indentation.
MIF is one of the three standard metrics used by QAC for demographic analysis.
Function-Based Metric
This metric counts the number of declared parameters in the function argument list. Note that ellipsis parameters are ignored.
Function-Based Metric
Hopkins, in Hatton & Hopkins[1] investigated software with a known audit history and observed a correlation between Static Path Count (PTH) and the number of bugs that had been found. This relationship is expressed as PBG.
PBG = log10 ( PTH )
[1] Hatton, L., Hopkins, T.R., (1989) Experiences With Flint, a Software Metrication Tool for Fortran 77, Symposium on Software Tools, Napier Polytechnic, Edinburgh, Scotland.
Function-Based Metric
This is a measure of the number of paths relative to the number of executable lines of code.
PDN = PTH / XLN
PDN is computed as zero when XLN is zero.
Function-Based Metric
This is similar to Nejmeh's[1] NPATH statistic and gives an upper bound on the number of possible paths in the control flow of a function. It is the number of non-cyclic execution paths in a function.
The NPATH value for a sequence of statements at the same nesting level is the product of the NPATH values for each statement and for the nested structures. NPATH is the product of:
Note:
else and default are counted whether they are present or not.
In switch statements, multiple case options on the same branch of the switch statement body are counted once for each independent branch only. For example:
switch( n )
{
case 0:
break; /* NPATH of this branch is 1 */
case 1:
case 2:
break; /* NPATH for case 1 & case 2 combined is 1 */
default:
break; /* NPATH for this default is 1 */
}
Since NPATH cannot be reliably computed if there are goto statements in the function, they are ignored by QAC for the purposes of calculating NPATH.
The following code example has a static path count of 26.
int n;
if ( n )
{
} /* block 1, paths 1 */
else if ( n )
{
if ( n )
{
} /* block 2, paths 1 */
else
{
} /* block 3, paths 1 */
/* block 4, paths block2+block3 = 2 */
switch ( n )
{
case 1 : break;
case 2 : break;
case 3 : break;
case 4 : break;
default: break;
} /* block 5, paths = 5 */
} /* block 6, paths block4*block5 = 10 */
else
{
if ( n )
{
} /* block 7, paths 1 */
else
{
} /* block 8, paths 1 */
} /* block 9, paths block7+block8 = 2 */
/* block 10, paths block1+block6+block9 = 13 */
if ( n )
{
} /* block 11, paths 1 */
else
{
} /* block 12, paths 1 */
/* block 13, paths block11+block12 = 2 */
/* outer block, paths block10*block13 = 26 */
Each condition is treated as disjoint. In other words, no conclusions are drawn about a condition that is tested more than once.
The true path count through a function usually obeys the inequality:
cyclomatic complexity <= true path count <= static path count
Static path count is one of the three standard metrics used by QAC for demographic analysis.
[1] Nejmeh, B.A. (1988), NPATH: A Measure of Execution Path Complexity and its Applications, Comm ACM, 31, (2), p. 188-200.
Function-Based Metric
RET is the count of the reachable return statements in the function, plus one if there exists a reachable implicit return at the } that terminates the function.
The following example shows an implicit return:
void foo( int x, int y )
{
printf( "x=%d, y=%d\n", x, y );
/* Here with implicit return. Hence RET = 1*/
}
Structured Programming requires that every function should have exactly one entry and one exit. This is indicated by a RET value of 1. RET is useful when the programmer wants to concentrate on the functions that do not follow the Structured Programming paradigm. For example, those with switch statements with returns in many or every branch.
Function-Based Metrics
These metrics count the number of statements in the function body. There are 3 variants on the metric:
ST1 is the base definition and counts all statements tabulated below.
ST2 is ST1 except block, empty statements and labels are not counted.
ST3 is ST2 except declarations are not counted.
The following chart shows the statements counted by the STST metrics:
| Statement Kind | ST1 | ST2 | ST3 |
| block | yes | ignore | ignore |
| simple statement followed by ; | yes | yes | yes |
| empty statement | yes | ignore | ignore |
| declaration statement | yes | yes | ignore |
| label | yes | ignore | ignore |
| break | yes | yes | yes |
| continue | yes | yes | yes |
| do | yes | yes | yes |
| for | yes | yes | yes |
| goto | yes | yes | yes |
| if | yes | yes | yes |
| return | yes | yes | yes |
| switch | yes | yes | yes |
| while | yes | yes | yes |
The following example shows statements counted by ST1, which for this function yields a value of 10:
void stst( void )
{
int i; /* 1 */
label_1: /* 2 */
label_2: /* 3 */
switch ( 1 ) /* 4 */
{ /* 5 */
case 0: /* 6 */
case 1: /* 7 */
case 2: /* 8 */
default: /* 9 */
break; /* 10 */
}
}
This metric indicates the maintainability of the function. Number of statements also correlates with most of the metrics defined by Halstead. The greater the number of statements contained in a function, the greater the number of operands and operators, and hence the greater the effort required to understand the function. Functions with high statement counts should be limited. Restructuring into smaller sub-functions is often appropriate.
Function-Based Metric
The number of function calls within a function. Functions with a large number of function calls are more difficult to understand because their functionality is spread across several components. Note that the calculation of SUB is based on the number of function calls and not the number of distinct functions that are called, see CAL.
A large SUB value may be an indication of poor design; for example, a calling tree that spreads too
rapidly.
See Brandl (1990)[1]
for a discussion of design complexity and how it is highlighted by the shape of the calling tree.
The following code example has an SUB value of 4.
extern dothis(int);
extern dothat(int);
extern dotheother(int);
void test()
{
int a, b;
a = 1;
b = 0;
if (a == 1)
{
dothis(a); /* 1 */
} else
{
dothat(a); /* 2 */
}
if (b == 1)
{
dothis(b); /* 3 */
} else
{
dotheother(b); /* 4 */
}
}
[1] Brandl, D.L. (1990), Quality Measures in Design, ACM Sigsoft Software Engineering Notes, vol 15, 1.
[x] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
This metric is the count of all statements within the function body that are guaranteed never to be executed. UNR uses the same method for identifying statements as metric ST1. Hence UNR counts the following as statements if unreachable.
Example yielding UNR = 4
void stunr( unsigned i )
{
if ( i >= 0 )
{
if ( i >= 0 )
{
while ( i >= 0 )
return;
} else
/* unreachable */
{
while ( i >= 0 )
return;
}
}
return; /* unreachable */
}
Function-Based Metric
An unused variable is one that has been defined but which is never referenced. A non-reused variable is a variable that has a value by assignment but which is never used subsequently.
Such variables are generally clutter and are often evidence of 'software ageing', which is the effect of a number of programmers making changes. The code below has an UNV value of 2.
int other_result;
extern int result;
int test()
{
int y; /* Unused */
int z;
z = 1; /* Non-Reused */
return (result + other_result);
}
Function-Based Metric
This is a count of lines in a function body that have code tokens. Comments, braces, and all tokens of declarations are not treated as code tokens. The function below has an XLN value of 9.
void fn( int n )
{
int x;
int y;
if ( x ) /* 1 */
{
x++; /* 2 */
for (;;) /* 3 */
/* Ignore comments */
/* Ignore braces */
{
switch ( n ) /* 4 */
{
case 1 : break; /* 5 */
case 2 : /* 6 */
case 3 : /* 7 */
break /* 8 */
; /* 9 */
}
}
}
}
This metric is used in the computation of the KDN and PDN metrics.
File-Based Metrics
The COCOMO metrics are produced for each source code file. You can display an estimate of development costs for a whole project by choosing the COCOMO Cost Model option from the Reports menu. See Chapter 6: Reports for a discussion of the COCOMO cost model and an explanation of the three programming modes: Organic, Semi-detached, and Embedded.
These metrics estimate the number of programmer-months required to create the source code in the respective environments.
BME = 3.6 * ( TPP / 1000 ) 1.20
BMO = 2.4 * ( TPP / 1000 ) 1.05
BMS = 3.0 * ( TPP / 1000 ) 1.12
File-Based Metric
BUG = 0.001 * EFF2/3
This is an estimate of the number of bugs in the file, based on the number of estimated tokens. Its value would normally be lower than the sum of the function-based PBG values. For a more detailed discussion of software bug estimates, see Hatton and Hopkins,[1].
[1] Hatton, L., Hopkins, T.R., (1989) Experiences With Flint, a Software Metrication Tool for Fortran 77, Symposium on Software Tools, Napier Polytechnic, Edinburgh, Scotland.
Function-Based Metric
This metric is defined to be the number of visible characters in comments, divided by the number of visible characters outside comments. Comment delimiters are ignored. Whitespace characters in strings are treated as visible characters.
A large value of CDN indicates that there may be too many comments, which can make a module difficult to read. A small value indicates that there may not be enough comments, which can make a module difficult to understand.
The code below has 28 visible characters in comments and 33 visible characters in the code. The resulting CDN value is 0.85.
int test()
/* This is a test */
{
int x;
int y;
/* This is another test */
return (x + y);
}
The value of CDN is affected by how QAC counts the comments. QAC can count comments in three possible ways:
Function-Based Metric
This is an estimate of the number of programmer days required to develop the source file. Unlike COCOMO statistics, which are based solely on the number of lines of code, this estimate is derived from the file's difficulty factor. It is a more accurate measure of the development time, especially after the scaling factor has been adjusted for a particular software environment.
DEV = EFF / dev_scaling
where dev_scaling is a scaling factor defined in qac.cfg. The default is 6000.
Function-Based Metric
This is a measure of the difficulty of a translation unit. An average C program has a difficulty of around 12. Anything significantly above this has a rich vocabulary and is potentially difficult to understand.
DIF = VOL / ( (2 + VAR) * log2 (2 + VAR) )
Function-Based Metric
This is a measure of the number of data objects (not including functions) declared with external linkage. It is an indication of the amount of global data being passed between modules. It is always desirable to reduce dependence on global data to a minimum.
extern int result;
int other_result;
main()
{
result = 20 + 30;
other_result = result * 2;
}
The above code sample has an ECT value of 2.
Function-Based Metric
This metric is a measure of the programmer effort involved in the production of a translation unit. It is used to produce a development time estimate.
Function-Based Metric
This metric is a count of the number of function definitions in the file.
Function-Based Metric
See Brandl[1]. Since the actual value of Brandl's metric requires a full, well-structured calling tree, FCO can only be an estimate. A high figure indicates a large change of complexity between levels of the calling tree. The metric is computed from FNC and the SUB values of the component functions in the translation unit:
The code example below has an FCO value of 1 (2 - 2 + 1).
BOOL isActive(CHANNEL c);
BOOL okToRead(TEXTCHANNEL c)
{
return !isActive(c);
}
BOOL okToPrint(PRINTCHANNEL c)
{
return !isActive(c);
}
[1] Brandl, D.L. (1990), Quality Measures in Design, ACM Sigsoft Software Engineering Notes, vol 15, 1.
Function-Based Metric
This metric and also ZIP are predictions derived from the vocabulary analysis metrics OPN and OPT of what the value of TOT should be. If they differ from TOT by more than a factor of 2, it is an indication of an unusual vocabulary. This usually means that either the source code contains sections of rather repetitive code or it has an unusually rich vocabulary. The two metrics are computed as follows:
ZIP = ( OPN + OPT ) * ( 0.5772 + ln (OPN + OPT) )
HAL = OPT * log2 ( OPT ) + OPN *
log2 ( OPN )
Function-Based Metric
This metric is the number of operands in a software component and is one of the Halstead vocabulary analysis metrics. Halstead considered that a component is a series of tokens that can be defined as either operators or operands.
Unlike OPN, this metric is the count of every instance of an operand in a file, regardless of whether or not it is distinct. OPN only counts the operands that are distinct. The code example below has a M20 value of 8.
void f( int a ) /* 1,2 -> f, a */
{
if ( a > 1 ) /* 3,4 -> a, 1 */
{
++a; /* 5 -> a */
while ( a > 1 ) /* 6,7 -> a, 1 */
{
--a; /* 8 -> a */
}
}
}
[x] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
This metric is the number of operators in a software component and is one of the Halstead vocabulary analysis metrics. Halstead considered that a component is a series of tokens that can be defined as either operators or
operands.
Unlike OPT, this metric is the count of every instance of an operator in a file, regardless of whether or not it is distinct. OPT only counts the operators that are distinct. The code example below has a M21 value of 22.
void f( int a ) /* 1,2,3,4 -> void, (, int, ) */
{ /* 5 -> { */
if ( a > 1) /* 6,7,8,9 -> if, (, >, ) */
{ /* 10 ->{ */
++a; /* 11,12 -> ++, ; */
while (a > 1) /* 13,14,15,16 -> while, (, >, ) */
{ /* 17 -> { */
--a; /* 18,19 -> --, ; */
} /* 20 -> } */
} /* 21 -> } */
} /* 22 -> } */
[x] Halstead, Maurice H. (1977). Elements of Software Science.
Function-Based Metric
This metric is the number of statements in a software component. This is a count of semicolons in a file except for the following instances:
The code example below has a M22 value of 5.
void f( int a )
{
struct { int i;
int j; }
ij; /* 1 */
a = 1; /* 2 */
a = 1; a = 2; /* 3,4 */
if
( a >
1 )
{
return; /* 5 */
}
}
Function-Based Metric
This metric is a count of the occurrences of C or C++ style comments in a source file except for those that are within the header of a file. A file header is defined as tokens preceding the first code token or preprocessor directive token.
M28 is based on the method used to compute CDN but differs from CDN in that CDN counts the visible characters within comments, whereas M28 counts the occurrences of comments. The code example below has a M28 value of 2.
/* Header comment 1 Count = 0 */
/* Header comment 2 Count = 0 */
/* Last header comment Count = 0
code follows */
#define CENT 100
/* Non header comment Count = 1 */
void f( int a )
{
/* Block scope comment Count = 2 */
a = CENT;
return;
}
Function-Based Metric
This metric is a count of C style or C++ comments in a source file that are within functions or annotate a line of code at file scope. Comments within functions are all comments at block scope. Comments that annotate code are ones that start or end on the same line as code.
M33 is based on the method used to compute CDN but differs from CDN in that CDN counts the visible characters within comments, whereas M33 counts the occurrences of comments. The code example below has a M33 value of 5.
/* Header comment 1 Count = 0 */
/* Header comment 2 Count = 0 */
/* Last header comment Count = 0
code follows */
#define CENT 100 /* Annotating comment M33 = 1 */
int /* Annotating comment M33 = 2 */
i;
/* Annotating comment M33 = 3 */ int j; /*
Annotating comment M33 = 4 */
/* Non internal comment M33 = 0 */
void f( int a )
{
/* Block scope comment M33 = 5 */
a = CENT;
return;
}
Function-Based Metric
This is the number of distinct operands used in the file. Distinct operands are defined as unique identifiers and each occurrence of a literal.
Most literals, except 0 and 1, are usually distinct within a program. Since macros are usually used for fixed success and failure values (such as TRUE and FALSE), the differences in counting strategies are fairly minimal. The code below has an OPN value of 11.
extern int result; /* 1 -> result */
static int other_result; /* 2 -> other_result */
main() /* 3 -> main */
{
int x; /* 4 -> x */
int y; /* 5 -> y */
int z; /* 6 -> z */
x = 45; /* 7 -> 45 */
y = 45; /* 8 -> 45 */
z = 1; /* 9 -> 1 */
result = 1; /* 10 -> 1 */
other_result = 0; /* 11 -> 0 */
return (x + other_result);
}
Function-Based Metric
This covers any source code tokens not supplied by the user, such as keywords, operators, and punctuation. OPT is used in the calculation of a number of other metrics.
The code below has an OPT value of 11.
extern int result; /* 1,2,3 -> extern, int, ; */
static int other_result; /* 4 -> static */
main() /* 5,6 -> ()*/
{ /* 7 -> { */
int x;
int y;
int z;
x = 45; /* 8 -> = */
y = 45;
z = 1;
result = 1;
other_result = 0;
return (x + other_result); /* 9,10 -> return, + */
} /* 11 -> } */
Function-Based Metric
This metric is computed as the number of variables and functions declared static at file scope. The code example below has an SCT value of 2.
static int other_result; /* 1 */
int result;
static int test() /* 2 */
{
int x;
int y;
int z;
z = 1;
return (x + other_result);
}
File-Based Metric
Also known as the "entropy" H, this metric is a widely recognized algorithm for estimating the program space required to encode the functions in a source file. SHN is measured in bits and is calculated as follows:
SHN = ZIP * log2 (√(OPN + OPT) + ln (OPN + OPT))
File-Based Metrics
The COCOMO metrics are produced for each source code file. You can display an accurate estimate of development costs for a whole project by choosing the COCOMO Cost Model option from the Reports menu. Refer to Chapter 6: Reports for a discussion of the COCOMO cost model and an explanation of the three programming modes: Organic, Semi-detached, and Embedded.
These metrics are a measure of elapsed time in months required to develop the source code in the respective environments.
TDE = 2.5 * BME 0.32
TDO = 2.5 * BMO 0.38
TDS = 2.5 * BMS 0.35
File-Based Metric
This metric is a count of the total number of source lines in the file after pre-processing. The pre-processed
file will reflect the processing of include files, pre-processor directives and the stripping of comment lines.
Empty lines are not counted.
See also TPP
File-Based Metric
This metric is the total number of tokens, not distinct tokens, in the source file. The code example below has an TOT value of 19.
int test() /* 1,2,3,4 */
{ /* 5 */
int x; /* 6,7,8
int y; /* 9,10,11 */
/*Excluded Comment*/
return (x + y); /* 12,13,14,15,16,17,18 */
} /* 19 */
File-Based Metric
This metric is a count of the total number of source lines in the file before pre-processing.
See also TLN
File-Based Metric
The metric represents the total number of distinct identifiers. The code below has an VAR value of 5.
int other_result; /* 1 */
extern int result; /* 2 */
int test() /* 3 */
{
int x; /* 4 */
int y; /* 5 */
return (x + y + other_result);
}
File-Based Metric
This is a measure of the number of bits required for a uniform binary encoding of the program text. It is used to calculate various Halstead vocabulary metrics.
The following is the calculation for the program volume:
VOL = TOT * log 2 ( OPN + OPT )
[x] Halstead, Maurice H. (1977). Elements of Software Science.
File-Based Metric
ZIP = ( OPN + OPT ) * ( 0.5772 + ln (OPN + OPT) )
See HAL.
File-Based Metric
This metric is the total number of characters in the file. Only visible characters are counted, except in string or character literals, in which case all characters are counted and tabs are treated as one character. When counting comment characters, the comment delimiter characters are counted.
File-Based Metric
This metric is the total number of code characters in the file. Only visible characters are counted, except in string or character literals, in which case all characters are counted and tabs are treated as one character. Characters comprising comments are not counted, this includes the comment delimiter characters.
File-Based Metric
This metric is the total number of visible comment characters in the file. The comment delimiter characters are not
counted.
Class-Based Metric
This is a count of the number of methods (member functions) or member objects of other classes accessed by a class. Only classes outside the inheritance hierarchy are considered because you would expect interaction with base and derived classes. Coupling to classes outside the inheritance tree should be viewed with suspicion as it makes the class less independent and less re-usable. This is one of Chidamber & Kemerer's[1] suite of object oriented metrics.
[1] Chidamber, S.R. and Kemerer, C.F. (1991). Towards a Metrics Suite for Object Oriented Design, Proceedings of OOPSLA, '91, Sigplan notices, vol.26, no. 11, ACM Press.
Class-Based Metric
This represents the number of derivations from the furthest base class down to this class. A high figure may indicate that the class depends on accumulated functionality, which makes understanding the class potentially difficult. This is one of the metrics defined by Chidamber & Kemerer.
Class-Based Metric
Methods within a class are partitioned into sets that access independent sets of member objects. The LCM metric is a count of sets of unrelated members for a type.
For example (default):
class cohesive
{
private:
int i1;
int i2;
int i3;
public:
void m1(int a) { i1 = a + i2; }
void m2(int a) { i2 = a; }
void m3(int a) { if (a > i3) ++i3; }
};
This above code sample has a LCM value of 2 because methods m1 and m2 access the set of member objects i1 and i2. Method m3 accesses only i3 and can be viewed as independent of m1 and m2. (m3 is not cohesive with the other two methods).
Similarly, where one method calls another, the set used for inclusion in LCM is the union of the sets from each method.
Variations of the calculation of LCM may explicitly exclude constructors, so the default behavior of CMA is that constructors are excluded when calculating this metric. To include constructors, enable the configuration option "-ProdOption LCM::include_constructor".
If constructors are included, and the constructor for such a type initializes all the members, then the value of LCM is guaranteed to be '1'.
This is one of the metrics defined by Chidamber & Kemerer.
Class-Based Metric
The number of methods declared within a class. This does not include methods declared in base classes. Classes with a large number of methods will be difficult to understand.
Class-Based Metric
This is the number of classes for which this class is an immediate base class. A high figure for this metric indicates greater dependence on the functionality of this class, and more potential knock-on effects from changes to it. This is one of the metrics defined by Chidamber & Kemerer.
Class-Based Metric
This metric indicates the number of inheritances for a class. Root base classes have a value of 0 while classes derived with a single inheritance have a value of 1. Classes that have multiple inheritance are prohibited by some programming standards.
Class-Based Metric
This indicates how functions can potentially be called directly from the class. The response set is calculated as the number of distinct class methods and functions called from the definitions of those methods. This is one of the metrics defined by Chidamber & Kemerer.
Class-Based Metric
This is the sum of cyclomatic complexities (See Cyclomatic complexity (CYC) in Function-Based
Metrics section of this document) for all the methods in the class. In the same way that cyclomatic complexity gives an
indication of the amount of testing required for an individual function, this metric gives an indication of the amount
of testing required for a whole class. This is one of the metrics defined by Chidamber & Kemerer.
Project-Wide Metric
This metric is defined to be the number of recursive paths in the call graph of the project's functions. A recursive path can be for one or more functions. The minimum, and often desirable, value of this metric is zero. Values greater than zero indicate the number of distinct loops in the call graph.
Project-Wide Metric
This metric is the number of functions that are not called in the project. It is the number of nodes in the call graph which are not themselves called. For example, main() is not called; hence the minimum (build) value of 1.
Project-Wide Metric
This metric is the number of function definitions in the project. Note that this metric is the sum of QAC's FNC metric values for each source file included in the project.
Project-Wide Metric
This metric is the sum of cyclomatic complexity values for each function definition in the project.
Note that this metric is the sum of QAC CYC metric values for each source file included in the
project.
Function structure diagrams show the control flow structures within source code. Decisions (if, switch, and the condition part of a loop) are displayed as forks in the structure. The corresponding join, further to the right, indicates where the paths rejoin. Backward arcs, caused by loops, are shown as dotted lines.
The function structure diagrams show the following code structures:
Each component progresses from the left to the right as the control flow would progress through the source code.
static int code = 0;
void funcStraight( void)
{
code = 1;
}
There is only one path through this particular function, which is represented as lying along the x-axis.
static int code = 0;
void funcIf( void)
{
if (code > 0)
{
code = 1;
}
}
This function has two paths. The first path is through the if statement and is shown by the raised line. The second path is where the if condition is false and is represented by the x-axis.
void funcIfElse( void)
{
if (code > 0)
{
code = 3;
} else
{
code = 4;
}
}
This function has two execution paths. The first path is the if sub-statement represented by the raised line. The second path is the else sub-statement represented by the x-axis.
Note that the body of this structure is longer than the body of the if statement. If the two arms of the if-else were not straight line code, the body of the if branch would appear at the left hand end of the raised line and the body of the else branch would appear to the right of the lower line.
static int code = 0;
void funcSwitch( void)
{
switch (code)
{
case 1:
if (code == 1)
{
/* block of code */
}
break;
case 2:
break;
case 3:
if (code == 3)
{
/* block of code */
}
break;
default:
break;
}
}
In the switch statement, the x-axis represents the default action, and each case statement is shown by a raised line. The two briefly raised lines represent the if statements within case 1 and case 3.
The diagram shows how the if statements are staggered. The if of case 1 is shown on the left and the if of case 3 is shown on the right.
static int code = 0;
void funcWhile( void)
{
while (code > 0)
{
--code;
}
}
In the while loop, the x-axis represents the path straight through the function as though the while loop had not been executed. The solid raised line shows the path of the while body. The dotted line shows the loop to the beginning of the while statement.
static int code = 0;
void doSomethingWith(int);
void funcFor( void)
{
int i;
for (i = 0; i > code; ++i)
{
doSomethingWith( i);
}
}
The for loop is similar to the while loop as for loops can be rewritten as while loops. For example, funcFor in the above example could be written as:
void funcFor( void)
{
int i = 0;
while (i > code)
{
/* body */
++i;
}
}
static int code = 0;
void funcWhileIfElse( void)
{
while (code > 0)
{
if (code == 1)
{
code = 0;
} else
{
code--;
}
}
}
This is an if-else contained within a while loop. The first solid raised line represents the while loop while the inner raised solid line represents the if-else loop. Other function structure components can be similarly nested.
static int code = 0;
void funcWhileIfBreak( void)
{
while (code > 0)
{
if (code == 3)
{
break;
}
code--;
}
if (code == 0)
{
code++;
}
}
The break jumps to the end of the while statement and causes a knot. A knot is where the control flow crosses the boundary of another statement block and indicates unstructured code. In this case, break jumps to the end of the while statement and the next part of the program, the if statement, is executed.
static int code = 0;
void funcWhileIfReturn( void)
{
while (code > 0)
{
if (code == 3)
{
return;
}
code--;
}
if (code == 0)
{
code++;
}
}
The return statement causes the program to jump to the end of the function. This jump breaks the control flow and causes a knot in the code.
static int code = 0;
void funcWhileIfContinue( void)
{
while (code > 0)
{
if (code == 3)
{
continue;
}
code--;
}
if (code == 0)
{
code++;
}
}
The continue statement causes the program to jump back to the beginning of the while loop.
static void funcUnReach( int i)
{
if (i)
{
i = 1;
}
goto Bad;
if (i)
{
i = 2;
}
Bad:
if (i)
{
i = 3;
}
return;
}
The raised red section represents code that is unreachable.
The structure and approximate position of the unreachable code is shown. It occurs after the first if condition and before the last if condition. Its position above the main structure shows that the control flow misses the middle if condition.
| All Manual Pages | 
|