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 these tools on your system:
- Node.js® - You can install Node.js® directly, or you can use NVM
(Node Version Manager) to install Node.js®. To use NVM, see the instructions
below.
Important:
Node.js® 16 or greater is required. It is recommended to use Node.js® 16, as Node.js® 17 or 18 can cause errors during
compilation.
- git
Use NVM to install and manage Node.js®
NVM is a useful tool for the installation and management of versions of Node.js®.
Tip:
It is recommended that you follow these steps even if you have already installed NVM and Node.js®. This ensures you are using the latest versions of these products every
time you set up a new GBC project.
-
Download and install the latest release of NVM.
- For Windows®, see here.
- For Linux® and macOS™, see here.
-
Use NVM to install Node.js®.
Important:
It is recommended to use Node.js® 16, as Node.js® 17 or
18 can cause errors during compilation.
- For Windows®, use the
"nvm list available"
command to
identify the latest long-term support
versions:nvm list available
Important:
On Windows® you must run
the command as administrator, it is not enough to simply have administrator
permissions.
Then use the "nvm install"
and "nvm use"
commands to install
and configure the latest 16.X.X versions of Node.js® and npm. For
example:
nvm install 16.18.1
nvm use 16.18.1
- For Linux and macOS, use the
"nvm list available"
command to
identify the latest long-term support
versions:$ nvm list available
Use the
"nvm install"
and "nvm use"
commands to install and configure the
latest 16.X.X versions of Node.js® and
npm:
$ nvm install 16.18.1
$ nvm use 16.18.1
Verify your third-party software
-
If you have installed the tools properly, these commands will successfully return the version
numbers. For example:
$ node -v
v16.18.1
$ npm -v
8.19.2
Set up your GBC project
With the third-party tools 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.
$ npm run install-gbc
Note:
- You must have internet access.
- You may need super-user rights on your system.
- 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 NVM or Node.js®. After you have upgraded NVM or 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 using the default customization (named
sample
) built
earlier in this procedure, open the following URL in a browser:
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.