Axmol Engine - Development setup

Common requirements

PowerShell: used to install Axmol. PowerShell 7 is recommended, it supports Windows, macOS and Linux.
- Quick installation:
  - macOS, Ubuntu, ArchLinux: run setup.ps1 in axmol root directory (recommended).
  - Windows 10+: system installed PowerShell 5.x should work, but in that case you'll need to run the command Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass -Force in order to allow PowerShell script file to run.
- Manual installation: Instructions / Download
CMake 3.28.1+
- Manual installation is recommended (download). Make sure to add CMake bin to the system PATH, otherwise axmol build will auto-setup it to tools/external/cmake.

Prerequisites

Download or clone Axmol from GitHub (https://github.com/axmolengine/axmol).
Enter axmol root directory.
Run setup.ps1 in windows powershell or (macOS/Linux/ArchLinux terminal). Restart the console after it has finished for environment variables to take effect.
Ensure that the C / C++ compiler toolset is installed on your host machine.
- Windows: Visual Studio 2022 with desktop workflow
- macOS: XCode 14.2+
- Linux: GCC (G++)

Creating a new project

Open any terminal(cmd.exe/powershell/pwsh/bash/zsh/WindowsTerminal/iTerm2). This is the command to generate a new project:

axmol new -p YOUR.UNIQUE.ID -d PROJECT_PATH -l [cpp|lua] [--portrait] PROJECT_NAME

Note: Avoid using special characters in YOUR.UNIQUE.ID

Type axmol new --help at the command line for the latest options. The options at the time of updating this document:

options:
    -h                  Show this help message and exit
    -p PACKAGE_NAME
                        Set a package name for project.
    -d DIRECTORY
                        Set the path where to place the new project.
    -l {cpp,lua}
                        Major programming language you want to use, should be [cpp | lua]
    --portrait
                        Set the project be portrait.
    -i[solated]
                        optionl, if present, will copy full engine sources to path/to/project/axmol

Examples:

Cpp: axmol new -p org.axmol.hellocpp -d D:\dev\projects\ -l cpp --portrait HelloCpp
Lua: axmol new -p org.axmol.hellolua -d D:\dev\projects\ -l lua --portrait HelloLua

Quick build for all target platforms (recommended)

The axmol build command will auto-setup the general toolsets, so you'll be able to easily build your project for any platform.

Win32:
- To generate project and build in console: axmol build -p win32
- To just generate project: axmol build -p win32 -c
WinUWP: axmol build -p winuwp
- To generate project and build in console: axmol build -p winuwp
- To just generate project: axmol build -p winuwp -c
Linux: axmol build
OSX:
- for Intel (x64): axmol build -p osx -a x64 -c (generate a xcodeproj, open with XCode to setup the code sign cert and build)
- for Apple Silicon (arm64): axmol build -p osx -a arm64 -c (generate a xcodeproj, open with XCode to setup the code sign cert and build)
Android: axmol build -p android -a arm64 (can run on Windows, Linux and macOS, and script will auto setup Android SDK)
iOS:
- for devices: axmol build -p ios -a arm64 -c (generate a xcodeproj, open with XCode to setup the code sign cert and build)
- for simulators:
  - for Intel (x64): axmol build -p ios -a x64 -sdk simulator -c
  - for Apple Silicon (arm64): axmol build -p ios -a arm64 -sdk simulator -c
tvOS:
- for devices: axmol build -p tvos -a arm64 -c (generate a xcodeproj, open with XCode to setup code sign cert and build)
- for simulator: axmol build -p tvos -a x64 -sdk simulator
WASM: axmol build -p wasm (it can run on Windows 8.1+, Linux and macOS, it requires a preinstalled python3 in env PATH)

Supported options for `axmol build`

Type axmol build --help at the command line for the latest options. The options at the time of updating this document:

To print out the help in console: axmol build -h

options:
  -h: show this help message and exit
  -p: build target platform, valid value are: win32,winuwp(winrt),linux,android,osx,ios,tvos,wasm
      for android: will search ndk in sdk_root which is specified by env:ANDROID_HOME first,
      if not found, by default will install ndk-r16b or can be specified by option: -cc 'ndk-r23c'
  -a: build arch: x86,x64,armv7,arm64; for android can be list by ';', i.e: 'arm64;x64'
  -cc: toolchain: for win32 you can specific -cc clang to use llvm-clang, please install llvm-clang from https://github.com/llvm/llvm-project/releases
  -xc: additional cmake options: i.e.  -xc '-Dbuild','-DCMAKE_BUILD_TYPE=Release'
  -xb: additional cross build options: i.e. -xb '--config','Release'
  -c: no build, only generate native project files (vs .sln, xcodeproj)
  -d: specify project dir to compile, i.e. -d /path/your/project/
  -f: force generate native project files. Useful if no changes are detected, such as with resource updates.
  -u: request upgrade prebuilt 3rd
 examples:
   - win32:
     - axmol [build] -p win32
     - axmol [build] -p win32 -cc clang
   - winuwp: axmol build -p winuwp
   - linux: axmol build -p linux
   - android:
     - axmol [build] -p android -a arm64
     - axmol [build] -p android -a 'arm64;x64'
   - osx:
     - axmol [build] -p osx -a x64
     - axmol [build] -p osx -a arm64
   - ios: axmol [build] -p ios -a x64
   - tvos: axmol [build] -p tvos -a x64
   - wasm: axmol [build] -p wasm

How to quick build a test project (e.g. 'cpp-tests')

Using a PowerShell console window (command pwsh), go to axmol\tests\<testdir e.g. 'cpp-tests'> directory and perform axmol build -p android -a arm64. It will build cpp-tests for Android.

Manually build with CMake

Windows (Visual Studio 2022)

Install CMake 3.27.4+.
Install Visual Studio 2022 (VS 2019 should be supported, but VS 2022 is recommended).
Create a new project as shown here.
In a console window, navigate into the root directory of the project you created in the previous step.
Generate the relevant Visual Studio project using the cmake command:

axmol build command described in the previous sections (preferred method) or cmake -S SOURCE_DIR -B BUILD_DIR -G VISUAL_STUDIO_VERSION_STRING -A [Win32|x64]

For example, let's say SOURCE_DIR is the current path ".", and BUILD_DIR (out-of-source build directory) is named "build":

(Since Axmol 2.1 c++20 is required for all platforms)
- 32 bit Visual Studio 2019: cmake -S . -B build -G "Visual Studio 16 2019" -A Win32
- 64 bit Visual Studio 2019: cmake -S . -B build -G "Visual Studio 16 2019" -A x64
- 32 bit Visual Studio 2022: cmake -S . -B build -G "Visual Studio 17 2022" -A Win32
- 64 bit Visual Studio 2022: cmake -S . -B build -G "Visual Studio 17 2022" -A x64
Use Visual Studio to open the newly created solution file. For example, ./build/ProjectName.sln.

Windows UWP (Visual Studio 2022)

~~It only supports C++17.~~ Since Axmol 2.1 migration to CppWinRT it has C++20 support.

cmake -B build_uwp -DCMAKE_SYSTEM_NAME=WindowsStore "-DCMAKE_SYSTEM_VERSION=10.0"

Creating the Visual Studio solution for all Axmol test projects (Win / UWP)

First, perform the steps 1. to 6., or the Windows UWP step above (if not is already done).

Open the solution (".\build\axmol.sln" or ".\build_uwp\axmol.sln") in Visual Studio and build any of the test projects via the IDE.

Improving the Visual Studio workflow, supporting linking with engine prebuilt libraries

Please see the Windows workflow guide.

Android (Android Studio)

Install Android Studio 2024.1.2+.
When starting Android Studio for the first time, it will guide you through the installation of the SDK and other tools. Please make sure that you do install them.
Start Android Studio and choose [Open an existing Android Studio Project] and select your project. For example, the existing cpp-test project located in axmol\tests\cpp-tests\proj.android.
Start Android Studio and open 'Tools' -> 'SDKManager', then switch to 'SDK Tools', check the 'Show Package Details' field, and choose the following tools clicking the button 'Apply' to install them:
- Android SDK Platform 34
- Android Gradle Plugin (AGP) 8.2.1
- Android SDK Build-Tools 34.0.0 match with AGP, refer to: https://developer.android.com/studio/releases/gradle-plugin
- Gradle 8.5
- NDK r23c
Wait for the Gradle sync to finish.

Note: if you use non-SDK provided CMake, you will need to download ninja from https://github.com/ninja-build/ninja/releases, and copy ninja.exe to CMake's bin directory.

Android Studio (without Android Studio)

Download Android command-tools.
Install Android devtools. Example in Windows:

# unzip command-tools at D:\dev\adt\
# Install android devtools
cd D:\dev\adt\
mkdir sdk
.\cmdline-tools\bin\sdkmanager.bat --verbose --sdk_root=D:\dev\adt\sdk "platform-tools" "cmdline-tools;latest" "platforms;android-34" "build-tools;34.0.0" "ndk;23.2.8568313"
set ANDROID_HOME=D:\dev\adt\sdk

# Goto xxx\proj.android
.\gradlew.bat assembleRelease -P__1K_ARCHS=arm64-v8a --parallel --info

iOS, tvOS and macOS

Ensure that XCode 13+ is installed.
Create a new project as shown here.
In a console window, navigate into the root directory of the project you created in the previous step.
Execute the following command: sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
Generate the relevant XCode project using one of the following commands:
- for iOS arm64:
  axmol build -p ios -a arm64 -c
- for iOS simulator arm64:
  axmol build -p ios -a arm64 -sdk simulator -c
- for iOS simulator x86_64:
  axmol build -p ios -a x64 -sdk simulator -c
- for tvOS arm64:
  axmol build -p tvos -a arm64 -c
- for tvOS simulator x86_64:
  axmol build -p tvos -a x64 -c
- for macOS x86_64(Intel) axmol build -p osx -c
- for macOS arm64(M1) axmol build -p osx -a arm64 -c
After CMake finishes generating, you can open the XCode project at build_${plat}_${arch} folder and run cpp-tests or other test targets. For OSC x64 should be build_x64.
Notes:
- Code signing is required to run the iOS / tvOS app on your device. Just change the bundle identifier until the auto manage signing is solved.
- Axmol only provides arm64, x86_64 prebuilt libraries for iOS / tvOS.

Linux (VSCode)

Run pwsh ./setup.ps1.
Open axmol source folder with VSCode.
Install C++, CMake extensions for VSCode.
VSCode will auto prompt you to choose the toolset for building. Select the gcc matching with your system installed default gcc:
```
# check gcc version
gcc -v
```
i.e. gcc version 11.3.0 (Ubuntu 11.3.0-1ubuntu1~22.04)
VSCode will run CMake config automatically. After done, click build in taskbar. You can also choose specific target to build and run.

Notes: if you need debug in VSCode, remember to choose CMake: [Debug] in the WSCode taskbar.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DevSetup.md

DevSetup.md

Axmol Engine - Development setup

Common requirements

Prerequisites

Creating a new project

Quick build for all target platforms (recommended)

Supported options for `axmol build`

How to quick build a test project (e.g. 'cpp-tests')

Manually build with CMake

Windows (Visual Studio 2022)

Windows UWP (Visual Studio 2022)

Creating the Visual Studio solution for all Axmol test projects (Win / UWP)

Improving the Visual Studio workflow, supporting linking with engine prebuilt libraries

Android (Android Studio)

Android Studio (without Android Studio)

iOS, tvOS and macOS

Linux (VSCode)

Files

DevSetup.md

Latest commit

History

DevSetup.md

File metadata and controls

Axmol Engine - Development setup

Common requirements

Prerequisites

Creating a new project

Quick build for all target platforms (recommended)

Supported options for axmol build

How to quick build a test project (e.g. 'cpp-tests')

Manually build with CMake

Windows (Visual Studio 2022)

Windows UWP (Visual Studio 2022)

Creating the Visual Studio solution for all Axmol test projects (Win / UWP)

Improving the Visual Studio workflow, supporting linking with engine prebuilt libraries

Android (Android Studio)

Android Studio (without Android Studio)

iOS, tvOS and macOS

Linux (VSCode)

Supported options for `axmol build`