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.

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

3. 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.

4. Download the latest GBC project package from the Four Js Products download area.
5. 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.
6. 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.

7. 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.
8. 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.
9. 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

10. 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.

11. 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.