Engine setup

(Setup instructions for the editor here).

This guide focuses on the tool and platform sdk installation.

Build instructions for the engine are found here here).

At the very minimum, you need to install the SDK for your host platform (Windows, macOS or Linux)

Supported hosts + targets

Here is a table of our supported target platforms, and on which host platform you can build it:

Required Software

Platform SDK

Our build system detects local installations of the platform SDK's.

See more detailed installation details further down in this document.

• macOS + iOS: XCode
• Linux: Clang++ (v17)
• Windows: Visual Studio Community 2022 + Clang
• Android: Android Studio
• HTML5: Emscripten SDK - Set EMSDK environment variable to locate the local installation.
• Consoles: We detect the appropriate environment variables for each platform. We refer to each vendor's installation notes.

Command prompt

Throughout our build instructions, we refer to commands that should be run in a shell. While we try to be as vanilla as possible, on Windows we only use git-bash. See instructions below.

• macOS - Terminal is a builtin tool in macOS
• Linux - Terminal is a builtin tool in Linux

• Windows - Terminal is a builtin tool in Windows.
  • It allows you to run different types of shells, like git-bash
  • note: We do not build from the regular Command prompt
  • Git For Windows - Installs Git (required), and also git-bash.
    • git-bash is currently our recommended shell for windows. ´git-bash´ can install as a Terminal add on.
      • During install, if asked, select the option to not do any CR/LF conversion.

Optional Setup - Command Prompt

It's useful to modify your command prompt to show the status of the repo you're in. E.g. it makes it easier to keep the git branches apart.

You do this by editing the PS1 variable in your shell. Put it in the recommended config for your system (e.g. .zprofile or .bashrc) Here's a very small improvement on the default prompt, whic shows you the time of the last command, as well as the current git branch name and its status:

git_branch() {
    git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}
acolor() {
  [[ -n $(git status --porcelain=v2 2>/dev/null) ]] && echo 31 || echo 33
}
export PS1='\t \[\033[32m\]\w\[\033[$(acolor)m\] $(git_branch)\[\033[00m\] $ '

Package managers

These are not strictly required, but helps install some of the software you need.

• winget - Winget is a package installer that will help install various helper tools such as Python, Java, ripgrep etc. Winget is preinstalled on Windows.

• Homebrew - Homebrew is a package mananger for macOS.

Once it is installed, you can install packages using

brew install <package_name>

• apt - (alternatively name apt-get) is a package mananger for Linux. It is the default package manager and is installed by default.

Once it is installed, you can install packages using

apt install <package_name>

Required Software - Java JDK 25

You can use a package manager or do a manual download and installation.

Install temurin jdk using winget:

winget install --id EclipseAdoptium.Temurin.25.JDK -e

The JDK bin path is automatically added to PATH environment variable, but you need to sign out and sign in again for it to take effect.

Install temurin jdk using apt-get:

> sudo apt-get install temurin-25-jdk

Once the Java SDK is installed you may need to add <java install path>/Contents/Home/bin to your PATH:

> nano ~/.bashrc
export PATH=<JAVA_INSTALL_PATH>/Contents/Home/bin:$PATH

After that, update the path by reloading the PATH variable:

source ~/.bashrc

Install temurin jdk using brew:

> brew install --cask temurin@25

after installation, it's installed under /Library/Java/JavaVirtualMachines/temurin-<version>.jdk/Contents/Home`

Once the Java SDK is installed you may need to add <java install path>/Contents/Home/bin to your PATH:

> nano ~/.zprofile
export PATH=<JAVA_INSTALL_PATH>/Contents/Home/bin:$PATH

After that, update the path by reloading the PATH variable:

source ~/.zprofile

Download and install the latest JDK 25 (25+36 or later) release from either of these locations:

• Adoptium/Temurin - The Adoptium Working Group promotes and supports high-quality runtimes and associated technology for use across the Java ecosystem

Finally, verify that Java is installed and working:

> javac -version

Required Software - Python 3

You need a 64 bit Python 3 version to build the engine and tools. The latest tested on all platforms is Python 3.10+.

You need to install a Python3 version from Python downloads.

Once Python has been installed you also need install certificates (for https requests):

> "/Applications/Python\ 3.12/Install\ Certificates.command"

Install Python using winget:

winget install -e --id Python.Python.3.12

Linux comes with a preinstalled version of Python.

Install an appropriate version from https://www.python.org/downloads/

Finally, verify that Python 3 is installed and working:

> python -V

Required Software - Git

Git is needed to work with our code base. It is used to push and pull code changes between the code repositories.

This is not needed if you've installed git-bash

You can download a command line version of Git.

During install, select the option to not do any CR/LF conversion.

You most likely want to set up working with ssh keys as well.

SSH Keys

Using Git Gui

• Run Git GUI
• Help > Show SSH Key
• If you don't have an SSH Key, press Generate Key
• Add the public key to your Github profile
• You might need to run start-ssh-agent (in C:\Program Files\Git\cmd)

Command line

Alternatively, you can easily create your own key from command line:

$ ssh-keygen -t ed25519 -C "[email protected]"
# Copy the contents of the public file
$ cat ~/.ssh/id_ed25519.pub
# Add the public key to your Github profile (under the Setting tab on your github user profile)
# Test your new key:
$ ssh -T [email protected]

Now you should be able to clone the defold repo from a command prompt:

> git clone [email protected]:defold/defold.git

You can install git using apt-get:

apt-get install git

Git is installed with XCode, but you can also install git using brew:

brew install git

Required Software - Platform SDK's

Each platform requires SDK's and other tools (e.g. debuggers)

XCode

We use XCode for building and debugging macOS + iOS targets.

While XCode is available from the App Store, we recommend logging into your Apple Developer account and downloading it manually from More Downloads.

After downloading XCode, you also need to install the Command line tools:

xcode-select --install

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose

Visual C++ 2022 Community

Download the Visual Studio Community 2022 version or use the Professional or Enterprise version if you have the proper licence.

• When installing, in the "Workloads" tab, select the "Desktop Development with C++"

• We also require Clang:

  • In Visual Studio Installer, under Individual components, select C++ Clang Compiler for Windows and MSBuild support for LLVM (clang-cl) toolset.

  • Add clang to your PATH. For a default installation, the path to add will likely be C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\bin

• There is also an optional 3rd party git client.

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose

There is no single "sdk" to install, but a list of libraries that are needed for development.

Development files

• libxi-dev - X11 Input extension library
• libxext-dev - X11 Miscellaneous extensions library
• freeglut3-dev - OpenGL Utility Toolkit development files
• libcurl4-openssl-dev - Development files and documentation for libcurl
• uuid-dev - Universally Unique ID library
• libopenal-dev - Software implementation of the OpenAL audio API
• libncurses5 - Needed by clang

Tools

• build-essential - Compilers
• autoconf - Automatic configure script builder
• automake - Tool for generating GNU Standards-compliant Makefiles
• libtool - Generic library support script

Download and install using apt-get:

apt-get install \
        autoconf \
        automake \
        build-essential \
        freeglut3-dev \
        libssl-dev \
        libtool \
        libxi-dev \
        libx11-xcb-dev \
        libxrandr-dev \
        libopenal-dev \
        libgl1-mesa-dev \
        libglw1-mesa-dev \
        libncurses5 \
        openssl \
        valgrind \
        uuid-dev \
        xvfb

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose

If you're using Ubuntu and it fails to install libncurses5, try:

sudo ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so.5 /usr/lib/libtinfo.so.5

and:

sudo ln -s /usr/lib/x86_64-linux-gnu/libncurses.so.5 /usr/lib/libncurses.so.5

There are two options:

• Download and install Android Studio.

• Set the ANDROID_HOME environment variable

  • E.g. ANDROID_HOME=/path/to/android/sdk

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose --platform=arm64-android

• Install Emscripten SDK
• Set EMSDK environment variable to locate the local installation.
  • E.g. EMSDK=/path/to/emsdk-4.0.7/

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose --platform=wasm-web

For each console we detect the appropriate environment variables used by each platform. We refer to each vendor's installation notes for their SDK's.

Once installed, verify the installation with

defold$ ./scripts/build.py check_sdk --verbose --platform=...

NOTE: this is not required to build the engine locally!

In order to build Extender images locally, you need access to prepackaged SDK's for each platform.

Due to licensing restrictions the SDKs are not distributed with Defold. You need to provide these from a URL accessible by your local machine so that build.py and the install_sdk command can download and unpack them.

In order to simplify this process we provide scripts to download and package the SDKs Read more about this process here.

The path to the SDKs can either be passed to build.py using the --package-path option or by setting the DM_PACKAGES_URL environment variable.

Optional Software

These tools are generally not needed for a regular build.

Optional Software - DotNet 9

In order to build and test the csharp languange bindings locally, you need to install DotNet 9.

There are a few ways to install the DotNet sdk:

• Install via https://dotnet.microsoft.com/en-us/download/dotnet/9.0

• Install via your package manager

  • macOS: brew search dotnet
  • Linux: apt-get install dotnet
  • Windows: winget install Microsoft.DotNet.SDK.9

• Install via dotnet-install.sh:

  <details><summary>Linux/macOS...</summary><p>

  Bash:

  shCopy

  > chmod +x ./dotnet-install.sh
  > ./dotnet-install.sh --channel 9.0
  

  </p></details> <details><summary>Windows...</summary><p>

  PowerShell (Windows):

  shCopy

  > ./dotnet-install.ps1 -Channel 9.0
  

  </p></details>

Additional Software for external libraries

These are needed in some special build scripts (e.g. when rebuilding external source libraries).

• curl - Command line tool for downloading files
• wget - Command line tool for downloading files
• cmake for easier building of external projects
• patch for easier patching on windows (when building external projects)

brew install wget curl cmake patch

apt-get install wget curl cmake patch

In powershell or bash:

winget install wget curl cmake Ninja-build.Ninja GnuWin32.Patch 

Optional Software - ccache

This is an optional tool to help speed up building the code by caching the results.

> brew install ccache

Configure ccache by running (source)

> ccache --max-size=5G

> apt-get install ccache

Configure ccache by running (source)

> ccache --max-size=5G

In powershell:

> winget install ccache

Configure ccache by running (source)

> ccache --max-size=5G

Optional Software

These are rarely used by developers in our build setup. They're mainly used to help unpack some archives and sync source code in a pl

• 7z - for extracting (e.g. android archives and binaries)
• dos2unix tool to convert line endings of certain source files (e.g. when building files in external/bullet3d)

brew install 7z dos2unix

apt-get install 7z

In powershell:

winget install 7z dos2unix

Alternative host systems

It is sometimes possible to cross compile to other systems.

Build Linux from Windows using WSL (Windows Subsystem for Linux)

It is possible to build Linux targets using WSL 1.

Install relevant packages (git, java, python, clang etc) using ./scripts/linux/install_wsl_packages.sh. If also updates your ~/.bashrc with updated paths.

Git clone into a mounted folder

In order to get the proper username of your files, we need to setup WSL for this. Otherwise the git clone won't work in a mounted C: drive folder.

Open (or create) the config file:

sudo nano /etc/wsl.conf

Add these lines:

[automount]
options = "metadata"

And restart your WSL session

X11

The script also sets the DISPLAY=localhost:0.0 which allows you to connect to a local X server.

A popular choice is VCXSRV

Build Linux from macOS using Docker

Build the docker container (Ubuntu). It will use the arch of your current host system.

./scripts/docker/build.sh

Run the guest system in the cwd of choice. E.g. to start setup for building Defold engine for Linux

cd <defold root>
./scripts/docker/run.sh
./scripts/build.py shell
./scripts/build.py install_ext
...