Suika3 Build Instructions
========================

Suika3 fully utilizes the CMake build system.

Notes:
* Requires CMake 3.22 or later
* Linux: GCC 4.4 or later (Clang is also supported)
* Windows: Visual Studio 2022/2026, or gcc/clang on WSL
* macOS: Xcode 8.2.1 or later required

---

## Linux (Wayland/X11 Dual)

### Prerequisites

* A `Linux` machine with any processor

On Debian, Ubuntu, or Raspberry Pi OS:
```
sudo apt-get install git cmake ninja-build build-essential libasound2-dev libx11-dev libxpm-dev libwayland-dev wayland-protocols libegl1-mesa-dev libegl-dev libgles-dev libwayland-client0 libwayland-egl1 libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-x libdecor-0-dev
```

On RedHat, Rocky Linux, Fedora, etc.:
```
sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install patch git cmake ninja-build alsa-lib-devel libX11-devel libXpm-devel wayland-devel wayland-protocols-devel mesa-libEGL-devel alsa-lib-devel gstreamer1.0-devel gstreamer1.0-plugins-base-devel libdecor-devel
```

### Steps

Open the terminal and type the following.
```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset linux
cmake --build --preset linux
```

The target file `build-linux/suika3` will be created.

If you want to debug Suika3 with GDB, you can use the `linux-debug` preset instead of `linux`.

---

## Linux (X11-Only)

### Prerequisites

* A `Linux` machine with any processor

On Debian, Ubuntu, or Raspberry Pi OS:
```
sudo apt-get install git cmake ninja-build build-essential libasound2-dev libx11-dev libxpm-dev mesa-common-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-x libdecor-0-dev
```

On RedHat, Rocky Linux, Fedora, etc.:
```
sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install patch git cmake ninja-build libX11-devel libXpm-devel alsa-lib-devel mesa-libGL-devel gstreamer1.0-devel gstreamer1.0-plugins-base-devel
```

### Steps

Open the terminal and type the following.
```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset linux-x11
cmake --build --preset linux-x11
```

The target file `build-linux-x11/suika3` will be created.

If you want to debug Suika3 with GDB, you can use the `linux-x11-debug` preset instead of `linux-x11`.


---

## Linux (Wayland)

Note that Wayland support is still experimental.
It is compatible with KDE, but has problems with showing windows on GNOME.

### Prerequisites

* A `Linux` machine with any processor

On Debian or Ubuntu:
```
sudo apt-get install git cmake ninja-build build-essential libasound2-dev libwayland-dev wayland-protocols libegl1-mesa-dev libegl-dev libgles-dev libwayland-client0 libwayland-egl1 libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-x libdecor-0-dev
```

On RedHat, Rocky Linux, Fedora, etc.:
```
sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install patch git cmake ninja-build wayland-devel wayland-protocols-devel mesa-libEGL-devel alsa-lib-devel gstreamer1.0-devel gstreamer1.0-plugins-base-devel libdecor-devel
```

### Steps

Open the terminal and type the following.
```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset linux-wayland
cmake --build --preset linux-wayland
```

The target file `build-linux-wayland/suika3` will be created.

If you want to debug Suika3 with GDB, you can use the `linux-wayland-debug` preset instead of `linux-wayland`.

---

## Windows (Visual Studio 2026)

Visual Studio is the recommended build environment for Windows, and is used for the official binary.

### Prerequisites

* A `Windows 11` PC with an Intel, AMD, or Arm64 processor
* `Visual Studio 2026` installed with C/C++ and CMake configured

### Steps

* Clone the repository.
* Open the root of the source code folder in Visual Studio.
* Wait for the CMake configuration to complete.
* Choose the `VS2026 x64 Release` target.
* Build the project.

The target file `out/build/windows-vs2026-x64-release/suika3.exe` will be created.

---

## Windows (WSL2)

This method uses MinGW on WSL2 to create a Windows exe file.
Note that it is possible to build Suika3 using MinGW,
but it is not recommended due to false positives in antivirus software.

### Prerequisites

* A `Windows 11` PC with an Intel, AMD, or Arm64 processor
* The `WSL2` feature installed
* `Ubuntu` or `Debian` installed on WSL2

```
sudo apt-get install cmake ninja-build mingw-w64
```

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset windows-mingw-x86_64
cmake --build --preset windows-mingw-x86_64
```

The target file `build-mingw-x86_64/suika3.exe` will be created.

---

## macOS (App Bundle)

This method creates an app bundle for macOS, and is used for the official binary.

### Prerequisites

* A Mac with an Apple Silicon or Intel processor
* `macOS 11` or later installed
* `Xcode` installed

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset macos
cmake --build --preset macos
```

The target `build-macos/Suika3.app` will be created.

### DMG Packaging

If you want to distribute Suika3 for macOS, you need to create a DMG file with code signing and notirization.
You need to have a `Developer ID Application` certificate in the keychain and be logged in with an Apple Developer account on Xcode.
Please note that an app bundle distributed via a zip file cannot access outside of the app bundle, so we use DMG here.

```
cd macos

# Sign the app.
codesign --timestamp --options runtime --entitlements ../resources/macos/macos.entitlements --deep --force --sign "Developer ID Application" Suika3.app

# Notarize the app. (takes some time)
ditto -c -k --sequesterRsrc --keepParent Suika3.app Suika3.zip
xcrun notarytool submit Suika3.zip --apple-id "$APPLE_ID" --team-id "$TEAM_ID" --password "$APP_SECRET" --wait
xcrun stapler staple Suika3.app

# Create a DMG file.
mkdir tmp
cp -Rv Suika3.app tmp/Suika3.app
hdiutil create -fs HFS+ -format UDBZ -srcfolder tmp -volname Suika3 Suika3.dmg

# Sign the DMG file to allow access to files outside the bundle (avoid Gatekeeper issues).
codesign --sign "Developer ID Application" Suika3.dmg
```

---

## macOS (CLI)

This method creates a command-line interface (CLI) version of Suika3 for macOS.
It is useful for debugging and development, but is not recommended for distribution.

### Prerequisites

* A Mac with an Apple Silicon or Intel processor
* `macOS 11` or later installed
* `Xcode` installed

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset macos-cli
cmake --build --preset macos-cli
```

The target `build-macos/Suika3.app` will be created.

If you want to debug Suika3 with LLDB, you can use the `macos-cli-debug` preset instead of `macos`.

---

## iOS

### Prerequisites

* A Mac with an Apple Silicon or Intel processor
* `macOS 11` or later installed
* `Xcode` installed

### Steps

* Pack assets into the `assets.arc` file.
* Download [the official binary](https://github.com/suika3-community/suika/releases) and extract it.
* Copy your `assets.arc` file into the `SDK/ios/resources` folder.
* Open the `SDK/ios` folder in Xcode.
* Build and run.

### Build from Scratch

If you want to build from scratch, use `cmake --preset ios-device` or `cmake --preset ios-simulator`,
then copy the built `libsuika3.a` file into the `SDK/ios/lib` folder, and open the `SDK/ios` folder in Xcode.

---

## Android

### Prerequisites

* `Android Studio`

### Steps

* Download [the official binary](https://github.com/suika3-community/suika/releases) and extract it.
* Copy your asset files into the `SDK/android/app/src/main/assets` folder.
* Open the `SDK/android` folder in Android Studio.

### Build from Scratch

If you want to build from scratch, use `cmake --preset android-arm64`, then copy the built `libsuika3.so` file into the `SDK/android/app/src/main/jniLibs/arm64-v8a` folder, and open the `SDK/android` folder in Android Studio.

---

## HarmonyOS NEXT / OpenHarmony

### Prerequisites

* `OpenHarmony SDK` installed

### Steps

* Download [the official binary](https://github.com/awemorris/suika/releases) and extract it.
* Copy your asset files into the `SDK/openharmony/entry/src/main/resources/rawfile` folder.
* Open the `SDK/openharmony` folder in DevEco.
* Build and run.

### Build from Scratch

If you want to build from scratch, use `cmake --preset openharmony-arm64`,
then copy the built `libsuika3.a` file into the `SDK/openharmony/entry/libs/arm64-v8a` folder,
and open the `SDK/openharmony` folder in DevEco.

---

## WebAssembly

### Prerequisites

* `emsdk` installed. (Any OS will do.)

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset wasm
cmake --build --preset wasm
```

The target file `wasm/index.html` will be created.

### Testing

To run the app, place your `assets.arc` file in the `wasm` folder.

After that, type `python -m http.server` and open `http://localhost:8000` in a browser window.

On Windows, you can use `suika3-web.exe` instead of `python`. It runs a small web server and opens the browser automatically.

---

## FreeBSD

### Prerequisites

* A `FreeBSD` machine
* `cmake` and `ninja` installed.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset freebsd
cmake --build --preset freebsd
```

The target file `build-freebsd/suika3` will be created.

---

## NetBSD

### Prerequisites

* A `NetBSD` machine
* `cmake` and `ninja` installed.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset netbsd
cmake --build --preset netbsd
```

The target file `build-netbsd/suika3` will be created.

---

## OpenBSD

### Prerequisites

* A `OpenBSD` machine
* `cmake` and `ninja` installed.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset openbsd
cmake --build --preset openbsd
```

The target file `build-openbsd/suika3` will be created.

---

## Solaris 11

### Prerequisites

* A `Solaris 11` machine
* `SunCC`, `cmake`, and `gmake` installed.
* `cmake` must be compiled by source code.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset solaris11
cmake --build --preset solaris11
```

The target file `build-solaris11/suika3` will be created.

---

## Solaris 10

### Prerequisites

* A `Solaris 10` machine
* `SunCC`, `cmake`, and `gmake` installed.
* `cmake` must be compiled by source code.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset solaris10
cmake --build --preset solaris10
```

The target file `build-solaris10/suika3` will be created.

---

## Haiku

### Prerequisites

* A `Haiku` machine
* `gcc`, `cmake`, and `ninja` installed.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset haiku
cmake --build --preset haiku
```

The target file `build-solaris10/suika3` will be created.

---

## Unity Plugin

### Prerequisites

* Full build of `LLVM-22` installed.

### Steps

Open the terminal and type the following.

```
git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset unity-win64
cmake --build --preset unity-win64
```

The target file `build-unity-win64/libsuika3.dll` will be created.

Note: Replace `win64` to one of `switch`, `ps5`, and `xbox`.

To use a vendor official SDK, open `cmake/toolchains/unity-*.cmake` and replace `CMAKE_C_COMPILER`, `CMAKE_CXX_COMPILER` and `CMAKE_AR`.
