Adding a Spec
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE |
The Waf spec system provides a template to create Visual Studio solutions and describes a build filter that determines which modules to build for particular platforms and configurations. The nature of the generic Waf build system is to be all projects that are defined through the wscript system, which acts recursively on the root directory structure. If no spec is specified when you execute a build or clean command, the Waf build system system attempts to build all modules that are supported by the selected target platform and configuration. The platform and configuration support is defined in each of the module's wscript definitions. For more information, see Adding a Build Module.
Project spec files are a collection of modules and definitions for a specific build pipeline. These files are useful for including existing modules or adding new ones as part of the build dependencies for your game project.
When you build in debug or profile configurations and their
_dedicated
counterparts, a spec file is not required. This is
because these two configurations build out of Lumberyard as modular shared components. In
performance and release configurations, however, all the modules that are marked as
CryEngineModules
are built monolithically, which means that they are built
into a single executable. This causes problems with similar modules that support the same
platform and configuration. Currently, the spec file is required for this scenario in order
to target specific modules to build into the monolithic .exe
files.
Adding a project requires these steps:
Topics
Creating a New Project Spec JSON File
In the following example a spec file called my_game
includes the
game engine modules as a base as well as custom modules for Windows. The spec file also
sets a custom #define for Windows builds.
You need to configure the values for the modules that you want to include in the spec
file (and optionally the target platform and configuration). The spec file can isolate
target_platform
modules for multiplatform builds.
Create a spec file called my_game.json
with the following:
{ "description" : "Configuration to build the Woodpecker", "visual_studio_name" : "Woodpecker", "comment" : "This is meant to only compile tools on Windows.", "disable_game_projects" : true, "platforms" : ["win"], "configurations" : ["debug","profile"], "modules" : [ "AzCore", "AzFramework", "AzToolsFramework", "GridMate", "LuaIDE", "Profiler" ] }
The spec files are located in the
directory and have the lumberyard_version
\dev\_WAF_\specs.json
file extension. For more information
about Waf spec files, see Waf Spec Files (*.json).
Spec | Description |
---|---|
all.json |
Configuration for all targets. |
dedicated_server.json |
Configuration to build dedicated servers for the enabled projects. |
external_sdks.json |
Configuration to build externally distributed binary-only libraries. |
game_and_engine.json |
Configuration to build the engine and game projects. |
pipeline.json |
Configuration to build Pipeline Only for building Resource Compiler, and also Maya, 3ds Max, and Photoshop plugins if Visual Studio 2010 and 2012 are installed. Build only in Profile or Debug mode (Release mode is only for the 3ds Max plugin) |
resource_compiler.json |
Configuration to build only the Resource Compiler. |
shadercachegen.json |
Configuration to build only the shadercache generator. |
tools.json |
Configuration to build nonessential tools. |
Adding the Spec File to the Visual Studio Solution Generator
Adding the spec file to the Visual Studio solution is optional.
To add the spec file to the Visual Studio solution
-
In a text editor, edit the
specs_to_include_in_project_generation
value in theuser_settings.options
file to add your spec file to the Visual Studio solution:[Visual Studio Project Generator] generate_vs_projects_automatically = True visual_studio_solution_name = LumberyardSDK visual_studio_solution_folder = Solutions specs_to_include_in_project_generation =
MySpec1, MySpec2, MySpec3
-
Enter the following command to regenerate the Visual Studio solution:
lmbr_waf.bat configure
Building the Spec
After saving the new spec, do one of the following:
-
Build the spec using Visual Studio (if you followed the steps above to add the spec to Visual Studio).
-
Build the spec from the command line by entering the following command for your version of Visual Studio:
lmbr_waf build_win_x64_vs
2017
_profile -p MySpec
The build
command builds the game project specified in the
user_settings
, even if the module is not defined in the spec. The
exception is if the option disable_game_projects
is set to
True
.