Musify工具的安装和使用

关于Musify工具的使用优先参考官方博客使用 musify 对代码进行平台迁移

当前每个版本的MUSA Toolkits都会包含Musify工具，本文档介绍如何快速部署和使用musify工具。

部署方法

1. 环境变量中增加（推荐）：

   可以在~/.bashrc文件中添加

   # musify tool 
   export PATH=/usr/local/musa/tools:${PATH} 
   

   然后source ~/.bashrc

   或者可以使用更简便的方法（但每次安装新版MUSA都要重新拷贝）：

   cp /usr/local/musa/tools/* /usr/bin 
   

2. 安装依赖(以Ubuntu系统为例)：

   sudo apt install ripgrep -y 
   sudo apt install python-is-python3 -y 
   sudo apt install pip -y 
   pip config set global.index-url https://pypi.mirrors.ustc.edu.cn/simple/ 
   pip install pyahocorasick==1.* 
   pip install ahocorapy 
   

   验证生效：

   ➜ musify-text -h                                                          
   usage: musify-text [-h] [-t | -c | -i] [-d {c2m,m2c}] [-m [MAPPING [MAPPING ...]]] [-q] [srcs [srcs ...]]
   
   positional arguments:
   srcs                  source files to be transformed
   
   optional arguments:
   -h, --help            show this help message and exit
   -t, --terminal        print code to stdout
   -c, --create          write code to newly created file, default action
   -i, --inplace         modify code inplace
   -d {c2m,m2c}, --direction {c2m,m2c}
                           convert direction
   -m [MAPPING [MAPPING ...]], --mapping [MAPPING [MAPPING ...]]
                           api mapping
   -q, --quiet           disable processing log  
   

使用示例

快速入门

1. 下载示例代码: musify_matrix_transpose.zip

2. 解压后，cd musify_matrix_transpose/src/，可以看到目录下两个CUDA代码文件：matrix_transpose.cu和error.cuh

3. 将CUDA代码转换到MUSA代码：

   ➜ musify-text -i *                                                                                                                             
   [INFO] [2023-11-30 10:39:58,266] Processing error.cuh
   [INFO] [2023-11-30 10:39:58,267] Processing matrix_transpose.cu
   

   打开文件可以看到里面的CUDA代码已经转换成为MUSA代码，即完成CUDA程序的迁移

4. 编译代码进行验证：返回到musify_matrix_transpose/目录下，执行mkdir build && cd build && cmake .. && make，编译成功后，运行可执行文件，即在MT GPU上运行MUSA程序

5. 也可以将MUSA代码再转换回CUDA代码：

   ➜ musify-text -i -d m2c *
   [INFO] [2023-11-30 10:43:53,876] Processing error.cuh
   [INFO] [2023-11-30 10:43:53,876] Processing matrix_transpose.cu
   

   再次查看文件，通过Musify工具已经将MUSA代码转换成CUDA代码

通用方法

➜ musify-text --inplace `rg --files -g '*.cu' -g '*.cuh' -g '*.cpp' -g '*.h'  -g '*.hpp' ${DIR}`
# 其中 -g '文件名后缀'； ${DIR}代表你要做转换的目录,需要使用者自行修改为需要porting的目录，建议**绝对目录**

其他方法

如果想使用其他方法(包括MUSA转CUDA），可以参考如下：

# Execute 'build/musify-text -h' to see more details
build/musify-text --inplace `rg --files -tcpp ${DIR}`
build/musify-text --inplace `rg --files --type-add 'cuda:*.cu' --type-add 'cuda:*.cuh' -tcuda -tcpp ${DIR}`
build/musify-text --inplace `find ${DIR} -name '*.cu' -name '*.cuh' -name '*.cpp' -name '*.h'`
build/musify-text --inplace `ls ${DIR}`
build/musify-text --inplace ${DIR}/*
# build/musify-text --inplace `or any method to list files here`
 
# Musa to Cuda Convertion
build/musify-text --inplace --direction m2c `rg --files ${DIR} -tcpp`