为 Linux、*BSD 平台编译

参见

本页面描述的是如何从源码编译 Linux 编辑器和导出模板二进制文件。如果你想要将项目导出到 Linux，请移步《为 Linux 导出》。

需求

要在Linux或其他类Unix系统下进行编译, 需要满足以下条件:

  • GCC 9+ 或 Clang 6+。

  • Python 3.8+.

  • SCons 4.0+ build system.

  • pkg-config（用于检测下面这些开发库）。

  • 开发库：

    • X11、Xcursor、Xinerama、Xi、XRandR。

    • Wayland 和 wayland-scanner。

    • Mesa。

    • ALSA。

    • PulseAudio。

  • 可选——libudev（使用 udev = yes 构建）。

参见

To get the Godot source code for compiling, see 获取源代码.

For a general overview of SCons usage for Godot, see 构建系统介绍.

针对各个发行版的单行命令

apk add \
  scons \
  pkgconf \
  gcc \
  g++ \
  libx11-dev \
  libxcursor-dev \
  libxinerama-dev \
  libxi-dev \
  libxrandr-dev \
  mesa-dev \
  eudev-dev \
  alsa-lib-dev \
  pulseaudio-dev

编译

启动终端，然后进入引擎源代码的根目录，输入：

scons platform=linuxbsd

备注

在 Godot 4.0 之前，Linux/*BSD 目标被称为 x11 而非 linuxbsd。如果你希望编译 Godot 3.x，请确保使用本文档的 3.x 分支。

小技巧

If you are compiling Godot to make changes or contribute to the engine, you may want to use the SCons options dev_build=yes or dev_mode=yes. See 开发别名与生产别名 for more info.

If all goes well, the resulting binary executable will be placed in the "bin" subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the Project Manager.

备注

如果你希望使用 Clang 而不是 GCC 编译器, 可以使用这个命令:

scons platform=linuxbsd use_llvm=yes

OpenBSD 上似乎必须使用 Clang，否则无法构建字体。在 RISC-V 架构的设备上请使用 Clang 编译器，不要使用 GCC 编译器。

小技巧

If you are compiling Godot for production use, you can make the final executable smaller and faster by adding the SCons option production=yes. This enables additional compiler optimizations and link-time optimization.

LTO takes some time to run and requires about 7 GB of available RAM while compiling. If you're running out of memory with the above option, use production=yes lto=none or production=yes lto=thin for a lightweight but less effective form of LTO.

备注

如果你想为自己的 Godot 构建和官方发布使用单独的编辑器设置，你可以通过在 bin/ 文件夹中创建一个名为 ._sc_ 或 _sc_ 的文件来启用 自包含模式。

运行无头/服务器构建

如果想要以无头模式运行，能够使用编辑器的自动导出项目功能，请使用普通构建：

scons platform=linuxbsd target=editor

然后使用 --headless 命令行参数：

./bin/godot.linuxbsd.editor.x86_64 --headless

如果要编译调试版本的服务器，支持远程调试工具，那么请使用：

scons platform=linuxbsd target=template_debug

要编译一个经过优化以运行专用游戏的服务器版本，请使用以下构建选项：

scons platform=linuxbsd target=template_release production=yes

构建导出模板

警告

Linux binaries usually won't run on distributions that are older than the distribution they were built on. If you wish to distribute binaries that work on most distributions, you should build them on an old distribution such as Ubuntu 16.04. You can use a virtual machine or a container to set up a suitable build environment.

To build Linux or *BSD export templates, run the build system with the following parameters:

  • （32 位）

scons platform=linuxbsd target=template_release arch=x86_32
scons platform=linuxbsd target=template_debug arch=x86_32

  • （64 位）

scons platform=linuxbsd target=template_release arch=x86_64
scons platform=linuxbsd target=template_debug arch=x86_64

请注意, 与你的主机平台相反的位(64/32)交叉编译并不总是直接的, 并且可能需要chroot环境.

To create standard export templates, the resulting files in the bin/ folder must be copied to:

$HOME/.local/share/godot/export_templates/<version>/

and named like this (even for *BSD which is seen as "Linux/X11" by Godot):

linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64

此外, 如果要编写自定义模块或自定义C ++代码, 则可能需要在此处将二进制文件配置为自定义导出模板:

../../../_images/lintemplates.png

你甚至不需要复制它们, 只需引用在Godot源文件夹的 bin/ 目录中生成的文件, 因此下次构建时, 将自动引用自定义模板.

Cross-compiling for RISC-V devices

To cross-compile Godot for RISC-V devices, we need to setup the following items:

  • riscv-gnu-toolchain. While we are not going to use this directly, it provides us with a sysroot, as well as header and libraries files that we will need. There are many versions to choose from, however, the older the toolchain, the more compatible our final binaries will be. If in doubt, use this version, and download riscv64-glibc-ubuntu-18.04-nightly-2021.12.22-nightly.tar.gz. Extract it somewhere and remember its path.

  • mold. This fast linker, is the only one that correctly links the resulting binary. Download it, extract it, and make sure to add its bin folder to your PATH. Run mold --help | grep support to check if your version of Mold supports RISC-V. If you don't see RISC-V, your Mold may need to be updated.

To make referencing our toolchain easier, we can set an environment variable like this:

export RISCV_TOOLCHAIN_PATH="path to toolchain here"

This way, we won't have to manually set the directory location each time we want to reference it.

With all the above setup, we are now ready to build Godot.

Go to the root of the source code, and execute the following build command:

PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH" \
scons arch=rv64 use_llvm=yes linker=mold lto=none target=editor \
    ccflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu" \
    linkflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu"

备注

RISC-V GCC has bugs with its atomic operations which prevent it from compiling Godot correctly. That's why Clang is used instead. Make sure that it can compile to RISC-V. You can verify by executing this command clang -print-targets, make sure you see riscv64 on the list of targets.

警告

The code above includes adding $RISCV_TOOLCHAIN_PATH/bin to the PATH, but only for the following scons command. Since riscv-gnu-toolchain uses its own Clang located in the bin folder, adding $RISCV_TOOLCHAIN_PATH/bin to your user's PATH environment variable may block you from accessing another version of Clang if one is installed. For this reason it's not recommended to make adding the bin folder permanent. You can also omit the PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH" line if you want to use scons with self-installed version of Clang, but it may have compatibility issues with riscv-gnu-toolchain.

The command is similar in nature, but with some key changes. ccflags and linkflags append additional flags to the build. --sysroot points to a folder simulating a Linux system, it contains all the headers, libraries, and .so files Clang will use. --gcc-toolchain tells Clang where the complete toolchain is, and -target riscv64-unknown-linux-gnu indicates to Clang the target architecture, and OS we want to build for.

If all went well, you should now see a bin directory, and within it, a binary similar to the following:

godot.linuxbsd.editor.rv64.llvm

You can now copy this executable to your favorite RISC-V device, then launch it there by double-clicking, which should bring up the project manager.

If you later decide to compile the export templates, copy the above build command but change the value of target to template_debug for a debug build, or template_release for a release build.

使用 Clang 和 LLD 可以加快开发速度

你也可以使用Clang和LD来构建Godot. 与默认的GCC + GNU ld设置相比, 这有两个好处:

  • 与GNU ld或gold相比,LD链接Godot的速度明显更快. 这导致更快的迭代时间.

  • 与GCC相比,Clang倾向于给出更多有用的错误信息.

为此，请从分发的包管理器中安装 Clang 和 lld 包，然后使用以下 SCons 命令：

scons platform=linuxbsd use_llvm=yes linker=lld

构建完成后，将在 bin/ 文件夹中创建一个以 .llvm 为后缀的新的二进制文件。

仍然建议使用GCC进行生产构建, 因为它们可以使用链接时间优化进行编译, 使产生的二进制文件更小, 更快.

如果发生了这个错误：

/usr/bin/ld: cannot find -l:libatomic.a: No such file or directory

有两种解决方法:

  • 在 Scon 命令中，添加 use_static_cpp=no 参数。

  • Follow these instructions to configure, build, and install libatomic_ops. Then, copy /usr/lib/libatomic_ops.a to /usr/lib/libatomic.a, or create a soft link to libatomic_ops by command ln -s /usr/lib/libatomic_ops.a /usr/lib/libatomic.a. The soft link can ensure the latest libatomic_ops will be used without the need to copy it every time when it is updated.

使用 mold 加快开发速度

For even faster linking compared to LLD, you can use mold. mold can be used with either GCC or Clang.

As of January 2023, mold is not readily available in Linux distribution repositories, so you will have to install its binaries manually.

  • 从发布页面下载 mold 二进制文件。

  • Extract the .tar.gz file, then move the extracted folder to a location such as .local/share/mold.

  • 将 $HOME/.local/share/mold/bin 添加到用户的 PATH 环境变量中。例如可以在 $HOME/.bash_profile 文件的末尾加上以下内容：

PATH="$HOME/.local/share/mold/bin:$PATH"

  • 打开新的终端（或者运行 source "$HOME/.bash_profile"），然后使用以下 SCons 命令编译 Godot：

    scons platform=linuxbsd linker=mold

使用系统库加快开发速度

Godot bundles the source code of various third-party libraries. You can choose to use system versions of third-party libraries instead. This makes the Godot binary faster to link, as third-party libraries are dynamically linked. Therefore, they don't need to be statically linked every time you build the engine (even on small incremental changes).

然而，并非所有 Linux 发行版都有可用的第三方库（或这些库不是最新版本）。

Moving to system libraries can reduce linking times by several seconds on slow CPUs, but it requires manual testing depending on your Linux distribution. Also, you may not be able to use system libraries for everything due to bugs in the system library packages (or in the build system, as this feature is less tested).

To compile Godot with system libraries, install these dependencies on top of the ones listed in the 针对各个发行版的单行命令:

sudo apt-get update
sudo apt-get install -y \
  libembree-dev \
  libenet-dev \
  libfreetype-dev \
  libpng-dev \
  zlib1g-dev \
  libgraphite2-dev \
  libharfbuzz-dev \
  libogg-dev \
  libtheora-dev \
  libvorbis-dev \
  libwebp-dev \
  libmbedtls-dev \
  libminiupnpc-dev \
  libpcre2-dev \
  libzstd-dev \
  libsquish-dev \
  libicu-dev

在安装了所有必要依赖后，使用下面的命令来构建 Godot：

scons platform=linuxbsd builtin_embree=no builtin_enet=no builtin_freetype=no builtin_graphite=no builtin_harfbuzz=no builtin_libogg=no builtin_libpng=no builtin_libtheora=no builtin_libvorbis=no builtin_libwebp=no builtin_mbedtls=no builtin_miniupnpc=no builtin_pcre2=no builtin_zlib=no builtin_zstd=no

On Debian stable, you will need to remove builtin_embree=no as the system-provided Embree version is too old to work with Godot's latest master branch (which requires Embree 4).

You can view a list of all built-in libraries that have system alternatives by running scons -h, then looking for options starting with builtin_.

警告

When using system libraries, the resulting binary is not portable across Linux distributions anymore. Do not use this approach for creating binaries you intend to distribute to others, unless you're creating a package for a Linux distribution.