# 快速上手

## CANN安装指南

开发者可访问[昇腾文档-昇腾社区](https://www.hiascend.com/document)->CANN社区版->软件安装，查看CANN软件安装引导，根据机器环境、操作环境和业务场景选择后阅读详细安装步骤。<br>

CANN包安装完成后，设置CANN环境变量：<br>

```sh
# root用户安装（默认路径）
source /usr/local/Ascend/latest/bin/set_env.sh
# 安装路径也可以是自己指定的路径${install_path}，如：
source ${install_path}/latest/bin/set_env.sh
```

## ACLSHMEM编译运行准备

### 1. ACLSHMEM库编译<br>

```sh
cd aclshmem
bash scripts/build.sh --package --python_extension
```

- {project_root}/package/{arch}/路径下会生成ACLSHMEM_{version}_linux-{arch}.run

- {project_root}/src/python/dist/路径下会生成aclshmem-xxx.whl

注：build.sh脚本参数介绍及使用可参考[脚本使用指南](03_scripts_guide.html)

### 2. 安装ACLSHMEM包<br>

软件包名为：ACLSHMEM\_{version}\_linux-{arch}.run <br>
其中，{version}表示软件版本号，{arch}表示CPU架构。<br>
安装run包（需要依赖CANN环境，请确保完成CANN安装）<br>

```sh
chmod +x 软件包名.run # 增加对软件包的可执行权限
./软件包名.run --check # 校验软件包安装文件的一致性和完整性
./软件包名.run --install --install-path=${install_path} # 安装软件，可使用--help查询相关安装选项，--install-path=可以指定任意目录，若不使用--install-path=方式指定装包目录的话，默认装包路径是/usr/local/Ascend/
```

出现提示`xxx install success!`则安装成功

### 3. 安装python wheel包<br>

在aclshmem/src/python/dist目录下，安装wheel包

```sh
pip3 install aclshmem-xxx.whl --force-reinstall
```

### 4. 设置ACLSHMEM库环境变量<br>

```sh
# root用户安装（默认路径）
source /usr/local/Ascend/aclshmem/latest/set_env.sh
# 安装路径也可以是自己指定的路径${install_path}，如：
source ${install_path}/aclshmem/latest/set_env.sh
```

## rank_table.json配置

样例运行前需先通过rank_table.json配置环境资源信息，可参考[rank table文件配置资源信息](https://www.hiascend.com/document/detail/zh/canncommercial/83RC1/hccl/hcclug/hcclug_000014.html)

```json
{
    "status":"completed",  // rank table可用标识，completed为可用
    "version":"1.0",       // rank table模板版本信息，配置为：1.0
    "server_count":"2",    // 参与训练的AI Server数目，此例中，有两个AI Server
    "server_list":
    [
        {
            "server_id":"node_0",  //AI Server标识，String类型，请确保全局唯一
            "device":[             // AI Server中的Device列表
                {
                    "device_id":"0",            // 处理器的物理ID
                    "device_ip":"192.168.1.8",  // 处理器真实网卡IP
                    "device_port":"16667",      // 处理器的网卡监听端口
                    "rank_id":"0"               // rank的标识，从0开始配置，请确保全局唯一
                },
                {
                    "device_id":"1",
                    "device_ip":"192.168.1.9", 
                    "device_port":"16667",
                    "rank_id":"1"
                }
            ]
        },
        {
            "server_id":"node_1",
            "device":[
                {
                    "device_id":"0",
                    "device_ip":"192.168.2.8",
                    "device_port":"16667",
                    "rank_id":"2"
                },
                {
                    "device_id":"1",
                    "device_ip":"192.168.2.9", 
                    "device_port":"16667",
                    "rank_id":"3"
                }
            ]
        }
    ]
}
```

## 样例运行验证

### 1. 在源码aclshmem目录下编译：

```sh
bash scripts/build.sh --examples
```

### 2. 执行[demo_rma_scalar_8p](https://gitcode.com/cann/aclshmem-dev/blob/master/examples/demo_rma_scalar_8p/README.md):

```sh
./build/bin/demo_rma_scalar_8p <rank_table.json文件路径> # 即上一节配置的rank_table.json文件存放路径
```

其他样例用法及样例说明，可参考examples/目录下各样例README.md