Configure your build

This procedure shows you how to provide build instructions with a "build configuration file".

When you execute the gbc build command, the build process requires information to complete the build. This information can be stored in a file:

  • In the file gbc-project-dir/custom.json, which is provided as the default example in every project.
  • In a file referenced by the --configuration argument of the gbc build command.
  • If neither of the previously mentioned files exist, gbc build uses the file .build/config/build.defaults.json.
Note:

If custom.json or a --configuration= file is provided, their values are merged with default values contained in .build/config/build.defaults.json.

Note:

The gbc command provides arguments to override the settings in these files. See gbc tool syntax.

The build configuration file is a JSON file.

/// sample custom.json file
{
  "compile": {
    "mode": "cdev",
    "customization": "customization/sample"
  },
   /// […]
}

The JSON object provided in this file has two main entries, compile and themes.

compile entry

The compile contains general build options. It is a JSON object and can have the following properties:

  • mode defines the build mode. Possible values are described in Table 1.
    Table 1. mode values
    "cdev" Default value. Builds the selected customization project for development. It compress all sources files in one file, yet is still human readable as it is not minified. It is possible to debug easily and it's faster than dev mode.
    "dev" Builds the selected customization project for development. It keeps all source files uncompressed/un-minified, which is easier to use when you want to find a function in a specific file while developing features. The main issue with dev mode is that GBC has many source files; it makes it slower to render.
    "prod" Builds the selected customization project for production. It compress all sources files in one file, and minimizes it. It is optimized for the browser, which makes it faster than either dev and cdev mode. This mode should not be used for developing / debugging, because it is not human readable.
    Note:

    These modes are documented if you type gbc build --help.

  • customization defines the customization to build. Possible values are described in Table 2.
    Table 2. customization values
    false Default value. No customization is applied, only bare GBC. Generates deliverables in gbc-project-dir/dist/web. This distribution is equivalent to the standard GBC runtime package.
    "NONE" Same as false.
    true Generates the sample customization. It is the same as having "customization":"customization/sample".
    "any/path" Builds GBC with customization at "any/path" folder relative to gbc-project-dir or, if not found, to gbc-project-dir/customization. If an absolute path is set, you must declare buildDist as well. Generates the specified customization project in gbc-project-dir/dist/any/path.
  • buildDist defines where to put the built products. Default is defined in customization rule. A path can be set here. If the path is relative, it will be gbc-project-dir/dist.

themes entry

The themes entry remains in the build configuration file only for backwards compatibility. It is recommended that you implement themes locally within a customization; see Working with themes.

Note:

If you define themes in your build configuration file, it does not merge with .build/config/build.defaults.json contents; it replaces the content instead.