Lumberyard and Waf

Learning how to work with Lumberyard’s build system is a key part of development. Waf is positioned as a “meta build system”- a framework to make build systems.

Waf Basics

Lumberyard’s build system is extensively documented in the User Guide.

Key files/file-types:

File	Description	Details
wscript	Module script	docs
*.waf_files	List of files for modules	docs
Tools/build/waf-1.x.y/	Build script source code (Python)
_WAF_/specs/	Specs- build configurations with lists of modules	spec format

Key commands:

# Help and list of commands
./lmbr_waf.bat --help
# List all commands
./lmbr_waf.bat --list
# GUI to create/edit `dev/_WAF_/usersettings.options`
./lmbr_waf.bat show_option_dialog
# Configure the project using `usersettings.options`
./lmbr_waf.bat configure
# Regenerate Visual Studio solution in `visual_studio_solution_folder` (default: `dev/Solutions/`)
./lmbr_waf.bat msvs

Waf build-related commands follow the format (build|clean|package|deploy)_PLATFORM[_ARCH]_TOOLCHAIN_CONFIG:

./lmbr_waf.bat clean_win_x64_vs2017_profile
# Use _WAF_/specs/engine_and_editor.json spec
./lmbr_waf.bat build_win_x64_vs2017_profile -p engine_and_editor
./lmbr_waf.bat build_win_x64_vs2017_profile --project-spec=engine_and_editor

Settings in usersettings.options can be overridden:

./lmbr_waf.bat build_win_x64_vs2017_profile --enabled-game-projects=SamplesProject

Adding/Removing a File

Check the project’s wscript for the list of files. Here’s Code\CryEngine\CryCommon\wscript:

def build(bld):
    bld.CryFileContainer(
        # SNIP
        target             = 'CryCommon',
        vs_filter          = 'Common',
        file_list          = 'crycommon.waf_files',
        # SNIP
)

crycommon.waf_files is json specifying the files and VS solution filters:

{
    "none":
    {
        "Root":
        [
            "QTangent.h"
        ],
        "Interfaces_h": [
            "InputTypes.h",
            "GameplayEventBus.h",
            "InputEventBus.h",
            "InputNotificationBus.h",
    ...

Re-generate Visual Studio projects:

# If `generate_vs_projects_automatically` is enabled
./lmbr_waf.bat configure
# Otherwise
./lmbr_waf.bat msvs

Creates a solution with a Common filter containing a “CryCommon” project with QTangent.h in the root and a Interfaces_h sub-filter:

Adding a Spec

It’s easy to create a new spec to only build a particular subset of modules. The Lumberyard User Guide has good documentation:

• “Adding a Spec”
• spec format

For example, we can create a spec to build the editor plugins- which are otherwise only built with the all spec.

1. Create _WAF_/specs/editor_plugins.json:

    {
        "description": "Editor Plugins",
        "visual_studio_name": "Editor Plugins",
   
        "modules" :
        [
            "AssetTagging",
            "ComponentEntityEditorPlugin",
            "CryDesigner",
            "DeploymentTool",
            "EditorAnimation",
            "EditorAssetImporter",
            "EditorModularBehaviorTree",
            "EditorUI_QT",
            "FBXPlugin",
            "FFMPEGPlugin",
            "MaglevControlPanel",
            "MetricsPlugin",
            "ParticleEditorPlugin",
            "PerforcePlugin",
            "ProjectSettingsTool",
            "UiCanvasEditor"
        ]
    }
   

2. Add the new spec to specs_to_include_in_project_generation: via Visual Studio Project Generator tab of ./lmbr_waf.bat show_option_dialog. Or, in _WAF_/user_settings.options:

    [Visual Studio Project Generator]
    specs_to_include_in_project_generation = all,editor_plugins
   

3. Generate Visual Studio files:

    ./lmbr_waf.bat msvs
    # Or, if `generate_vs_projects_automatically` is enabled
    ./lmbr_waf.bat configure
   

4. Build: select [Editor Plugins] configuration in Visual Studio. Or:

    ./lmbr_waf.bat build_win_x64_vs2017_profile -p editor_plugins
   

Upgrading

With Lumberyard 1.21 released, now is also a good time to walk through a simple engine upgrade.

1. Update git repo
   • Update

       # Assumes you're working on a fork.  If not, skip this and replace `upsteam` with `origin`
       git remote add upstream https://github.com/aws/lumberyard.git
     
       git fetch --all
       git checkout master
       git pull upstream master
     

   • Optionally, if you subscribe to the “nuke it from orbit” school of thought:

       Remove-Item -Recurse -Path ./dev,./3rdParty
       # Restore dev/ and 3rdParty/
       git reset --hard
       # Remove untracked files/directories
       git clean -fd
     

2. Update binaries and 3rd-party dependencies

    ./git_bootstrap.exe
    # If it doesn't start automatically
    ./SetupAssistant.bat
   

3. Re-initialize Waf

    cd dev/
    ./lmbr_waf.bat configure
   

Tips

• The configurations have rather long names. You can embiggen the Solution Configurations drop-down (from here):

  1. Tools > Customize…
  2. Commands tab, Toolbar: “Standard”
  3. In Preview: select Solution Configurations
  4. Click Modify Selection button
  5. Here’s Width of 150:
     

• If you’re a licensed Playstation/Xbox developer you can get access to Lumberyard PS4/Xbone code (from the FAQ):

  If you are a licensed Microsoft Xbox developer, please e-mail your name, studio name, and the licensed e-mail address to lumberyard-consoles@amazon.com. If you are a licensed Sony PlayStation developer, please visit SCE DevNet. Under the Middleware Directory click “Confirm Status” for Amazon Lumberyard.

• If you use Perforce SCC, you may need to set the character encoding to UTF-8 to avoid SetupAssistant reporting 3rd-party libraries as invalid. This can be done via P4CHARSET (Connection > Environment Settings) or for all connections via Edit > Preferences > Display: