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.2.x and v1.3.x .

General Prerequisites

We assume that you have successfully installed EOSIO v1.2.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

  • Regarding Ubuntu, if you are using a server edition (i.e. not desktop), you’ll need to have gnome-terminal and an X server installed.
  • We also assume you have Python 3.5 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 available in your WSL, but this condition is likely to be already satisfied, as WSL ships with Python 3.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 all EOSFactory export statements are removed:

export EOSIO_SOURCE_DIR=...
export EOSIO_EOSFACTORY_DIR=...
export U_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.

If everything has been removed correctly, this command should return an empty value:

echo $EOSIO_SOURCE_DIR

Especially this one is important - make sure it returns an empty value:

echo $EOSIO_SHARED_MEMORY_SIZE_MB

Next, run the build.sh script:

cd eosfactory
./build.sh -e /path/to/your/local/EOSIO/repository -w /path/to/your/local/workspace

NOTE: Make sure to supply the correct paths:

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

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 build script by pointing it to the EOSIO source code:

./build.sh -e /path/to/your/local/EOSIO/repository -w /path/to/your/local/workspace

NOTE: Make sure to supply the correct paths:

  • The first one is meant to be the location of the EOSIO source code that you have cloned from the official EOSIO repository.
  • The second one is meant to be the location of your smart-contract workspace. It has to be already existent, so you need to create it manually.

In our case the EOSIO location is ~/Workspaces/EOS/eos, and the workspace location is ~/Workspaces/EOS/contracts, but yours will most probably be different:

./build.sh -e ~/Workspaces/EOS/eos -w ~/Workspaces/EOS/contracts

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 build script by pointing it to the EOSIO source code:

./build.sh -e /path/to/your/local/EOSIO/repository -w /path/to/your/local/workspace

NOTE: Make sure to supply the correct paths:

  • The first one is meant to be the location of the EOSIO source code that you have cloned from the official EOSIO repository.
  • The second one is meant to be the location of your smart-contract workspace. It has to be already existent, so you need to create it manually.

In our case the EOSIO location is /mnt/d/Workspaces/EOS/eos, and the workspace location is /mnt/d/Workspaces/EOS/contracts, but yours will most probably be different:

./build.sh -e /mnt/d/Workspaces/EOS/eos -w /mnt/d/Workspaces/EOS/contracts

NOTE: The build script assumes that your WSL is located in this directory:

%LocalAppData%\\Packages\\CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc

If you have the latest WSL release, this assumption is most likely valid. However, if for some reasons your WSL is in a different location, run the build script again with an additional -o parameter pointing to your WSL rootfs directory, for example:

./build.sh -e /mnt/d/Workspaces/EOS/eos -o %LocalAppData%\Packages\CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc\LocalState\rootfs

If you are unsure what the path is in your case, open Windows Explorer, navigate to the %LocalAppData%\\Packages folder and search for rootfs.

Source system variables

If the build process is successful, you should see this message:

         ______ ____   _____  ______      _____ _______ ____  _______     __
        |  ____/ __ \ / ____||  ____/\   / ____|__   __/ __ \|  __ \ \   / /
        | |__ | |  | | (___  | |__ /  \ | |       | | | |  | | |__) \ \_/ / 
        |  __|| |  | |\___ \ |  __/ /\ \| |       | | | |  | |  _  / \   /  
        | |___| |__| |____) || | / ____ \ |____   | | | |__| | | \ \  | |   
        |______\____/|_____/ |_|/_/    \_\_____|  |_|  \____/|_|  \_\ |_|  

At this stage you need to source the system variables that were created during EOSFactory installation. The command may differ depending on your system.

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

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

    source ~/.bash_profile
    

NOTE: If you have Visual Studio Code installed on your machine, make sure it’s shut down (or restart it completely after installing EOSFactory). Otherwise those system variables will not be visible to VSC and some CMake-based tasks executed in VSC might fail.

Install termcolor

In order to make unit test output more readable we recommend installing the termcolor extension for Python:

python3 -m pip install termcolor

NOTE: If the above command fails you might need to install python3-pip:

sudo apt install python3-pip

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

NOTE: When running 01_hello_world this error is to be expected, as we are testing failure due to authority mismatch:

Error 3040003: Transaction should have at least one required authority

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 the test fails due to the ModuleNotFoundError error, make sure that after building EOSFactory you’ve sourced the newly created system variables, as described in the previous section.

Case 3

If a unit test fails with the string indices must be integers error, make sure you have EOSIO v1.2.0 (or higher) installed. Also, make sure no other instance of nodeos is running on your machine.

Case 4

If nodeos is launched but fails to produce blocks, make sure the EOSIO_SHARED_MEMORY_SIZE_MB variable has been properly removed from system variables, as described above.

Case 5

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 6

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:

"EOSIO_SOURCE_DIR": "/mnt/x/Workspaces/EOS/eos",
"EOSIO_EOSFACTORY_DIR": "/mnt/x/Workspaces/EOS/eosfactory",
"EOSIO_DATA_DIR": "/mnt/x/Workspaces/EOS/eosfactory/build/daemon/data-dir/",
"EOSIO_CONFIG_DIR": "/mnt/x/Workspaces/EOS/eosfactory/build/daemon/data-dir/",
"KEOSD_WALLET_DIR": "${HOME}/eosio-wallet/",
"nodeExe": "/mnt/x/Workspaces/EOS/eos/build/programs/nodeos/nodeos",
"cleosExe": "/mnt/x/Workspaces/EOS/eos/build/programs/cleos/cleos",
"genesisJson": "/mnt/x/Workspaces/EOS/eosfactory/build/daemon/data-dir/genesis.json",
"EOSIO_DAEMON_ADDRESS": "127.0.0.1:8888",
"EOSIO_KEY_PRIVATE": "5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3",
"EOSIO_KEY_PUBLIC": "EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
"EOSIO_WALLET_ADDRESS": "127.0.0.1:8888",
"EOSIO_DAEMON_NAME": "nodeos",
"EOSIO_WASM_CLANG": "${HOME}/opt/wasm/bin/clang",
"EOSIO_BOOST_INCLUDE_DIR": "${HOME}/opt/boost/include",
"EOSIO_WASM_LLVM_LINK": "${HOME}/opt/wasm/bin/llvm-link",
"EOSIO_WASM_LLC": "${HOME}/opt/wasm/bin/llc",
"EOSIO_S2WASM": "/usr/local/bin/eosio-s2wasm",
"EOSIO_WAST2WASM": "/usr/local/bin/eosio-wast2wasm",
"sharedMemory": "200",
"contractWorkspace": "/mnt/x/Workspaces/EOS/contracts",
"workspaceEosio": "/mnt/x/Workspaces/EOS/eos/build/contracts/"

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:

./build.sh

NOTE: After the initial successful installation, unless the path to your EOSIO source code and/or your workspace directory has changed, you don’t need to supply them when doing subsequent EOSFactory builds, as those paths are already stored in your system variables. If you do need to supply those parameters, use this syntax:

./build.sh -e /path/to/your/local/EOSIO/repository -w /path/to/your/local/workspace

And to get help for the build script:

./build.sh -h