Adding a Build Module

You can create a custom build module in the Lumberyard Waf build system. You can use predefined build modules to add any shared library or plugin into the Lumberyard engine SDK.

The default Waf system defines modules and methods that will take various keywords into Waf commands to build applications and shared and static libraries as well as serving as a project container for files. There cryengine_modules.py file defines functions that wrap these modules with additional keywords and logic to extend the behavior of standard Waf into a system that supports the requirements of Lumberyard. In addition to providing standard Waf build functionality, the functions in the various modules add support for precompiled headers (pch), content file support (.waf_files), monolithic build capability, uber file support, and Microsoft Visual Studio (msvs) generation.

Creating a module requires the following steps:

1. Create the source folder and script

2. Create a basic wscript module

3. Create the .waf_files content file

4. Specify additional include paths and external library linking

5. Add a project dependency

Creating a New Module

You can create and add the following types of modules to the Lumberyard Waf build system:

In this topic’s example you create a CryEngineModule.

Build Module Keywords

The following describes the general keywords that are supported by the build modules. The listed targetable keywords can be specific to a platform or a configuration. The keyword by itself is used for all supported platforms and configurations, but if you need keywords that are specific to a platform or configuration, you must include the name of the platform or configuration in the name.

Other things to consider:

• The general pattern for platform plus configuration-specific values is __.
• The general pattern for platform-specific values is _
• The general pattern for configuration-specific values is _

You can use the following keyword macros to reduce the verboseness of wscript files:

_ndebug_**
This macro eliminates the need to repeatedly specify certain non-debug flags. Lumberyard has one debug configuration and three non-debug configurations.

Creating a Basic Wscript Module

The wscript file specifies the name of the module (target), .waf_files content file (file_list), Visual Studio filter (vs_filter), and precompiled headers (pch).

Create a wscript module with the following:

def build(bld):
 
    bld.CryEngineModule(
        target      = 'MyEngineModule',
        vs_filter   = 'LyEngine',
        file_list   = 'myenginemodule.waf_files',
        pch         = 'StdAfx.cpp'
    )

In order for the Lumberyard Waf build system to pick up the new folder and script, you must add the new folder to the list of subfolders to recurse. Because you are adding this project under lumberyard_version/Code/CryEngine/MyEngineModule, you need to update the wscript located in the parent lumberyard_version/Code/CryEngine folder.

Update the wscript located in the lumberyard_version/Code/CryEngine folder with the following:

SUBFOLDERS = [
        'CryInput',
        'Cry3DEngine',
        ...
        'MyEngineModule',
    ]
 
def build(bld):
    # Recursive into all sub projects
    bld.recurse(SUBFOLDERS)

Creating the .waf_files Content File

In the example wscript, you specified a file called myenginemodule.waf_files as the project content file. The project content file can be one of the following:

• A single file that defines the source files for the project
• A list of files that define the source files for the project
• Platform/configuration, where certain files are included only for a particular platform (for example, console-specific files)

The following myenginemodule.waf_files example demonstrates a simple module with six files:

{
    "NoUberFile":
    {
        "Root":
        [
            "StdAfx.cpp",
            "StdAfx.h"
        ]
    },
    "myenginemodule_uber_0.cpp":
    {
        "Root":
        [
            "myenginecore.cpp",
            "myenginecore.h",
            "myengineextras.cpp",
            "myengineextras.h"
        ]
    }
}

Specifying Additional Include Paths and External Library Linking

To configure the module to link to external modules, you need to update the wscript to specify the include path and link related project settings flags such as includes, lib, libpath, and linkflags.

In this example, you add the following to your module:

1. Google mock libraries for Win x64

2. Preprocessor DEFINE called USE_GMOCK to inject into the compile based on the platform Win x64

3. Link-time code generation flag to enable instrumentation (/LTCG:PGOPTIMIZE)

Add the following to your wscript module:

def build(bld):
 
    bld.CryEngineModule(
        target          = 'MyEngineModule',
        vs_filter       = 'LyEngine',
        file_list       = 'myenginemodule.waf_files',
        pch             = 'StdAfx.cpp',
 
        win_includes    = [Path('Code/SDKs/GoogleMock/include')],
        win_lib         = ['gmock'],
        win_linkflags   = ['/LTCG:PGOPTIMIZE'],
        win_defines     = ['USE_GMOCK'],
        win_x64_debug_libpath       = [Path('Code/SDKs/GoogleMock/bin/x64/Debug')],
        win_x64_profile_libpath     = [Path('Code/SDKs/GoogleMock/bin/x64/Release')],
        win_x64_performance_libpath = [Path('Code/SDKs/GoogleMock/bin/x64/Release')],
        win_x64_release_libpath     = [Path('Code/SDKs/GoogleMock/bin/x64/Release')]
    )
)

Note
The following are duplicated to cover all possible configurations that you specified in the waf_branch_spec: win_x64_profile_libpath, win_x64_profile_performance, and win_x64_release_libpath.

Adding and Linking to a Project Dependency

If you want to link to another module that is built within the system, you can use the use parameter for the build.

Update your wscript module to link to the CryPerforce module:

def build(bld):
 
    bld.CryEngineModule(
        target          = 'MyEngineModule',
        vs_filter       = 'LyEngine',
        file_list       = 'myenginemodule.waf_files',
        pch             = 'StdAfx.cpp',
        use             = ['CryPerforce'],
 
        win_includes    = [Path('Code/SDKs/GoogleMock/include')],
        win_lib         = ['gmock'],
        win_defines     = ['USE_GMOCK'],
        win_x64_debug_libpath       = [Path('Code/SDKs/GoogleMock/bin/x64/Debug')],
        win_x64_profile_libpath     = [Path('Code/SDKs/GoogleMock/bin/x64/Release')],
        win_x64_performance_libpath = [Path('Code/SDKs/GoogleMock/bin/x64/Release')],
        win_x64_release_libpath     = [Path('Code/SDKs/GoogleMock/bin/x64/Release')]
    )
)