gbc tool syntax

The gbc tool is used for building, cleaning, and managing customizations in GBC projects, offering commands like build, info, clean, and theme-graph with various options for customization and debugging. It supports features such as creating widgets, zip files, setting compile modes, and generating JSON graphs for theme variable relationships.

Note:

If you are on Microsoft® Windows®, ensure you are using the legacy Command Prompt (cmd.exe) command-line utility to execute gbc instructions; do not use the Powershell command-line utility. If you are using a Genero Workplace Window, you are using the legacy Command Prompt (cmd.exe) command-line utility.

To run the gbc tool without commands:

gbc [ option [...] ]
Table 1. gbc options
Option Description
-v, -V, --version Display the GBC version.
-h, --help Display help for the gbc command.
-d, --debug Output extra debugging.
The gbc tool supports the following commands:

gbc build

The gbc build command builds the GBC.

gbc build [ option [...] ]
Table 2. gbc build options
Option Description
-A, --all Build GBC without customization and each customization in customization folder in their default build output folders. --build-dist has no effect.
-C, --configuration configuration Build configuration file
-c, --customization customization-id Build a specific customization. Supersedes the value set in file custom.json. Can take customization-id to explicitly build the given GBC customization in dist/customization-id, unless --build-dist is defined.
-nc, --no-customization Build ignoring specified customization (in config file); explicitly build GBC without customization in dist/web (unless --build-dist is defined).
-s, --customization-suffix customizationSuffix Set customization suffix.
-H, --html-cache Uses dated url suffix for resources (default: false).
-z, --create-zip Creates a runtime zip in the archive/ folder.
-m, --compile-mode compileMode
Set compile mode:
  • dev -- every file is provided separately.
  • cdev (default) -- files are packed.
  • prod -- files are packed and minified.
-d, --build-dist buildDist Set a build destination, a custom target build directory relative to dist/ folder.
-t, --themes List themes to build.
-w, --watch Keep rebuild when sources change (default: false).
-D, --debug Output extra debugging (default: false).
-h, --help Display help for the gbc build command.

Examples

To build the customization project specified in the custom.json file: 

$ gbc build

To build the customization named "sample":

$ gbc build --customization sample

To create a zip file of the "sample" customization (the compilation mode is taken from the custom.json file): 

$ gbc build --customization sample --create-zip

To set the compilation mode to "prod", and create a zip file of the "sample" customization:

$ gbc build --customization sample --compile-mode prod --create-zip

To build the GBC project without any customization, and place the results in the gbc-project-dir/dist/web directory:

$ gbc build --no-customization

gbc info

The gbc info command retrieves information about customizations. 

gbc info [ command ] [ option [...] ]
Table 3. gbc info options
Option Description
-h, --help Display help for the gbc info command.
Table 4. gbc info commands
Option Description
buildnumber Returns the current build number in format 'BUILD=<buildnumber>' on the console.
help [ command ] Display help for the named command.

Example

To return the build number (not the version number) of the GBC project:

$ gbc info

gbc clean

The gbc clean command cleans files in the project.

gbc clean [ command ] [ option [...] ]
Table 5. gbc clean options
Option Description
-D, --dry-run List only files that would be cleaned.
-h, --help Display help for the gbc clean command.
Table 6. gbc clean commands
Option Description
tests Clean test binary files in the project.
orig Clean *.orig files in the project.
dependencies Clean node_modules/ folder in the project.
dist [ option [...] ] Clean a customization output or 'dist/web/' folder in the project. To view the available options, see Table 7.
default Clean .cache/, archive/, and dist/ folders in the project.
all Clean all dispensable files in the project.
help [ command ] Display help for the named command.
Table 7. gbc clean dist options
Option Description
-c, --customization customization Clean a specific customization.
-a, --all Clean dist/ complete folder.
-h, --help Display help for the gbc clean dist command.

Examples

To remove all customization projects from the .cache/, archive/, and dist/ folders:

$ gbc clean

To remove all customization projects from the .cache/, archive/, dist/, and node_modules/ folders:

$ gbc clean all

To remove the "sample" project from the dist/ folder:

$ gbc clean dist --customization customization/sample

To remove the dist/ folder and all its built projects:

$ gbc clean dist --all

gbc theme-graph

The gbc theme-graph command builds a tree-structured JSON file representing theme variable relationships, which will help you understand dependencies between theme variables and thereby better understand potential knock-on effects when customizing given variables. The JSON graph file that it outputs can be viewed using a JSON graph viewer. 

gbc theme-graph [ option ] inputFile [ variableNames ... ]
Where:
  • option is described in Table 8.
  • inputFile is the theme json file containing the variables. You can use any json file in the gbc-project-dir/src/theme/definition path. If the inputFile does not exist, the algorithm will generate the JSON data directly from the GBC project. No JSON data file will be created, but the JSON graph data will be generated.
  • variableNames is a space-separated list of theme variable names or a part of variable names (for example, button, field, input, and so on) used to filter on when building the graph.
Table 8. theme-graph options
Option Description
--valueType valueTypes ... Include only nodes in the graph with the specified value types (for example, size, color, and so on). The default is to include all nodes.
-d, --defaultValueFilter Use also the default value for filtering nodes.
-c, --noChildren When building a filtered graph, the child nodes are not queried
-p, --noParents When building a filtered graph, the parent nodes are not queried.
-s, --simple Remove all information in the nodes except the name and relationship.
-h, --help Display help for the theme-graph command.

Examples

Generate a JSON graph from the variables.json file, containing all the theme variables. This will output a large graph to variables.graph.json.

gbc theme-graph variables.json

Generate a JSON graph with all the variables having "button" in their names and include their relationships to ancestor and descendant nodes.

gbc theme-graph variables.json button

Generate a JSON graph with all the variables having "palette" in their names or with the default value filter and include their relationships to ancestor and descendant nodes.

gbc theme-graph variables.json palette --defaultValueFilter

Generate a JSON graph with all the variables having "mt" in their names and include their relationships to their child nodes only.

gbc theme-graph variables.json mt --noParents

Generate a JSON graph with all the variables having "mt" in their names and include their relationships to their parent nodes only.

gbc theme-graph variables.json mt --noChildren

Generate a JSON graph with all the variables having "mt" in their names and include their relationships to ancestor and descendant nodes with a valueType equal to "color".

gbc theme-graph variables.json mt --valueType color

Generate a JSON graph with all the variables having "mt" in their names and include their relationships to ancestor and descendant nodes, displaying only the name and relationship. This will output a simpler graph.

gbc theme-graph variables.json mt --simple

gbc create-widget

The gbc create-widget command generates the base structure for a widget by creating the necessary JavaScript, template, and SCSS files in the js and sass directories of your customization directory.

gbc create-widget [ options ] customizationPath widgetName
Where:
  • options are described in Table 9.
  • customizationPath is the path to your customization folder where the widget files will be created.
  • widgetName is the name of the widget to create (for example, MyCustomWidget).
Table 9. create-widget options
Option Description

--base

The base widget to extend (optional). If not specified it defaults to WidgetBase
Tip: Identifying widgets

If unsure which widget to modify, use browser developer inspection tools (press F12) to find the CSS class ending with "...Widget" and identify the widget. For more information, refer to the JavaScript source files in the directory gbc-project-dir/src/js/base/widget/widgets and its subdirectories, where you can read the class documentation and comments for each widget implementation.
--override Override the base template and automatically register the widget with WidgetFactory. You can only use the --override option when the --base option is also specified.
-h, --help Display help for the create-widget command.

Examples

There are different ways of using the command, depending on what you want to achieve:
  • Generate a new widget: if you just want the basic structure of a widget based on the default WidgetBase:
    gbc create-widget customizationPath widgetName
    For example:
    gbc create-widget customization/myCusto MyCustomWidget
    This command generates a JavaScript, a template, and SCSS file that you can customize:
    • JavaScript file: MyCustomWidget.js
    • Template file: MyCustomWidget.tpl.html
    • SCSS file: MyCustomWidget.scss, which is referenced by an import statement in the customization.scss file.
  • Extend a custom base widget: if you want to extend a custom base widget (for example EditWidget), use the --base option:
    gbc create-widget customizationPath widgetName --base baseWidget
    For example:
    gbc create-widget customization/myCusto MyEditWidget --base EditWidget
    This command generates a JavaScript, a template, and an SCSS file that inherit the contents of the specified base widget file, allowing you to add your own customizations or modifications.
    • JavaScript file: MyEditWidget.js
    • Template file: MyEditWidget.tpl.html
    • SCSS file: MyEditWidget.scss, which is referenced by an import statement in the customization.scss file.
  • Override a custom base widget: if you want to replace the specified base widget and register your new widget with the WidgetFactory instead, use the --override option. You can only use the --override option when the --base option is also specified:
    gbc create-widget customizationPath widgetName --base baseWidget --override
    For example:
    gbc create-widget customization/myCusto MyEditWidget --base EditWidget --override
    This command generates a JavaScript, a template, and an SCSS file that inherit the contents of the specified base widget file, allowing you to add your own customizations or modifications.
    • JavaScript file: MyEditWidget.js
    • Template file: MyEditWidget.tpl.html
    • SCSS file: MyEditWidget.scss, which is referenced by an import statement in the customization.scss file.

gbc create-test

The gbc create-test command generates a base .spec.ts file in the TypeScript format for writing TestCafe tests in a GBC project. It helps you quickly set up new test files that follow the expected structure and import the necessary GBC test utilities.

gbc create-test testname [ customApp ]
Where:
  • testname is the name of the test or full path to the test. For example, this can be GBC-1234 or tests/mydir/GBC-1234.spec.ts.
  • customApp is optional. It is the name of the Genero sample app the test targets.
Table 10. create-test options
Option Description
-h, --help Display help for the create-test command.

Examples

There are different ways of using the command, depending on what you want to achieve:
  • Create a test named GBC-1234 in the default location:
    gbc create-test GBC-1234
    • A test file is created at tests/automated_tests/GBC-1234.spec.ts.
    • The test will run against the deployed GBC-1234 sample.
  • Create a test file in a specific directory:
    gbc create-test tests/custom/GBC-1234.spec.ts
  • Create a test and link it to a specific application:
    gbc create-test GBC-5432 myTestcase
    • Adds customApp: "myTestcase" in the test metadata.
    • The test will run against the deployed myTestcase sample.

Generated template

Each test includes:
  • An import from gbcCase.ts
  • A startTest() block with metadata (keywords, customApp)
  • An empty gbcTestRun() ready to be filled in with your test logic.
import { gbcTestRun, startTest } from '../../tools/testcafe/lib/gbcCase';

startTest("GBC-5432", {
    keywords: [],
    customApp: "ux"
});

gbcTestRun("Test template for GBC-5432", async te => {
    // Your test logic here
});

Once created, the test can be executed using the gbc testcafe command, for example, gbc testcafe -f GBC-5432. For details and more examples, go to gbc testcafe.

gbc testcafe

The gbc testcafe command runs tests using TestCafe, with configuration adapted to GBC projects. It simplifies the execution of automated tests in your customization environment.

gbc testcafe [ options ]
Table 11. testcafe options
Option Description
-B browser

Specifies the browser or environment to run tests in:

  • chrome-canary: Launches Chrome Canary
  • chrome:emulation:device: Launches Chrome with a mobile device profile. Replace device with a Chrome DevTools device name (for example, "iPhone 1", "Pixel 7", "Pixel 2")
  • chrome:headless: Launches Chrome in headless mode
  • chromium: Launches Chromium
  • edge: Launches Microsoft Edge (desktop)
  • firefox: Launches Mozilla Firefox™ (desktop)
  • gdc: Launches tests on GDC. Requires the GDCDIR environment variable to point to the GDC installation directory
  • opera: Launches Opera (desktop)
  • remote: Starts a local or remote connection server and displays a URL + QR code to connect from another browser/device
  • remote:android: Remote connection, Android™ Chrome (mobile context)
  • remote:gdc: Remote connection via GDC (desktop)
  • remote:gma: Remote connection, GMA (Android)
  • remote:gmi: Remote connection, GMI (iOS)
  • remote:ios: Remote connection, iOS Safari® (mobile context)
  • safari: Launches Apple® Safari (desktop, macOS™ only)
-f name_filter Runs a specified test by fixture name, where the fixture name ends in .spec.ts.
-F folder Deploy all testcases from a specific folder.
-h, --help Display help for the create-test command.

Conventions

All test files must be placed inside the tests/automated_tests/ folder at the root of your GBC project.

Test files should follow the .spec.ts naming convention (for example. login.spec.ts, search.spec.ts).
Important:

We recommend using the gbc create-test command to generate your .spec.ts test files. This ensures they are created with the correct structure and in the right location.

Examples

There are different ways of using the command, depending on what you want to achieve:
  • Run all tests on Chrome (default):
    gbc testcafe
  • Run all tests using the Firefox browser:
    gbc testcafe -B firefox
  • Run a specific test file (for example, myTest.spec.ts):
    gbc testcafe -f myTest
  • Run a specific test with mobile emulation (for example, Pixel 2):
    gbc testcafe -f myTest -B chrome:emulation:device=Pixel 2

gbc testcase

The gbc testcase command compiles and deploys one or more testcases (.xcf). It takes care of:
  • Compiling Genero source (.4gl) and form (.per) files.
  • Building a Genero Archive (.gar).
  • Deploying the Genero Archive to the GAS using the gasadmin command.
gbc testcase [ options ]
Table 12. testcase options
Option Description
-f name_filter Deploy only testcases matching a name filter.
-F folder Deploy all testcases from a specific folder.
-h, --help Display help for the create-test command.

Conventions

Place all your testcase projects under a tests/ folder located at the root of your GBC project.

Each testcase must include a .xcf configuration file, placed in the same directory as its corresponding source (.4gl and .per) files.

We recommend organizing each testcase in its own subfolder, for example:

tests/genero_sample/myTestcase
├── myTestcase.xcf
├── myTestcase.4gl
├── myTestcase.per

Examples

There are different ways of using the command, depending on what you want to achieve:
  • Deploy all testcases in the default tests/ folder:
    gbc testcase
  • Deploy only testcases matching a name filter (for example, myTestcase.xcf):
    gbc testcase -f myTestcase
  • Deploy all testcases from a specific folder (for example, test/genero_sample/customCases:
    gbc testcase -F tests/genero_sample/customCases