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.jsIt 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.
-
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.
-
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
-
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.
-
Download the latest GBC project package from the Four Js Products download
area.
-
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.
-
From a command prompt, navigate to the GBC project directory.
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.
-
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.
-
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.
-
Execute the default 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
-
Test your newly-built customization.
-
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
.
-
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.
-
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.