Skip to content

Commit 371b096

Browse files
jtragliajtraglia
authored
Add extended help option in Makefile (#4547)
1 parent 8938ed3 commit 371b096

File tree

1 file changed

+155
-35
lines changed

1 file changed

+155
-35
lines changed

‎Makefile

Lines changed: 155 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,16 @@ ALL_EXECUTABLE_SPEC_NAMES = \
3535
BOLD = $(shell tput bold)
3636
NORM = $(shell tput sgr0)
3737

38-
# Print target descriptions.
38+
# Print help.
3939
help:
40+
ifeq ($(verbose),true)
41+
@$(MAKE) -s help-verbose
42+
else
43+
@$(MAKE) -s help-nonverbose
44+
endif
45+
46+
# Print basic help output.
47+
help-nonverbose:
4048
@echo "make $(BOLD)clean$(NORM) -- delete all untracked files"
4149
@echo "make $(BOLD)comptests$(NORM) -- generate compliance tests"
4250
@echo "make $(BOLD)coverage$(NORM) -- run pyspec tests with coverage"
@@ -46,6 +54,152 @@ help:
4654
@echo "make $(BOLD)reftests$(NORM) -- generate reference tests"
4755
@echo "make $(BOLD)serve_docs$(NORM) -- start a local docs web server"
4856
@echo "make $(BOLD)test$(NORM) -- run pyspec tests"
57+
@echo ""
58+
@echo "Run 'make $(BOLD)help verbose=true$(NORM)' to print detailed usage/examples."
59+
@echo ""
60+
61+
# Print verbose help output.
62+
help-verbose:
63+
@echo ""
64+
@echo "$(BOLD)BUILDING$(NORM)"
65+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
66+
@echo ""
67+
@echo "$(BOLD)make pyspec$(NORM)"
68+
@echo ""
69+
@echo " Builds Python specifications for all consensus phases. This command installs"
70+
@echo " the eth2spec package and copies mainnet/minimal configs to the test directory."
71+
@echo ""
72+
@echo " Example: make pyspec"
73+
@echo ""
74+
@echo "$(BOLD)TESTING$(NORM)"
75+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
76+
@echo ""
77+
@echo "$(BOLD)make test$(NORM)"
78+
@echo ""
79+
@echo " Runs pyspec tests with various configuration options. Tests run in parallel"
80+
@echo " by default using pytest with the minimal preset and fastest BLS library."
81+
@echo ""
82+
@echo " Parameters:"
83+
@echo " k=<test> Run specific test by name"
84+
@echo " fork=<fork> Test specific fork (phase0, altair, bellatrix, capella, etc.)"
85+
@echo " preset=<preset> Use specific preset (mainnet or minimal; default: minimal)"
86+
@echo " bls=<type> BLS library type (py_ecc, milagro, arkworks, fastest; default: fastest)"
87+
@echo ""
88+
@echo " Examples:"
89+
@echo " make test"
90+
@echo " make test k=test_verify_kzg_proof"
91+
@echo " make test fork=deneb"
92+
@echo " make test preset=mainnet"
93+
@echo " make test preset=mainnet fork=deneb k=test_verify_kzg_proof"
94+
@echo " make test bls=arkworks"
95+
@echo ""
96+
@echo "$(BOLD)make coverage$(NORM)"
97+
@echo ""
98+
@echo " Runs tests with code coverage tracking and generates an HTML report."
99+
@echo " Automatically opens the coverage report in your browser after completion."
100+
@echo ""
101+
@echo " Parameters:"
102+
@echo " k=<test> Run specific test by name"
103+
@echo " fork=<fork> Test specific fork"
104+
@echo ""
105+
@echo " Examples:"
106+
@echo " make coverage"
107+
@echo " make coverage k=test_process_attestation"
108+
@echo " make coverage fork=electra"
109+
@echo ""
110+
@echo "$(BOLD)CODE QUALITY$(NORM)"
111+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
112+
@echo ""
113+
@echo "$(BOLD)make lint$(NORM)"
114+
@echo ""
115+
@echo " Runs all linters and formatters to check code quality:"
116+
@echo " - mdformat: Formats markdown files"
117+
@echo " - codespell: Checks for spelling mistakes"
118+
@echo " - ruff: Python linter and formatter"
119+
@echo " - mypy: Static type checker for Python"
120+
@echo ""
121+
@echo " Example: make lint"
122+
@echo ""
123+
@echo "$(BOLD)TEST GENERATION$(NORM)"
124+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
125+
@echo ""
126+
@echo "$(BOLD)make reftests$(NORM)"
127+
@echo ""
128+
@echo " Generates reference test vectors for consensus spec tests. These tests are"
129+
@echo " used by client implementations to verify correctness. This command will write"
130+
@echo " reference tests to the ../consensus-spec-tests/ directory."
131+
@echo ""
132+
@echo " Parameters:"
133+
@echo " runner=<runner> Generate tests for specific runner (bls, operations, etc.)"
134+
@echo " k=<test> Generate specific test cases (comma-separated)"
135+
@echo " fork=<fork> Generate for specific fork (comma-separated)"
136+
@echo " preset=<preset> Generate for specific preset (comma-separated)"
137+
@echo " threads=N Number of threads to use (default: auto)"
138+
@echo " verbose=true Enable verbose output"
139+
@echo ""
140+
@echo " Examples:"
141+
@echo " make reftests"
142+
@echo " make reftests runner=bls"
143+
@echo " make reftests runner=operations k=invalid_committee_index"
144+
@echo " make reftests runner=operations fork=fulu"
145+
@echo " make reftests runner=operations preset=mainnet"
146+
@echo " make reftests runner=operations k=invalid_committee_index,invalid_too_many_committee_bits"
147+
@echo " make reftests runner=operations preset=mainnet fork=fulu k=invalid_committee_index"
148+
@echo " make reftests runner=bls threads=1 verbose=true"
149+
@echo ""
150+
@echo " Tip:"
151+
@echo " Use the following command to list available runners:"
152+
@echo " ls -1 tests/generators/runners | grep -v '/$$' | sed 's/\.py$$//'"
153+
@echo ""
154+
@echo "$(BOLD)make comptests$(NORM)"
155+
@echo ""
156+
@echo " Generates compliance tests for fork choice. These tests verify that"
157+
@echo " implementations correctly handle fork choice scenarios."
158+
@echo ""
159+
@echo " Parameters:"
160+
@echo " fc_gen_config=<config> Configuration size (tiny, small, standard; default: tiny)"
161+
@echo " fork=<fork> Generate for specific fork (comma-separated)"
162+
@echo " preset=<preset> Generate for specific preset (comma-separated)"
163+
@echo " threads=N Number of threads to use"
164+
@echo ""
165+
@echo " Examples:"
166+
@echo " make comptests"
167+
@echo " make comptests fc_gen_config=standard"
168+
@echo " make comptests fc_gen_config=standard fork=deneb preset=mainnet threads=8"
169+
@echo ""
170+
@echo "$(BOLD)make kzg_setups$(NORM)"
171+
@echo ""
172+
@echo " Generates KZG trusted setup files for testing. Creates trusted setups for"
173+
@echo " both minimal and mainnet presets with predefined parameters."
174+
@echo ""
175+
@echo " Example: make kzg_setups"
176+
@echo ""
177+
@echo "$(BOLD)DOCUMENTATION$(NORM)"
178+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
179+
@echo ""
180+
@echo "$(BOLD)make serve_docs$(NORM)"
181+
@echo ""
182+
@echo " Builds and serves the documentation locally using MkDocs. Copies spec files,"
183+
@echo " removes deprecated content, and starts a local web server for viewing docs."
184+
@echo ""
185+
@echo " Example: make serve_docs"
186+
@echo " Then open: http://127.0.0.1:8000"
187+
@echo ""
188+
@echo "$(BOLD)MAINTENANCE$(NORM)"
189+
@echo "$(BOLD)--------------------------------------------------------------------------------$(NORM)"
190+
@echo ""
191+
@echo "$(BOLD)make clean$(NORM)"
192+
@echo ""
193+
@echo " Removes all untracked files. This includes:"
194+
@echo " - Virtual environment (venv/)"
195+
@echo " - Build artifacts"
196+
@echo " - Cache files"
197+
@echo ""
198+
@echo " $(BOLD)WARNING:$(NORM) This will delete ALL untracked files. Make sure to commit or"
199+
@echo " stash any important changes first."
200+
@echo ""
201+
@echo " Example: make clean"
202+
@echo ""
49203

50204
###############################################################################
51205
# Virtual Environment
@@ -87,17 +241,6 @@ pyspec: $(VENV) setup.py pyproject.toml
87241
TEST_REPORT_DIR = $(PYSPEC_DIR)/test-reports
88242

89243
# Run pyspec tests.
90-
#
91-
# To run a specific test, append k=<test>, eg:
92-
# make test k=test_verify_kzg_proof
93-
# To run tests for a specific fork, append fork=<fork>, eg:
94-
# make test fork=deneb
95-
# To run tests for a specific preset, append preset=<preset>, eg:
96-
# make test preset=mainnet
97-
# Or all at the same time, eg:
98-
# make test preset=mainnet fork=deneb k=test_verify_kzg_proof
99-
# To run tests with a specific bls library, append bls=<bls>, eg:
100-
# make test bls=arkworks
101244
test: MAYBE_TEST := $(if $(k),-k=$(k))
102245
# Disable parallelism which running a specific test.
103246
# Parallelism makes debugging difficult (print doesn't work).
@@ -199,23 +342,6 @@ COMMA:= ,
199342
TEST_VECTOR_DIR = $(CURDIR)/../consensus-spec-tests/tests
200343

201344
# Generate reference tests.
202-
# This will forcibly rebuild pyspec just in case.
203-
# To generate reference tests for a single runner, append runner=<runner>, eg:
204-
# make reftests runner=bls
205-
# To generate reference tests with more details, append verbose=true, eg:
206-
# make reftests runner=bls verbose=true
207-
# To generate reference tests with fewer threads, append threads=N, eg:
208-
# make reftests runner=bls threads=1
209-
# To generate reference tests for a specific test, append k=<test>, eg:
210-
# make reftests runner=operations k=invalid_committee_index
211-
# To generate reference tests for a specific fork, append fork=<fork>, eg:
212-
# make reftests runner=operations fork=fulu
213-
# To generate reference tests for a specific preset, append preset=<preset>, eg:
214-
# make reftests runner=operations preset=mainnet
215-
# To generate reference tests for a list of tests, forks, and/or presets, append them as comma-separated lists, eg:
216-
# make reftests runner=operations k=invalid_committee_index,invalid_too_many_committee_bits
217-
# Or all at the same time, eg:
218-
# make reftests runner=operations preset=mainnet fork=fulu k=invalid_committee_index
219345
reftests: MAYBE_VERBOSE := $(if $(filter true,$(verbose)),--verbose)
220346
reftests: MAYBE_THREADS := $(if $(threads),--threads=$(threads))
221347
reftests: MAYBE_RUNNERS := $(if $(runner),--runners $(subst ${COMMA}, ,$(runner)))
@@ -245,12 +371,6 @@ kzg_setups: pyspec
245371
COMP_TEST_VECTOR_DIR = $(CURDIR)/../compliance-spec-tests/tests
246372

247373
# Generate compliance tests (fork choice).
248-
# This will forcibly rebuild pyspec just in case.
249-
# To generate compliance tests with a particular configuration, append fc_gen_config=<config>,
250-
# where <config> can be either tiny, small or standard, eg:
251-
# make comptests fc_gen_config=standard
252-
# One can specify threads=N, fork=<fork> or preset=<preset> as with reftests, eg:
253-
# make comptests fc_gen_config=standard fork=deneb preset=mainnet threads=8
254374
comptests: FC_GEN_CONFIG := $(if $(fc_gen_config),$(fc_gen_config),tiny)
255375
comptests: MAYBE_THREADS := $(if $(threads),--threads=$(threads),--fc-gen-multi-processing)
256376
comptests: MAYBE_FORKS := $(if $(fork),--forks $(subst ${COMMA}, ,$(fork)))

0 commit comments

Comments
 (0)