Installation

Installation instructions for icpp-pro

---

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

Install icpp-pro

icpp-pro is available via PyPI:

# For Linux, Mac or Windows
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-22.0

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

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

Install dfx

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

Linux & Mac

You can install with curl:

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

Verify it works with:

dfx --version

Windows

dfx is not available for Windows.

Please install dfx in wsl (Windows Subsystem Linux):

# From a WSL (Ubuntu) shell
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

Verify it works with:

# From a (Miniconda) Powershell
wsl --% . ~/.local/share/dfx/env; 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.

Windows

After installation of icpp-pro, you install the mingw64 compiler with:

icpp install-mingw64

Notes:

• We install it in ~/.icpp/mingw64 and it will not interfere with your system's mingw64 installatoin
• We use the 64bit UCRT version from winlibs.com

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++")

Windows

didc is not available as a prebuild binary for Windows.

Please install didc in wsl (Windows Subsystem Linux), using the same instructions as for Linux.

Verify it works with:

# From a Miniconda Powershell
wsl --% didc --version

> wsl --% didc encode '("hello C++")'
4449444c0001710968656c6c6f20432b2

> wsl --% 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}"
      }
    ]
}

For Windows:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "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
}

For Windows:

{
    "configurations": [
        {
            "name": "Win32",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "${env:USERPROFILE}\\.icpp\\mingw64\\bin\\clang++.exe",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "windows-clang-x64"
        }
    ],
    "version": 4
}