Introduction to the Common Development of China Mobile Chain Contracts (5) Compilation of Contract Projects

Purpose

This document introduces the project tree directory of the engineering development smart contract project, and introduces the meaning and purpose of each folder and file. This document will follow the content of the address book contract implemented in the previous article, and introduce the initialization project as an example. It is suitable for developers who are new to contract development to understand smart contract projects and help them quickly understand and get started with smart contracts.

Smart Contract Introduction

As a distributed and trusted computing platform, blockchain is its most essential feature of decentralization. A record of every transaction is immutably stored on the blockchain. Smart contracts define actions and transaction codes that can be executed on the blockchain. Can be executed on a blockchain and include the contract execution state as part of the immutable history of that blockchain instance.

As a result, developers can rely on the blockchain as a trusted computing environment where the input, execution, and results of smart contracts are independent from outside influence.

Terminology Explanation

WebAssembly（WASM）

A virtual machine for executing Portable Binary Code Format, hosted in nodeos.

Application Binary Interface (ABI)

An interface that defines how data is marshaled into and out of the WebAssembly virtual machine.

Introduction to Make

The make tool can be regarded as an intelligent batch processing tool. It does not have the function of compiling and linking itself, but compiles and links by calling the command specified by the user in the Makefile file.

It allows users to build and install without knowing the build details, since the details are documented in the Makefile.

Introduction to CMake

CMake is a cross-platform installation (compilation) tool, which can describe the installation (compilation process) of all platforms with simple sentences. The configuration file is named CMakeLists.txt, which can output Makefile files by identifying CMakeLists.txt, and can test the C++ features supported by the compiler. Developers familiar with an integrated development environment (IDE) can use CMake to build software in a standard way.

The initialization project generated through the command line in EOS comes with a CMakeLists.txt file. If there is no need to make personalized changes, the user only needs to use the cmake command to build the project, and no other modifications are required.

Grammar introduction:

The PROJECT keyword can be used to specify the project name and supported languages, all languages are supported by default

PROJECT(HELLO) specifies the project name and supports all languages
PROJECT(HELLO CXX) specifies the project name, supports C++
PROJECT(HELLO C CXX) specifies the project name, supports C and C++

The SET keyword is used to display the specified variable

SET(SRC_LIST main.cpp) The SRC_LIST variable contains main.cpp
SET(SRC_LIST main.cpp t1.cpp t2.cpp) SRC_LIST variable contains multiple cpp

The MESSAGE keyword outputs user-defined information to the terminal

SEND_ERROR generated an error, the generation process was skipped
STATUS outputs information prefixed with --
FATAL_ERROR terminates all cmake processes immediately

The ADD_EXECUTABLE keyword generates an executable file

ADD_EXECUTABLE(hello ${SRC_LIST}) generates an executable file named hello, and the source file read variable is SRC_LIST

Introduction to the directory tree after compilation

(1) Overview

This article still takes the addressbook project as an example.

Use the initialization eosio-init tool to create a smart contract project with a custom project name. Add the path of the created project after --path=, and add the name of the created project after --project=. Execute the following command to get a smart contract empty project addressbook:

eosio-init --path=. --project=addressbook

There is an empty build folder in the project, enter the build directory and run the command:

cmake ..

The directive will generate constructs based on the CMakeLists.txt files in the root and src folders. All temporary files will be generated in the build directory without any impact on the source files, also known as external builds.

The content of the CMakeLists.txt file in the root directory is as follows:

include(ExternalProject)
# if no cdt root is given use default path
if(EOSIO_CDT_ROOT STREQUAL "" OR NOT EOSIO_CDT_ROOT)
   find_package(eosio.cdt)
endif()

ExternalProject_Add(
   addressbook_project
   SOURCE_DIR ${CMAKE_SOURCE_DIR}/src
   BINARY_DIR ${CMAKE_BINARY_DIR}/addressbook
   CMAKE_ARGS -DCMAKE_TOOLCHAIN_FILE=${EOSIO_CDT_ROOT}/lib/cmake/eosio.cdt/EosioWasmToolchain.cmake
   UPDATE_COMMAND ""
   PATCH_COMMAND ""
   TEST_COMMAND ""
   INSTALL_COMMAND ""
   BUILD_ALWAYS 1
)

The file specifies the form of the external construction, the location of the source folder after construction, and the configuration related to eosio.

The CMakeLists.txt file in src is as follows:

project(addressbook)

set(EOSIO_WASM_OLD_BEHAVIOR "Off")
find_package(eosio.cdt)

add_contract( addressbook addressbook addressbook.cpp )
target_include_directories( addressbook PUBLIC ${CMAKE_SOURCE_DIR}/../include )
target_ricardian_directory( addressbook ${CMAKE_SOURCE_DIR}/../ricardian )

The document states:

projectProject name
All cpp files involved in the add_contract contract
The header file storage location of the target_include_directories contract
The Ricardian contract storage location of the target_ricardian_directory contract

After running cmake, the following files will be created in the build folder:

├── addressbook 空文件夹
├── addressbook_project-prefix 项目前缀文件夹
├── CMakeFiles CMake版本文件夹
├── cmake_install.cmake 安装文件
├── CMakeCache.txt Cache文件
└── Makefile CMake初始化文件

Run the following command to complete the build:

make

After running successfully, the addressbook folder will generate the following content:

├── CMakeFiles CMake版本文件夹
├── addressbook.abi 应用程序二进制接口文件
├── addressbook.wasm WebAssembly文件
├── cmake_install.cmake 安装文件
├── CMakeCache.txt Cache文件
└── Makefile CMake初始化文件

(2) CMake file set

The CMakeFiles folder, cmake_install.cmake file, CMakeCache.txt file, and Makefile file are all CMake-related files generated by the cmake command. This file set will appear repeatedly in the automatically built folder directory, and generally does not need to be changed.

1. CMakeFiles folder

Various files related to CMake version and project startup are stored in the CMakeFiles folder.

2. cmake_install.cmake file

cmake_install.cmake installs the script for the project directory, installs the configuration name and components.

# Install script for directory: /home/xxx/biosboot/genesis/addressbook

# Set the install prefix
if(NOT DEFINED CMAKE_INSTALL_PREFIX)
  set(CMAKE_INSTALL_PREFIX "/usr/local")
endif()
string(REGEX REPLACE "/$" "" CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}")

# Set the install configuration name.
if(NOT DEFINED CMAKE_INSTALL_CONFIG_NAME)
  if(BUILD_TYPE)
    string(REGEX REPLACE "^[^A-Za-z0-9_]+" ""
           CMAKE_INSTALL_CONFIG_NAME "${BUILD_TYPE}")
  else()
    set(CMAKE_INSTALL_CONFIG_NAME "")
  endif()
  message(STATUS "Install configuration: \"${CMAKE_INSTALL_CONFIG_NAME}\"")
endif()

# Set the component getting installed.
if(NOT CMAKE_INSTALL_COMPONENT)
  if(COMPONENT)
    message(STATUS "Install component: \"${COMPONENT}\"")
    set(CMAKE_INSTALL_COMPONENT "${COMPONENT}")
  else()
    set(CMAKE_INSTALL_COMPONENT)
  endif()
endif()

# Install shared libraries without execute permission?
if(NOT DEFINED CMAKE_INSTALL_SO_NO_EXE)
  set(CMAKE_INSTALL_SO_NO_EXE "1")
endif()

# Is this installation the result of a crosscompile?
if(NOT DEFINED CMAKE_CROSSCOMPILING)
  set(CMAKE_CROSSCOMPILING "FALSE")
endif()

if(CMAKE_INSTALL_COMPONENT)
  set(CMAKE_INSTALL_MANIFEST "install_manifest_${CMAKE_INSTALL_COMPONENT}.txt")
else()
  set(CMAKE_INSTALL_MANIFEST "install_manifest.txt")
endif()

string(REPLACE ";" "\n" CMAKE_INSTALL_MANIFEST_CONTENT
       "${CMAKE_INSTALL_MANIFEST_FILES}")
file(WRITE "/home/ljy/biosboot/genesis/addressbook/addressbook/build/${CMAKE_INSTALL_MANIFEST}"
     "${CMAKE_INSTALL_MANIFEST_CONTENT}")

3. CMakeCache.txt file

The CMakeCache.txt file describes some initialization values established and used by CMake. If you need to change it, you can edit the file and save and exit.

# This is the CMakeCache file.
# For build in directory: /home/xxx/biosboot/genesis/addressbook/build
# It was generated by CMake: /usr/bin/cmake
# You can edit this file to change values found and used by cmake.
# If you do not want to change any of the values, simply exit the editor.
# If you do want to change a value, simply edit, save, and exit the editor.
# The syntax for the file is as follows:
(文件的语法如下：)
# KEY:TYPE=VALUE
(键：类型=值)
# KEY is the name of a variable in the cache.
(KEY是缓存中变量的名称。)
# TYPE is a hint to GUIs for the type of VALUE, DO NOT EDIT TYPE!.
(TYPE是对GUI的VALUE类型的提示，请勿编辑TYPE！。)
# VALUE is the current value for the KEY.
(VALUE是KEY的当前值。)

4. Makefile

Makefile files are automatically generated by the Unix Makefiles generator according to the version, please do not edit them. Executes the default target when there are no arguments to generate.

# CMAKE generated file: DO NOT EDIT!
# Generated by "Unix Makefiles" Generator, CMake Version 3.16

# Default target executed when no arguments are given to make.
default_target: all

.PHONY : default_target

# Allow only one "make -f Makefile2" at a time, but pass parallelism.
.NOTPARALLEL:

(3) Project folder addressbook

After the construction is completed, in addition to the CMake file set, there are two files addressbook.abi and addressbook.wasm in the project folder.

addressbook.abi is the application binary interface file ABI (Application Binary Interface). Describes the low-level interface between an application and the operating system, between an application and its libraries, or between components of an application.

The ABI covers various details such as:

Size, layout and alignment of data types;
Calling convention (controls how the parameters of the function are passed and how the return value is accepted);
Which register is used for which function parameter; whether the first function parameter passed through the stack is pushed to the stack first or last;
Encoding of system calls and how an application makes system calls to the operating system;
In a complete operating system ABI, the binary format of object files, program libraries, etc.

The .abi file defines how data is marshaled into and out of the WASM engine.

addressbook.wasm is a WebAssembly file, a new format that is portable, small in size, fast in loading and compatible with the Web. WebAssenbly is not a programming language, but a compilation target of a compiler. The .wasm file can be regarded as the file generated after the .cpp file is compiled. A .wasm file is the binary code executed by the WebAssembly engine in the blockchain. The WebAssembly engine is hosted in a nodeos daemon and executes smart contract code.

(4) Project prefix folder addressbook_project-prefix

The temporary folder generated by cmake contains two folders, src and tmp. Most of them are empty files, or cmd instructions related to cmake.

Computer access to DDC web portal

ddc.bsnbase.com

-END-

Introduction to the Common Development of China Mobile Chain Contracts (5) Compilation of Contract Projects

Guess you like