How to setup env for caret_report

1. 問題概述

官方 caret_report 的 README.md 未完整列出相依套件，且 Babeltrace 2 Python 介面 (bt2) 未於 PyPI 發佈，導致在乾淨的 venv 裡執行：

pip install bt2

會回報：

ERROR: Could not find a version that satisfies the requirement bt2 (from versions: none)
ERROR: No matching distribution found for bt2

同時，若意外載入舊版 numexpr / bottleneck，Pandas 亦會顯示：

UserWarning: Pandas requires version '2.8.4' or newer of 'numexpr' …
UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' …

2. 解決方案總覽

  1. 在系統層（APT）安裝 python3-bt2。
  2. 建立能讀取系統套件的虛擬環境 (python -m venv --system-site-packages …)。
  3. 在 venv 中安裝其餘相依套件，並強制升級 numexpr / bottleneck。
  4. 執行範例或分析腳本。

3. 詳細步驟

3.1 安裝系統層 bt2 

# (0) 確認 universe 軟體庫已啟用
sudo add-apt-repository universe          # 已啟用可跳過
sudo apt update

# (1) 安裝 Babeltrace 2 Python 介面
sudo apt install python3-bt2

# (2) 驗證版本
python3 - <<'PY'
import bt2, sys
print(f"{bt2.__version__} → {sys.executable}")
PY

其他發行版請對應安裝 babeltrace2 或 python-bt2 套件。

3.2 建立能存取系統套件的 venv

cd ~/repo/caret_report
deactivate 2>/dev/null || true    # 若仍在舊 venv，先退出
rm -rf venv

python3 -m venv --system-site-packages venv
source venv/bin/activate

# 再度驗證 bt2
python - <<'PY'
import bt2, sys
print(f"{bt2.__version__} → {sys.executable}")
PY

3.3 安裝 caret_report 相依套件

pip install \
  "Flask>=3" \
  anytree \
  pyyaml \
  typeguard \
  numpy \
  tqdm \
  pandas \
  multimethod \
  "pydantic>=1.10" \
  "numexpr>=2.8.4" \
  "bottleneck>=1.3.6"

若 CI 或團隊需要固定版本，建議改寫 requirements.txt 或使用 Poetry。

3.4 執行範例（以 Autoware 為例）

cd sample_autoware
source ~/caret-v0.6.2/install/local_setup.bash
source run.sh ~/.ros/tracing/session-20250729085810

4. 常見警告排除

警告訊息 可能原因 解法
requires version '2.8.4' or newer of 'numexpr'
requires version '1.3.6' or newer of 'bottleneck' 		Python 載入了 ~/.local/lib 內較舊版本 在作用中 venv 執行：
pip install --upgrade "numexpr>=2.8.4" "bottleneck>=1.3.6"
或 pip uninstall --user numexpr bottleneck 後重裝
找不到 bt2 未使用 --system-site-packages 或系統未安裝 python3-bt2 依 3.1、3.2 步驟重建

5. 後續建議

  1. 文件同步：將本指引併入 docs/setup_guide.md，並於 README 置入連結。
  2. CI 測試：在 CI pipeline 加入安裝步驟，確保 PR 不因環境差異失敗。
  3. 離線安裝方案：若需全離線環境，可在內部私有 PyPI 伺服器發佈自行編譯之 bt2 wheel。
Edited by Ching-Hao Liu