Add 'make venv' target (#6775)

Fixes #6775

.github/workflows/format.yml

@@ -28,16 +28,16 @@ jobs:
         env:
           CI_BUILD_STAGE_NAME: build
         run: |
-          bash ci/ci-install.bash &&
+          sudo apt install clang-format-18
-          sudo apt-get install clang-format-18 yapf3 &&
+          git config --global user.email "action@example.com"
-          sudo pip3 install gersemi==0.23.1 mbake &&
-          git config --global user.email "action@example.com" &&
           git config --global user.name "github action"
       - name: Format code
         run: |
-          autoconf &&
+          autoconf
-          ./configure &&
+          ./configure
-          make -j 2 format CLANGFORMAT=clang-format-18 &&
+          make venv
+          source .venv/bin/activate
+          make -j 2 format CLANGFORMAT=clang-format-18
           git status
       - name: Push
         run: |-

.github/workflows/reusable-lint-py.yml

@@ -34,13 +34,17 @@ jobs:
       - name: Install packages for build
         run: ./ci/ci-install.bash
 
-    # We use specific version numbers, otherwise a Python package
-    # update may add a warning and break our build
-      - name: Install packages for lint
-        run: sudo pip3 install mypy==1.18.2 pylint==3.0.2 ruff==0.1.3 clang sphinx sphinx_rtd_theme sphinxcontrib-spelling breathe ruff
-
       - name: Configure
-        run: autoconf && ./configure --enable-longtests --enable-ccwarn
+        run: |
+          autoconf
+          ./configure --enable-longtests --enable-ccwarn
+
+      - name: Install python dependencies
+        run: |
+          sudo apt install python3-clang
+          make venv
 
       - name: Lint
-        run: make -k lint-py
+        run: |
+          source .venv/bin/activate
+          make -k lint-py

.github/workflows/reusable-test.yml

@@ -77,14 +77,18 @@ jobs:
             ${{ env.CACHE_KEY }}-
 
       - name: Install test dependencies
-        run: ./ci/ci-install.bash
+        run: |
+          ./ci/ci-install.bash
+          make venv
 
       - name: Test
         id: run-test
         continue-on-error: true
         env:
           TESTS: ${{ inputs.suite }}
-        run: ./ci/ci-script.bash
+        run: |
+          source .venv/bin/activate
+          ./ci/ci-script.bash
 
       - name: Combine code coverage data
         if: ${{ inputs.dev-gcov }}

.gitignore

@@ -17,6 +17,7 @@
 *.pdf
 /Makefile
 /.ccache
+/.venv/
 /artifact/
 README
 TAGS

Makefile.in

@@ -575,7 +575,7 @@ format-make mbake:
 	$(MBAKE) --version
 	$(MBAKE) $(MBAKE_FLAGS) $(MAKE_FILES)
 
-YAPF = yapf3
+YAPF = yapf
 YAPF_FLAGS = -i --parallel
 
 format-py yapf:
@@ -843,3 +843,20 @@ preexist:
 
 maintainer-dist: preexist tag
 	svnorcvs release $(DISTTAGNAME)
+
+######################################################################
+# Python venv
+
+VENV_PATH ?= .venv
+
+.PHONY: venv
+venv:
+	# Create virtual environment using the python3 picked up by configure
+	[ -e $(VENV_PATH) ] || @PYTHON3@ -m venv --system-site-packages $(VENV_PATH)
+	# Install python3 dependencies
+	$(VENV_PATH)/bin/pip3 install -r python-dev-requirements.txt
+	@echo
+	@echo "Installed Python virtual environment, in:"
+	@echo "  $(VENV_PATH)"
+	@echo "To activate, run:"
+	@echo "  source $(VENV_PATH)/bin/activate"

docs/guide/install.rst

@@ -153,22 +153,37 @@ need to be present to run Verilator:
 
    sudo apt-get install git autoconf flex bison
 
-Those developing Verilator itself also need these (see internals.rst):
+Those developing Verilator itself also need the following additional
+packages (see internals.rst), and a Python virtual environment:
 
 .. code-block:: bash
 
    sudo apt-get install clang clang-format-18 cmake gdb gprof graphviz lcov
-   sudo apt-get install python3-clang python3-distro pipx yapf3 bear jq
+   sudo apt-get install python3-clang bear jq
-   python3 -m venv --system-site-packages ~/.verilator_pyenv
-   source ~/.verilator_pyenv/bin/activate
-   pip3 install sphinx sphinx_rtd_theme sphinxcontrib-spelling breathe gersemi mbake mypy ruff
-   pip3 install git+https://github.com/antmicro/astsee.git
-   pipx install sarif-tools
    cpan install Pod::Perldoc
-   #
-   # Later, when building or testing Verilator, you will need
-   source ~/.verilator_pyenv/bin/activate
 
+The Python virtual environment is only required for running the whole test
+suite, and for additional development steps like linting and formatting. It is
+not required for building Verilator itself. To install the python virtual
+environment and all dependencies automatically, run the following once, after
+``configure``:
+
+.. code-block:: bash
+
+   # Create Python virutal environment in .venv:
+   make venv
+
+   # Or alternatively, to put it somewhere else:
+   make venv VENV_PATH=where_you_want_it
+
+Then activate the virtual environment in the shell using:
+
+.. code-block:: bash
+
+   source .venv/bin/activate
+
+   # Or if installed somewhere else:
+   source where_you_want_it/bin/activate
 
 Install SystemC
 ^^^^^^^^^^^^^^^

python-dev-requirements.txt

@@ -0,0 +1,33 @@
+# Copyright 2003-2025 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
+# Lesser General Public License Version 3 or the Perl Artistic License
+# Version 2.0.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# These packages are only required for developers who want to run the whole
+# test suite, or other development steps like code formatting or linting.
+# They are NOT required for building, running or packaging Verilator itself.
+
+# The usual use of this file is via the `make venv` target, as described in
+# docs/guide/install.rst
+
+# We use specific version numbers, otherwise a Python package update may add a
+# warning and break our builds
+
+# Keep sorted
+
+breathe==4.36.0
+compiledb==0.10.7
+distro==1.9.0
+gersemi==0.23.1
+mbake==1.4.3
+mypy==1.19.0
+pylint==3.0.2
+ruff==0.14.8
+sarif-tools==3.0.5
+sphinx_rtd_theme==3.0.2
+sphinx==8.1.3
+sphinxcontrib-spelling==8.0.2
+yapf==0.43.0
+
+git+https://github.com/antmicro/astsee.git