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

Overview

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 any file referenced by the --configurationfile 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 will be merged with default values contained in .build/config/build.defaults.json

The gbc command provides arguments to override the settings in these files. See GBC build tool reference.

Compilation configuration contents

The compilation 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

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

• mode defines the compilation mode. Possible values are:

  "cdev"	Default value. Compiles 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"	Compiles 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"	Compiles the selected customization project for production. It compress all sources files in one file, and minifies 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 as it is not human readable.

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

• customization defines the customization to compile. Possible values are:

  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"	Compiles GBC with cutomization 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 compilation products. Default will be as defined in customization rule. A path can be set here. If the path is relative, it will be relative to gbc-project-dir/dist

themes entry

The themes entry remains in the compilation configuration file only for backwards compatibility. It is recommended that you implement themes locally within a customization.

To define themes locally within a customization, see Add a theme.

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