Star314
143
代码
代码
Issues10
Pull Requests41
Actions
项目讨论
Wiki
分析
Star314
143
已合并
support webide,docker build env #129
zhangjie创建于 3月24日
support webide,docker build env #129
已合并
zhangjie创建于 3月24日
从newstarzj/oam-toolsmaster合入到cann/oam-toolsmaster
共 4 个文件变更+511-0
Adocs/quick_install.md+181-0
@@ -0,0 +1,181 @@
1+# 环境部署
2+ 
3+请您先参考下面步骤完成基础环境搭建和源码下载，确保已安装NPU驱动、固件和CANN软件（`Ascend-cann-toolkit`和`Ascend-cann-ops`）等。
4+ 
5+## 环境准备
6+ 
7+本项目提供多种搭建昇腾环境的方式，请按需选择。
8+ 
9+> **说明**：本文提到的编译态和运行态含义如下，请根据实际情况选择。
10+>
11+> - 编译态：针对仅编译本项目不运行的场景，只需安装CANN toolkit包。
12+> - 运行态：针对运行本项目的场景（编译运行或纯运行），需安装驱动与固件、CANN toolkit包、CANN ops包。
13+ 
14+| 安装方式 | 使用说明 | 使用场景 |
15+| ----- | ------ | ------ |
16+| WebIDE | 一站式开发平台，提供在线直接运行的昇腾环境，无需手动安装。<br>当前可提供单机算力，**默认安装最新商发版CANN包**。 | 适用于没有昇腾设备的开发者。|
17+| Docker | Docker镜像是一种高效部署方式，已预集成CANN包和必备依赖。<br>当前仅适用于Atlas A2系列产品，OS仅支持Ubuntu操作系统。**默认安装最新商发版CANN包**。 |适用有昇腾设备，需要快速搭建环境的开发者。|
18+| 手动安装 | - |适用有昇腾设备，想体验手动安装CANN包或体验最新master分支能力的开发者。|
19+ 
20+### 方式1：WebIDE环境
21+ 
22+对于无昇腾设备的开发者，可直接使用WebIDE开发平台，即“**一站式开发平台**”，该平台为您提供在线可直接运行的昇腾环境，环境中已安装必备的驱动固件、软件包和依赖，无需手动安装。更多关于开发平台的介绍请参考[LINK](https://gitcode.com/org/cann/discussions/54)。
23+ 
24+1. 进入开源项目，单击“`云开发`”按钮，使用已认证过的华为云账号登录。若未注册或认证，请根据页面提示进行注册和认证。
25+ 
26+ <img src="./figures/cloudIDE.png" alt="云平台" width="750px" height="90px">
27+ 
28+2. 根据页面提示创建并启动云开发环境，单击“`连接 > WebIDE `”进入一站式开发平台，开源项目的源码资源默认在`/mnt/workspace`目录下。
29+ 
30+ <img src="./figures/webIDE.png" alt="云平台" width="1000px" height="150px">
31+ 
32+ 
33+### 方式2：Docker部署
34+ 
35+对于不依赖昇腾设备的开发者，若您想快速搭建昇腾环境，可使用Docker镜像部署。
36+ 
37+> **说明**：镜像文件比较大，下载需要一定时间，请您耐心等待。关于docker命令的选项介绍可通过`docker --help`查询。
38+ 
39+1.**下载镜像**
40+ 
41+- 步骤1：以root用户登录宿主机。确保宿主机已安装Docker引擎（版本1.11.2及以上）。
42+- 步骤2：从[昇腾镜像仓库](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884)拉取已预集成CANN软件包及开发所需依赖的镜像。命令如下，根据实际架构选择：
43+ 
44+ ```bash
45+ # 示例：拉取ARM架构的CANN开发镜像
46+ docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
47+ # 示例：拉取X86架构的CANN开发镜像
48+ docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops
49+ ```
50+ 
51+2.**运行Docker**
52+拉取镜像后，需要以特定参数启动容器，以便容器内能访问宿主的昇腾设备。
53+ 
54+```bash
55+docker run --name oam-tools -it swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops bash
56+```
57+| 参数 | 说明 | 注意事项 |
58+| :--- | :--- | :--- |
59+| `--name oam-tools` | 为容器指定名称，便于管理。 | 可自定义。 |
60+| `-it` | `-i`（交互式）和 `-t`（分配伪终端）的组合参数。 | - |
61+| `swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10-ops` | 指定要运行的Docker镜像。 |请确保此镜像名和标签（tag）与你通过`docker pull`拉取的镜像完全一致。 |
62+| `bash` | 容器启动后立即执行的命令。 | - |
63+ 
64+3.**初始化环境**
65+进入容器后，执行以下命令初始化环境：
66+ 
67+```bash
68+curl -fsSL https://gitcode.com/oam-tools/init_env.sh | bash
69+```
70+ 
71+### 方式3：手动安装
72+ 
73+对于有昇腾设备的开发者，若您想手动搭建昇腾环境，请参考下述步骤。
74+ 
75+#### 前置依赖
76+ 
77+ 本项目源码编译用到的依赖如下，请注意版本要求。
78+ 
79+ - python >= 3.9.0
80+ - gcc >= 7.3.0
81+ - cmake >= 3.16.0
82+ - ccache
83+ - CANN toolkit组合包：`Ascend-cann-toolkit_${cann_version}_linux-${arch}.run`
84+ - CANN ops组合包：`Ascend-cann-${chip_type}-ops_${cann_version}_linux-${arch}.run`
85+ - protobuf >= 25.1
86+ - abseil >= 20230802.1
87+ - json >= 3.11.3
88+ - googletest（仅执行UT时依赖，建议版本 release-1.11.0）
89+ - mockcpp（仅执行UT时依赖，建议版本 2.7）
90+ - pytest（仅执行UT时依赖，建议版本 9.0.1）
91+
92+ 其中：
93+ - \$\{chip\_type\}：表示昇腾AI处理器型号，如910_93、910b等。
94+ - \$\{cann\_version\}：表示CANN包版本号，需要与Toolkit包版本号相同。
95+ - \$\{arch\}：表示CPU架构，如aarch64、x86_64。
96+ 
97+#### 软件安装
98+ 
99+1. **安装驱动与固件（运行态依赖）**
100+ 
101+ 驱动与固件的下载和安装操作请参考《[CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)》中“准备软件包”和“安装NPU驱动和固件”章节。驱动与固件是运行态依赖，若仅编译算子，可以不安装。
102+ 
103+2. **安装CANN包**
104+ 
105+ - **场景1：体验master版本能力或基于master版本进行开发**
106+ 
107+ 请单击[下载链接](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-mirror/software/master/)，选择最新时间版本，并根据产品型号和环境架构下载对应包。安装命令如下，更多指导参考《[CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)》。
108+ 
109+ 1. 安装CANN toolkit包
110+ 
111+ ```bash
112+ # 确保安装包具有可执行权限
113+ chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run
114+ # 安装命令
115+ ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --install-path=${install_path}
116+ ```
117+ 
118+ 2. 安装CANN ops包（运行态依赖）
119+ 
120+ ops包是运行态依赖，若仅编译算子，可不安装此包。
121+ 
122+ ```bash
123+ # 确保安装包具有可执行权限
124+ chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run
125+ # 安装命令
126+ ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run --install --install-path=${install_path}
127+ ```
128+ 
129+ - \$\{cann\_version\}：表示CANN包版本号。
130+ - \$\{arch\}：表示CPU架构，如aarch64、x86_64。
131+ - \$\{soc\_name\}：表示NPU型号名称。
132+ - \$\{install\_path\}：表示指定安装路径，ops包需与toolkit包安装在相同路径，root用户默认安装在`/usr/local/Ascend`目录。
133+ 
134+ - **场景2：体验已发布版本能力或基于已发布版本进行开发**
135+ 
136+ 请访问[CANN官网下载中心](https://www.hiascend.com/cann/download)，选择发布版本（仅支持CANN 8.5.0及后续版本），并根据产品型号和环境架构下载对应包，最后参考网页提供的命令完成安装。
137+ 
138+## 环境验证
139+ 
140+安装完CANN包后，需验证环境和驱动是否正常。
141+ 
142+- **检查NPU设备**
143+ 
144+ ```bash
145+ # 运行npu-smi，若能正常显示设备信息，则驱动正常
146+ npu-smi info
147+ ```
148+- **检查CANN安装**
149+ 
150+ ```bash
151+ # 查看CANN toolkit包版本信息（默认路径安装），WebIDE场景下将/usr/local替换为/home/developer
152+ cat /usr/local/Ascend/cann/${arch}-linux/ascend_toolkit_install.info
153+ # 查看CANN ops包版本信息（默认路径安装），WebIDE场景下将/usr/local替换为/home/developer
154+ cat /usr/local/Ascend/cann/${arch}-linux/ascend_ops_install.info
155+ ```
156+ 
157+## 环境变量配置
158+ 
159+按需选择合适的命令使环境变量生效。
160+```bash
161+# 默认路径安装，以root用户为例（非root用户，将/usr/local替换为${HOME}）
162+source /usr/local/Ascend/cann/set_env.sh
163+# 指定路径安装
164+# source ${install_path}/cann/set_env.sh
165+```
166+ 
167+## 源码下载
168+ 
169+源码下载命令如下，请将\$\{tag\_version\}替换为目标分支标签名，源码分支标签与CANN版本配套关系参见[release仓库](https://gitcode.com/cann/release-management)。
170+ 
171+```bash
172+# 下载项目对应分支源码
173+git clone -b ${tag_version} https://gitcode.com/cann/otm-tools.git
174+```
175+ 
176+对于WebIDE或Docker环境，已默认提供最新商发版本的项目源码，如需获取其他版本的源码，也需通过上述命令下载源码。
177+ 
178+> [!NOTE] 注意
179+>
180+> - gitcode平台在使用HTTPS协议的时候要配置并使用个人访问令牌代替登录密码进行克隆，推送等操作。
181+> - 若您的编译环境无法访问网络，无法通过git指令下载代码，请先在联网环境中下载源码，再手动上传至目标环境。
Ainit_env.sh+330-0
@@ -0,0 +1,330 @@
1+#!/bin/bash
2+# ----------------------------------------------------------------------------
3+# Copyright (c) 2025 Huawei Technologies Co., Ltd.
4+#
5+# Licensed under the Apache License, Version 2.0 (the "License");
6+# you may not use this file except in compliance with the License.
7+# You may obtain a copy of the License at
8+#
9+# http://www.apache.org/licenses/LICENSE-2.0
10+#
11+# Unless required by applicable law or agreed to in writing, software
12+# distributed under the License is distributed on an "AS IS" BASIS,
13+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+# See the License for the specific language governing permissions and
15+# limitations under the License.
16+# ----------------------------------------------------------------------------
17+ 
18+set -e
19+ 
20+RED='\033[0;31m'
21+GREEN='\033[0;32m'
22+YELLOW='\033[1;33m'
23+NC='\033[0m'
24+ 
25+CANN_VERSION="8.5.0"
26+CHIP_TYPE="910b"
27+CANN_BASE_URL="https://ascend.devcloud.huaweicloud.com/artifactory/cann-run/software"
28+INSTALL_PATH="${INSTALL_PATH:-/usr/local/Ascend}"
29+ 
30+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
31+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
32+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
33+ 
34+check_command() { command -v "$1" &>/dev/null; }
35+ 
36+get_arch() {
37+ local arch=$(uname -m)
38+ case $arch in
39+ x86_64) echo "x86_64" ;;
40+ aarch64) echo "aarch64" ;;
41+ *) log_error "Unsupported architecture: $arch"; return 1 ;;
42+ esac
43+}
44+ 
45+detect_cann_path() {
46+ local paths=(
47+ "/usr/local/Ascend/ascend-toolkit/latest"
48+ "/usr/local/Ascend/latest"
49+ "/usr/local/Ascend/cann-${CANN_VERSION}"
50+ "/usr/local/Ascend/cann-${CANN_VERSION}-beta.1"
51+ "/usr/local/Ascend/cann"
52+ "$HOME/Ascend/ascend-toolkit/latest"
53+ "$HOME/Ascend/latest"
54+ "$HOME/Ascend/cann-${CANN_VERSION}"
55+ "$HOME/Ascend/cann-${CANN_VERSION}-beta.1"
56+ "$HOME/Ascend/cann"
57+ )
58+ 
59+ for p in "${paths[@]}"; do
60+ if [ -d "$p" ] && [ -f "$p/bin/setenv.bash" ]; then
61+ echo "$p"
62+ return 0
63+ fi
64+ done
65+ 
66+ if [ -d "/usr/local/Ascend" ]; then
67+ for d in /usr/local/Ascend/ascend-toolkit/*; do
68+ [ -d "$d" ] && [ -f "$d/bin/setenv.bash" ] && echo "$d" && return 0
69+ done
70+ for d in /usr/local/Ascend/cann-*; do
71+ [ -d "$d" ] && [ -f "$d/bin/setenv.bash" ] && echo "$d" && return 0
72+ done
73+ fi
74+ return 1
75+}
76+ 
77+install_cann() {
78+ log_info "Checking CANN installation..."
79+ 
80+ local existing_cann=$(detect_cann_path)
81+ if [ -n "$existing_cann" ]; then
82+ log_info "CANN already installed at: $existing_cann"
83+ return 0
84+ fi
85+ 
86+ log_info "CANN not found, starting installation..."
87+ log_warn "This will download ~3GB of packages"
88+ 
89+ local arch=$(get_arch)
90+ local download_dir="/tmp/cann_install"
91+ mkdir -p "$download_dir"
92+ cd "$download_dir"
93+ 
94+ local toolkit_pkg="Ascend-cann-toolkit_${CANN_VERSION}_linux-${arch}.run"
95+ local ops_pkg="Ascend-cann-${CHIP_TYPE}-ops_${CANN_VERSION}_linux-${arch}.run"
96+ local toolkit_url="${CANN_BASE_URL}/${CANN_VERSION}/${arch}/${toolkit_pkg}"
97+ local ops_url="${CANN_BASE_URL}/${CANN_VERSION}/${arch}/${ops_pkg}"
98+ 
99+ if [ ! -f "$toolkit_pkg" ]; then
100+ log_info "Downloading CANN toolkit (${arch})..."
101+ log_info "URL: $toolkit_url"
102+ wget -q --show-progress --no-check-certificate -O "$toolkit_pkg" "$toolkit_url" || {
103+ log_error "Failed to download toolkit"
104+ return 1
105+ }
106+ fi
107+ 
108+ if [ ! -f "$ops_pkg" ]; then
109+ log_info "Downloading CANN ops (${CHIP_TYPE}, ${arch})..."
110+ log_info "URL: $ops_url"
111+ wget -q --show-progress --no-check-certificate -O "$ops_pkg" "$ops_url" || {
112+ log_error "Failed to download ops"
113+ return 1
114+ }
115+ fi
116+ 
117+ log_info "Installing CANN toolkit..."
118+ chmod +x "$toolkit_pkg"
119+ ./$toolkit_pkg --full --install-path="$INSTALL_PATH" || {
120+ log_error "Failed to install toolkit"
121+ return 1
122+ }
123+ 
124+ log_info "Installing CANN ops..."
125+ chmod +x "$ops_pkg"
126+ ./$ops_pkg --install --install-path="$INSTALL_PATH" || {
127+ log_warn "Ops installation may have issues (this can be normal on non-NPU systems)"
128+ }
129+ 
130+ log_info "Cleaning up..."
131+ rm -f "$toolkit_pkg" "$ops_pkg"
132+ cd - > /dev/null
133+ 
134+ log_info "CANN installation completed"
135+}
136+ 
137+setup_cann_env() {
138+ log_info "Setting up CANN environment..."
139+ 
140+ CANN_PATH=$(detect_cann_path)
141+ if [ -z "$CANN_PATH" ]; then
142+ log_error "CANN installation not found after installation!"
143+ return 1
144+ fi
145+ 
146+ log_info "CANN path: $CANN_PATH"
147+ export ASCEND_HOME_PATH="$CANN_PATH"
148+ 
149+ if [ -f "$CANN_PATH/bin/setenv.bash" ]; then
150+ source "$CANN_PATH/bin/setenv.bash"
151+ log_info "Sourced setenv.bash"
152+ fi
153+ 
154+ local pkg_inc="$CANN_PATH/pkg_inc"
155+ local arch_inc=""
156+
157+ if [ -d "$CANN_PATH/x86_64-linux/include" ]; then
158+ arch_inc="$CANN_PATH/x86_64-linux/include"
159+ elif [ -d "$CANN_PATH/aarch64-linux/include" ]; then
160+ arch_inc="$CANN_PATH/aarch64-linux/include"
161+ fi
162+ 
163+ if [ -n "$arch_inc" ] && [ -d "$arch_inc" ]; then
164+ mkdir -p "$pkg_inc"
165+ for dir in mmpa fmk ts adump; do
166+ if [ ! -e "$pkg_inc/$dir" ] && [ -d "$arch_inc/$dir" ]; then
167+ ln -sf "$arch_inc/$dir" "$pkg_inc/$dir" 2>/dev/null && \
168+ log_info "Linked $dir"
169+ fi
170+ done
171+ fi
172+}
173+ 
174+install_system_deps() {
175+ log_info "Checking system dependencies..."
176+ 
177+ if check_command apt-get; then
178+ apt-get update -qq 2>/dev/null
179+ local pkgs=""
180+ check_command curl || pkgs="$pkgs curl"
181+ check_command wget || pkgs="$pkgs wget"
182+ check_command git || pkgs="$pkgs git"
183+ check_command cmake || pkgs="$pkgs cmake"
184+ check_command make || pkgs="$pkgs make"
185+ check_command g++ || pkgs="$pkgs g++"
186+ check_command ccache || pkgs="$pkgs ccache"
187+
188+ if [ -n "$pkgs" ]; then
189+ log_info "Installing:$pkgs"
190+ apt-get install -y -qq $pkgs 2>/dev/null || log_warn "Some packages may have failed"
191+ fi
192+ elif check_command yum; then
193+ local pkgs=""
194+ check_command curl || pkgs="$pkgs curl"
195+ check_command wget || pkgs="$pkgs wget"
196+ check_command git || pkgs="$pkgs git"
197+ check_command cmake || pkgs="$pkgs cmake"
198+ check_command make || pkgs="$pkgs make"
199+ check_command g++ || pkgs="$pkgs gcc-c++"
200+
201+ if [ -n "$pkgs" ]; then
202+ log_info "Installing:$pkgs"
203+ yum install -y -q $pkgs 2>/dev/null || log_warn "Some packages may have failed"
204+ fi
205+ fi
206+ 
207+ log_info "cmake: $(cmake --version 2>&1 | head -1)"
208+ log_info "g++: $(g++ --version 2>&1 | head -1)"
209+ check_command ccache && log_info "ccache: available" || log_warn "ccache: not installed"
210+}
211+ 
212+install_python_deps() {
213+ log_info "Checking Python dependencies..."
214+ 
215+ local python="python3"
216+ check_command python3 || python="python"
217+
218+ log_info "Python: $($python --version 2>&1)"
219+ 
220+ local required=("pytest>=9.0.1" "coverage>=7.10.0" "pytest-cov>=7.0.0")
221+ local to_install=()
222+ 
223+ for pkg in "${required[@]}"; do
224+ local name=$(echo "$pkg" | sed 's/>=.*//')
225+ $python -c "import $name" 2>/dev/null || to_install+=("$pkg")
226+ done
227+ 
228+ if [ ${#to_install[@]} -ne 0 ]; then
229+ log_info "Installing Python packages: ${to_install[*]}"
230+ $python -m pip install --upgrade pip -q 2>/dev/null || true
231+ $python -m pip install "${to_install[@]}" -q 2>/dev/null || \
232+ log_warn "Some Python packages may have failed to install"
233+ else
234+ log_info "All Python dependencies satisfied"
235+ fi
236+ 
237+ check_command pytest && log_info "pytest: $(pytest --version 2>&1 | head -1)"
238+ check_command coverage && log_info "coverage: $(coverage --version 2>&1 | head -1)"
239+}
240+ 
241+show_help() {
242+ echo "Usage: $0 [OPTIONS]"
243+ echo ""
244+ echo "oam-tools development environment setup script"
245+ echo ""
246+ echo "Options:"
247+ echo " --cann-version VERSION CANN version (default: ${CANN_VERSION})"
248+ echo " --chip-type TYPE Chip type: 910b, 910_93, etc. (default: ${CHIP_TYPE})"
249+ echo " --install-path PATH Installation path (default: ${INSTALL_PATH})"
250+ echo " --skip-cann Skip CANN installation"
251+ echo " --help Show this help"
252+ echo ""
253+ echo "Examples:"
254+ echo " $0 # Install with defaults"
255+ echo " $0 --skip-cann # Skip CANN, install only deps"
256+ echo " $0 --chip-type 910_93 # Use 910_93 ops package"
257+ echo ""
258+}
259+ 
260+main() {
261+ local SKIP_CANN=false
262+ 
263+ while [[ $# -gt 0 ]]; do
264+ case $1 in
265+ --cann-version)
266+ CANN_VERSION="$2"
267+ shift 2
268+ ;;
269+ --chip-type)
270+ CHIP_TYPE="$2"
271+ shift 2
272+ ;;
273+ --install-path)
274+ INSTALL_PATH="$2"
275+ shift 2
276+ ;;
277+ --skip-cann)
278+ SKIP_CANN=true
279+ shift
280+ ;;
281+ --help|-h)
282+ show_help
283+ exit 0
284+ ;;
285+ *)
286+ log_warn "Unknown option: $1"
287+ shift
288+ ;;
289+ esac
290+ done
291+ 
292+ echo ""
293+ echo "=========================================="
294+ echo " oam-tools Development Environment Setup"
295+ echo "=========================================="
296+ echo ""
297+ echo "Configuration:"
298+ echo " CANN Version: ${CANN_VERSION}"
299+ echo " Chip Type: ${CHIP_TYPE}"
300+ echo " Install Path: ${INSTALL_PATH}"
301+ echo ""
302+ 
303+ local work_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
304+ cd "$work_dir"
305+ log_info "Working directory: $work_dir"
306+ 
307+ install_system_deps
308+ 
309+ if [ "$SKIP_CANN" = true ]; then
310+ log_info "Skipping CANN installation (--skip-cann)"
311+ else
312+ install_cann
313+ fi
314+ 
315+ setup_cann_env
316+ install_python_deps
317+ 
318+ echo ""
319+ log_info "=========================================="
320+ log_info " Development environment ready!"
321+ log_info "=========================================="
322+ echo ""
323+ echo "Next steps:"
324+ echo " bash build.sh # Build project"
325+ echo " bash build.sh -u # Build and run UT"
326+ echo " bash build.sh -u --cov # Build with coverage"
327+ echo ""
328+}
329+ 
330+main "$@"