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-20.0

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

<Your Home>/
|- .icpp/
|  |- wasi-sdk-20.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)"

This command will install a binary compatible with your operating system in ~/bin/dfx

Verify it works with:

dfx --version

Windows

dfx is not available for Windows.

Please install dfx in wsl (Windows Subsystem Linux) and make it globally available, with the commands:

# From a WSL (Ubuntu) shell
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
sudo cp ~/bin/dfx /usr/local/bin/dfx
sudo chmod +x /usr/local/bin/dfx

Verify it works with:

# From a (Miniconda) Powershell
wsl --% . ~/.local/share/dfx/env; dfx --version

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:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "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": "C:\\mingw64\\bin\\clang++.exe",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "windows-clang-x64"
        }
    ],
    "version": 4
}

Optional: Install Clang

To interactively debug in VS Code, install the Clang compiler and make clang & clang++ available on the path.

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

IMPORTANT:

  • The compiler HAS to be GCC 13.2.0 (with POSIX threads) + LLVM/Clang/LLD/LLDB 17.0.6 + MinGW-w64 11.0.1 (UCRT) - release 5
  • earlier versions had a limitation regarding variants and will not link
  • we have not yet been able to get it working with later versions

From winlibs.com download the 64bit version of latest UCRT runtime that includes the LLVM/Clang/LLD/LLDB compiler.

We tested everything with:

GCC 13.2.0 (with POSIX threads) + LLVM/Clang/LLD/LLDB 17.0.6 + MinGW-w64 11.0.1 (UCRT) - release 5

NOTE: do NOT use mingw32, because you will get errors at compile time about the missing types __int128_t and __uint128_t.

Unzip the file, and copy the mingw64 folder to your C drive. After this, the compilers will be available in:

# For 64 bit systems
C:\mingw64\bin\clang
C:\mingw64\bin\clang++

Add the C:\mingw64\bin path to the system environment variable Path.

Verify Installation

On all OS systems, verify the installation in a terminal with:

clang++ --version