Skip to main content
Last updated on

Compile Apache Doris on ARM Platforms

This document describes how to compile Apache Doris on ARM64 platforms, including hardware and operating system compatibility, dependency installation, and the build process.

info

This document is for guidance only. Other errors may occur in different ARM environments. You are welcome to report them or submit solutions in doris-website Issues.

tip

Starting from version 3.0.3, the ARM platform supports compilation and deployment in compute-storage decoupled mode.

1. Hardware and Operating System Compatibility​

The following environments have been verified by the community:

Operating SystemVersionExample CPU
KylinOSKylin-Server-10-SP1-Release-Build04-20200711Phytium FT-2000+/64
CentOS7.9 and above (AltArch)aarch64
Ubuntu20.04aarch64
Memory page size

ARM server distributions ship kernels with either 4 KiB or 64 KiB memory pages (KylinOS V10 and CentOS 7/8 aarch64 are commonly 64 KiB, Ubuntu is 4 KiB); check with getconf PAGESIZE. The jemalloc that Doris builds on ARM uses --with-lg-page=16, so one binary runs on kernels of either page size, but some third-party libraries bake page-size assumptions in at build time. When you build or validate yourself, cover the kernel you actually deploy on; see item 4 of FAQ 4.2.

Reference output:

# KylinOS
$ cat /etc/.kyinfo
name=Kylin-Server
milestone=10-SP1-Release-Build04-20200711
arch=arm64
beta=False
time=2020-07-11 17:16:54
dist_id=Kylin-Server-10-SP1-Release-Build04-20200711-arm64-2020-07-11 17:16:54

$ cat /proc/cpuinfo
model name  : Phytium,FT-2000+/64

# CentOS 7.9
$ lsb_release -a
LSB Version:	:core-4.1-aarch64:core-4.1-noarch
Distributor ID:	CentOS
Description:	CentOS Linux release 7.9.2009 (AltArch)
Release:	7.9.2009
Codename:	AltArch

2. Software Environment Configuration​

2.1 Dependency Version Reference Table (Using JDK 8 as an Example)​

ComponentVersionNotes
Git2.0+
JDK1.8.0JDK 17 is required to compile 3.0+ or master
Maven3.6.33.9.9 is recommended
NodeJS16.3.0
LDB Toolchain0.9.10.21+ is recommended for ARM
autoconf2.69Install from source
bison3.0.4
Common system packagesInstalled automatically by yum/aptbyacc, patch, automake, libtool, make, which, file, ncurses-devel, gettext-devel, unzip, bzip2, zip, util-linux, wget, git, python2

2.2 Commands to Install the Software Environment​

  1. Create the root directories for downloaded packages and installed software
# Create the root directory for downloaded packages
mkdir /opt/tools
# Create the root directory for installed software
mkdir /opt/software
  1. Install dependencies
  • Git
  # To skip the compilation hassle, install directly with yum
  yum install -y git
  • JDK 8
  # When compiling Doris 2.1 or earlier versions, you can install JDK 8
  # Option 1: Install directly with yum. The devel package provides tools such as jps
  yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel

  # Option 2: Download the arm64 package, extract it, and configure environment variables
  cd /opt/tools
  wget https://doris-thirdparty-repo.bj.bcebos.com/thirdparty/jdk-8u291-linux-aarch64.tar.gz && \
    tar -zxvf jdk-8u291-linux-aarch64.tar.gz && \
    mv jdk1.8.0_291 /opt/software/jdk8
  • JDK 17
  # To compile Doris 3.0 (inclusive) or later versions, or the master branch, replace JDK 8 with JDK 17
  yum install -y java-17-openjdk java-17-openjdk-devel
  • Maven
  cd /opt/tools
  # Download, extract, and configure environment variables
  wget https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz && \
    tar -zxvf apache-maven-3.9.9-bin.tar.gz && \
    mv apache-maven-3.9.9 /opt/software/maven
  • NodeJS
  cd /opt/tools
  # Download the arm64 package
  wget https://doris-thirdparty-repo.bj.bcebos.com/thirdparty/node-v16.3.0-linux-arm64.tar.xz && \
    tar -xvf node-v16.3.0-linux-arm64.tar.xz && \
    mv node-v16.3.0-linux-arm64 /opt/software/nodejs
  • LDB Toolchain
  cd /opt/tools
  # Download the ARM version of LDB Toolchain
  wget https://github.com/amosbird/ldb_toolchain_gen/releases/download/v0.21/ldb_toolchain_gen.aarch64.sh && \
    bash ldb_toolchain_gen.aarch64.sh /opt/software/ldb_toolchain/
  1. Configure environment variables
# Configure environment variables (using JDK 8 as an example)
vim /etc/profile.d/doris.sh
export JAVA_HOME=/opt/software/jdk8
export MAVEN_HOME=/opt/software/maven
export NODE_JS_HOME=/opt/software/nodejs
export LDB_HOME=/opt/software/ldb_toolchain
export PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$NODE_JS_HOME/bin:$LDB_HOME/bin:$PATH

# Save, exit, and refresh environment variables
source /etc/profile.d/doris.sh

# Verify the installation (using JDK 8 as an example)
java -version
> java version "1.8.0_291"
mvn -version
> Apache Maven 3.9.9
node --version
> v16.3.0
gcc --version
> gcc-11
  1. Install additional environments and components
# Install common system packages
sudo yum install -y byacc patch automake libtool make which file ncurses-devel gettext-devel unzip bzip2 bison zip util-linux wget git python2

# Install autoconf-2.69
cd /opt/tools
wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz && \
    tar zxf autoconf-2.69.tar.gz && \
    mv autoconf-2.69 /opt/software/autoconf && \
    cd /opt/software/autoconf && \
    ./configure && \
    make && \
    make install

3. Compilation​

tip

On the ARM platform, only LDB Toolchain is recommended for compilation. This method applies to Doris versions after commit 7f3564.

For how to download and install LDB Toolchain, see the section above. For the subsequent build steps, see Compile with LDB Toolchain. JDK and NodeJS must be replaced with the aarch64 versions (see the section above).

If you have trouble downloading the prebuilt third-party libraries, use thirdparty/build-thirdparty.sh to build them yourself. Use gcc when building third-party libraries:

export DORIS_TOOLCHAIN=gcc

The following build switches behave differently on ARM than on x86_64:

  • AVX2: USE_AVX2 only applies to x86_64 and does not need to be set on ARM. The ARM instruction set is selected with ARM_MARCH (4.0 and later, default armv8-a+crc), for example ARM_MARCH=armv8-a+crc+simd sh build.sh --be.
  • libunwind: On 4.1.3 and earlier (including 3.x and 4.0), libunwind does not work on ARM and you need export USE_UNWIND=OFF before building. Starting with master (July 2026) and 4.1.4, the USE_UNWIND switch has been removed (apache/doris#64093): libunwind is always enabled on every Linux platform and setting the variable no longer has any effect. The bundled libunwind 1.6.2 crashes the BE on startup on kernels with 64 KiB memory pages; see item 4 of FAQ 4.2.
  • Azure: On 4.1 and earlier, env.sh sets DISABLE_BUILD_AZURE=ON automatically on ARM, so nothing needs to be set. Since August 2026, master (apache/doris#66908) builds the Azure libraries on ARM as well and links them into the BE by default. To opt out, set export DISABLE_BUILD_AZURE=ON (the BE does not link them); when building the third-party libraries, export DISABLE_THIRDPARTY_BUILD_AZURE=ON additionally skips building Azure itself.

If you still encounter issues during compilation or startup, see FAQ. If no relevant solution is available, you are welcome to open an issue.

4. FAQ​

4.1 Compilation Issues​

1. Cannot find the directory when compiling the third-party library libhdfs3.a​

  • Symptom:

    The following error appears during compilation and installation:

    not found lib/libhdfs3.a file or directory

  • Cause:

    The third-party library dependency failed to download.

  • Solution:

    Recompile third-party libraries using a third-party download repository.

  export REPOSITORY_URL=https://doris-thirdparty-repo.bj.bcebos.com/thirdparty
  sh /opt/doris/thirdparty/build-thirdparty.sh

REPOSITORY_URL contains the source packages of all third-party libraries and their historical versions.

2. python command not found​

  • Symptom:

    Running build.sh throws the following exception:

    /opt/doris/env.sh: line 46: python: command not found

    Python 2.7.18

  • Cause:

    The system invokes Python with commands such as python2.7, python3.6, python2, or python3 by default, but Doris dependencies require a command named python (2.7+ is fine).

  • Solution:

    Create a symbolic link at /usr/bin/python.

      # Check the python installation directory
      whereis python
      # Create the symbolic link
      sudo ln -s /usr/bin/python2.7 /usr/bin/python

3. No output directory after compilation​

  • Symptom:

    After build.sh finishes, the output directory is not found in the directory.

  • Cause:

    The compilation did not succeed. Recompile.

  • Solution:

      sh build.sh --clean

4. spark-dpp compilation failure​

5. Compilation fails due to insufficient free space​

  • Symptom:

    During compilation, building a CXX object fails with a message that there is no free space:

    fatal error: error writing to /tmp/ccKn4nPK.s: No space left on device

    1112 | } // namespace doris::vectorized

    compilation terminated.

  • Cause:

    The device has insufficient free space.

  • Solution:

    Free up space on the device, for example by deleting unneeded files.

6. pkg.m4 not found in pkg.config​

  • Symptom:

    A "file not found" error appears during compilation:

    Couldn't find pkg.m4 from pkg-config. Install the appropriate package for your distribution or set ACLOCAL_PATH to the directory containing pkg.m4.

    The logs show that this happens while compiling the libxml2 third-party library.

  • Cause:

    During the compilation of the libxml2 third-party library, pkg.m4 cannot be located. Possible reasons:

    1. The Ubuntu system has an issue while loading environment variables, so the index under the ldb directory is not loaded successfully.
    2. The environment variable lookup fails during the libxml2 build, so the build does not search the ldb/aclocal directory.

  • Solution:

    Copy the pkg.m4 file under ldb/aclocal to the libxml2/m4 directory and rebuild the third-party libraries:

      cp /opt/software/ldb_toolchain/share/aclocal/pkg.m4 /opt/doris/thirdparty/src/libxml2-v2.9.10/m4
      sh /opt/doris/thirdparty/build-thirdparty.sh

7. Test CURL_HAS_TLS_PROXY fails​

  • Symptom:

    An error is reported during third-party package compilation:

    -- Performing Test CURL_HAS_TLS_PROXY - Failed

    CMake Error at cmake/dependencies.cmake:15 (get_property):

    INTERFACE_LIBRARY targets may only have whitelisted properties. The property "LINK_LIBRARIES_ALL" is not allowed.

    Inspecting the logs reveals that the curl header file cannot be found:

    fatal error: curl/curl.h: No such file or directory

    2 | #include <curl/curl.h>

    compilation terminated.

    ninja: build stopped: subcommand failed.

  • Cause:

    The build used the system's built-in gcc 9.3.0 instead of LDB Toolchain. The LDB Toolchain environment variables need to be configured correctly.

  • Solution:

    Configure the LDB environment variables:

      # Configure environment variables
      vim /etc/profile.d/ldb.sh
      export LDB_HOME=/opt/software/ldb_toolchain
      export PATH=$LDB_HOME/bin:$PATH
      # Save, exit, and refresh environment variables
      source /etc/profile.d/ldb.sh
      # Test
      gcc --version
      > gcc-11

8. Compilation aborts with ninja failed with: signal: killed​

  • Symptom:

    BE or third-party library compilation fails midway with a message containing:

    ninja failed with: signal: killed

  • Cause:

    The machine is out of memory.

  • Solution:

    Use a machine with more memory (at least 16 GB) for compilation, or reduce the build concurrency (-j).

4.2 Startup Issues​

1. FE fails to start, transaction -20 issue​

  • Symptom:

    When starting FE, a transaction error 20 is reported, with status UNKNOWN:

    [BDBEnvironment.setup():198] error to open replicated environment. will exit.

    com.sleepycat.je.rep.ReplicaWriteException: (JE 18.3.12) Problem closing transaction 20. The current state is:UNKNOWN. The node transitioned to this state at:Fri Apr 22 12:48:08 CST 2022

  • Cause:

    Insufficient disk space.

  • Solution:

    Free up disk space or mount a new disk.

2. BDB environment setup exception, disk lookup error​

  • Symptom:

    After migrating the disk where FE resides, starting FE throws an exception:

    2022-04-22 16:21:44,092 ERROR (MASTER 172.28.7.231_9010_1650606822109(-1)|1) [BDBJEJournal.open():306] catch an exception when setup bdb environment. will exit.

    com.sleepycat.je.DiskLimitException: (JE 18.3.12) Disk usage is not within je.maxDisk or je.freeDisk limits and write operations are prohibited: maxDiskLimit=0 freeDiskLimit=5,368,709,120 adjustedMaxDiskLimit=0 maxDiskOverage=0 freeDiskShortage=1,536,552,960 diskFreeSpace=3,832,156,160 availableLogSize=-1,536,552,960 totalLogSize=4,665 activeLogSize=4,665 reservedLogSize=0 protectedLogSize=0 protectedLogSizeMap=

  • Cause:

    The location of FE has been migrated, and the disk information recorded in the metadata does not match. Alternatively, the disk is damaged or not mounted.

  • Solution:

    • Check that the disk is healthy, initialized, and mounted correctly.
    • Repair FE metadata.
    • In test environments, you can delete the metadata directory and restart.

3. BE coredumps on startup, with libc.so or glibc-compatibility/ in the core stack​

  • Cause:

    The glibc version on the current machine is too low. Confirm with ldd --version. This issue may occur if the version is below 2.27.

  • Solution:

    Recompile BE with the following environment variable added:

      export GLIBC_COMPATIBILITY=OFF

4. BE coredumps immediately on startup on ARM, with unw_backtrace, access_mem, is_plt_entry in the core stack​

  • Symptom:

    An ARM BE built from 4.1.4 or from master after July 2026 segfaults right after start_be.sh, with no BE log lines in be.out, and a core stack (innermost frame first) like:

    access_mem
    is_plt_entry
    _ULaarch64_step
    _ULaarch64_tdep_trace
    unw_backtrace
    ...
    __libc_csu_init

    and getconf PAGESIZE prints 65536.

  • Cause:

    These versions statically link GNU libunwind 1.6.2 on ARM (apache/doris#64093), whose AArch64 memory validator hard-codes a 4 KiB page size. On a kernel with 64 KiB memory pages every validation fails and libunwind dereferences an uninitialized address before main(). Kernels with 4 KiB pages are not affected, which is why this does not reproduce on x86_64 or on Ubuntu ARM.

  • Solution:

    Build from code or use a release that includes apache/doris#67877 (libunwind upgraded to 1.8.3); until then, use 4.1.3 on kernels with 64 KiB pages. The crash happens before main(), so no be.conf setting can work around it.

4.3 Issues With Other Components​

  • Symptom

    If you see error messages for any of the following components, handle them with the same solution below:

    • bison: error fseterr.c when installing bison-3.0.4
    • flex: flex command not found
    • cmake: cmake command not found / cmake cannot find dependent libraries / cmake cannot find CMAKE_ROOT / cmake cannot find the compiler set in the CXX environment variable
    • boost: Boost.Build engine build failure
    • mysql: cannot find the .a file of the mysql client dependency
    • gcc: GCC 11+ is required

  • Cause

    The correct LDB Toolchain was not used for compilation.

  • Solution

    • Check whether the LDB Toolchain environment variables are configured.
    • Check whether the gcc version matches what is recommended in Compile with LDB Toolchain.
    • Delete the ldb directory created by running ldb_toolchain_gen.aarch64.sh, run the script again, configure the environment variables, and verify the gcc version.
Report issue
ASF
Resources
Community
Join the community
Copyright © 2026 The Apache Software Foundation,Licensed under the Apache License, Version 2.0. Apache, Doris, Apache Doris, the Apache feather logo and the Apache Doris logo are trademarks of The Apache Software Foundation.