Installation

Installation instructions for icpp-pro

---

It is recommended to do the installation in a Python virtual environment, like Miniconda or venv

Python version

icpp-pro requires python 3.11 or higher

Install icpp-pro

icpp-pro is available via PyPI, for Linux and Mac.

On Windows, use WSL Ubuntu.

pip install icpp-pro

# verify
$ icpp --version
icpp-pro version: x.y.z
wasi-sdk version: wasi-sdk-X.Y

Install wasi-sdk

Install the wasi-sdk compiler with:

icpp install-wasi-sdk

If a wasi-sdk binary is not available for your system, you can build it yourself using the instructions provided here, and then install it in ~/.icpp/wasi-sdk/wasi-sdk-25.0

After installation of the wasi-sdk compiler, your folder layout must look as follows:

<Your Home>/
|- .icpp/
|  |-wasi-sdk
|  |  |- wasi-sdk-25.0/
|  |  |  |- bin/
|  |  |  |- lib/
|  |  |  |- share/

Install icp-cli

icp is the command-line interface for managing your Internet Computer project. icpp-pro requires icp-cli 1.2.0 or higher.

You install it with npm:

npm install -g @icp-sdk/icp-cli

Verify it works with:

icp --version

Create a default identity

icp-cli does not ship with any identities, and the greet project's tests deploy as - and assert on - one named default. Create it once:

icp identity new default --storage plaintext
icp identity default default

Install Clang compiler

The Clang compiler toolchain is required for two reasons: 1. The wasi2ic utility is written in Rust, and Rust requires a Clang compiler 2. The icpp build-native command uses it to build a debug executable for interactive debugging in VS Code.

For each platform, it works slightly different to install it.

Linux (Ubuntu)

# Install clang++-18
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 18

# Create soft links for compiler executables
sudo ln --force -s /usr/bin/clang-18 /usr/bin/clang
sudo ln --force -s /usr/bin/clang++-18 /usr/bin/clang++

Mac

Install Xcode Command Line Tools, which includes the Clang compiler.

Install Rust compiler

The Rust compiler toolchain is required for the wasi2ic utility, which is written in Rust.

After installation of icpp-pro, you install it with:

icpp install-rust

Notes:

• we install it in ~/.icpp/rust, and it will not interfere with your system's Rust installation.

Optional: Install didc

didc is a very handy tool for translating candid between text format and the raw byte format.

You will use this tool when creating unit and smoke tests based on the raw byte format.

It is also what icpp build-wasm uses to generate the Javascript & Typescript bindings from your .did file. If didc is not installed, that step is skipped with a notice - pass --generate-bindings no if you do not need the bindings.

Linux

You can install with curl from https://github.com/dfinity/candid/releases:

# Get the latest version and store in VERSION_DIDC
# eg. 2023-07-11
export VERSION_DIDC=`curl --silent "https://api.github.com/repos/dfinity/candid/releases/latest" | grep -e '"tag_name"' | cut -c 16-25`

# download & install
wget https://github.com/dfinity/candid/releases/download/${VERSION_DIDC}/didc-linux64
sudo mv didc-linux64 /usr/local/bin/didc
chmod +x /usr/local/bin/didc

Verify it works with:

didc --version

$ didc encode '("hello C++")'
4449444c0001710968656c6c6f20432b2b

$ didc decode 4449444c0001710968656c6c6f20432b2b
("hello C++")

Mac

You can install with curl from https://github.com/dfinity/candid/releases:

# Get the latest version and store in VERSION_DIDC
# eg. 2023-07-11
export VERSION_DIDC=`curl --silent "https://api.github.com/repos/dfinity/candid/releases/latest" | grep -e '"tag_name"' | cut -c 16-25`

# download & install
wget https://github.com/dfinity/candid/releases/download/${VERSION_DIDC}/didc-macos
sudo mv didc-macos /usr/local/bin/didc
chmod +x /usr/local/bin/didc

Verify it works with:

didc --version

% didc encode '("hello C++")'
4449444c0001710968656c6c6f20432b2b

% didc decode 4449444c0001710968656c6c6f20432b2b
("hello C++")

Optional: Install VS Code

Install VS Code, with these extensions:

Extension	Author	Description
C/C++	Microsoft	C/C++ IntelliSense, debugging, and code browsing.
C/C++ Extension Pack	Microsoft	Popular extensions for C++ development in Visual Studio Code.
CodeLLDB	Vadim Chugunov	A native debugger powered by LLDB

Configure VS Code

To configure VS Code for use with icpp, add two files to a .vscode directory at the root of your project.

File: .vscode/launch.json

Add this file will allow you to start the debugger and set breakpoints in your C++ smart contract code:

For Linux:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug mockic.exe",
            "program": "${workspaceFolder}/greet/build-native/mockic.exe",
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

For Mac:

{
    "version": "0.2.0",
    "configurations": [
        {
          "type": "cppdbg",
          "MIMode": "lldb",
          "request": "launch",
          "name": "Debug mockic.exe",
          "program": "${workspaceFolder}/greet/build-native/mockic.exe",
          "args": [],
          "cwd": "${workspaceFolder}"
      }
    ]
}

File: .vscode/c_cpp_properties.json

Adding this file will provide C++ code checking & completion in the editor.

For Linux:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/clang++",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "linux-clang-x64"
        }
    ],
    "version": 4
}

For Mac:

{
    "configurations": [
        {
            "name": "Mac",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/clang++",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "macos-clang-x64"
        }
    ],
    "version": 4
}