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 now compatible with the latest release of EOSIO, tagged as v1.0.8 (or higher), and from now on we expect it to be fully compatible with any subsequent EOSIO release.

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

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 assume that you have successfully installed EOSIO v1.0.8 (or higher) on your machine. If that’s not the case, please refer to this guide.
  • 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.
  • We also assume that you have successfully installed EOSIO v1.0.8 (or higher) on your machine. If that’s not the case, please refer to this guide.
  • 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.

Build EOSFactory 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 existant, 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 EOSFactory 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 existant, 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 EOSFactory

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/unittest1.py
python3 ./tests/unittest2.py
python3 ./tests/unittest3.py

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

Error 3090004: missing required authority

Troubleshooting

Case 1

If the test fails due to the can't open file './tests/unittest1.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 decribed in the previous section.

Case 3

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

Subsequent EOSFactory 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

If you want to rebuild EOSFactory from scratch, apply the -r option:

./build.sh -r

And to get help for the build script:

./build.sh -h