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 Node.js® on your system. 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: LTS version Node.js

It is recommended to use the lastest LTS version of Node.js® 20 or greater, as older versions are no longer compatible and may cause errors during compilation.

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: LTS version Node.js
It is recommended to use the lastest LTS version of Node.js® 20 or greater, as older versions are no longer compatible and may 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 lastest LTS version 20.X.X versions of Node.js® and npm. For example:
```
nvm install 20.9.0
nvm use 20.9.0 
```
- For Linux and macOS, use the "nvm list available" command to identify the latest long-term support versions:
```
$ nvm list available
```
  Then use the "nvm install" and "nvm use" commands to install and configure the lastest LTS version 20.X.X versions of Node.js® and npm. For example:
```
$ nvm install 20.9.0
$ nvm use 20.9.0 
```

Verify your third-party software

If you have installed the tools properly, these commands will successfully return the version numbers. For example:
```
$ node -v
v20.9.0
$ npm -v
10.1.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.
```
$ 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.
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.
```
$ 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 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.
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.

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