mirror of https://github.com/axmolengine/axmol.git
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# 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](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) / [Download](https://github.com/PowerShell/PowerShell/releases)
|
|
- **CMake 3.28.1+**
|
|
- Manual installation is recommended ([download](https://cmake.org/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](https://github.com/axmolengine/axmol)).
|
|
2. Enter `axmol` root directory.
|
|
3. Run `setup.ps1` in windows powershell or (macOS/Linux/ArchLinux terminal). 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
|
|
|
|
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 -c`
|
|
- for Apple Silicon (arm64): `axmol build -p ios -a arm64 -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`
|
|
- WASM: `axmol build -p wasm` (it can run on Windows 8.1+, Linux and macOS, it requires a preinstalled [python3](https://www.python.org/) 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)
|
|
|
|
1. Install [CMake 3.27.4+](https://cmake.org/download/).
|
|
2. Install Visual Studio 2022 (VS 2019 should be supported, but VS 2022 is recommended).
|
|
3. Create a new project as shown [here](#creating-a-new-project).
|
|
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:
|
|
|
|
```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```
|
|
|
|
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"```
|
|
|
|
#### 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).
|
|
|
|
7. 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](https://github.com/axmolengine/axmol/issues/564).
|
|
|
|
### Android (Android Studio)
|
|
|
|
1. Install [Android Studio 2023.1.1+](https://developer.android.com/studio).
|
|
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:
|
|
- 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
|
|
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](https://developer.android.com/studio#command-tools).
|
|
2. Install Android devtools. Example in Windows:
|
|
|
|
```bat
|
|
# 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
|
|
|
|
1. Ensure that XCode 13+ is installed.
|
|
2. Create a new project as shown [here](#creating-a-new-project).
|
|
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 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```
|
|
|
|
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:
|
|
```sh
|
|
# 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.
|