Build variants

When you bundle a game, you need to choose what type of engine you wish to use. You have three basic options:

• Debug
• Release
• Headless

These different versions are also referred to as Build variants

Debug

This type of executable is typically used during development of a game as it has several useful debugging features included:

• Profiler - Used for gathering performance and usage counters. Learn how to use the profiler in the Profiling manual.
• Logging - The engine will log system information, warnings and errors when logging is enabled. The engine will also output logs from the Lua print() function and from native extensions logging using dmLogInfo(), dmLogError() and so on. Learn how to read these logs in the Game and System Logs manual.
• Hot reload - Hot-reload is a powerful feature which lets a developer reload resource while the game is running. Learn how to use this in the Hot-Reload manual.
• Engine services - It is possible to connect to and interact with a debug version of a game through a number of different open TCP ports and services. The services include the hot-reload feature, remote log access and the profiler mentioned above, but also other services to remotely interact with the engine. Learn more about the engine services in the developer documentation.

Release

This variant has the debugging features disabled. This options should be chosen when the game is ready to be released to the app store or in other ways shared with players. It is not recommended to release a game with the debugging features enabled for a number of reasons:

• The debugging features take up a little bit of size in the binary, and it is a best practice to try to keep the binary size of a released game as small as possible.
• The debugging features takes a little bit of CPU time as well. This can impact the performance of the game if a user has a low-end hardware. On mobile phones the increased CPU usage will also contribute to heating and battery drain.
• The debugging features may expose information about the game that is not intended for the eyes of the players, either from a security, cheating or fraud perspective.

Headless

This executable runs without any graphics and sound. It means that you can run the game unit/smoke tests on a CI server, or even have it as a game server in the cloud.

App Manifest

Not only can you add native code to the engine with the Native Extensions feature, you can also remove standard parts of the engine. E.g. if you don’t need a physics engine, you can remove that from the executable. Learn how to exclude unused feature in the application manifest manual.

Combined context

The app manifest actually has the same structure and syntax as the extension manifest. This allows us to merge the contexts for one platform together when finally building.

And, Defold itself, has its own build manifest as the foundation (build.yml). For each extension that is built, the manifests are combined as follows:

manifest = merge(game.appmanifest, ext.manifest, build.yml)

This is so the user can override the default behaviour of the engine and also each extension. And, for the final link stage, we merge the app manifest with the defold manifest:

manifest = merge(game.appmanifest, build.yml)

Syntax

Here is an example for reference:

platforms:
    x86_64-osx:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    x86_64-linux:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    js-web:
        context:
            excludeLibs: []
            excludeJsLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    wasm-web:
        context:
            excludeLibs: []
            excludeJsLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    x86-win32:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    x86_64-win32:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    armv7-android:
        context:
            excludeLibs: []
            excludeJars: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    armv7-ios:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []
    arm64-ios:
        context:
            excludeLibs: []
            excludeSymbols: []
            libs: []
            linkFlags: []

White listing

For all the keywords, we apply white listing filter. This is to avoid illegal path handling and accessing files outside of the build upload folder.

linkFlags

Here you can add flags to the specific platform compiler.

libs

This flag is only used if you wish to add a library that is part of the platform or Defold SDK. All libraries in your app’s extensions are added automatically, and you shouldn’t add those to this flag. Here’s an example where the 3D physics is removed from the engine:

x86_64-linux:
    context:
        excludeLibs: ["physics","LinearMath","BulletDynamics","BulletCollision"]
        excludeSymbols: []
        libs: ["physics_2d"]
        linkFlags: []

Exclude flags

These flags are used to remove things previously defined in the platform context. Here’s an example of how to remove the Facebook extension from the engine (Note the (.*) which is a regexp to help remove the correct items).

armv7-android:
    context:
        excludeLibs: ["facebookext"]
        excludeJars: ["(.*)/facebooksdk.jar","(.*)/facebook_android.jar"]
        excludeSymbols: ["FacebookExt"]
        libs: []
        linkFlags: []

Where’s the list of all flags, libraries, symbols???

We might put some of them here, but we also think our time is better spent completing the feature of moving the manifest configuration into the Editor, making it a seamless step for the user.

In the meantime, we’ll keep the Manifestation tool updated.