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.
- 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®.
Verify your third-party software
-
If you have installed the tools properly, these commands will successfully
return the version numbers.
$ node -v
v16.17.0
$ npm -v
8.15.0
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 folder 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
-
To test your newly built customization, execute this command to run the
standalone GAS:
$ httpdispatch -E res.path.gbc.user=gbc-project-dir/dist/customization
Tip:
- Launch the Genero Workplace Window to ensure an environment suitable for Genero commands (such
as
httpdispatch
).
- It can helpful to add the following 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.
The resource res.path.gbc.user
amends the default
GBC_LOOKUP_PATH
. To run a given application using a
given customization, amend the application URL with the query string
parameter gbc=customization-name
.
For example, 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
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.