Skip to content

Latest commit

 

History

History
354 lines (262 loc) · 12.2 KB

01.InstallingEOSFactory.md

File metadata and controls

354 lines (262 loc) · 12.2 KB
Raw

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)

General prerequisites

We assume that you have successfully installed EOSIO v1.8.0 on your machine. Binary installation suffices.

NOTE: On MacOS Brew is required for the EOSIO instalation.

EOSIO deployed in Docker is NOT supported.

Also, we assume that you have installed eosio.cdt v1.6.1. Binary installation suffices.

Prerequisites for Ubuntu & MacOS

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

Prerequisites for Windows

  • We assume that you have Windows Subsystem for Linux - Ubuntu 18.04 installed.
  • We assume that both EOSIO and EOSIO.CDT are installed to the Windows Ubuntu bash. If you prefer to compile them from sources, we recommend cloning them in the Windows file structure, 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. Also make sure your WSL has pip3 18.1 (or higher) installed.
  • It is advisable to have Python installed on the Windows side, as well: this enables using a linter with the scripts on the Ubuntu side.

Python dependencies

EOSFactory depends on termcolor and psutil nonstandard Python packages. It can be installed by running:

pip3 install --user termcolor
pip3 install --user psutil

NOTE: The switch --user may have to be omitted with a virtual envitonment.

Install 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

When prompted, supply the path pointing to the 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.

Install 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 that is accessible to WSL.

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

cd /mnt/c/Workspaces/EOS/eosfactory

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

./install.sh

When prompted, supply the path pointing to the location of your smart-contract workspace, e.g. /mnt/c/Workspaces/EOS/contracts. It has to be existent, so if you don't have it already, you need to create it manually.

Verify the installation

Now let's verify that EOSFactory works and is properly hooked up to EOSIO:

python3 -m eosfactory.config

The correct output should be similar to this:

EOSFactory version 3.4.0.
Dependencies:
https://github.com/EOSIO/eos version 1.8.0
https://github.com/EOSIO/eosio.cdt version 1.6.1
Python version 3.5 or higher

    EOSFactory package is installed as a link to the directory:
    '/mnt/c/Workspaces/EOS/eosfactory/eosfactory/'

The current configuration of EOSFactory:
{
    "CONFIG_FILE": "/mnt/c/Workspaces/EOS/eosfactory/config/config.json",
    "EOSIO_CDT_VERSION": [
        "1.6.1"
    ],
    "EOSIO_CLI_EXECUTABLE": "cleos",
    "EOSIO_CONTRACT_WORKSPACE": "/mnt/c/Workspaces/EOS/contracts",
    "EOSIO_CPP": "eosio-cpp",
    "EOSIO_CPP_DIR": "/usr/opt/eosio.cdt/1.6.1/",
..........................................
..........................................

Now, you can try tests. Make sure your working directory is switched to eosfactory:

cd eosfactory

And then run those three tests:

python3 tests/hello_world.py
python3 tests/eosio_token.py
python3 tests/tic_tac_toe.py

Install from PyPi repository

Since the v3.0.0 release, EOSFactory supports installation with the pip3 installer. EOSFactory installed as a plain Python module does not contain such additional features that can be obtained via the GitHub repository only:

  • test scripts,
  • tutorials, some of them executable.

Instead, the EOSFactory library can be used as a staring point for user's extensions.

You can install the PyPi of EOSFactory with the pip3 command:

pip3 install --user eosfactory-tokenika

NOTE: The switch --user may have to be omitted with a virtual environment.

Those two versions, GitHub and PyPi are identical in terms of codebase, while they differ in their folder structure.

The configuration can be printed with this command:

python3 -m eosfactory.config

In the printout, you'll see a note about the nature of the active package:

EOSFactory version 3.4.0.
Dependencies:
https://github.com/EOSIO/eos version 1.8.0
https://github.com/EOSIO/eosio.cdt version 1.6.1
Python version 3.5 or higher

    EOSFactory is installed as a PyPi package.

The current configuration of EOSFactory:
{
    "CONFIG_FILE": "/mnt/c/Workspaces/EOS/eosfactory/config/config.json",
    "EOSIO_CDT_VERSION": [
        "1.6.1"
    ],
    "EOSIO_CLI_EXECUTABLE": "cleos",
    "EOSIO_CONTRACT_WORKSPACE": "/mnt/c/Workspaces/EOS/contracts",
    "EOSIO_CPP": "eosio-cpp",
    "EOSIO_CPP_DIR": "/usr/opt/eosio.cdt/1.6.1/",
..........................................
..........................................

NOTE: We recommend installing the EOSFactory package locally. However, it can also be installed globally. When installed globally, tests have to be executed as sudo. However, if KEOSD operates locally ($HOME/eosio-wallet), it issues a misleading fatal error message complaining that the wallet already exists.

Uninstalling

Make sure your working directory is switched to eosfactory:

cd eosfactory

Then

./uninstall.sh

Or, anywhere in the system, do

pip3 uninstall eosfactory-tokenika

Troubleshooting specific errors

Nodeos version error

There is a bug in eosio nodeos executable that makes it to response erratically. The command python3 -m eosfactory.config attempts to verify the version of the EOSIO installation, which is quite frequently unsuccessful and results in the following error message:

ERROR!
Cannot determine the version of the installed 'eosio' package.
The error message:
Command '['/usr/bin/nodeos', '--version']' returned non-zero exit status 255.

Troubleshooting general problems

Verify EOSFactory configuration

Make sure EOSFactory configuration is correct by running this command:

python3 -m eosfactory.config

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

EOSFactory version 3.4.0.
Dependencies:
https://github.com/EOSIO/eos version 1.8.0
https://github.com/EOSIO/eosio.cdt version 1.6.1
Python version 3.5 or higher


    EOSFactory package is installed as a link to the directory:
    '/mnt/c/Workspaces/EOS/eosfactory/eosfactory/'


The current configuration of EOSFactory:
{
    "CONFIG_FILE": "/mnt/c/Workspaces/EOS/eosfactory/config/config.json",
    "EOSIO_CDT_VERSION": [
        "1.6.1"
    ],
    "EOSIO_CLI_EXECUTABLE": "cleos",
    "EOSIO_CONTRACT_WORKSPACE": "/mnt/c/Workspaces/EOS/contracts",
    "EOSIO_CPP": "eosio-cpp",
    "EOSIO_CPP_DIR": "/usr/opt/eosio.cdt/1.6.1/",
    "EOSIO_CPP_INCLUDES": [
        "/usr/opt/eosio.cdt/1.6.1/include",
        "/usr/opt/eosio.cdt/1.6.1/include/libcxx",
        "/usr/opt/eosio.cdt/1.6.1/include/eosiolib/core",
        "/usr/opt/eosio.cdt/1.6.1/include/eosiolib/contracts"
    ],
    "EOSIO_GENESIS_JSON": "/home/cartman/.local/share/eosio/nodeos/config/genesis.json",
    "EOSIO_KEY_PRIVATE": "5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3",
    "EOSIO_KEY_PUBLIC": "EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
    "EOSIO_SHARED_MEMORY_SIZE_MB": "300",
    "EOSIO_VERSION": [
        "1.8.0"
    ],
    "EOS_FACTORY_DIR": "/mnt/c/Workspaces/EOS/eosfactory",
    "INCLUDE": "/mnt/c/Workspaces/EOS/eosfactory/includes",
    "KEOSD_EXECUTABLE": "keosd",
    "KEOSD_WALLET_DIR": "/home/cartman/eosio-wallet/",
    "LIBS": null,
    "LOCAL_NODE_ADDRESS": "127.0.0.1:8888",
    "LOCAL_NODE_CONFIG_DIR": "/mnt/c/Workspaces/EOS/eosfactory/config",
    "LOCAL_NODE_DATA_DIR": "/home/cartman/.local/share/eosio/nodeos/data/",
    "LOCAL_NODE_EXECUTABLE": "nodeos",
    "NODEOS_STDOUT": null,
    "TEMPLATE_DIR": "/mnt/c/Workspaces/EOS/eosfactory/templates/contracts",
    "WALLET_MANAGER_ADDRESS": "127.0.0.1:8888",
    "WSL_ROOT": "C:/Users/cartman/AppData/Local/Packages/CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc/LocalState/rootfs"
}

You can overwrite the above settings with entries in the configuration
file located here:
/mnt/c/Workspaces/EOS/eosfactory/config/config.json


There are undefined setting:
{
    "LIBS": null,
    "NODEOS_STDOUT": null
}

Next, note the entries of the value null. Some of them signal configuration errors.

Enable error traceback

Normally, error messages do not involve traceback. You can enable tracebacking:

import eosfactory.core.setup as setup
setup.is_raise_error = True

Verify command lines

Technically, EOSFactory wraps EOSIO executables -- namely cleos, keos, nodeos -- with its own API. Therefore, in error conditions, it makes sense to inspect command lines sent to the EOSIO executables. The boolean variable eosfactory.core.setup.is_print_command_lines sets the debugging status. For example, if deployment of the contract in the test script hello_world.py fails, modify the script:

        import eosfactory.core.setup as setUp   ## added
        setup.is_print_command_lines = True      ## added
        smart.build()
        smart.deploy()
        setup.is_print_command_lines = False     ## added

Now, if you run the script, you can see raw bash commands that can be inspected and tried:

######## command line sent to eosio-cpp:
/usr/bin/eosio-cpp -I=/mnt/c/Workspaces/EOS/eosfactory/contracts_windows/_wslqwjvacdyugodewiyd /mnt/c/Workspaces/EOS/eosfactory/contracts_windows/_wslqwjvacdyugodewiyd/src/_wslqwjvacdyugodewiyd.cpp:
WASM file writen to file: 
    /mnt/c/Workspaces/EOS/eosfactory/contracts_windows/_wslqwjvacdyugodewiyd/build/_wslqwjvacdyugodewiyd.wasm
######## command line sent to cleos:
/usr/bin/cleos --url http://127.0.0.1:8888 set contract kswquviprmbi /mnt/c/Workspaces/EOS/eosfactory/contracts_windows/_wslqwjvacdyugodewiyd build/_wslqwjvacdyugodewiyd.wasm build/_wslqwjvacdyugodewiyd.abi

Note that there is another facility, corresponding to the eosfactory.core.setup.is_print_command_lines setting: it is eosfactory.core.setup.is_save_command_lines. If set, all the command lines are printed to the file command_lines.txt in the current working directory.

Verify communication with cleos

EOSFactory offers another debugging tool: printing requests send by cleos to nodeos, and responses from nodeos. For example, if deployment of the contract in the test script hello_world.py fails, modify the script:

        import eosfactory.core.setup as setUp   ## added
        setup.is_print_command_lines = True      ## added
        setup.is_print_request = True           ## added
        # setup.is_print_response = True        ## volume printout
        smart.build()
        smart.deploy()
        setup.is_print_request = False          ## added
        setup.is_print_command_lines = False     ## added
        setup.is_print_response = False         ## added

Subsequent installations

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

cd eosfactory
git pull

And then just run:

./install.sh