Suika3 LogoSuika3

Suika3 建置说明

Suika3 完全采用 CMake 建置系统。

注意事项：

  • 需要 CMake 3.22 以上
  • Linux：GCC 4.4 以上（也支援 Clang）
  • Windows：Visual Studio 2022/2026，或在 WSL 上使用 gcc/clang
  • macOS：需要 Xcode 8.2.1 以上

Linux（Wayland/X11 双模式）

必要条件

  • 一台任何处理器的 Linux 电脑

在 Debian、Ubuntu 或 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

在 RedHat、Rocky Linux、Fedora 等系统上：

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

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-linux/suika3。

如果你想用 GDB 除错 Suika3，可以改用 linux-debug preset，而不是 linux。

Linux（仅 X11）

必要条件

  • 一台任何处理器的 Linux 电脑

在 Debian、Ubuntu 或 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

在 RedHat、Rocky Linux、Fedora 等系统上：

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

步骤

开启终端机并输入以下指令。

git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset linux-x11
cmake --build --preset linux-x11

会产生目标档 build-linux-x11/suika3。

如果你想用 GDB 除错 Suika3，可以改用 linux-x11-debug preset，而不是 linux-x11。

Linux（Wayland）

请注意，Wayland 支援仍属实验性质。 它和 KDE 相容，但在 GNOME 上显示视窗时有问题。

必要条件

  • 一台任何处理器的 Linux 电脑

在 Debian 或 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

在 RedHat、Rocky Linux、Fedora 等系统上：

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

步骤

开启终端机并输入以下指令。

git clone https://github.com/suika3-community/suika3.git
cd suika3
cmake --preset linux-wayland
cmake --build --preset linux-wayland

会产生目标档 build-linux-wayland/suika3。

如果你想用 GDB 除错 Suika3，可以改用 linux-wayland-debug preset，而不是 linux-wayland。

Windows（Visual Studio 2026）

Visual Studio 是 Windows 的建议建置环境，也是官方二进位档所使用的方式。

必要条件

  • 一台配备 Intel、AMD 或 Arm64 处理器的 Windows 11 PC
  • 已安装并设定好 C/C++ 与 CMake 的 Visual Studio 2026

步骤

  • 复制此储存库。
  • 在 Visual Studio 中开启原始码资料夹的根目录。
  • 等待 CMake 组态完成。
  • 选择 VS2026 x64 Release 目标。
  • 建置专案。

会产生目标档 out/build/windows-vs2026-x64-release/suika3.exe。

Windows（WSL2）

这种方式会在 WSL2 上使用 MinGW 建立 Windows exe 档。 请注意，虽然可以用 MinGW 建置 Suika3，但不建议这样做，因为防毒软体可能会出现误判。

必要条件

  • 一台配备 Intel、AMD 或 Arm64 处理器的 Windows 11 PC
  • 已安装 WSL2 功能
  • WSL2 上已安装 Ubuntu 或 Debian
sudo apt-get install cmake ninja-build mingw-w64

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-mingw-x86_64/suika3.exe。

macOS（App Bundle）

这种方式会建立 macOS 的 app bundle，也是官方二进位档所使用的方式。

必要条件

  • 一台配备 Apple Silicon 或 Intel 处理器的 Mac
  • 已安装 macOS 11 或更新版本
  • 已安装 Xcode

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-macos/Suika3.app。

DMG 打包

如果你想释出 macOS 版 Suika3，就需要建立一个具备程式码签章与公证的 DMG 档。 你需要在钥匙圈中拥有 Developer ID Application 凭证，并且已在 Xcode 中登入 Apple Developer 帐号。 请注意，透过 zip 档释出的 app bundle 无法存取 bundle 外部的内容，因此这里改用 DMG。

cd macos

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

# 公证 app。（需要一些时间）
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

# 建立 DMG 档。
mkdir tmp
cp -Rv Suika3.app tmp/Suika3.app
hdiutil create -fs HFS+ -format UDBZ -srcfolder tmp -volname Suika3 Suika3.dmg

# 签署 DMG 档，以允许存取 bundle 外部的档案（避免 Gatekeeper 问题）。
codesign --sign "Developer ID Application" Suika3.dmg

macOS（CLI）

这种方式会建立 macOS 版 Suika3 的命令列介面（CLI）版本。 它适合除错与开发，但不建议用于释出。

必要条件

  • 一台配备 Apple Silicon 或 Intel 处理器的 Mac
  • 已安装 macOS 11 或更新版本
  • 已安装 Xcode

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-macos/Suika3.app。

如果你想用 LLDB 除错 Suika3，可以改用 macos-cli-debug preset，而不是 macos。

iOS

必要条件

  • 一台配备 Apple Silicon 或 Intel 处理器的 Mac
  • 已安装 macOS 11 或更新版本
  • 已安装 Xcode

步骤

  • 将素材打包成 assets.arc 档。
  • 下载 官方二进位档 并解压缩。
  • 将你的 assets.arc 档复制到 SDK/ios/resources 资料夹。
  • 在 Xcode 中开启 SDK/ios 资料夹。
  • 建置并执行。

从头建置

如果你想从头建置，请使用 cmake --preset ios-device 或 cmake --preset ios-simulator， 接著把建置好的 libsuika3.a 档复制到 SDK/ios/lib 资料夹，然后在 Xcode 中开启 SDK/ios 资料夹。

Android

必要条件

  • Android Studio

步骤

  • 下载 官方二进位档 并解压缩。
  • 将你的素材档复制到 SDK/android/app/src/main/assets 资料夹。
  • 在 Android Studio 中开启 SDK/android 资料夹。

从头建置

如果你想从头建置，请使用 cmake --preset android-arm64，然后把建置好的 libsuika3.so 档复制到 SDK/android/app/src/main/jniLibs/arm64-v8a 资料夹，最后在 Android Studio 中开启 SDK/android 资料夹。

HarmonyOS NEXT / OpenHarmony

必要条件

  • 已安装 OpenHarmony SDK

步骤

  • 下载 官方二进位档 并解压缩。
  • 将你的素材档复制到 SDK/openharmony/entry/src/main/resources/rawfile 资料夹。
  • 在 DevEco 中开启 SDK/openharmony 资料夹。
  • 建置并执行。

从头建置

如果你想从头建置，请使用 cmake --preset openharmony-arm64， 接著把建置好的 libsuika3.a 档复制到 SDK/openharmony/entry/libs/arm64-v8a 资料夹， 然后在 DevEco 中开启 SDK/openharmony 资料夹。

WebAssembly

必要条件

  • 已安装 emsdk。（任何作业系统都可以。）

步骤

开启终端机并输入以下指令。

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

会产生目标档 wasm/index.html。

测试

要执行应用程式，请把你的 assets.arc 档放到 wasm 资料夹中。

接著输入 python -m http.server，并在浏览器视窗中开启 http://localhost:8000。

在 Windows 上，你可以改用 suika3-web.exe 取代 python。它会启动一个小型网页伺服器，并自动开启浏览器。

FreeBSD

必要条件

  • 一台 FreeBSD 电脑
  • 已安装 cmake 与 ninja

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-freebsd/suika3。

NetBSD

必要条件

  • 一台 NetBSD 电脑
  • 已安装 cmake 与 ninja

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-netbsd/suika3。

OpenBSD

必要条件

  • 一台 OpenBSD 电脑
  • 已安装 cmake 与 ninja

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-openbsd/suika3。

Solaris 11

必要条件

  • 一台 Solaris 11 电脑
  • 已安装 SunCC、cmake 与 gmake
  • cmake 必须以原始码编译

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-solaris11/suika3。

Solaris 10

必要条件

  • 一台 Solaris 10 电脑
  • 已安装 SunCC、cmake 与 gmake
  • cmake 必须以原始码编译

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-solaris10/suika3。

Haiku

必要条件

  • 一台 Haiku 电脑
  • 已安装 gcc、cmake 与 ninja

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-solaris10/suika3。

Unity Plugin

必要条件

  • 已安装完整建置的 LLVM-22。

步骤

开启终端机并输入以下指令。

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

会产生目标档 build-unity-win64/libsuika3.dll。

注意：请把 win64 改成 switch、ps5 或 xbox 其中之一。

若要使用厂商官方 SDK，请开启 cmake/toolchains/unity-*.cmake，并修改 CMAKE_C_COMPILER、CMAKE_CXX_COMPILER 与 CMAKE_AR。