Lumberyard
User Guide (Version 1.21)

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.

    • platform.win_x64_vs2015.json – Windows options for Microsoft Visual Studio 2015.

    • platform.win_x64_vs2017.json – Windows options for Microsoft Visual Studio 2017.

  • user_settings.options – Use this file to override default values defined in the default_settings.json file and platform-specific settings files.

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_installation\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

            Waf settings dialog box.

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

default_settings.json Options

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

Build Options

Attribute Override Parameter Description Default
copy_3rd_party_pdbs --copy-3rd-party-pdbs

Copies .pdb files from third party libraries for debugging.

Warning

This option increases the memory usage of your Visual Studio development environment.

True
crash_handler_token --crash-handler-token Token that you use to submit crash reports.
crash_handler_url --crash-handler-url Endpoint where you submit crash reports.
enable_dynamic_file_globbing --enable-dynamic-file-globbing

Enables globbing of files during all build operations, globbing only once during configure.

Note

Excessive usage of file globbing negatively impacts build performance.

False
enable_link_time_optimization --enable-link-time-optimization If true, link time optimizations and code generation are enabled in the performance and release configurations. False
enable_memory_tracking --enable-memory-tracking

Enable the AZCORE_ENABLE_MEMORY_TRACKING define, which allows the Memory Driller to run and track all allocations.

Note

This option severely impacts code execution times.

False
enable_msvc_timings --enable-msvc-timings Enable output timing information for msvc compile and link operations. False
enable_whole_program_optimization --enable-whole-program-optimization If set to True, whole program optimizations are enabled for performance and release builds. False
external_crash_reporting --external-crash-reporting Zip and upload symbols and build client with external crash reporting enabled. The value set is an additional build tag that is passed to the crash reporter system.
gems_optional --gems-optional Allows building of projects without gems.json files. False
generate_debug_info --generate-debug-info Option to generate debug symbols and .pdb files for the build. True
generate_map_file --generate-map-file Generate a map file during linking if the platform supports it. False
generate_sig_debug_output

--sig-delta

-s

Generate debug output showing signature differences that caused a task to rerun. False
layout_binaries_only --layout-binaries-only Update only the binaries in a current layout. This supports programmer rapid iteration mode. False
layout_hard_linking --layout-hard-linking If true, layouts are hard links, not full copies of files. True
layout_include_pdbs --layout-include-pdbs When adding the binaries to the layout, include the .pdb files. False
max_parallel_link --max-parallel-link Controls the number of C++ linking operations that happen in parallel. 2
packaged_build_time --packaged-build-time A float value indicating the time that the build was packaged.
product_sku -product-sku Enables a project wide define PRODUCT_SKU_value. The specified value alters where .pak files are built to and read from and determines which platform resources are used in the gem\resources\ directory. For example, for a demo version of the game, you could set product_sku = demo. After PRODUCT_SKU_demo is defined, you can disable systems based on its value. default
symbol_token --symbol-token Specify the token used for uploading symbols.
uber_file_size --uber-file-size Maximum content size of auto-generated uber files. 307200
upload_symbol_list --upload-symbol-list Specify the list of symbol patterns to upload for crash reporting.
use_crcfix --use-crcfix Use the crcfix tool to precompute CRCs in AZ_CRC macros. True
use_debug_code_generator --use_debug_code_generator Uses the version of the code generator located in the \Bin64xxxx.Debug directory instead of the \Bin64xxxx directory. False
use_precompiled_header --use-precompiled-header Use a precompiled header for compilation where applicable. True
use_uber_files --use-uber-files Use uber files for compilation. False
version --force-version The version of the game project to embed in the game launchers. 0.0.0.0
win_build_renderer --win-build-renderer Specifies the type of renderer for a monolithic build. Possible values are DX11 or DX12. DX11

Deployment Options

Attribute Override Parameter Description Default
deploy_projects_automatically --deploy-projects-automatically Automatically runs the deploy command after each build. True

Game Projects

Attribute Override Parameter Description Default
enabled_game_projects --enabled-game-projects Comma-separated list of game projects to enable for compiling. By default, the possible values are:
  • CloudGemDefectReportSample

  • CloudGemSamples

  • MultiplayerSample

  • SamplesProject

  • StarterGame

CloudGemSamples, StarterGame

IncrediBuild Options

Attribute Override Parameter Description Default
auto_update_incredibuild_settings --auto-update-incredibuild-settings Automatically attempts to update the registry for IncrediBuild, if needed. These registry updates are required to configure IncrediBuild to work properly with the Waf build system. False
incredibuild_max_cores --incredibuild-max-cores Control the number of processes spawned by IncrediBuild. 128
incredibuild_profile --incredibuild-profile The IncrediBuild configuration value to load for IncrediBuild builds. Tools/build/waf-1.7.13/profile.xml
use_incredibuild

-i

--use-incredibuild

Use IncrediBuild if available.

Windows PC builds require at a minimum the Make and Build tools package.

Android builds additionally require the Dev Tools Acceleration package.

False

Misc Options

Attribute Override Parameter Description Default
bootstrap_third_party_override --3rdpartypath Optional parameter to pass the location of the \3rdParty directory as part of the bootstrap process.
bootstrap_tool_param --bootstrap-tool-param

Value set by Lumberyard Setup Assistant to inform Waf which platforms should be enabled.

Note

This setting is automatically configured through Lumberyard Setup Assistant and should not be updated manually.

has_server_configs --has-server-configs Optional parameter to enable the _dedicated_server configurations. True
has_test_configs --has-test-configs Optional parameter to enable the _test configurations. True
max_cores --max-cores Number of parallel processes for local builds. To limit the number of cores used, set a specific value. A value less than or equal to 0 indicates that as many cores as needed will be used based on available hardware. 0

Packaging Options

Attribute Override Parameter Description Default
copy_assets --always-copy-assets An option specific to iOS and macOS. When running the packaging command, always copy any assets that are specified to the package, even for debug or profile builds. False
package_projects_automatically --package-projects-automatically Automatically run the packaging command after each build, where available. This option is supported on Android, iOS, and macOS. True
run_xcode_for_packaging --runxcode-for-packaging An option specific to iOS and macOS. When running the packaging command, run xcode_* from the command line to generate the app bundle resources for iOS and macOS platforms. True

Visual Studio Project Generator

Attribute Override Parameter Description Default
default_project --visual-studio-solution-default-project The Visual Studio default project if not set in the solution user options (.suo ) file. Editor
generate_vs_projects_automatically --generate-vs-projects-automatically Automatically generates Visual Studio projects and solutions. True
msvs_version --msvs-version Version of the Visual Studio solution to generate. 14
specs_to_include_in_project_generation --specs-to-include-in-project-generation List of Waf spec files to include in the Visual Studio solution generation. all, game, game_and_engine
visual_studio_solution_folder --visual-studio-solution-folder Name of the directory in which the generated Visual Studio solution should be stored. Solutions
visual_studio_solution_name --visual-studio-solution-name Name of the generated Visual Studio solution. LumberyardSDK

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

Attribute Override Parameter Description Default
out_folder_android_armv7_clang --output-folder-android-armv7-clang The base output folder name for the android_armv7_clang platform. BinAndroidArmv7Clang
out_folder_android_armv8_clang --output-folder-android-armv8-clang The base output folder name for the android_armv8_clang platform. BinAndroidArmv8Clang
out_folder_ios --output-folder-ios Absolute or relative iOS target platform build output path. BinIos
output_folder_darwin_x64 --output-darwin-x64 Absolute or relative macOS (Darwin) target platform build output path. BinMac64
out_folder_win_x64_clang --output-folder-win64-clang The base output folder name for the win_x64_clang platform. Bin64clang
out_folder_win_x64_vs2013 --output-folder-win64-vs2013 The base output folder name for the win_x64_vs2013 platform. Bin64vc120
out_folder_win_x64_vs2015 --output-folder-win64-vs2015 The base output folder name for the win_x64_vs2015 platform. Bin64vc140
out_folder_win_x64_vs2017 --output-folder-win64-vs2017 The base output folder name for the win_x64_vs2017 platform. Bin64vc141

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 in the lumberyard_installation\dev\_WAF_\settings\build_configurations.json file.

Output Folder Name Extensions

Attribute Override Parameter Description Default
output_folder_ext_debug --output-folder-ext-debug The output folder name extension for debug builds. Debug
output_folder_ext_performance --output-folder-ext-performance The output folder name extension for performance builds. Performance
output_folder_ext_profile --output-folder-ext-profile The output folder name extension for profile builds.
output_folder_ext_release --output-folder-ext-release The output folder name extension for release builds. Release

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.

Android

The following settings for Android are defined in the lumberyard_version\dev\_WAF_\settings\platforms\common.android.json file.

Android Options

Attribute Override Parameter Description Default
android_maven_force_http --android-maven-force-http-requests Forces Android Maven library requests to use HTTP instead of HTTPS. False
android_asset_mode --android-asset-mode

Specify one of the following asset packaging modes:

  • configuration_default – Use the current build configuration to determine how to package the assets (for example, loose_files for debug or profile, project_settings for release or performance).

  • loose_files – No additional processing is done on the compiled assets.

  • loose_paks.pak files are generated from the compiled assets.

  • apk_files – The compiled assets are packaged inside the APK.

  • apk_paks.pak files are generated and packaged inside the APK.

  • project_settings – Use the use_[main|patch]_obb settings in the project.json file to determine whether .pak files in the APK or OBBs are used.

configuration_default

Android Deploy

Attribute Override Parameter Description Default
deploy_android --deploy-android Deploys to an Android device after a successful package command. True
deploy_android_clean_device --deploy-android-clean-device Completely uninstalls the app from the target device. True
deploy_android_device_filter --deploy-android-device-filter Comma-separated list of Android device IDs to deploy to. If empty, deploys to all connected devices.
deploy_android_executable --deploy-android-executable Installs the executable .apk file on the Android device. True
deploy_android_install_options --deploy-android-install-options Provides additional options to specify for the install command.
deploy_android_replace_apk --deploy-android-replace-apk When installing the .apk file to the Android device, uses the -r option to force the replacement of the package. True

Android Project Generator

Attribute Override Parameter Description Default
android_studio_project_folder --android-studio-project-folder Name of the directory in which the generated Android Studio project should be stored. Solutions
android_studio_project_name --android-studio-project-name Name of the root Android project directory and Android Studio project name. LumberyardAndroidSDK
generate_android_projects_automatically --generate-android-projects-automatically Automatically generates Android Studio projects. True

iOS

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

iOS Options

Attribute Override Parameter Description Default
ios_paks --ios-paks Forces .pak files to be built in non-release builds. False

iOS Project Generator

Attribute Override Parameter Description Default
generate_ios_projects_automatically --generate-ios-projects-automatically Automatically generate an Xcode project for iOS. True
ios_project_name --ios-project-name Name of the generated iOS project. LumberyardiOSSDK
ios_project_folder --ios-project-folder Name of the directory in which the generated iOS projects should be stored. Solutions

macOS

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

Mac Options

Attribute Override Parameter Description Default
mac_build_monolithic --mac-build-monolithic Boolean flag to generate a monolithic or a non-monolithic build for macOS. False
darwin_paks --darwin-paks Forces .pak files to be built in non-release builds. False

Mac Project Generator

Attribute Override Parameter Description Default
generate_mac_projects_automatically --generate-mac-projects-automatically Automatically generate Xcode projects for macOS. True
mac_project_name --mac-project-name Name of the generated project. LumberyardSDK
mac_project_folder --mac-project-folder Name of the directory in which the generated macOS projects should be stored. Solutions

Windows Options

The following settings for Windows are defined in the lumberyard_version\dev\_WAF_\settings\platforms\platform.win_x64_vs2015.json and lumberyard_version\dev\_WAF_\settings\platforms\platform.win_x64_vs2017.json files.

Windows Options

Attribute Override Parameter Description Default
win_enable_clang_for_windows --win-enable-clang-for-windows Enables building and configuring with Clang for Windows.
win_vs2015_winkit --win-vs2015-winkit The windows kit that Visual Studio 2015 builds Windows targets against.
win_vs2017_vcvarsall_args --win-vs2017-vcvarsall-args Additional arguments to pass to the vcvarsall.bat file.
win_vs2017_vswhere_args --win-vs2017-vswhere-args The arguments to pass to vswhere when locating Visual Studio 2017 executables. The default maximum is the last version that Lumberyard was tested against before release. The default minimum is the last known ABI incompatibility for Lumberyard builds. -version [15.7.27703.2035,15.9.28307.423]
win_vs2017_winkit --win-vs2017-winkit The windows kit that Visual Studio 2017 builds Windows targets against.