status-im
/
eth2.0-specs
mirror of https://github.com/status-im/eth2.0-specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2346 from ethereum/pyspecdocs 

update pyspec dev usage docs, improve makefile
This commit is contained in:
Alex Stokes 2021-04-22 08:30:44 -07:00 committed by GitHub
parent 9c189ffc4b 1c8f56c84b
commit b0aee5b271
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 56 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Makefile
View File

@ -2,7 +2,10 @@ SPEC_DIR = ./specs
SSZ_DIR = ./ssz SSZ_DIR = ./ssz
TEST_LIBS_DIR = ./tests/core TEST_LIBS_DIR = ./tests/core
TEST_GENERATORS_DIR = ./tests/generators TEST_GENERATORS_DIR = ./tests/generators
# The working dir during testing
PY_SPEC_DIR = $(TEST_LIBS_DIR)/pyspec 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 TEST_VECTOR_DIR = ../eth2.0-spec-tests/tests
GENERATOR_DIR = ./tests/generators GENERATOR_DIR = ./tests/generators
SOLIDITY_DEPOSIT_CONTRACT_DIR = ./solidity_deposit_contract 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) $(wildcard $(SPEC_DIR)/sharding/*.md)
COV_HTML_OUT=.htmlcov 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} CURRENT_DIR = ${CURDIR}
LINTER_CONFIG_FILE = $(CURRENT_DIR)/linter.ini LINTER_CONFIG_FILE = $(CURRENT_DIR)/linter.ini
@ -53,17 +57,17 @@ partial_clean:
rm -f .coverage rm -f .coverage
rm -rf $(PY_SPEC_DIR)/.pytest_cache rm -rf $(PY_SPEC_DIR)/.pytest_cache
rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/.pytest_cache rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/.pytest_cache
rm -rf $(PY_SPEC_DIR)/phase0 rm -rf $(ETH2SPEC_MODULE_DIR)/phase0
rm -rf $(PY_SPEC_DIR)/altair rm -rf $(ETH2SPEC_MODULE_DIR)/altair
rm -rf $(PY_SPEC_DIR)/merge rm -rf $(ETH2SPEC_MODULE_DIR)/merge
rm -rf $(PY_SPEC_DIR)/$(COV_HTML_OUT) rm -rf $(COV_HTML_OUT_DIR)
rm -rf $(PY_SPEC_DIR)/.coverage rm -rf $(TEST_REPORT_DIR)
rm -rf $(PY_SPEC_DIR)/test-reports
rm -rf eth2spec.egg-info dist build rm -rf eth2spec.egg-info dist build
rm -rf build rm -rf build
clean: partial_clean clean: partial_clean
rm -rf venv rm -rf venv
# legacy cleanup. The pyspec venv should be located at the repository root
rm -rf $(PY_SPEC_DIR)/venv rm -rf $(PY_SPEC_DIR)/venv
rm -rf $(DEPOSIT_CONTRACT_COMPILER_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_COMPILER_DIR)/venv
rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/venv rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/venv
@ -88,7 +92,7 @@ pyspec:
# installs the packages to run pyspec tests # installs the packages to run pyspec tests
install_test: 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 test: pyspec
. venv/bin/activate; cd $(PY_SPEC_DIR); \ . venv/bin/activate; cd $(PY_SPEC_DIR); \

67
tests/core/pyspec/README.md
View File

@ -7,27 +7,30 @@ With this executable spec,
test-generators can easily create test-vectors for client implementations, 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. 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 ## Dev Install
All the dynamic parts of the spec are automatically built with `python setup.py pyspecdev`. First, create a `venv` and install the developer dependencies (`test` and `lint` extras):
Unlike the regular install, this outputs spec files to their original source location, instead of build output only.
Alternatively, you can build a sub-set of the pyspec with the distutil command: ```shell
```bash make install_test
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
``` ```
## Py-tests All the dynamic parts of the spec are built with:
After installing, you can install the optional dependencies for testing and linting. ```shell
With makefile: `make install_test`. (venv) python setup.py pyspecdev
Or manually: run `pip install .[test]` and `pip install .[lint]`. ```
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 not intended for client-consumption.
These tests are testing the spec itself, to verify consistency and provide feedback on modifications of the spec. 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). 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 #### Manual
From the repository root: See `Dev install` for test pre-requisites.
Install venv and install: Tests are built for `pytest`.
```bash
python3 -m venv venv Caveats:
. venv/bin/activate - Working directory must be `./tests/core/pyspec`. The work-directory is important to locate eth2 configuration files.
python setup.py pyspecdev - 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: 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. 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 ## Contributing