This is an automated email from the ASF dual-hosted git repository.
zclll pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 5ec60c5aa2b Add BE multi-directory shared cache documentation for
ccache optimization with git worktree (#3452)
5ec60c5aa2b is described below
commit 5ec60c5aa2ba745cc2352ca43c66b66238f6676b
Author: zclllyybb <[email protected]>
AuthorDate: Wed Mar 11 23:15:12 2026 +0800
Add BE multi-directory shared cache documentation for ccache optimization
with git worktree (#3452)
docs of https://github.com/apache/doris/pull/61234
---
community/developer-guide/be-multi-directory.md | 66 +++++++++++++++++++++
.../current/developer-guide/be-multi-directory.md | 68 ++++++++++++++++++++++
sidebarsCommunity.json | 1 +
3 files changed, 135 insertions(+)
diff --git a/community/developer-guide/be-multi-directory.md
b/community/developer-guide/be-multi-directory.md
new file mode 100644
index 00000000000..9e2d97e491a
--- /dev/null
+++ b/community/developer-guide/be-multi-directory.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "BE Multi-Directory Shared Cache",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# BE Multi-Directory Shared Cache
+
+When working with AI Agents for Doris BE development, a common pattern is to
use `git worktree` or similar methods to maintain multiple development branches
in different directories simultaneously. Due to ccache's sensitivity to full
path names, even when the majority of cpp files are identical across different
directories, ccache cannot hit the cache, causing worktree directories to
recompile from scratch, significantly slowing down development. To address this
issue, we have implemente [...]
+
+## Directory Requirements
+
+Doris has already set `CCACHE_BASEDIR` and `-ffile-prefix-map` in the
environment configuration file, mapping most compilation options to the same
path for cache hit. **The premise is that all Doris development directories
must share the same parent directory.** All Doris development directories must
satisfy relationship like this:
+
+```bash
+xxx/doris_main
+xxx/doris1
+xxx/doris2
+```
+
+## Environment Configuration
+
+1. In addition to the above settings, hardcoded paths still need to be
manually adjusted. The UBSAN IGNORELIST of the main repository needs to be
hardcoded in the `custom_env.sh` of the worktree directory:
+
+```bash
+export UBSAN_IGNORELIST=${DORIS_MAIN_REPO}/conf/ubsan_ignorelist.txt
+```
+
+Where `DORIS_MAIN_REPO` is the path to the main repository. We recommend
configuring this value directly in the main repository's `custom_env.sh`, and
having the AI workflow automatically pass it to all worktree directories
through `hooks/setup_worktree.sh` and `AGENTS.md`.
+
+2. To ensure sufficient cache space, manually increase the ccache cache
capacity:
+
+```bash
+ccache --set-config=max_size=50G
+```
+
+## Debug Method
+
+You can use `ccache -s` to view cache statistics and confirm whether the cache
is working. Pay attention to the `cache hit rate` field; if the value is too
low, it indicates the cache is not being hit correctly. Before each
observation, you can use `ccache -z` to clear the statistics to ensure accurate
results. When cache hits are problematic, you can enable ccache debug logs to
confirm:
+
+```bash
+export CCACHE_LOGFILE=/path/to/xxx
+export CCACHE_DEBUG=1
+```
+
+You can view detailed cache hit information in `CCACHE_LOGFILE` to help
identify issues. After enabling `CCACHE_DEBUG=1`, each compilation unit will
generate its own `*.ccache-input-text` file, recording the input information of
that compilation unit, including source file paths and compilation options.
Theoretically, the same file in two different directories must have
**completely identical `ccache-input-text` content** to hit the ccache cache.
For files that fail to hit the cache, you [...]
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/developer-guide/be-multi-directory.md
b/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/developer-guide/be-multi-directory.md
new file mode 100644
index 00000000000..338580f0698
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs-community/current/developer-guide/be-multi-directory.md
@@ -0,0 +1,68 @@
+---
+{
+ "title": "BE 多目录共享缓存",
+ "language": "zh-CN"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# BE 多目录共享缓存
+
+在与 AI Agent 协作进行 Doris BE 开发时，一种常见的模式是利用 `git worktree`
等方式同时在不同目录下维护多个开发分支，并行开发。由于 ccache 缓存对全路径名敏感，因此在不同的目录中，即使绝大多数 cpp 文件内容相同，ccache
也无法命中缓存，导致 worktree 目录必须从零开始编译，极大拖慢开发速度。为解决这一问题，我们进行了定制的优化，按以下方式配置即可：
+
+## 目录要求
+
+Doris 已经在环境配置文件中设定了 `CCACHE_BASEDIR` 和
`-ffile-prefix-map`，对于绝大多数编译选项已经映射为同一路径，以便缓存命中。**它的前提是所有 Doris
开发目录必须共享相同的父目录。**即所有 Doris 开发目录必须满足：
+
+```bash
+xxx/doris_main
+xxx/doris1
+xxx/doris2
+```
+
+如上所示的并列关系。
+
+## 环境配置
+
+1. 除上述设定外，硬编码路径仍需要手动调整，需要在 worktree 目录的 `custom_env.sh` 中硬编码主库的 UBSAN
IGNORELIST：
+
+```bash
+export UBSAN_IGNORELIST=${DORIS_MAIN_REPO}/conf/ubsan_ignorelist.txt
+```
+
+其中 `DORIS_MAIN_REPO` 是主库的路径。我们推荐将该值直接配置在主库的 `custom_env.sh` 中，通过
`hooks/setup_worktree.sh` 和 `AGENTS.md` 的配合，由 AI 工作流自动传递给所有 worktree 目录。
+
+2. 为保证缓存空间足够，请手动扩大 ccache 缓存容量：
+
+```bash
+ccache --set-config=max_size=50G
+```
+
+## 调试方式
+
+可以通过 `ccache -s` 来查看缓存统计信息，确认缓存是否生效。重点关注 `cache hit rate`
字段，如果值过低说明缓存未正确命中。每次观测前可以通过 `ccache -z` 清空统计信息以确保结果准确。确认缓存命中有问题时，可以开启 ccache
Debug 日志来确认：
+
+```bash
+export CCACHE_LOGFILE=/path/to/xxx
+export CCACHE_DEBUG=1
+```
+
+在 `CCACHE_LOGFILE` 中可以查看详细的缓存命中情况，帮助定位问题。开启 `CCACHE_DEBUG=1` 后，每一个编译单元都会产生自己的
`*.ccache-input-text` 文件，记录该编译单元的输入信息，包括源文件路径、编译选项等。理论上两个不同目录的相同文件，**各自的
`ccache-input-text` 内容需要完全一致，才能命中 ccache 缓存。**对于未命中的文件，可以查看两侧
`ccache-input-text` 文件差异明确未命中原因。
diff --git a/sidebarsCommunity.json b/sidebarsCommunity.json
index c3d98fcbd6b..603b43cdcf3 100644
--- a/sidebarsCommunity.json
+++ b/sidebarsCommunity.json
@@ -70,6 +70,7 @@
"developer-guide/arthas",
"developer-guide/fe-idea-dev",
"developer-guide/fe-vscode-dev",
+ "developer-guide/be-multi-directory",
"developer-guide/be-vscode-dev",
"developer-guide/be-clion-dev",
{
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
