msMemScope Installation Guide

1. Installation Description

This tool has been integrated into CANN. If CANN has been installed and this tool does not need to be updated, you can directly use it without following the instructions in this document.

If CANN has not been installed in your environment, install the Ascend NPU driver and CANN software (including the Toolkit and ops) by referring to CANN Quick Installation, and configure environment variables.

If you need to upgrade this tool separately or use the latest version, you can install it in any of the following ways: Online Installation, Offline Installation, and Installation from Source.

2. Installation Methods

2.1 Online Installation

If your device has Internet access, you can run a single command to automatically download and install the tool. Visit the Ascend community, select the target CANN version, and choose "online installation". The system will guide you through the subsequent operations.

2.2 Offline Installation

For devices that are not connected to the Internet, such as those on an enterprise intranet, download the complete offline installation package on a device that has Internet access and then transfer the package to the target device for installation. Visit the Ascend community, select the target CANN version, and choose "offline installation". The system will guide you through the subsequent operations.

2.3 Installation from Source

2.3.1 Installing Dependencies

Before the installation, ensure that the Git and Python environments are available. For details, see [version requirements](https://gitcode.com/Ascend/msmemscope/blob/26.0.0/docs/en/development_guide/development_guide.md#development environment-settings). If requirements are not met, run the following command to install dependencies.

Debian:

sudo apt-get install -y python3 git build-essential cmake

openEuler:

sudo yum install -y python3 git gcc gcc-c++ make cmake

2.3.2 Compiling and Building a RUN Package

Run the following git command on the terminal to clone the msMemScope source code.
```
git clone https://gitcode.com/Ascend/msmemscope.git -b 26.0.0
```
Download the Python third-party dependencies. Note that sqlite3 is an optional choice and is used for offline functions.
```
pip3 install -r ./requirements.txt
```
Download and build dependencies.
```
cd ./<remote-name>/build
python3 build.py local test
```
Parameters:
- local: local building. If this parameter is added, dependencies such as gtest and json are downloaded for local building. Generally, these dependencies are downloaded only for the first building unless they are updated.
- test: test cases.

Compile the package in the ./build directory.

bash make_run.sh

Pack all the outputs into a RUN package for installation and upgrade. If the following information is displayed, packaging is successful.

[INFO] Run file created successfully: xx/mindstudio-memscope_<version>_linux-<arch>.run
Usage instructions:
  Install: bash mindstudio-memscope_<version>_linux-<arch>.run --install --install-path=/path
  Upgrade: bash mindstudio-memscope_<version>_linux-<arch>.run --upgrade --install-path=/path
  Version: bash mindstudio-memscope_<version>_linux-<arch>.run --version
  Help:    bash mindstudio-memscope_<version>_linux-<arch>.run --help

Note: arch indicates the CPU architecture. After the compilation is complete, the package is generated in the ./build directory.

2.3.3 Installing the RUN Package

Grant the execute permission on the RUN package.

chmod +x mindstudio-memscope_<version>_linux-<arch>.run

Install the package.
```
bash mindstudio-memscope_<version>_linux-<arch>.run --install --install-path=<path>
```
Note: path indicates the installation directory.

Install msMemScope in the path directory. After the installation is successful, the following information is displayed:
```
source <path>/msmemscope/set_env.sh
[INFO] Installation completed successfully
```

2.3.4 Verifying the Installation

Check whether the set_env.sh file is generated in the <path>/msmemscope directory.

2.3.5 Configuring Environment Variables

Before using msMemScope, run the following command to configure the PYTHONPATHand PATH environment variables.

source <path>/msmemscope/set_env.sh

After the environment variables are configured, the following information is displayed:

Setting up msmemscope environment...
bash: local: can only be used in a function
✓ Added to PYTHONPATH (forced to front):<path>/msmemscope/python
bash: local: can only be used in a function
✓ Added to PATH (forced to front): <path>/msmemscope/bin
msmemscope environment setup completed

3. Uninstallation

If you have set the LD_PRELOAD environment variable when using the memory profiling function, run the unset LD_PRELOAD command to reset the environment variable before uninstallation to avoid uninstallation failure.

Perform the following steps to uninstall the tool:

Download the script.
```
curl -O https://inst.obs.cn-north-4.myhuaweicloud.com/26.0.0/ms_install.py
```
- An internet connection is required for downloading. If the environment does not allow internet access or is offline, download the script on a machine with internet connectivity first, and then copy it to the target device.
- If the command does not respond, or if you encounter connection failures, SSL certificate errors, or other issues, please refer to the FAQs.
Uninstall the tool.
```
python ms_install.py uninstall {tools_name}
```
Replace {tools_name} with the name of the tool to be uninstalled. You can run the python ms_install.py help command to query the tool name, which is displayed under the Available Tools field in the command output.

If the uninstallation is successful, the following information is displayed:
```
Successfully uninstalled 1 tool ({tools_name})
```

4. Upgrade

Upgrading follows a "uninstall first, then install" approach. Simply run the installation command, and the tool will automatically uninstall the old version and guide you through the overlay installation process.

5. Appendix

Option Description

This section describes the parameters related to the RUN package. This package supports one-click installation using command line options. The options can be used together. You can select the options as required.

Installation command syntax: ./mindstudio-memscope_<version>_linux-<arch>.run [options]

For details, see Table 1.

If options queried by running the ./mindstudio-memscope_<version>_linux-{arch}.run --help command are not in the following table, they are reserved or apply to other products. You do not need to pay attention to them.

Table 1 Options

Option	Description
--help	Queries help information.
--version	Queries version information.
--install	Installs the package. You can specify the installation path `--install-path=<path>` or use the default installation path.
--upgrade	Upgrades the installed software to a later version from an earlier version. To roll back from a later version to an earlier version, uninstall the later version and install the required version.
--install-path	Specifies the installation path. This option must be used together with --install and --upgrade.