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:
For example, we can create a spec to build the editor plugins- which are otherwise only built with the all
spec.
- 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"
]
}
-
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
-
Generate Visual Studio files:
./lmbr_waf.bat msvs # Or, if `generate_vs_projects_automatically` is enabled ./lmbr_waf.bat configure
-
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.
-
Update git repo
# 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
-
Update binaries and 3rd-party dependencies
./git_bootstrap.exe # If it doesn't start automatically ./SetupAssistant.bat
-
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):
- Tools > Customize…
- Commands tab, Toolbar : “Standard”
- In Preview: select Solution Configurations
- Click Modify Selection button
- 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.
Top comments (0)