From c99d72d54197a93c164a6b1df355e42aced072f7 Mon Sep 17 00:00:00 2001 From: protolambda Date: Wed, 21 Apr 2021 03:17:33 +0200 Subject: [PATCH 1/2] update pyspec dev usage docs, improve makefile --- Makefile | 20 ++++++----- tests/core/pyspec/README.md | 67 ++++++++++++++++++++++++------------- 2 files changed, 56 insertions(+), 31 deletions(-) diff --git a/Makefile b/Makefile index 8f053e7a7..0522c8842 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,10 @@ SPEC_DIR = ./specs SSZ_DIR = ./ssz TEST_LIBS_DIR = ./tests/core TEST_GENERATORS_DIR = ./tests/generators +# The working dir during testing PY_SPEC_DIR = $(TEST_LIBS_DIR)/pyspec +ETH2SPEC_MODULE_DIR = $(PY_SPEC_DIR)/eth2spec +TEST_REPORT_DIR = $(PY_SPEC_DIR)/test-reports TEST_VECTOR_DIR = ../eth2.0-spec-tests/tests GENERATOR_DIR = ./tests/generators SOLIDITY_DEPOSIT_CONTRACT_DIR = ./solidity_deposit_contract @@ -27,7 +30,8 @@ MARKDOWN_FILES = $(wildcard $(SPEC_DIR)/phase0/*.md) $(wildcard $(SPEC_DIR)/alta $(wildcard $(SPEC_DIR)/sharding/*.md) COV_HTML_OUT=.htmlcov -COV_INDEX_FILE=$(PY_SPEC_DIR)/$(COV_HTML_OUT)/index.html +COV_HTML_OUT_DIR=$(PY_SPEC_DIR)/$(COV_HTML_OUT) +COV_INDEX_FILE=$(COV_HTML_OUT_DIR)/index.html CURRENT_DIR = ${CURDIR} LINTER_CONFIG_FILE = $(CURRENT_DIR)/linter.ini @@ -53,17 +57,17 @@ partial_clean: rm -f .coverage rm -rf $(PY_SPEC_DIR)/.pytest_cache rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/.pytest_cache - rm -rf $(PY_SPEC_DIR)/phase0 - rm -rf $(PY_SPEC_DIR)/altair - rm -rf $(PY_SPEC_DIR)/merge - rm -rf $(PY_SPEC_DIR)/$(COV_HTML_OUT) - rm -rf $(PY_SPEC_DIR)/.coverage - rm -rf $(PY_SPEC_DIR)/test-reports + rm -rf $(ETH2SPEC_MODULE_DIR)/phase0 + rm -rf $(ETH2SPEC_MODULE_DIR)/altair + rm -rf $(ETH2SPEC_MODULE_DIR)/merge + rm -rf $(COV_HTML_OUT_DIR) + rm -rf $(TEST_REPORT_DIR) rm -rf eth2spec.egg-info dist build rm -rf build clean: partial_clean rm -rf venv + # legacy cleanup. The pyspec venv should be located at the repository root rm -rf $(PY_SPEC_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_COMPILER_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/venv @@ -88,7 +92,7 @@ pyspec: # installs the packages to run pyspec tests install_test: - python3 -m venv venv; . venv/bin/activate; python3 -m pip install .[lint]; python3 -m pip install -e .[test] + python3 -m venv venv; . venv/bin/activate; python3 -m pip install -e .[lint]; python3 -m pip install -e .[test] test: pyspec . venv/bin/activate; cd $(PY_SPEC_DIR); \ diff --git a/tests/core/pyspec/README.md b/tests/core/pyspec/README.md index d84054f11..33695a223 100644 --- a/tests/core/pyspec/README.md +++ b/tests/core/pyspec/README.md @@ -7,27 +7,30 @@ With this executable spec, test-generators can easily create test-vectors for client implementations, and the spec itself can be verified to be consistent and coherent through sanity tests implemented with pytest. -## Building - -To build the pyspec: `python setup.py build` - (or `pip install .`, but beware that ignored files will still be copied over to a temporary dir, due to pip issue 2195). -This outputs the build files to the `./build/lib/eth2spec/...` dir, and can't be used for local test running. Instead, use the dev-install as described below. - ## Dev Install -All the dynamic parts of the spec are automatically built with `python setup.py pyspecdev`. -Unlike the regular install, this outputs spec files to their original source location, instead of build output only. +First, create a `venv` and install the developer dependencies (`test` and `lint` extras): -Alternatively, you can build a sub-set of the pyspec with the distutil command: -```bash -python setup.py pyspec --spec-fork=phase0 --md-doc-paths="specs/phase0/beacon-chain.md specs/phase0/fork-choice.md" --out-dir=my_spec_dir +```shell +make install_test ``` -## Py-tests +All the dynamic parts of the spec are built with: -After installing, you can install the optional dependencies for testing and linting. -With makefile: `make install_test`. -Or manually: run `pip install .[test]` and `pip install .[lint]`. +```shell +(venv) python setup.py pyspecdev +``` + +Unlike the regular install, this outputs spec files to their intended source location, +to enable debuggers to navigate between packages and generated code, without fragile directory linking. + +By default, when installing the `eth2spec` as package in non-develop mode, +the distutils implementation of the `setup` runs `build`, which is extended to run the same `pyspec` work, +but outputs into the standard `./build/lib` output. +This enables the `eth2.0-specs` repository to be installed like any other python package. + + +## Py-tests These tests are not intended for client-consumption. These tests are testing the spec itself, to verify consistency and provide feedback on modifications of the spec. @@ -39,20 +42,32 @@ However, most of the tests can be run in generator-mode, to output test vectors Run `make test` from the root of the specs repository (after running `make install_test` if have not before). +Note that the `make` commands run through the build steps: it runs the `build` output, not the local package source files. + #### Manual -From the repository root: +See `Dev install` for test pre-requisites. -Install venv and install: -```bash -python3 -m venv venv -. venv/bin/activate -python setup.py pyspecdev +Tests are built for `pytest`. + +Caveats: +- Working directory must be `./tests/core/pyspec`. The work-directory is important to locate eth2 configuration files. +- Run `pytest` as module. It avoids environment differences, and the behavior is different too: + `pytest` as module adds the current directory to the `sys.path` + +Full test usage, with explicit configuration for illustration of options usage: +```shell +(venv) python -m pytest --config=minimal eth2spec ``` -Run the test command from the `tests/core/pyspec` directory: +Or, to run a specific test file, specify the full path: +```shell +(venv) python -m pytest --config=minimal ./eth2spec/test/phase0/block_processing/test_process_attestation.py ``` -pytest --config=minimal eth2spec + +Or, to run a specific test function (specify the `eth2spec` module, or the script path if the keyword is ambiguous): +```shell +(venv) python -m pytest --config=minimal -k test_success_multi_proposer_index_iterations eth2spec ``` Options: @@ -64,6 +79,12 @@ Options: Run `make open_cov` from the root of the specs repository after running `make test` to open the html code coverage report. +### Advanced + +Building spec files from any markdown sources, to a custom location: +```bash +(venv) python setup.py pyspec --spec-fork=phase0 --md-doc-paths="specs/phase0/beacon-chain.md specs/phase0/fork-choice.md" --out-dir=my_spec_dir +``` ## Contributing From 1c8f56c84b27820fca67051041518c57a9fa2c37 Mon Sep 17 00:00:00 2001 From: Diederik Loerakker Date: Thu, 22 Apr 2021 02:35:54 +0200 Subject: [PATCH 2/2] Fix indentation of comment Co-authored-by: Alex Stokes --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 0522c8842..e4969ff2f 100644 --- a/Makefile +++ b/Makefile @@ -67,7 +67,7 @@ partial_clean: clean: partial_clean rm -rf venv - # legacy cleanup. The pyspec venv should be located at the repository root + # legacy cleanup. The pyspec venv should be located at the repository root rm -rf $(PY_SPEC_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_COMPILER_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/venv