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.9 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 dfx

dfx is the command-line interface for managing your Internet Computer project.

You can install with curl:

sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

Verify it works with:

dfx --version

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.

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
}