Waf User Options and Settings

In Lumberyard, the Waf options for configure and build time operations in are determined primarily by the following files in the lumberyard_version\dev\_WAF_ subdirectory:

• default_settings.json – Declares most of the configurable settings that control how Lumberyard and its game projects are built, including the default values.
• Platform-specific settings – Settings and defaults declared in the settings sections of .json files in the lumberyard_version\dev\_WAF_\settings\platforms subdirectory, including the following:
  • common.android.json – Options for Android.
  • platform.darwin_x64.json – Options for macOS.
  • platform.ios.json – Options for iOS.
  • common.win_msvc.json – Windows options for Microsoft Visual Studio.
  • platform.win_x64_vs2017.json – Windows options for Microsoft Visual Studio 2017.
  • platform.win_x64_vs2019.json – Windows options for Microsoft Visual Studio 2019.
• user_settings.options – Use this file to override default values defined in the default_settings.json file and platform-specific settings files.

Topics

• default_settings.json
• user_settings.options
• Waf User Settings (user_settings.options)

default_settings.json

The default_settings.json file and the settings sections of platform-specific .json files use the following format to organize related settings into groups:

"Group Name":[
    {
            "long_form": "Command line form",
            "short_form": "Optional short form of the command line option",
            "attribute": "Waf option attribute",
            "default_value": "Default value",
            "description": "Brief description of the setting"
      },...
],
...

Each option can have the following attributes:

• long_form – The long form of the command line argument that Waf accepts as a command-line override to the setting. This overrides both the default value and any override value in the user_settings.options file. The long form is usually preceded with a double hyphen (for example, --enable-my-option).
• short_form – (Optional) The short form of the command argument override option (for example, -s).
• attribute – The name of the attribute for configure and builds. The attribute is set to the Options WAF module object. This form of the attribute name is used in the user_settings.options override file.
• default_value – The default value if the setting is not overridden in the user_settings.options file or by the related command line argument.
• description – A brief description of the option.

The following example shows the enabled_game_projects attribute in the Game Projects section of the default_settings.json file.

...  
"Game Projects": [
        {
            "long_form": "--enabled-game-projects", 
            "attribute": "enabled_game_projects", 
            "default_value": "StarterGame,CloudGemSamples", 
            "description": "Comma-separated list of game projects to enable for compiling"
        }
    ],
...

user_settings.options

Use the user_settings.options file to override the default values specified in default_settings.json and platform-specific settings .json files. This configuration file is in a standard .cfg file format (not .json) with section names in brackets, as in the following example:

[Game Projects]
;enabled_game_projects = StarterGame,CloudGemSamples

The groupings are defined in the default_settings.json file and in the platform-specific settings .json files. The user_settings.options file uses the form of the attribute for each setting as it is defined in the corresponding .json file.

Overriding Default Values

The default values are commented out with a semi-colon ‘;’ comment token at the beginning of each line in the user_settings.options file. To override a value, remove the semicolon from the beginning of the line and set the attribute to the value that you want. For example, the option to use IncrediBuild is off (False) by default. If you want to set it to True, modify the corresponding section of the user_settings.options file to resemble the following:

[Incredibuild Options]
use_incredibuild = True
;incredibuild_max_cores = 128
;auto_update_incredibuild_settings = False
;incredibuild_profile = Tools/build/waf-1.7.13/profile.xml

Overriding user_settings.options Changes

If you use the the user_settings.options file to override a default value like use_incredibuild, you can override the change temporarily by using the command line argument defined for the setting, as shown in the following example:

lmbr_waf build_win_x64_vs2017_profile -p all --use-incredibuild=False

Note
Using the lmbr_waf command to override a value does not update the value in the user_settings.options file.

Waf User Settings (user_settings.options)

Global Waf build system settings are specified in the user_settings.options file located in the lumberyard_version\dev\_WAF_ subdirectory. If the user_settings.options file does not exist, Lumberyard uses the default_settings.json and platform-specific .json files to create a new one automatically. Every build that runs refers to this file to get the option values specific to the build.

The settings listed can be modified in the file directly, or through the Lumberyard WAF settings dialog box. To invoke the settings dialog box, enter show_option_dialog command into Waf as follows:

lmbr_waf show_option_dialog

The tables in the following sections describe the options available for override in the user_settings.options file. To override any setting, you can use the Override Parameter for the attribute. For more information, see Overriding user_settings.options Changes.

Topics

• default_settings.json Options
• Output Folder Options
• Platform-Specific Options

default_settings.json Options

The following tables describe the options defined in the default_settings.json file.

Build Options

Deployment Options

Game Projects

IncrediBuild Options

Misc Options

Packaging Options

Visual Studio Project Generator

Output Folder Options

Output folder options determine build output paths and folder name extensions for specific types of builds and environments.

The output path attributes in the Output Folder table can have configuration-based extensions from the Output Folder Name Extensions table. The output path attributes are autogenerated by Waf from the enabled platforms. The default values are defined by the default_folder_name attribute in each target’s lumberyard_version\dev\_WAF_\settings\platforms\platform.target.json\ file.

Output Folder

The following name extensions are appended to the output folder based on the target platform builds. These configuration extension options are autogenerated by Waf. The default values are defined by the default_output_ext attribute for each configuration in the lumberyard_version\dev\_WAF_\settings\build_configurations.json file.

Output Folder Name Extensions

Platform-Specific Options

Specific settings for Android, iOS, macOS, and Windows are defined in files located in the lumberyard_version\dev\_WAF_\settings\platforms\ directory as noted.

All Platforms

The following settings define whether or not a platform is enabled to build. The default value comes from the value of the enabled key found in each platform-specific file in the lumberyard_version\dev\_WAF_\settings\platforms\ directory.

Enable Platform

Android

This section has been relocated to another part of the Lumberyard documentation, and is now part of the Reference for Android. See Waf settings.

iOS

The following settings for iOS are defined in the lumberyard_version\dev\_WAF_\settings\platforms\platform.ios.json file.

iOS Options

iOS Project Generator

macOS

The following settings for macOS are defined in the lumberyard_version\dev\_WAF_\settings\platforms\platfrom.darwin_x64.json file.

Mac Options

Mac Project Generator

Windows

The following settings for Visual Studio are defined in the lumberyard_version\dev\_WAF_\settings\platforms\common.win_msvc.json file.

Visual Studio Options

The following settings for Visual Studio 2017 are defined in the lumberyard_version\dev\_WAF_\settings\platforms\platform.win_x64_vs2017.json file.

Visual Studio 2017 Options

The following settings for Visual Studio 2019 are defined in the lumberyard_version\dev\_WAF_\settings\platforms\platform.win_x64_vs2019.json file.

Visual Studio 2019 Options