# Purpose 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](https://infinitexlabs.com/setup-ide-for-eos-development/) and try to solve the following shortcomings: - build multiple contracts within the same project - do not have to copy eosio header files in your project directory - do not have to recompile eosio sdk libs within your project - provide build configuration similar to c++/CMake project (eg, add_library, target_include_directories, target_link_libraries, etc) # Prerequisites 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). # Limitation 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. # Tutorial Source The tutorial source repositories are : [eosio-cmake](https://github.com/awalga/eosio-cmake) and [eosio-cmake-tutorial](https://github.com/awalga/eosio-cmake-tutorial): # How it works ## Create a new project ### Tutorial folder structure - Create a new folder for our tutorial eosio-cmake-tutorial: - Copy `scripts/eosiosdk.cmake` `scripts/eosiosdk-util.cmake` `scripts/FindEOSIOSDKLibs.cmake` from [eosio-cmake](https://github.com/awalga/eosio-cmake) to `eosio-cmake-tutorial/cmake`. - Create `include/contracts/hello.hpp` inside eosio-cmake-tutorial - Create `include/contracts/hello.cpp`inside 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 ``` ### Editing our first contract - Edit include/contracts/hello.hpp: ``` // // 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 ``` - Edit src/hello.cpp: ``` // // 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)) ``` - Edit CMakeLists.txt: ``` 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 $ $) # $) 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") ``` ### Building our first contract ``` > 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`. ### Installing our first contract ``` > 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. ### Editing our second contract Our second contrat is the tic_tac_toe contract from eosio tutorial. - Create and edit include/contracts/tic_tac_toe.hpp ``` /** * @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 board; // Initialize board with empty cell void initialize_board() { board = std::vector(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 ``` - Create and edit src/tic_tac_toe.cpp ``` /** * @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& 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 consecutive_column(tic_tac_toe::game::board_width, 3 ); vector 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 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)) ``` - Modify CMakeLists.txt ``` # 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 $ $) # $) 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) ``` ### Building both contracts ``` > 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 ``` ### Installing both contracts ``` > make hello_install > make tic_tac_toe_install ``` # Use from Clion 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 ![](https://cdn.steemitimages.com/DQmZWFvKLtiZrdVB5afXJHGyDFYx81c2t7cmUKM8ARwhqiy/image.png) ## Targets and dependancies in Clion ![](https://cdn.steemitimages.com/DQma4Th33hZeaLcAdV6LZerNHf155GCCnd1ma8psdYh2mm1/image.png) # Next step The next step will provide features to test and deploy contracts to an eosio contract.