Installing EOSFactory

The purpose of this tutorial is to demonstrate how to install EOSFactory on any operating system, including Ubuntu, MacOS and Windows.

We’ve tested EOSFactory on the following platforms:

  • Ubuntu 18.04 (Bionic)
  • MacOS 10.13 (High Sierra)
  • Windows 10 (version 1803)

NOTE: EOSFactory is compatible with EOSIO v1.3.x .

General prerequisites

We assume that you have successfully installed EOSIO v1.3.0 (or higher) on your machine. If that’s not the case, please refer to this guide.

NOTE: EOSFactory requires EOSIO to be compiled from the source code, i.e. not deployed in Docker.

After the build is complete, make sure to install EOSIO with this command:

sudo ./eosio_install.sh

Prerequisites for Ubuntu & MacOS

  • We assume you have Python 3.5 (or higher) installed.

Prerequisites for Windows

  • We assume that you have Windows Subsystem for Linux - Ubuntu 18.04 installed.
  • The only option you have regarding EOSIO installation is building it in the Ubuntu 18.04 bash (supplied by WSL), as it cannot be compiled directly on a Windows machine. What we recommend is clone the EOSIO source code in Windows and keep it in the Windows file structure, yet build it in WSL, taking advantage of the fact that the entire Windows file structure is fully accessible in WSL.
  • And finally, we assume you have Python 3.5 (or higher) available in your WSL, but this condition is likely to be already satisfied, as WSL ships with Python 3.6.5 by default.

Upgrading from previous version

If you have a previous installation of EOSFactory on your machine, please remove all EOSFactory export statements from your system.

To do this, edit the .profile or .bash_profile file:

  • If you are on Ubuntu or Windows Subsystem for Linux:

    nano ~/.profile
    
  • If you are on MacOS:

    nano ~/.bash_profile
    

And make sure that all EOSFactory export statements are removed:

export EOSIO_SOURCE_DIR=...
export EOSFACTORY_DIR=...
export HOME=...
export eosf=...
export EOSIO_SHARED_MEMORY_SIZE_MB=...
export EOSIO_CONTRACT_WORKSPACE=...
export PYTHONPATH=...

Also, if you’re on Ubuntu make sure there are no similar export statements in the ~/.bashrc file. If there are any, remove all of them.

When you’re done, restart your console to apply the change.

Build on Ubuntu & MacOS

Clone EOSFactory source code from the repository:

git clone https://github.com/tokenika/eosfactory.git

Open a bash terminal and navigate to the eosfactory folder:

cd eosfactory

Then run the install script by pointing it to the EOSIO source code:

./install.sh

NOTE: When prompted supply the correct paths:

  • The first one is the location of the EOSIO source code that you have cloned from the official EOSIO repository, e.g. ~/Workspaces/EOS/eos.
  • The second one is the preferred location of your smart-contract workspace, e.g. ~/Workspaces/EOS/contracts. It has to be existent, so if you don’t have it already, you need to create it manually.

Build on Windows

Clone EOSFactory source code from the repository:

git clone https://github.com/tokenika/eosfactory.git

NOTE: We recommend keeping EOSFactory in the Windows file structure, not WSL.

Open a WSL bash terminal and navigate to the eosfactory folder:

cd /mnt/d/Workspaces/EOS/eosfactory

Then run the install script by pointing it to the EOSIO source code:

./install.sh

NOTE: When prompted supply the correct paths:

  • The first one is the location of the EOSIO source code that you have cloned from the official EOSIO repository, e.g. /mnt/d/Workspaces/EOS/eos.
  • The second one is the preferred location of your smart-contract workspace, e.g. /mnt/d/Workspaces/EOS/contracts. It has to be existent, so if you don’t have it already, you need to create it manually.

Test the build

Now let’s verify that EOSFactory works and is properly hooked up to EOSIO.

First, make sure your working directory is switched to eosfactory:

cd eosfactory

And then run those three tests:

python3 tests/01_hello_world.py
python3 tests/02_eosio_token.py
python3 tests/03_tic_tac_toe.py

Troubleshooting specific errors

Case 1

If the test fails due to the can't open file 'tests/01_hello_world.py' error, make sure your current working directory is eosfactory.

Case 2

If a unit tests fails due to the execve error, make sure you have executed the eosio_install.sh script after EOSIO build, as described above.

Case 3

If a unit test fails with the No such file or directory: ~/eosio-wallet/ error, please make sure this directory exists, and if not, create one manually.

Troubleshooting general problems

First, make sure EOSFactory configuration is correct by running this command:

cd eosfactory
python3 utils/config.py

As a result, you should get data similar to this:

"ABIGEN_EXECUTABLE": "/mnt/d/Workspaces/EOS/eos/build/programs/eosio-abigen/eosio-abigen",
"BOOST_INCLUDE_DIR": "/home/sygnet/opt/boost/include",
"EOSIO_ABIGEN": null,
"EOSIO_CLI_EXECUTABLE": "/mnt/d/Workspaces/EOS/eos/build/programs/cleos/cleos",
"EOSIO_CONTRACT_WORKSPACE": "/mnt/d/Workspaces/EOS/contracts",
"EOSIO_CPP": null,
"EOSIO_GENESIS_JSON": "/mnt/d/Workspaces/EOS/eosfactory/localnode/genesis.json",
"EOSIO_KEY_PRIVATE": "5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3",
"EOSIO_KEY_PUBLIC": "EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
"EOSIO_SHARED_MEMORY_SIZE_MB": "200",
"EOSIO_SOURCE_DIR": "/mnt/d/Workspaces/EOS/eos",
"EOSIO_WORKSPACE": "/mnt/d/Workspaces/EOS/eos/build/contracts/",
"KEOSD_WALLET_DIR": "/home/sygnet/eosio-wallet/",
"LOCAL_NODE_ADDRESS": "127.0.0.1:8888",
"LOCAL_NODE_CONFIG_DIR": "/mnt/d/Workspaces/EOS/eosfactory/localnode",
"LOCAL_NODE_DATA_DIR": "/mnt/d/Workspaces/EOS/eosfactory/localnode",
"LOCAL_NODE_EXECUTABLE": "/mnt/d/Workspaces/EOS/eos/build/programs/nodeos/nodeos",
"NODE_API": "cleos",
"NODE_IN_WINDOW": 0,
"S2WASM_EXECUTABLE": "/mnt/d/Workspaces/EOS/eos/build/externals/binaryen/bin/eosio-s2wasm",
"WALLET_MANAGER_ADDRESS": "127.0.0.1:8888",
"WASM_CLANG_EXECUTABLE": "/home/sygnet/opt/wasm/bin/clang",
"WASM_LLC_EXECUTABLE": "/home/sygnet/opt/wasm/bin/llc",
"WASM_LLVM_LINK_EXECUTABLE": "/home/sygnet/opt/wasm/bin/llvm-link",
"WAST2WASM_EXECUTABLE": "/mnt/d/Workspaces/EOS/eos/build/libraries/wasm-jit/Source/Programs/eosio-wast2wasm",
"WSL_ROOT": "C:/Users/tokenika/AppData/Local/Packages/CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc/LocalState/rootfs"

Next, verify that all the above paths are resolved.

Subsequent builds

If you want to upgrade to the latest version of EOSFactory:

cd eosfactory
git pull

And then just run:

./install.sh