본문으로 건너뛰기
최종 수정: 에

ARM 플랫폼에서 Apache Doris 컴파일하기

이 문서는 하드웨어 및 운영 체제 호환성, 의존성 설치, 빌드 과정을 포함하여 ARM64 플랫폼에서 Apache Doris를 컴파일하는 방법을 설명합니다.

정보

이 문서는 참고용입니다. ARM 환경에 따라 다른 오류가 발생할 수 있습니다. doris-website 이슈에 문제를 보고하거나 해결 방법을 제출해 주세요.

팁

3.0.3 버전부터 ARM 플랫폼에서 컴퓨팅과 스토리지가 분리된 모드로 컴파일하고 배포할 수 있습니다.

1. 하드웨어 및 운영 체제 호환성​

다음 환경은 커뮤니티에서 검증되었습니다.

운영 체제버전CPU 예시
KylinOSKylin-Server-10-SP1-Release-Build04-20200711Phytium FT-2000+/64
CentOS7.9 이상 (AltArch)aarch64
Ubuntu20.04aarch64
메모리 페이지 크기

ARM 서버용 배포판은 메모리 페이지 크기가 4 KiB 또는 64 KiB인 커널을 제공합니다(KylinOS V10과 CentOS 7/8 aarch64는 일반적으로 64 KiB, Ubuntu는 4 KiB). getconf PAGESIZE로 확인하세요. Doris가 ARM에서 빌드하는 jemalloc은 --with-lg-page=16을 사용하므로 하나의 바이너리로 두 페이지 크기의 커널에서 모두 실행할 수 있습니다. 다만 일부 서드파티 라이브러리는 빌드 시점에 페이지 크기에 대한 가정을 고정합니다. 직접 빌드하거나 검증할 때는 실제 배포 대상 커널에서도 확인하세요. 자세한 내용은 FAQ 4.2의 4번 항목을 참조하세요.

참고 출력:

# 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. 소프트웨어 환경 설정​

2.1 의존성 버전 참조 테이블(JDK 8 기준)​

구성 요소버전참고 사항
Git2.0+
JDK1.8.03.0+ 또는 master를 컴파일하려면 JDK 17 필요
Maven3.6.33.9.9 권장
NodeJS16.3.0
LDB Toolchain0.9.1ARM에서는 0.21+ 권장
autoconf2.69소스에서 설치
bison3.0.4
공통 시스템 패키지yum/apt로 자동 설치byacc, patch, automake, libtool, make, which, file, ncurses-devel, gettext-devel, unzip, bzip2, zip, util-linux, wget, git, python2

2.2 소프트웨어 환경 설치 명령어​

  1. 다운로드한 패키지와 설치한 소프트웨어를 저장할 루트 디렉터리 생성
# Create the root directory for downloaded packages
mkdir /opt/tools
# Create the root directory for installed software
mkdir /opt/software
  1. 의존성 설치
  • 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 (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 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. 컴파일​

팁

ARM 플랫폼에서는 컴파일에 LDB Toolchain만 사용할 것을 권장합니다. 이 방법은 커밋 7f3564 이후의 Doris 버전에 적용됩니다.

LDB Toolchain 다운로드 및 설치 방법은 위 절을 참조하세요. 이후 빌드 단계는 LDB Toolchain으로 컴파일하기를 참조하세요. JDK와 NodeJS는 aarch64 버전으로 교체해야 합니다(위 절 참조).

미리 빌드된 서드파티 라이브러리를 다운로드하는 데 문제가 있다면 thirdparty/build-thirdparty.sh를 사용하여 직접 빌드하세요. 서드파티 라이브러리를 빌드할 때는 gcc를 사용하세요.

export DORIS_TOOLCHAIN=gcc

다음 빌드 옵션은 ARM에서 x86_64와 다르게 동작합니다.

  • AVX2: USE_AVX2는 x86_64에만 적용되므로 ARM에서는 설정할 필요가 없습니다. ARM 명령어 집합은 ARM_MARCH로 선택합니다(4.0 이상, 기본값 armv8-a+crc). 예를 들어 ARM_MARCH=armv8-a+crc+simd sh build.sh --be와 같이 실행합니다.
  • libunwind: 4.1.3 이하(3.x 및 4.0 포함)에서는 ARM에서 libunwind가 동작하지 않으므로 빌드 전에 export USE_UNWIND=OFF를 설정해야 합니다. master(2026년 칠월)와 4.1.4부터는 USE_UNWIND 옵션이 제거되었습니다(apache/doris#64093). 모든 Linux 플랫폼에서 libunwind가 항상 활성화되며, 이 변수를 설정해도 더 이상 효과가 없습니다. 함께 제공되는 libunwind 1.6.2는 메모리 페이지 크기가 64 KiB인 커널에서 BE 시작 시 충돌을 일으킵니다. 자세한 내용은 FAQ 4.2의 4번 항목을 참조하세요.
  • Azure: 4.1 이하에서는 env.sh가 ARM에서 자동으로 DISABLE_BUILD_AZURE=ON을 설정하므로 별도로 설정할 필요가 없습니다. 2026년 팔월부터 master(apache/doris#66908)는 ARM에서도 Azure 라이브러리를 빌드하고 기본적으로 BE에 링크합니다. 이를 사용하지 않으려면 export DISABLE_BUILD_AZURE=ON을 설정하세요(BE가 해당 라이브러리를 링크하지 않음). 서드파티 라이브러리를 빌드할 때 export DISABLE_THIRDPARTY_BUILD_AZURE=ON도 설정하면 Azure 자체의 빌드도 건너뜁니다.

컴파일 또는 시작 과정에서 여전히 문제가 발생한다면 FAQ를 참조하세요. 관련 해결 방법이 없다면 이슈를 등록해 주세요.

4. FAQ​

4.1 컴파일 문제​

1. 서드파티 라이브러리 libhdfs3.a 컴파일 시 디렉터리를 찾을 수 없음​

  • 증상:

    컴파일 및 설치 중 다음 오류가 발생합니다.

    not found lib/libhdfs3.a file or directory

  • 원인:

    서드파티 라이브러리 의존성을 다운로드하지 못했습니다.

  • 해결 방법:

    서드파티 다운로드 저장소를 사용하여 서드파티 라이브러리를 다시 컴파일하세요.

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

REPOSITORY_URL에는 모든 서드파티 라이브러리와 이전 버전의 소스 패키지가 포함되어 있습니다.

2. python 명령을 찾을 수 없음​

  • 증상:

    build.sh를 실행하면 다음 예외가 발생합니다.

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

    Python 2.7.18

  • 원인:

    시스템은 기본적으로 python2.7, python3.6, python2 또는 python3 등의 명령으로 Python을 호출하지만, Doris 의존성에는 python이라는 이름의 명령이 필요합니다(2.7+ 사용 가능).

  • 해결 방법:

    /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. 컴파일 후 output 디렉터리가 없음​

  • 증상:

    build.sh가 완료된 후 해당 디렉터리에서 output 디렉터리를 찾을 수 없습니다.

  • 원인:

    컴파일에 성공하지 못했습니다. 다시 컴파일하세요.

  • 해결 방법:

      sh build.sh --clean

4. spark-dpp 컴파일 실패​

5. 여유 공간 부족으로 컴파일 실패​

  • 증상:

    컴파일 중 여유 공간이 없다는 메시지와 함께 CXX 객체 빌드가 실패합니다.

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

    1112 | } // namespace doris::vectorized

    compilation terminated.

  • 원인:

    장치의 여유 공간이 부족합니다.

  • 해결 방법:

    불필요한 파일을 삭제하는 등의 방법으로 장치의 공간을 확보하세요.

6. pkg.config에서 pkg.m4를 찾을 수 없음​

  • 증상:

    컴파일 중 "파일을 찾을 수 없음" 오류가 발생합니다.

    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.

    로그를 보면 libxml2 서드파티 라이브러리를 컴파일할 때 이 오류가 발생합니다.

  • 원인:

    libxml2 서드파티 라이브러리를 컴파일하는 동안 pkg.m4를 찾을 수 없습니다. 가능한 원인은 다음과 같습니다.

    1. Ubuntu 시스템에서 환경 변수를 불러오는 중 문제가 발생하여 ldb 디렉터리 아래의 인덱스를 정상적으로 불러오지 못합니다.
    2. libxml2 빌드 중 환경 변수 조회가 실패하여 빌드 과정에서 ldb/aclocal 디렉터리를 검색하지 않습니다.

  • 해결 방법:

    pkg.m4 파일을 ldb/aclocal에서 libxml2/m4 디렉터리로 복사한 후 서드파티 라이브러리를 다시 빌드하세요.

      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. CURL_HAS_TLS_PROXY 테스트 실패​

  • 증상:

    서드파티 패키지 컴파일 중 오류가 보고됩니다.

    -- 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.

    로그를 확인하면 curl 헤더 파일을 찾을 수 없다는 내용이 나옵니다.

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

    2 | #include <curl/curl.h>

    compilation terminated.

    ninja: build stopped: subcommand failed.

  • 원인:

    빌드에 LDB Toolchain 대신 시스템에 내장된 gcc 9.3.0이 사용되었습니다. LDB Toolchain 환경 변수를 올바르게 설정해야 합니다.

  • 해결 방법:

    LDB 환경 변수를 설정하세요.

      # 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. ninja failed with: signal: killed 메시지와 함께 컴파일 중단​

  • 증상:

    BE 또는 서드파티 라이브러리 컴파일이 도중에 실패하며 다음 내용이 포함된 메시지가 표시됩니다.

    ninja failed with: signal: killed

  • 원인:

    머신의 메모리가 부족합니다.

  • 해결 방법:

    메모리가 더 많은 머신(최소 16 GB)에서 컴파일하거나 빌드 동시 실행 수(-j)를 줄이세요.

4.2 시작 문제​

1. FE 시작 실패, 트랜잭션 -20 문제​

  • 증상:

    FE를 시작하면 상태가 UNKNOWN인 트랜잭션 오류 20이 보고됩니다.

    [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

  • 원인:

    디스크 공간이 부족합니다.

  • 해결 방법:

    디스크 공간을 확보하거나 새 디스크를 마운트하세요.

2. BDB 환경 설정 예외, 디스크 조회 오류​

  • 증상:

    FE가 위치한 디스크를 마이그레이션한 후 FE를 시작하면 예외가 발생합니다.

    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=

  • 원인:

    FE의 위치가 변경되어 메타데이터에 기록된 디스크 정보가 일치하지 않습니다. 또는 디스크가 손상되었거나 마운트되지 않았을 수 있습니다.

  • 해결 방법:

    • 디스크가 정상 상태이며 올바르게 초기화되고 마운트되었는지 확인하세요.
    • FE 메타데이터를 복구하세요.
    • 테스트 환경에서는 메타데이터 디렉터리를 삭제한 후 다시 시작할 수 있습니다.

3. BE 시작 시 core dump 발생, core 스택에 libc.so 또는 glibc-compatibility/ 포함​

  • 원인:

    현재 머신의 glibc 버전이 너무 낮습니다. ldd --version으로 확인하세요. 버전이 2.27 미만이면 이 문제가 발생할 수 있습니다.

  • 해결 방법:

    다음 환경 변수를 추가하여 BE를 다시 컴파일하세요.

      export GLIBC_COMPATIBILITY=OFF

4. ARM에서 BE 시작 직후 core dump 발생, core 스택에 unw_backtrace, access_mem, is_plt_entry 포함​

  • 증상:

    4.1.4 또는 2026년 칠월 이후의 master에서 빌드한 ARM BE는 start_be.sh 실행 직후 세그먼테이션 오류가 발생합니다. be.out에는 BE 로그가 남지 않으며, core 스택(가장 안쪽 프레임부터)은 다음과 같습니다.

    access_mem
    is_plt_entry
    _ULaarch64_step
    _ULaarch64_tdep_trace
    unw_backtrace
    ...
    __libc_csu_init

    또한 getconf PAGESIZE는 65536을 출력합니다.

  • 원인:

    이 버전들은 ARM에서 GNU libunwind 1.6.2를 정적으로 링크합니다(apache/doris#64093). 이 라이브러리의 AArch64 메모리 검증기에는 페이지 크기가 4 KiB로 하드 코딩되어 있습니다. 메모리 페이지 크기가 64 KiB인 커널에서는 모든 검증이 실패하고, libunwind가 main() 실행 전에 초기화되지 않은 주소를 역참조합니다. 페이지 크기가 4 KiB인 커널은 영향을 받지 않으므로 x86_64 또는 Ubuntu ARM에서는 이 문제가 재현되지 않습니다.

  • 해결 방법:

    apache/doris#67877(libunwind를 1.8.3으로 업그레이드)이 포함된 코드에서 빌드하거나 해당 변경이 포함된 릴리스를 사용하세요. 그전까지는 페이지 크기가 64 KiB인 커널에서 4.1.3을 사용하세요. 충돌이 main() 실행 전에 발생하므로 be.conf 설정으로는 이 문제를 우회할 수 없습니다.

4.3 다른 구성 요소 관련 문제​

  • 증상

    다음 구성 요소에서 오류 메시지가 표시되면 아래의 동일한 해결 방법을 적용하세요.

    • bison: bison-3.0.4 설치 시 fseterr.c 오류
    • flex: flex 명령을 찾을 수 없음
    • cmake: cmake 명령을 찾을 수 없음 / cmake가 의존 라이브러리를 찾을 수 없음 / cmake가 CMAKE_ROOT를 찾을 수 없음 / cmake가 CXX 환경 변수에 설정된 컴파일러를 찾을 수 없음
    • boost: Boost.Build 엔진 빌드 실패
    • mysql: mysql 클라이언트 의존성의 .a 파일을 찾을 수 없음
    • gcc: GCC 11+ 필요

  • 원인

    컴파일에 올바른 LDB Toolchain이 사용되지 않았습니다.

  • 해결 방법

    • LDB Toolchain 환경 변수가 설정되어 있는지 확인하세요.
    • gcc 버전이 LDB Toolchain으로 컴파일하기에서 권장하는 버전과 일치하는지 확인하세요.
    • ldb_toolchain_gen.aarch64.sh 실행으로 생성된 ldb 디렉터리를 삭제하고 스크립트를 다시 실행한 후 환경 변수를 설정하고 gcc 버전을 확인하세요.
Report issue