This tutorial describes how to use CMake (and CLion) to build smart contracts for the eosio blockchain. This work was motivated by the absence of build tools that can be used directly from an IDE. Also it was inspired from a previous work done by InfiniteXLabs and try to solve the following shortcomings:
To complete this tutorial, you need to be familiar with CMake, install eosio sdk for your environment, install clang, optional but recommended CLion (or another C++ IDE).
This tutorial is a work in progress hence has been tested only on macosx, lacks some useful features (like CMake tests) and does not cover contract deployment to an eosio blockchain.
The tutorial source repositories are : eosio-cmake and eosio-cmake-tutorial:
Create a new folder for our tutorial eosio-cmake-tutorial:
Copy scripts/eosiosdk.cmake scripts/eosiosdk-util.cmake scripts/FindEOSIOSDKLibs.cmake from eosio-cmake to eosio-cmake-tutorial/cmake.
Create include/contracts/hello.hpp inside eosio-cmake-tutorial
Create include/contracts/hello.cppinside eosio-cmake-tutorial
Your folder should look like :
|---- eosio-cmake-tutorial
|---- CMakeLists.txt
|---- include
|---- contracts
|----hello.hpp
|---- src
|---- hello.cpp
|---- cmake
|---- eosiosdk.cmake
|---- eosiosdk-util.cmake
|---- FindEOSIOSDKLibs.cmake
//
// MIT License.
//
#ifndef EOSIO_HELLO_WORLD_HELLO_HPP
#define EOSIO_HELLO_WORLD_HELLO_HPP
#include
#include
#include
using namespace eosio;
class hello : public eosio::contract {
public:
hello(account_name n);
/// @abi action
void hi( account_name user );
};
#endif //EOSIO_HELLO_WORLD_HELLO_HPP
//
// MIT License.
//
#include "contracts/hello.hpp"
using namespace eosio;
hello::hello(account_name n) : contract(n) {}
void hello::hi(account_name user) {
print("Hello, EOS", name{user});
}
EOSIO_ABI(hello, (hi))
cmake_minimum_required(VERSION 3.10)
project(eosio-cmake-tutorial)
################################
## Project
################################
set(PROJECT_VERSION_MAJOR "0")
set(PROJECT_VERSION_MINOR "1")
set(PROJECT_VERSION_PATCH "0")
set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
set(VERSION ${PROJECT_VERSION})
message("\n-- Configuring ${PROJECT_NAME} ${PROJECT_VERSION}...\n")
################################
## Cmake dependencies
################################
include(cmake/eosiosdk.cmake)
include(cmake/eosiosdk-util.cmake)
include(cmake/FindEOSIOSDKLibs.cmake)
################################
## Compiler Flags
################################
set(CMAKE_CXX_STANDARD 14)
################################
# Library Build
################################
# target hello
add_eosio_wasm_library(hello CONTRACT SOURCES src/hello.cpp)
target_eosio_wasm_compile_definitions(hello PUBLIC -DBOOST_DISABLE_ASSERTS -DBOOST_EXCEPTION_DISABLE)
target_eosio_wasm_include_directories(hello
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
# $)
target_eosio_wasm_link_libraries(hello eosio libc++ libc musl Boost)
add_eosio_wasm_abi(hello HEADERS include/contracts/hello.hpp)
################################
## Install
################################
eosio_wasm_install(hello CONTRACT
CODE DESTINATION "${CMAKE_INSTALL_FULL_CODEDIR}/hello"
ABI DESTINATION "${CMAKE_INSTALL_FULL_ABIDIR}/hello")
> cd eosio-cmake-tutorial
> mkdir build && cd build
> mkdir install && -DCMAKE_INSTALL_PREFIX=install ..
> make contracts
Scanning dependencies of target hello_link
[ 16%] Building LLVM bitcode src/hello.cpp.bc
[ 33%] Linking LLVM bitcode executable lib/hello.bc
[ 50%] Generating textual assembly hello.s
[ 66%] Generating WAST wast/hello.wast
[ 83%] Generating WASM wast/hello.wast
[ 83%] Built target hello_link
Scanning dependencies of target hello_abi_gen
[100%] Generating ABI abi/hello.abi
2018-09-20T11:17:15.814 thread-0 abi_generator.hpp:68 ricardian_contracts ] Warning, no ricardian clauses found for
[100%] Built target hello_abi_gen
Scanning dependencies of target hello
Target hello output wasm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/bin
Target hello outputllvm bytecode to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/lib
Target hello output wast and asm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/code
Target hello output abi to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/abi
[100%] Built target hello
Scanning dependencies of target contracts
[100%] Built target contracts
This step should output the following folders abi``code bin lib respectively containing hello.abi, hello.wast, hello.wasm, hello.bc.
> mkdir hello_install
Scanning dependencies of target hello_install
Installing contracts abi
/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/abi:/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/install/abi/hello
Installing contracts wasm
/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/bin:/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/install/code/hello
Installing contracts wast
/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/code:/Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/install/code/hello
[100%] Built target hello_install
This step will install abi and code in install directory.
Our second contrat is the tic_tac_toe contract from eosio tutorial.
/**
* @file
* @copyright defined in eos/LICENSE.txt
*/
#ifndef EOSIO_HELLO_WORLD_TIC_TAC_TOE_HPP
#define EOSIO_HELLO_WORLD_TIC_TAC_TOE_HPP
#include
/**
* @defgroup tictactoecontract Tic Tac Toe Contract
* @brief Defines the PvP tic tac toe contract example
* @ingroup examplecontract
*
* @details
* For the following tic-tac-toe game:
* - Each pair of player can have 2 unique game, one where player_1 become host and player_2 become challenger and vice versa
* - The game data is stored in the "host" scope and use the "challenger" as the key
*
* (0,0) coordinate is on the top left corner of the board
* @code
* (0,2)
* (0,0) - | o | x where - = empty cell
* - | x | - x = move by host
* (2,0) x | o | o o = move by challenger
* @endcode
*
* Board is represented with number:
* - 0 represents empty cell
* - 1 represents cell filled by host
* - 2 represents cell filled by challenger
* Therefore, assuming x is host, the above board will have the following representation: [0, 2, 1, 0, 1, 0, 1, 2, 2] inside the game object
*
* In order to deploy this contract:
* - Create an account called tic.tac.toe
* - Add tic.tac.toe key to your wallet
* - Set the contract on the tic.tac.toe account
*
* How to play the game:
* - Create a game using `create` action, with you as the host and other account as the challenger.
* - The first move needs to be done by the host, use the `move` action to make a move by specifying which row and column to fill.
* - Then ask the challenger to make a move, after that it's back to the host turn again, repeat until the winner is determined.
* - If you want to restart the game, use the `restart` action
* - If you want to clear the game from the database to save up some space after the game has ended, use the `close` action
* @{
*/
class tic_tac_toe : public eosio::contract {
public:
tic_tac_toe( account_name self ):contract(self){}
/**
* @brief Information related to a game
* @abi table games i64
*/
struct game {
static const uint16_t board_width = 3;
static const uint16_t board_height = board_width;
game() {
initialize_board();
}
account_name challenger;
account_name host;
account_name turn; // = account name of host/ challenger
account_name winner = N(none); // = none/ draw/ name of host/ name of challenger
std::vector<uint8_t> board;
// Initialize board with empty cell
void initialize_board() {
board = std::vector<uint8_t>(board_width * board_height, 0);
}
// Reset game
void reset_game() {
initialize_board();
turn = host;
winner = N(none);
}
auto primary_key() const { return challenger; }
EOSLIB_SERIALIZE( game, (challenger)(host)(turn)(winner)(board))
};
/**
* @brief The table definition, used to store existing games and their current state
*/
typedef eosio::multi_index< N(games), game> games;
/// @abi action
/// Create a new game
void create(const account_name& challenger, const account_name& host);
/// @abi action
/// Restart a game
/// @param by the account who wants to restart the game
void restart(const account_name& challenger, const account_name& host, const account_name& by);
/// @abi action
/// Close an existing game, and remove it from storage
void close(const account_name& challenger, const account_name& host);
/// @abi action
/// Make movement
/// @param by the account who wants to make the move
void move(const account_name& challenger, const account_name& host, const account_name& by, const uint16_t& row, const uint16_t& column);
};
/// @}
#endif //EOSIO_HELLO_WORLD_TIC_TAC_TOE_HPP
/**
* @file
* @copyright defined in eos/LICENSE.txt
*/
#include
using namespace eosio;
/**
* @brief Check if cell is empty
* @param cell - value of the cell (should be either 0, 1, or 2)
* @return true if cell is empty
*/
bool is_empty_cell(const uint8_t& cell) {
return cell == 0;
}
/**
* @brief Check for valid movement
* @detail Movement is considered valid if it is inside the board and done on empty cell
* @param row - the row of movement made by the player
* @param column - the column of movement made by the player
* @param board - the board on which the movement is being made
* @return true if movement is valid
*/
bool is_valid_movement(const uint16_t& row, const uint16_t& column, const vector<uint8_t>& board) {
uint32_t movement_location = row * tic_tac_toe::game::board_width + column;
bool is_valid = movement_location < board.size() && is_empty_cell(board[movement_location]);
return is_valid;
}
/**
* @brief Get winner of the game
* @detail Winner of the game is the first player who made three consecutive aligned movement
* @param current_game - the game which we want to determine the winner of
* @return winner of the game (can be either none/ draw/ account name of host/ account name of challenger)
*/
account_name get_winner(const tic_tac_toe::game& current_game) {
auto& board = current_game.board;
bool is_board_full = true;
// Use bitwise AND operator to determine the consecutive values of each column, row and diagonal
// Since 3 == 0b11, 2 == 0b10, 1 = 0b01, 0 = 0b00
vector<uint32_t> consecutive_column(tic_tac_toe::game::board_width, 3 );
vector<uint32_t> consecutive_row(tic_tac_toe::game::board_height, 3 );
uint32_t consecutive_diagonal_backslash = 3;
uint32_t consecutive_diagonal_slash = 3;
for (uint32_t i = 0; i < board.size(); i++) {
is_board_full &= is_empty_cell(board[i]);
uint16_t row = uint16_t(i / tic_tac_toe::game::board_width);
uint16_t column = uint16_t(i % tic_tac_toe::game::board_width);
// Calculate consecutive row and column value
consecutive_row[column] = consecutive_row[column] & board[i];
consecutive_column[row] = consecutive_column[row] & board[i];
// Calculate consecutive diagonal \ value
if (row == column) {
consecutive_diagonal_backslash = consecutive_diagonal_backslash & board[i];
}
// Calculate consecutive diagonal / value
if ( row + column == tic_tac_toe::game::board_width - 1) {
consecutive_diagonal_slash = consecutive_diagonal_slash & board[i];
}
}
// Inspect the value of all consecutive row, column, and diagonal and determine winner
vector<uint32_t> aggregate = { consecutive_diagonal_backslash, consecutive_diagonal_slash };
aggregate.insert(aggregate.end(), consecutive_column.begin(), consecutive_column.end());
aggregate.insert(aggregate.end(), consecutive_row.begin(), consecutive_row.end());
for (auto value: aggregate) {
if (value == 1) {
return current_game.host;
} else if (value == 2) {
return current_game.challenger;
}
}
// Draw if the board is full, otherwise the winner is not determined yet
return is_board_full ? N(draw) : N(none);
}
/**
* @brief Apply create action
*/
void tic_tac_toe::create(const account_name& challenger, const account_name& host) {
require_auth(host);
eosio_assert(challenger != host, "challenger shouldn't be the same as host");
// Check if game already exists
games existing_host_games(_self, host);
auto itr = existing_host_games.find( challenger );
eosio_assert(itr == existing_host_games.end(), "game already exists");
existing_host_games.emplace(host, [&]( auto& g ) {
g.challenger = challenger;
g.host = host;
g.turn = host;
});
}
/**
* @brief Apply restart action
*/
void tic_tac_toe::restart(const account_name& challenger, const account_name& host, const account_name& by) {
require_auth(by);
// Check if game exists
games existing_host_games(_self, host);
auto itr = existing_host_games.find( challenger );
eosio_assert(itr != existing_host_games.end(), "game doesn't exists");
// Check if this game belongs to the action sender
eosio_assert(by == itr->host || by == itr->challenger, "this is not your game!");
// Reset game
existing_host_games.modify(itr, itr->host, []( auto& g ) {
g.reset_game();
});
}
/**
* @brief Apply close action
*/
void tic_tac_toe::close(const account_name& challenger, const account_name& host) {
require_auth(host);
// Check if game exists
games existing_host_games(_self, host);
auto itr = existing_host_games.find( challenger );
eosio_assert(itr != existing_host_games.end(), "game doesn't exists");
// Remove game
existing_host_games.erase(itr);
}
/**
* @brief Apply move action
*/
void tic_tac_toe::move(const account_name& challenger, const account_name& host, const account_name& by, const uint16_t& row, const uint16_t& column ) {
require_auth(by);
// Check if game exists
games existing_host_games(_self, host);
auto itr = existing_host_games.find( challenger );
eosio_assert(itr != existing_host_games.end(), "game doesn't exists");
// Check if this game hasn't ended yet
eosio_assert(itr->winner == N(none), "the game has ended!");
// Check if this game belongs to the action sender
eosio_assert(by == itr->host || by == itr->challenger, "this is not your game!");
// Check if this is the action sender's turn
eosio_assert(by == itr->turn, "it's not your turn yet!");
// Check if user makes a valid movement
eosio_assert(is_valid_movement(row, column, itr->board), "not a valid movement!");
// Fill the cell, 1 for host, 2 for challenger
const uint8_t cell_value = itr->turn == itr->host ? 1 : 2;
const auto turn = itr->turn == itr->host ? itr->challenger : itr->host;
existing_host_games.modify(itr, itr->host, [&]( auto& g ) {
g.board[row * tic_tac_toe::game::board_width + column] = cell_value;
g.turn = turn;
g.winner = get_winner(g);
});
}
EOSIO_ABI( tic_tac_toe, (create)(restart)(close)(move))
# target tic tac toe
add_eosio_wasm_library(tic_tac_toe CONTRACT SOURCES src/tic_tac_toe.cpp)
target_eosio_wasm_compile_definitions(tic_tac_toe PUBLIC -DBOOST_DISABLE_ASSERTS -DBOOST_EXCEPTION_DISABLE)
target_eosio_wasm_include_directories(tic_tac_toe
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>)
# $)
target_eosio_wasm_link_libraries(tic_tac_toe eosio libc++ libc musl Boost)
add_eosio_wasm_abi(tic_tac_toe HEADERS include/contracts/tic_tac_toe.hpp)
> cd build
> rm -rf *
> mkdir install && cmake -DCMAKE_INSTALL_PREFIX=install ..
> make contracts
Scanning dependencies of target hello_link
[ 8%] Building LLVM bitcode src/hello.cpp.bc
[ 16%] Linking LLVM bitcode executable lib/hello.bc
[ 25%] Generating textual assembly hello.s
[ 33%] Generating WAST wast/hello.wast
[ 41%] Generating WASM wast/hello.wast
[ 41%] Built target hello_link
Scanning dependencies of target hello_abi_gen
[ 50%] Generating ABI abi/hello.abi
2018-09-20T13:03:36.315 thread-0 abi_generator.hpp:68 ricardian_contracts ] Warning, no ricardian clauses found for
[ 50%] Built target hello_abi_gen
Scanning dependencies of target hello
Target hello output wasm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/bin
Target hello outputllvm bytecode to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/lib
Target hello output wast and asm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/code
Target hello output abi to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/abi
[ 50%] Built target hello
Scanning dependencies of target tic_tac_toe_link
[ 58%] Building LLVM bitcode src/tic_tac_toe.cpp.bc
[ 66%] Linking LLVM bitcode executable lib/tic_tac_toe.bc
[ 75%] Generating textual assembly tic_tac_toe.s
[ 83%] Generating WAST wast/tic_tac_toe.wast
[ 91%] Generating WASM wast/tic_tac_toe.wast
[ 91%] Built target tic_tac_toe_link
Scanning dependencies of target tic_tac_toe_abi_gen
[100%] Generating ABI abi/tic_tac_toe.abi
2018-09-20T13:03:39.947 thread-0 abi_generator.hpp:68 ricardian_contracts ] Warning, no ricardian clauses found for
[100%] Built target tic_tac_toe_abi_gen
Scanning dependencies of target tic_tac_toe
Target tic_tac_toe output wasm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/bin
Target tic_tac_toe outputllvm bytecode to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/lib
Target tic_tac_toe output wast and asm to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/code
Target tic_tac_toe output abi to /Users/awalga/Data/project/eosio/eosio-cmake-tutorial/build/abi
[100%] Built target tic_tac_toe
Scanning dependencies of target contracts
[100%] Built target contracts
> make hello_install
> make tic_tac_toe_install
Clion is a C++ IDE with built in support for CMake projects and more. Open the previous project from Clion. Clion will create build dependancies based on our CMakeLists.txt
The next step will provide features to test and deploy contracts to an eosio contract.