2. 编程环境

本节以Ubuntu 18.04系统环境为例进行本地离线安装示范。支持的软硬件平台兼容列表，参见《曦云^® 系列通用GPU用户指南》中“系统支持范围”章节。

2.1. 安装准备

操作步骤

执行以下命令，检查是否拥有支持MXMACA的GPU。
```
lspci | grep 9999
```
- 如果机器上有N（N＞0）张曦云GPU板卡，回显中含“9999”字段的行数为N时，则表示曦云GPU板卡正常在位。
  
  例如，若机器上有2张曦云C500且都正常在位，回显信息如下所示。
```
01:00.0 Display controller: Device 9999:4001 (rev 01)
02:00.0 Display controller: Device 9999:4001 (rev 01)
```
- 如果机器上有曦云系列GPU板卡但无内容显示，执行以下命令，检查是否已成功安装对应的GPU板卡驱动。
```
lsmod | grep metax
```
  若无内容显示，则表示未成功安装对应的GPU板卡驱动。驱动安装参见《曦云^® 系列通用GPU驱动安装指南》中“安装驱动”章节。
  
  备注
  
  驱动安装成功后，需要重启系统。
验证是否拥有支持MXMACA编程环境的Linux发行版。

执行以下命令，确认正在运行的Linux发行版及其版本号。
```
uname -m && cat /etc/*release
```
MXMACA编程环境仅在某些特定的Linux发行版上受支持。详情参见《曦云^® 系列通用GPU用户指南》中“系统支持范围”章节。

例如，机器是64位系统（x86_64），并且安装了Ubuntu 18.04的操作系统，回显信息如图 2.1 所示。

图 2.1 编程环境验证回显示例
验证系统是否已安装正确版本的GCC、g++、libstdc++、CMake和Make。

以验证系统上安装的GCC版本为例，执行以下命令：
```
gcc --version
```
使用MXMACA工具包进行开发必须安装GCC、g++、libstdc++、CMake和Make。运行MXMACA应用程序不需要。它们通常是作为Linux安装的一部分进行安装的，在大多数情况下，与受支持的Linux一起安装的GCC、g++、libstdc++、CMake和Make，都会正常工作。

例如，Ubuntu 18.04操作系统上安装了GCC 7.5.0版本，回显信息如图 2.2 所示。

图 2.2 系统验证回显示例

2.2. 安装MXMACA编程环境

MXC500 GPU的MXMACA编程环境从2.31.0开始支持以下两种安装方法：

本地离线安装MXMACA编程环境：支持所有发行版本的MXMACA软件栈。详细步骤参见 2.2.1 本地离线安装MXMACA编程环境。
在线安装MXMACA编程环境：支持2.31.0及之后版本的MXMACA软件栈，主要面向特定操作系统选定版本的包管理器安装（Package Manager Installation）。详细步骤参见 2.2.2 在线安装MXMACA编程环境。

2.2.1. 本地离线安装MXMACA编程环境

2.2.1.1. 安装MXMACA编程环境

备注

如果已安装了旧版本的MXMACA，请参见 2.2.1.5 卸载MXMACA编程环境的相应方式进行卸载后，再安装新版本的MXMACA。

操作步骤

安装MXMACA依赖。

MXMACA的依赖列表，参见表 2.1。

请确认表格中的依赖库是否都已安装；若没有，请自行获取并安装。

表 2.1 MXMACA依赖列表

序号

依赖名称

依赖安装命令

1

libelf1

sudo apt install libelf1

2

libnuma1

sudo apt install libnuma1
1. 以libnuma1为例，执行以下命令：
```
dpkg -l 'libnuma1'
```
2. 如果系统返回 dpkg-query: no packages found matching libnuma1，使用 apt 安装 libnuma1。
```
sudo apt install libnuma1
```
3. 使用以下命令再次进行查询。结果如图 2.3 所示，表示 libnuma1 安装成功。
```
dpkg -l 'libnuma1'
```
  图 2.3 libnuma1安装成功示例
解压获取安装包。
1. 获取MXMACA SDK的tar安装包 maca-sdk-mxc500-x.x.x.x-deb-x86_64.tar.xz，解压后可以看到 mxmaca-sdk-install.sh、version_compatible_check.sh、appimage、deb 等子目录。将安装包放入目标服务器，包内基础文件如下所示。
```
├── appimage
├── deb
├── mxmaca-sdk-install.sh
└── version_compatible_check.sh

2 directories, 2 files
```
2. 获取metax驱动安装包 metax-driver-mxc500-x.x.x.x-deb-x86_64.run。将安装包放入目标服务器。

执行以下命令，安装MXMACA编程环境。

cd xxx ##（MXMACA SDK解压目录）
sudo ./mxmaca-sdk-install.sh

结果如图 2.4 所示，用户需接受MXMACA SDK End User License Agreement（EULA），方可继续安装。

../_images/figure_2_4.png — 图 2.4 MXMACA SDK EULA接受或退出

接受MXMACA SDK EULA继续安装，安装成功后的目录如下所示。

root@device-01:/opt/maca$ tree -L 1
.
├── bin
├── etc
├── ffmpeg
├── include
├── lib
├── mxgpu_llvm
├── ompi
├── samples
├── share
├── tools
├── ucx
├── Version.txt
└── wheel

12 directories, 1 file

2.2.1.2. 配置MXMACA编程环境

MXMACA目前仅支持在默认路径 /opt/maca 下进行安装。

操作步骤

将以下MXMACA路径加入 PATH 环境变量中。

export PATH=$PATH:/opt/maca/mxgpu_llvm/bin:/opt/maca/bin

定义以下MXMACA环境变量。

export MACA_PATH=/opt/maca
export LD_LIBRARY_PATH=/opt/maca/lib:/opt/maca/mxgpu_llvm/lib

2.2.1.3. 启用MXMACA程序的访问权限

MXMACA程序需要特定文件夹的访问权限，但MXMACA程序进程不会修改文件夹中任何文件内容。

操作步骤

执行以下命令，启用访问权限。
```
sudo usermod –aG video $USER
```
将用户加入video用户组，为其启用访问权限。

2.2.1.4. 验证MXMACA编程环境的安装

操作步骤

执行以下命令，检查是否正确安装MXMACA编程环境。

macainfo

如下所示，如果 macainfo 在有曦云系列GPU运行的系统中正常运行，说明MXMACA编程环境安装成功。

root@device-01:/opt/maca$ macainfo
======================
MXC System Attributes
======================
Runtime Version: 1.0
System Timestamp Freq: 1000MHz
Signal Max Wait Time: 18446744073709551615(0xffffffffffffffff)
Machine Model: LARGE
System Endianess: LITTLE

2.2.1.5. 卸载MXMACA编程环境

操作步骤

执行以下命令，卸载MXMACA编程环境。
```
sudo /opt/maca/bin/mxmaca-sdk-install.sh -U
sudo /opt/mxdriver/mxdriver-install.sh -U
```
备注

使用MXMACA安装在系统路径下的 mxmaca-sdk-install.sh 和 mxdriver-install.sh 脚本进行卸载。

2.2.2. 在线安装MXMACA编程环境

在线安装MXMACA编程环境时，会与系统的包管理系统进行交互。rpm或deb软件包在安装时通过包管理器（如apt、yum或pip）自动下载。详细步骤参见在线指导：https://developer.metax-tech.com/softnova/index。

2.3. 验证MXMACA编程环境

2.3.1. 获取MXMACA源码示例

操作步骤

参见 2.2 安装MXMACA编程环境，成功安装MXMACA编程环境后，在 samples 目录下获取MXMACA源码示例。

root@device-01:/opt/maca$ tree -L 1
.
├── bin
├── etc
├── ffmpeg
├── include
├── lib
├── mxgpu_llvm
├── ompi
├── samples (*)
├── share
├── tools
├── ucx
├── Version.txt
└── wheel

12 directories, 1 file

2.3.2. 验证MXMACA编程环境

通过Makefile构建Linux MXMACA程序。

2.3.2.1. 用参考示例项目的Makefile构建MXMACA程序

示例项目的Makefile会使用一些特定选项，可参见表 2.2。

操作步骤

复制一个示例项目（比如 vectorAdd）到测试路径下，并将当前路径更改为要构建MXMACA程序的示例项目路径。
```
mkdir test
cp /opt/maca/samples/0_Introduction/vectorAdd/ test/ -R
cd test/vectorAdd/
```

选择以下任一方法构建MXMACA程序。

仅构建MXMACA程序：
```
$ make
```
MXMACA程序会被构建并生成到示例项目所在路径下，进行运行和启动。

构建并直接启动MXMACA程序：

$ make run
[Vector addition of 50000 elements]
Copy input data from the host memory to the MXMACA device
MXMACA kernel launch with 196 blocks of 256 threads
Copy output data from the MACA device to the host memory
Test PASSED
MXMACA Sample Done

执行以下命令，清除构建MXMACA程序时生成的项目文件。
```
make clean
```

2.3.2.2. 用自己的Makefile构建MXMACA程序

操作步骤

如需从零开始写一个MXMACA项目Makefile，可参见访问 Makefile官方指导手册。

新建自己的Makefile时，如果需要使用一些特定选项，可参见表 2.2 进行配置。

表 2.2 列出了mxcc编译和构建MXMACA程序时支持的典型选项。mxcc支持的更多选项，参见《曦云^® 系列通用GPU mxcc编译器用户指南》。

表 2.2 编译和构建MXMACA程序时的可用选项
序号	选项	选项备注
1	# Location of the MXMACA Toolkit `MACA_PATH ?= /opt/maca`
2	# start deprecated interface # `TARGET_ARCH ?= x86_64`	仅支持x86_64
3	#architecture `HOST_ARCH := $(shell uname -m)` `TARGET_ARCH ?= $(HOST_ARCH)`	仅支持x86_64
4	#operating system `HOST_OS := $(shell uname -s 2>/dev/null \| tr "[:upper:]" "[:lower:]")` `TARGET_OS ?= $(HOST_OS)`	初始支持的操作系统为Ubuntu 18.04。其他操作系统将会按需支持。
5	# host compiler `HOST_COMPILER ?= mxcc`
6	# Device compiler `MXCC := mxcc`
7	# Internal flags `MXCCFLAGS := -x maca`
8	#Install directory `MACA_INSTALL_TARGET_DIR := /opt/maca/bin`	示例项目不会使用此选项

参考 2.3.2.1 用参考示例项目的Makefile构建MXMACA程序，构建MXMACA程序并清除构建MXMACA程序时生成的项目文件。

表 2.1 MXMACA依赖列表
序号	依赖名称	依赖安装命令
1	libelf1	sudo apt install libelf1
2	libnuma1	sudo apt install libnuma1