Skip to content

Latest commit

 

History

History
196 lines (149 loc) · 10.1 KB

DevSetup.md

File metadata and controls

196 lines (149 loc) · 10.1 KB

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 1k/install-pwsh.sh 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

  1. Download or clone Axmol from GitHub (https://github.com/axmolengine/axmol).
  2. Enter axmol root directory.
  3. Run pwsh setup.ps1. Restart the console after it has finished for environment variables to take effect.
  4. 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

Enter to PowerShell (pwsh). 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 more options.

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. For example:

  • Win32: axmol build -p win32
  • WinUWP: axmol build -p winuwp
  • Linux: axmol build
  • OSX: axmol build -p osx -a x64
  • 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 simulator: axmol build -p ios -a x64
  • 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
  • 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

-p: build target platforms: win32, winuwp, linux, android, osx, ios, tvos, watchos, wasm
    For android: it will search the NDK in sdk_root first, which is specified by env ANDROID_HOME. 
    If not found, by default it will install ndk-r16b, or you can specify by the option: -cc 'ndk-r23c'
-a: build architecture: x86, x64, armv7, arm64
-d: the build workspace. For example, the project root which contains root CMakeLists.txt, empty use script run working directory (aka cwd)
-cc: The C/C++ compiler toolchain: clang, msvc or gcc(mingw). Leave it empty tou use the current installed default.
    msvc: msvc-120, msvc-141
    ndk: ndk-r16b, ndk-r16b+
-xt: cross build tool. Default: cmake. For Android it can be gradlew, or it can be the path of the cross-build tool program
-xc: cross build tool configure options. For example,  -xc '-Dbuild'
-xb: cross build tool build options. For example, -xb '--config','Release'
-prefix: the install location for missing tools in the system. Default is "$HOME/build1k"
-sdk: specific Windows SDK version. For example, -sdk '10.0.19041.0'. Leaved empty, cmake will auto-choose the latest available
-setupOnly: this parameter is present, it only will execute the 'setup' step  
-configOnly: if this parameter is present, it will skip the 'build' step

How to quick build the engine for host targets

Go to axmol root directory and run build.ps1 without any parameters. It will build HelloCpp by default.

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)

  1. Install CMake 3.27.4+.

  2. Install Visual Studio 2022 (VS 2019 should be supported, but VS 2022 is recommended).

  3. Create a new project as shown here.

  4. In a console window, navigate into the root directory of the project you created in the previous step.

  5. Generate the relevant Visual Studio project using the cmake command:

    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

  6. 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" "-DAX_VS_DEPLOYMENT_TARGET=10.0.17763.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).

  1. 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)

  1. Install Android Studio 2023.1.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.
  3. 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.
  4. 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:
  5. 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)

  1. Download Android command-tools.
  2. 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 -PPROP_BUILD_TYPE=cmake -PPROP_APP_ABI=arm64-v8a --parallel --info

iOS, tvOS and macOS

  1. Ensure that XCode 13+ is installed.

  2. Create a new project as shown here.

  3. In a console window, navigate into the root directory of the project you created in the previous step.

  4. Execute the following command: sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

  5. Generate the relevant XCode project using one of the following commands:

    • for iOS arm64:
      axmol build -p ios -a arm64 -c
    • for iOS simulator x86_64:
      axmol build -p ios -a x64 -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

  6. 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.

  7. 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)

  1. Run pwsh ./setup.ps1.
  2. Open axmol source folder with VSCode.
  3. Install C++, CMake extensions for VSCode.
  4. 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)
  5. 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.