A Comprehensive Guide to Building and Debugging Apache Doris

Apache Doris, a high-performance, real-time analytical database, boasts an impressive underlying architecture and code design. For developers, mastering source code compilation and debugging is key to understanding Doris’s core. However, the build process involves multiple toolchains and dependency configurations, and during debugging, you may encounter various complex issues that can leave beginners feeling overwhelmed.

This article walks you through the process from source code to runtime, providing a detailed analysis of Apache Doris’s compilation and debugging procedures. From environment setup and code checkout to troubleshooting common issues, we combine practical examples to help you quickly get started with Doris development and debugging. 

Overview

Have you ever wondered how a SQL query is parsed and executed from start to finish? In Apache Doris, this process involves multiple core components and complex internal mechanisms. This article will guide you through the journey from source code to runtime, offering a comprehensive analysis of Doris’s build and debugging process, and helping you gain a deep understanding of SQL execution principles.

1. Environment

Basic Environment

1. Computer configuration. MacBook Pro (Chip: Apple M1, macOS: 15.1)
2. JDK. Version 17
3. Doris branch. Use the Doris Master branch (specifically, the branch-2.1)

Installing Environment Dependencies

When using Homebrew, the installed JDK version is 17 because on macOS the arm64 version of Homebrew does not include JDK 8 by default. Currently, Doris supports only JDK8 and JDK17.

brew install automake autoconf libtool pkg-config texinfo coreutils gnu-getopt \ python@3 cmake ninja ccache bison byacc gettext wget pcre maven llvm@16 openjdk@17 npm

Dependency Explanation

1. Java, Maven, etc. These can be downloaded separately for easier management.

• On macOS, Zulu JDK17 is recommended.
• Maven can be downloaded from the official Maven website.
• Manually downloaded Java and Maven must be configured in your environment variables.

2. Other dependencies’ environment variables (example for Apple Silicon Macs):

export PATH=/opt/homebrew/opt/llvm/bin:$PATH 
export PATH=/opt/homebrew/opt/bison/bin:$PATH
export PATH=/opt/homebrew/opt/texinfo/bin:$PATH 

ln -s -f /opt/homebrew/bin/python3 /opt/homebrew/bin/python

Add the above configurations to your ~/.bashrc or ~/.zshrc file and run source ~/.bashrc or source ~/.zshrc to apply the changes.

Installing Thrift

Note: Thrift needs to be installed only when you are debugging just the FE (Frontend). When debugging both BE (Backend) and FE, the BE third-party libraries already include Thrift.

MacOS:    
1. Download: `brew install thrift@0.16.0`   
2. Create a symbolic link:        
`mkdir -p ./thirdparty/installed/bin`
# Apple Silicon 芯片 macOS
`ln -s /opt/homebrew/Cellar/thrift@0.16.0/0.16.0/bin/thrift ./thirdparty/installed/bin/thrift`
# Intel 芯片 macOS
`ln -s /usr/local/Cellar/thrift@0.16.0/0.16.0/bin/thrift ./thirdparty/installed/bin/thrift`

Note: Running `brew install thrift@0.16.0` on macOS may report that the version cannot be found. To resolve this, execute the following commands in the terminal:  
    1. `brew tap homebrew/core --force`
    2. `brew tap-new $USER/local-tap`
    3. `brew extract --version='0.16.0' thrift $USER/local-tap`
    4. `brew install thrift@0.16.0`

 Reference: `https://gist.github.com/tonydeng/02e571f273d6cce4230dc8d5f394493c`

Fetching Your Code

Clone your code by executing the following commands:

cd ~
mkdir DorisDev
cd DorisDev
git clone <https://github.com/GitHubID/doris.git>

Setting Environment Variables

export DORIS_HOME=~/DorisDev/doris
export PATH=$DORIS_HOME/bin:$PATH

Downloading Doris Build Dependencies

1. Visit the Apache Doris Third Party Prebuilt page (link) to find the source code for all third-party libraries. You can directly download doris-thirdparty-source.tgz.

2. Alternatively, you can download the precompiled third-party libraries from the same page, which saves you from compiling these libraries yourself. Refer to the commands below.

cd thirdparty
rm -rf installed

# For Intel Macs: curl -L <https://github.com/apache/doris-thirdparty/releases/download/automation/doris-thirdparty-prebuilt-darwin-x86_64.tar.xz> \\
    -o - | tar -Jxf -
# For Apple Silicon Macs: curl -L <https://github.com/apache/doris-thirdparty/releases/download/automation/doris-thirdparty-prebuilt-darwin-arm64.tar.xz> \\
    -o - | tar -Jxf -

# Verify that protoc and thrift run correctly: 
cd installed/bin

./protoc --version
./thrift --versio

When running protoc and thrift, you might encounter issues opening them due to developer verification problems. In that case, navigate to Security & Privacy and click the Open Anyway button in the General tab to confirm that you want to open the binary. For more details, refer to Apple Support.

Increase the System Maximum File Descriptor Limit

After modifying, run source on the corresponding file to apply the changes.

# For bash: echo 'ulimit -n 65536' >>~/.bashrc 
# For zsh: echo 'ulimit -n 65536' >>~/.zshrc

2. Compiling Doris

Navigate to your Doris home directory and run the build script:

cd $DORIS_HOME
 
# Compile the entire Doris project: 
sh build.sh 
# Or compile only FE and BE: 
sh build.sh --fe --be

If you want to speed up the build process and you do not require the FE frontend page, you can comment out the FE UI build section in the build.sh script:

# FE UI must be built before building FE
#if [[ "${BUILD_FE}" -eq 1 ]]; then
#    if [[ "${BUILD_UI}" -eq 1 ]]; then
#        build_ui
#    fi
#fi

After a successful compilation, you should see output similar to the following:

3. Debugging

Configuring the Debug Environment

This guide covers debugging the Doris FE only.

# Copy the compiled package to a separate directory:
 cp -r output/ ../doris-run 

# Configure FE/BE settings: 
 1. Set the IP and directories. 
 2. For BE, add the extra configuration: min_file_descriptor_number = 10000.

Start debugging using IntelliJ IDEA. 

Important: Do not open the root directory of the Doris project; instead, open the FE directory to avoid conflicts with CLion.

Generating FE Code

Open the IDEA terminal, navigate to the root directory of the code, and execute:

sh generated-source.sh

Wait until you see the message “Done”.

Configuring Debug for FE

1. Edit configurations.

2. Add a DorisFE configuration. Click the + icon in the upper left to add an Application configuration. Refer to the image below for the specific settings.

3. Working directory. Set it to the fe directory within the source code.

4. Environment variables. Configure the environment variables similarly to those exported in fe/bin/start_fe.sh in the Doris root directory. The DORIS_HOME variable should point to the directory you copied earlier during setup.

JAVA_OPTS=-Xmx8092m;
LOG_DIR=/Users/abc/DorisDev/doris-run/fe/log;
PID_DIR=/Users/abc/DorisDev/doris-run/fe/log;
DORIS_HOME=/Users/abc/DorisDev/doris-run/fe

Starting FE

Click Run or Debug. This will trigger the build process for FE; once completed, the FE will start. In this guide, we choose Debug.

Starting BE

Since you have already copied the compiled package to the doris-run directory, start the BE from within that directory:

sh bin/start_be.sh --daemon

Debugging FE

1. Connect to the FE. Use a MySQL client or DBeaver to connect to the FE launched by IDEA.

mysql -uroot -h127.0.0.1 -P9030

2. Add the BE node to the cluster.

alter system add backend "127.0.0.1:9050";

3. Set breakpoints in code. Locate the ConnectProcessor code in the project:

Set a breakpoint at the handleQuery method. When you execute a query, the debugger will hit the breakpoint, and you can start an enjoyable debugging journey. For instance, if you are working on the Doris syntax migration task mentioned in previous sessions, you can use debugging to iteratively refine your code.

FAQs

Question 1

During compilation, you might encounter a lock conflict error:

Could not acquire lock(s)

Answer

Delete any .lock files in your local Maven repository by running:

find ~/.m2/repository -name "*.lock" -delete

Question 2

During compilation, an error caused by a newer version of Node.js may occur:

opensslErrorStack: ['error:03000086:digital envelope routines::initialization error'] library: 'digital envelope routines' reason: 'unsupported' code: 'ERR_OSSL_EVP_UNSUPPORTED'

Answer

Set Node.js to use the legacy OpenSSL provider by executing:

# Instruct Node.js to use the legacy OpenSSL provider export NODE_OPTIONS=--openssl-legacy-provider

Reference: StackOverflow Discussion

Question 3

IntelliJ IDEA fails to start FE with the error:

java: OutOfMemoryError: insufficient memory

Answer

Maven’s compiler may not have enough memory. Increase the memory allocation as shown below:

Question 5

IntelliJ IDEA fails to start FE with the error:

java: cannot find symbol  Symbol:   class GeneratedMemoPatterns  Location: package org.apache.doris.nereids.pattern

Answer

Resolve this issue by executing the following commands in the Doris root directory:

mv fe/fe-core/target/generated-sources/annotations/org/apache/doris/nereids/pattern/ fe/fe-core/target/generated-sources/org/apache/doris/ 
mv fe/fe-core/target/generated-sources/cup/org/apache/doris/analysis/ fe/fe-core/target/generated-sources/org/apache/doris/

Question 5

In some versions, compilation may fail with the error:

error: reference to ‘detail’ is ambiguous

Answer

Modify the code according to this PR or execute the following commands:

wget https://github.com/apache/doris/pull/43868.patch 
git apply 43868.patch

Question 6

In some versions during debugging, the FE on port 9030 fails to start, and fe.log reports:

Can not find help zip file: help-resource.zip

Answer

Navigate to the doris/docs directory, execute the following commands, and then restart FE:

cd doris/docs sh build_help_zip.sh
cp -r build/help-resource.zip ../fe/fe-core/target/classes

By following this guide, you should be able to set up your environment, compile, and debug Apache Doris with greater ease. Happy debugging!