Set up your GBC build environment

Before you customize GBC, you need to prepare your working environment. Preparing your environment starts with the installation of third-party software, followed by the download and preparation of the GBC project package.

Note:

If you have installed a previous version of the GBC build environment, it is recommended that you install your new GBC build environment into a new directory.

Required third-party software

You need to have Node.js installed on your system. You can either install Node.js directly by following the instructions below, or you can use a version manager like Node Version Manager (NVM) to manage different versions of Node.js.

For Windows®, you can download and install NVM from GitHub here. For Linux® and macOS™, you can find the installation instructions here.

Important: LTS version Node.js

It is recommended to use the latest Long-Term Support (LTS) version of Node.js® in preference to the Current version. The LTS is the recommended version, as it is stable and receives updates for a longer period, while the current version may contain the latest features but may not be as stable as the LTS version.

Tip:

It is recommended that you regularly update your Node.js version even if you have already installed Node.js®. This ensures you are using the latest version every time you set up a new GBC project.

  1. Download Node.js

    In this step, you will download a file to install Node.js. For additional installation options, visit nodejs.org. Navigate to the official Node.js website at nodejs.org and download the most recent Long-Term Support (LTS) version.

  2. Install Node.js.
    • For Windows®, run the installer: open the downloaded .msi file.

      A wizard guides you through the installation process. Choose the installation location, the default is usually fine. At the option to select the components you want to install, accept the default options as they are usually fine.

    • For Linux®, extract the downloaded .xz file to a location of your choice.
      sudo tar -xf node-vversion-linux-x64.tar.xz 
      After extracting the files, remember to add the path to the node's bin directory to your PATH environment variable.
    • For macOS™, run the installer: open the downloaded .pkg file.

      A wizard guides you through the installation process. Choose the installation location, the default is usually fine. Enter your password if prompted to complete the installation.

Verify your third-party software

  1. Verify the Installation.
    If you have installed Node.js properly, these commands will display the installed versions of Node.js and npm, respectively. For example:
    $ node -v
    version number
    $ npm -v
    version number

Set up your GBC project

With Node.js installed, download the GBC project package and prepare it for your customization efforts.

  1. Download the latest GBC project package from the Four Js Products download area.
  2. Extract it to a location of your choosing. This directory is known as the "GBC project directory".
    Each new GBC project package should be extracted to a new, empty directory. Do not extract on top of an existing GBC project directory.
    The Genero Browser Client User Guide uses the placeholder variable gbc-project-dir to refer to the GBC project directory; when encountered, replace with the path to your GBC project directory.
  3. From a command prompt, navigate to the GBC project directory.
    $ cd gbc-project-dir
    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.

  4. Install the Node Package Manager (npm) in the GBC project directory.
    $ npm install
    Note:
    • You must have internet access.
    • Run this command whenever you get a new version of the project package.
  5. Install the gbc build package using the Node Package Manager.
    • Install the gbc command globally with your node.js installation. You may need super-user rights on your system.
      $ npm run install-gbc
    • If you don’t have rights to install new tools globally on your system, you can configure NPM to install the gbc build tool in a directory you have read/write access. For example:
      npm config set prefix /usr/npm-packages-directory
      npm run install-gbc

      NPM is configured to install the package into the "prefix" directory instead of the default installation directory, and now you can run the command to install the GBC tool in your gbc-project-dir.

      To use the gbc build tool globally, you must also add the path to /usr/npm-packages-directory in your PATH environment variable.
      On Linux/UNIX /macOS
      export PATH=/usr/npm-packages-directory:${PATH} 
      On Windows:
      set PATH=\usr\npm-packages-directory;%PATH%
    Note:
    • You must have internet access.
    • Unless you have reinstalled Node.js®, this command is only needed once.
  6. Execute the default build.
    $ gbc build
    The gbc-project-dir/dist/customization/sample directory is created. It contains the built version of the GBC with the provided customization sample defined in gbc-project-dir/customization/sample.
    Warning:

    You may encounter GBC build errors that require you to upgrade Node.js®. After you have upgraded Node.js®, delete the GBC project you were setting up, and start with a fresh, unzipped GBC project.

Test using the standalone GAS

  1. Test your newly-built customization.
    1. At a console, start the standalone GAS with the path to your project's dist/customization directory.
      Tip:
      • Launch the Genero Workplace Window to ensure an environment suitable for Genero commands (such as httpdispatch).
      • It can be helpful to add the following log arguments to the httpdispatch command:
        • -E res.log.output.type=CONSOLE,DAILYFILE
        • -E res.log.categories_filter=ALL
      • Use a dedicated console to run the httpdispatch command. This allows you to rebuild your GBC customization without needing to re-execute httpdispatch afterwards.
      $ httpdispatch -E res.path.gbc.user=gbc-project-dir/dist/customization

      The resource res.path.gbc.user amends the default GBC_LOOKUP_PATH.

    2. To run the Genero demo application using the default customization (named sample) built earlier in this procedure, open the URL for your GAS in a browser:
      GAS 5.00 and greater
      http://localhost:6394/ua/r/demo?gbc=sample
      GAS prior to 5.00
      http://localhost:6394/ua/r/gwc-demo?gbc=sample
      To run a given application using a given customization, amend the application URL with the query string parameter gbc=customization-name.

Build a project continuously

To make the development cycle quicker, there is a built-in rule that will watch for any modifications in your customization, then immediately rebuild the customization when modifications are detected.

  1. To use this rule, execute the following command from a dedicated command prompt:
    $ gbc build -w

    You will need to refresh your browser once the build completes.

    Note:
    • Use a dedicated console, as this option is designed to run permanently. It will not return to the command prompt.
    • Depending on your operating system, it is advised to abort and re-run the command if you add new files.

What to do next

Create your own customization project