Overview

This tutorial will go through the process of adding a new "spec" to your game project.

A "spec" essentially defines a collection of modules which again are a collection of source files. It also specifies which platforms as well as which configuration are available for the spec named WAF build pipeline.

Once successfully created a spec can be selected from the WAF Interface.

Step 1: Creating a spec file

To create a WAF Spec File you will need to located the folder all specs reside in. They can be found in <GAME_SDK_DIR>/__WAF__/specs/<spec_name>.json.

The name of the spec is defined by the file name itself i.e. <spec_name>.json. WAF will automatically regard all files within this folder as specs, hence you do not have to register the spec elsewhere.

The WAF Spec File itself was design to be easily readable and maintainable.

Let's create a spec with the following parameters:

The first step is to create a new file in "<GAME_SDK_DIR>/__WAF__/specs/" called "MyFirstSpec.json".

Now that we have created the files we will have to specify the parameters of the spec.

Open the new file for edit.

The file itself should be written in JSON. (see WAF Spec File (*.json) for more information.)

In the second step we will add some basic spec information to the file.

• A description which provides users some basic information about the purpose of this spec
• The platforms that are available for this spec.
• The configurations that are available for this spec.
• The project the spec targets.
• The name this project should show up as in the generated Visual Studio Solution.
  
  

{
   "description"            : "Description of MySpec which will show up in the GUI.",    
    "valid_platforms"        : [ "win", "linux" ],
    "valid_configuration"    : [ "debug", "release" ],
  "game_projects"          : "MyFirstProject",
    "visual_studio_name"     : "MyFirstProject",  
  ...
}

In the third step we will add the module configuration to the file.

{
  ...
  "modules"        : [ "Module1", "Module2", "Module3" ],
  "win_modules"    : [ "WindowsLauncher", "Module_WinOnly" ],
  "linux_modules"  : [ "LinuxLauncher", "Module_LinuxOnly" ]
}

The "modules" is a platform dependent entry identifier. In this specific case the modules that are listed in "modules" will be shared between the Windows and Linux build.

The modules listed in "win_modules" will only be included in the build pipeline if a windows target is used.

The modules listed in "linux_modules" will only be included in the build pipeline if a windows target is used.

Step 2: Build Spec

You can now build your spec using the WAF Command-Line Interface with the command.

• cry_waf.exe build_win_x64_debug --project-spec=MyFirstSpec

or

• cry_waf.exe build_linux_x64_release --project-spec=MyFirstSpec

Additionally you can direct WAF to include this spec when generating Visual Studio Solutions so you can select and build it from within Visual Studio.

By default new specs are not included automatically. This is to avoid polluting the solution with projects that are not of interest to you which would otherwise slow down your Visual Studio experience.

In order to include your spec in the Visual Studio solution you will need to execute cry_waf, select "WAF Options".

Navigate to the "Visual Studio Project Generation" tab and select the specs you want to be include in Visual Studio.

Once done, select exit and save the configuration.


Note: You can always change your selection later and regenerate the solution. So if you happen to primarily work with one or two specs and rarely work with a third or fourth spec. You might want to add the third spec when you have to work with it and remove it again after.

You will then need to regenerate the Visual Studio Solution.

When you open or reload your Visual Studio Solution the next time you will be able to select your spec from the Visual Studio Configuration Manager drop down menu.

To build the spec from within Visual Studio select Build-> Build Solution (F7).

Step 3: Launch Spec

To launch the spec on Windows x64 execute the produced .exe file from the platforms binary output directory.

To launch and debug the application from within Visual Studio, select the "Windows Launcher" as StartupProject and then debug the application by selecting Debug->Start Debugging (F5).