IC智能合约编程：C++语言开发环境

编辑：同济大学元宇宙Web3实验室主任 ~ 宋志光

参考文献：https://docs.icpp.world/getting-started.html

To create canister smart contracts it is common practice to use an SDK. The IC SDK is a common entry point. The IC SDK supports a few programming languages out of the box.

要创建容器智能合约，通常的做法是使用 SDK。 IC SDK 是一个常见的入口点。 IC SDK 支持多种开箱即用的编程语言。

The most common languages to use are:

It is also possible to split your work between multiple languages. Different canister smart contracts talk to each other using the Candid language (an IDL used commonly in ICP smart contracts). What language works behind the Candid interface, however, does not matter.

也可以将您的工作拆分为多种语言。 不同的容器智能合约使用 Candid 语言（ICP 智能合约中常用的 IDL）相互通信。 然而，Candid 界面背后使用什么语言并不重要。

C++ Canister Development Kit

icpp-pro is a CDK to develop C++ smart contracts for the Internet Computer.

"...needed to have more flexibility with using c++ code as backend server. With the introduction of icpp within icp, it is now possible to create something that crosses the borders of what is possible."Ktimam Imam ( ICSoccerWorld)

======================

Getting Started

Introduction to developing canisters in C++

Install icpp-pro

First install icpp-pro as explained in the Installation Guide

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

Create the greet project

Create the greet starter project with:

icpp init

This will create a complete C++ project, with:


demo script

In the root folder of the greet project, you can find two demo scripts:

  • demo.ps1 , for Windows PowerShell
  • demo.sh, for Linux & Mac

You can run these scripts, as demonstrated in these short videos:

The sections below explain each step, and show how to run them from the command line.

Start local IC network

Start the local IC network with:

# In a Windows PowerShell (MiniConda is recommended):
wsl --% dfx start --clean --background

# In a Linux/Mac terminal
dfx start --clean --background

Build the WebAssembly file

You compile & link your code with:

icpp build-wasm

icpp will compile the C++ files defined in the icpp.toml file and create a wasm file in the build folder. The name of the wasm file to be created is defined inside icpp.toml .

Deploy

Deploy the build/greet.wasm to a canister in the local network with:

# In a Windows PowerShell (MiniConda is recommended):
wsl --% dfx deploy

# In a Linux/Mac terminal
dfx deploy

dfx deploys the files specified in dfx.json file.

Test

Test with dfx

You can test the APIs from the command line, using dfx canister call.

For example, call the greet_2 API of your deployed greet canister with:

# In a Windows PowerShell (MiniConda is recommended):
wsl --% dfx canister --network local call greet greet_2 '("C++ Developer")'

# In a Linux/Mac terminal
dfx canister --network local call greet greet_2 '("C++ Developer")'

# The response will be:
(
  "hello C++ Developer!\nYour principal is: .....-..etc..",
)

Test with Candid UI

You can also test the APIs from your browser, using the Candid UI.

Note that the .did file is not (yet) embedded in the wasm, so you need to provide both the canister ID and the did file.

Test automation with pytest

icpp-pro comes with a smoke testing framework.

To run the automated API tests against your locally deployed canister, issue this command:

# from directory: `greet`

# Make sure the canister is deployed as described above.
# Then run the smoke tests using pytest
pytest --network local
=================== test session starts ===================
platform linux -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0
rootdir: /home/<path>/icpp
plugins: anyio-3.6.2
collected 4 items                                         

test/test_apis.py ..                                [100%]

==================== 4 passed in 0.13s ====================

Notes:

  • pytest is installed automatically with icpp.

  • pytest will automatically detect the test folder:

greet/
|- test/
|  |- conftest.py   # pytest fixtures
|  |- test_apis.py  # the API tests
|  |- __init__.py   # empty file turning `test` into a python package
                    # -> required by pytest to resolve fixture imports

Debug with VS Code

icpp-pro comes with a native development framework.

build-native

To create a native executable with the build in Mock IC, use the command:

icpp build-native

Run mockic.exe

You can run the native executable directly, with the command:

build-native/mockic.exe

Debug interactively

First, Install & Configure VS Code for use with icpp.

Then set breakpoints in your code and start the debugger.

The MockIC that was included in the executable will run the tests that you specified in native/main.cpp and call your Smart Contract functions as if they're run in a canister.

This allows you to debug your Smart Contract interactively, not having to rely on debug_print statements alone. This speeds up your development process tremendously.

Next Steps

You can find additional Smart Contract examples in the icpp-demos repository.

IC Limitations

For the most part you can write any style of C++20, but the IC has two limitations to be aware of.

No file system

If your C++ code is making use of the file system, you will get an error message during compile time.

icpp uses the wasi-sdk compiler and sometimes, even when you are not using the file-system, the compiled Wasm module still includes functions that use the file-system and as a result it adds external system interfaces that the IC canister system API does not support. You will get an error during deployment to the canister.

To work around that issue, we have implemented traps to stub those functions. This allows you to compile & deploy your code without the system interfaces being added to the Wasm module, and if it so happens that you actually do use them, a trap with a clear message will occur at runtime.

300 Globals limit

The IC has a hard limit allowing only 300 globals.

If your compiled Wasm module has more, then you will get this error message during deployment:

$ dfx deploy
...
Error: Failed while trying to deploy canisters.
Caused by: Failed while trying to deploy canisters.
  Failed while trying to install all canisters.
    Failed to install wasm module to canister 'greet'.
      Failed to install wasm in canister 'rrkah-fqaaa-aaaaa-aaaaq-cai'.
        Failed to install wasm.
          The Replica returned an error: code 5, message: 
          "Wasm module of canister rrkah-fqaaa-aaaaa-aaaaq-cai is not valid: 
          Wasm module defined 667 globals which exceeds the maximum number allowed 300."

You can check how many globals are in your compiled Wasm module with these commands:

icpp build-wasm
wasm2wat <path-to-wasm> | grep "(global (;" | wc

We have found that the following creates many globals in the Wasm module and you must avoid using it:

  • From the sstream module:
  • std::stringstream
  • std::istringstream


IC智能合约编程：C++语言开发环境
arkMeta Crypto Network Limited, arkSong 2023年10月16日
标签
我们的博客
登录 留下评论

IC边缘节点：Boundary nodes
Boundary nodes