From 527f185862345c9ebd76227050f297f76ed624c9 Mon Sep 17 00:00:00 2001 From: Spacetown Date: Tue, 14 Dec 2021 16:32:15 +0100 Subject: [PATCH] Add review remarks. --- .github/workflows/deploy.yml | 10 +- .github/workflows/test.yml | 11 +- .gitignore | 2 + CONTRIBUTING.rst | 37 +++--- admin/Dockerfile.qa | 6 +- doc/requirements.txt | 4 + noxfile.py | 237 ++++++++++++++++++----------------- 7 files changed, 154 insertions(+), 153 deletions(-) create mode 100644 doc/requirements.txt diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index c42380bbd..dd6b4bc45 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -20,7 +20,7 @@ jobs: - name: Run release_checklist run: | admin/release_checklist 5.0 - + deploy: runs-on: ubuntu-18.04 needs: release-check @@ -47,16 +47,16 @@ jobs: python -m pip install nox - name: Lint with flake8 run: | - python -m nox --non-interactive --session lint + nox --non-interactive --session lint - name: Test with pytest run: | - python -m nox --non-interactive --session "tests_version($CC)" + nox --non-interactive --session "tests_compiler($CC)" - name: Generate documentation run: | - python -m nox --non-interactive --session doc + nox --non-interactive --session doc - name: Build run: | - python -m nox --non-interactive --session build_wheel + nox --non-interactive --session build_wheel - name: Upload distribution if: ${{ success() }} uses: actions/upload-artifact@v2 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b74c8afca..1656566af 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -105,7 +105,6 @@ jobs: - name: Setup environment run: | echo "USE_COVERAGE=${{ ( ( matrix.os == 'windows-2019' ) && ( matrix.python-version == '3.7' ) ) || ( ( matrix.os == 'ubuntu-18.04' ) && ( matrix.gcc == 'gcc-6' ) && ( matrix.python-version == '3.8' ) ) }}" >> $GITHUB_ENV - echo "TEST_OPTS=--archive_differences" >> $GITHUB_ENV shell: bash - name: Install msys with GCC (Windows) if: ${{ startsWith(matrix.os,'windows-') }} @@ -134,16 +133,16 @@ jobs: python3 -m pip install nox codecov - name: Lint files run: | - python3 -m nox --non-interactive --session lint + nox --non-interactive --session lint - name: Check format of files if: ${{ ( matrix.python-version != 'pypy3' ) }} # Currently fail of this job is OK. continue-on-error: true run: | - python -m nox --non-interactive --session black + nox --non-interactive --session black - name: Test with pytest run: | - python -m nox --non-interactive --session "tests_version(${{ matrix.gcc }})" + nox --non-interactive --session "tests_compiler(${{ matrix.gcc }})" -- --archive_differences - name: Upload pytest test results if: ${{ failure() }} uses: actions/upload-artifact@v2 @@ -174,10 +173,10 @@ jobs: - uses: actions/checkout@v2 - name: Build Docker run: | - python3 -m nox --non-interactive --session "docker_qa_build_version(${{ matrix.gcc }})" + python3 -m nox --non-interactive --session "docker_qa_build_compiler(${{ matrix.gcc }})" - name: Run Docker run: | - python3 -m nox --non-interactive --session "docker_qa_run_version(${{ matrix.gcc }})" + python3 -m nox --non-interactive --session "docker_qa_run_compiler(${{ matrix.gcc }})" - name: Upload pytest test results if: ${{ failure() }} uses: actions/upload-artifact@v2 diff --git a/.gitignore b/.gitignore index a8b6f3bd0..7bfd4d9b7 100644 --- a/.gitignore +++ b/.gitignore @@ -34,6 +34,8 @@ gcovr-*/ # VS Code .vscode +*.code-workspace # PyCharm .idea + diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5d91cddc7..81a9d3a21 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -243,7 +243,10 @@ The QA process (``python3 -m nox``) consists of multiple parts: - documentation build (``python3 -m nox --session doc``) The tests are in the ``gcovr/tests`` directory. -You can run the tests with ``python3 -m nox --session tests_version($CC)``. +You can run the tests with ``python3 -m nox --session tests`` +for the default GCC version (used from environment ``CC``iv availabele, else gcc-5. +You can also select the gcc version if you run the tests with e.g. +``python3 -m nox --session tests_compiler(gcc-8)``. There are unit tests for some parts of gcovr, and a comprehensive corpus of example projects @@ -305,54 +308,47 @@ and have set up a :ref:`development environment `. You can select a different GCC version by setting the CC environment variable. Supported versions are ``CC=gcc-5``, ``CC=gcc-6``, ``CC=gcc-8`` and ``clang-10``. -You can run the tests with additional options by setting the environment variable -``TEST_OPTS``. Run all tests after each change is a bit slow, therefore you can +You can run the tests with additional options by adding ``--`` and then the options +to the test invocation. Run all tests after each change is a bit slow, therefore you can limit the tests to a specific test file, example project, or output format. For example: .. code:: bash # run only XML tests - export TEST_OPTS="-k 'xml'" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'xml' # run the simple1 tests - export TEST_OPTS="-k 'simple1'" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'simple1' # run the simple1 tests only for XML - export TEST_OPTS="-k 'xml and simple1'" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'xml and simple1' To see which tests would be run, add the ``--collect-only`` option: .. code:: bash #see which tests would be run - export TEST_OPTS="--collect-only" - python3 -m nox --session tests + python3 -m nox --session tests -- --collect-only Sometimes during development you need to create reference files for new test or update the current reference files. To do this you have to add ``--generate_reference`` or ``--update-reference`` option -to the ``TEST_OPTS`` variable. +to the test invocation. By default generated output files are automatically removed after test run. -To skip this process you can add ``--skip_clean`` option the ``TEST_OPTS``. +To skip this process you can add ``--skip_clean`` option the test invocation. For example: .. code:: bash # run tests and generate references for simple1 example - export TEST_OPTS="-k 'simple1' --generate_reference" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'simple1' --generate_reference # run tests and update xml references for simple1 example - export TEST_OPTS="-k 'xml and simple1' --update_reference" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'xml and simple1' --update_reference # run only XML tests and do not remove generated files - export TEST_OPTS="-k 'xml' --skip_clean" - python3 -m nox --session tests + python3 -m nox --session tests -- -k 'xml' --skip_clean When the currently generated output reports differ to the reference files you can create a ZIP archive named ``diff.zip`` in the tests directory @@ -363,8 +359,7 @@ with the differences as an artifact. .. code:: bash # run tests and generate a ZIP archive when there were differences - export TEST_OPTS="--archive_differences" - python3 -m nox --session tests + python3 -m nox --session tests -- --archive_differences .. versionchanged:: NEXT Change how to start test from ``make test`` to ``python3 -m nox --session test`` diff --git a/admin/Dockerfile.qa b/admin/Dockerfile.qa index 7491399c3..7a23624de 100644 --- a/admin/Dockerfile.qa +++ b/admin/Dockerfile.qa @@ -27,6 +27,6 @@ USER docker:docker # Unicode is necessary for some tools like "black" to work. ENV LC_ALL=C.UTF-8 LANG=C.UTF-8 -CMD ( echo docker | sudo -S -p "Running chmod with sudo" chown -R docker:docker /gcovr ) && \ - echo "" && \ - python3 -m nox --non-interactive +CMD ( echo docker | sudo -S -p "Running chmod with sudo..." chown -R docker:docker /gcovr/gcovr ) && \ + echo "\ndone\nStarting test..." && \ + python3 -m nox --envdir /tmp/envs --non-interactive diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..6da1ceef8 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +sphinx +sphinx_rtd_theme +sphinxcontrib-autoprogram == 0.1.5 ; python_version == "3.6" +sphinxcontrib-autoprogram >= 0.1.5 ; python_version >= "3.7" diff --git a/noxfile.py b/noxfile.py index 943ba635a..fcb1a00a3 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,6 +1,7 @@ import os import platform import shutil +import shlex import nox GCC_VERSIONS = ["gcc-5", "gcc-6", "gcc-8", "clang-10"] @@ -12,15 +13,11 @@ "gcovr/gcov_parser.py", ] -nox.options.sessions = [ - "qa", - "lint", - "doc", - "tests_version({})".format(GCC_VERSION2USE), -] + +nox.options.sessions = ["qa"] -def set_environment(session: "nox.session", cc: str, check: bool = True) -> None: +def set_environment(session: nox.session, cc: str, check: bool = True) -> None: if check and (shutil.which(cc) is None): session.env["CC_REFERENCE"] = cc cc = "gcc" @@ -40,16 +37,25 @@ def set_environment(session: "nox.session", cc: str, check: bool = True) -> None session.env["GCOV"] = gcov -@nox.session -def qa(session: "nox.session") -> None: - for session_id in nox.options.sessions: - session.log("Notify session {}".format(session_id)) - session.notify(session_id) +@nox.session(python=False) +def qa(session: nox.session) -> None: + """Run the quality tests.""" + session_id = "lint" + session.log(f"Notify session {session_id}") + session.notify(session_id, []) + session_id = "doc" + session.log(f"Notify session {session_id}") + session.notify(session_id, []) + session_id = f"tests_compiler({GCC_VERSION2USE})" + session.log(f"Notify session {session_id}") + session.notify(session_id) @nox.session -def lint(session: "nox.session") -> None: +def lint(session: nox.session) -> None: + """Run the lint (flake8 and black).""" session.install("flake8") + # Black installs under Pypy but doesn't necessarily run (cf psf/black#2559). if platform.python_implementation() == "CPython": session.install("black") if session.posargs: @@ -73,7 +79,8 @@ def lint(session: "nox.session") -> None: @nox.session -def black(session: "nox.session") -> None: +def black(session: nox.session) -> None: + """Run black, a code formatter and format checker.""" session.install("black") if session.posargs: args = session.posargs @@ -83,35 +90,35 @@ def black(session: "nox.session") -> None: @nox.session -def doc(session: "nox.session") -> None: - session.install( - "sphinx", - "sphinx_rtd_theme", - "sphinxcontrib-autoprogram==0.1.5 ; python_version=='3.6'", - "sphinxcontrib-autoprogram>=0.1.5 ; python_version>='3.7'", - ) +def doc(session: nox.session) -> None: + """Generate the documentation.""" + session.install("-r", "doc/requirements.txt") session.install("-e", ".") - session.run("bash", "-c", "cd doc && make html O=-W", external=True) + session.chdir("doc") + session.run("make", "html", "O=-W", external=True) -@nox.session -def tests(session: "nox.session") -> None: - session_id = "tests_version({})".format(GCC_VERSION2USE) - session.log("Notify session {}".format(session_id)) +@nox.session(python=False) +def tests(session: nox.session) -> None: + """Run the tests with the default GCC version.""" + session_id = f"tests_compiler({GCC_VERSION2USE})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session -def tests_all_versions(session: "nox.session") -> None: +@nox.session(python=False) +def tests_all_compiler(session: nox.session) -> None: + """Run the tests with all GCC versions.""" for version in GCC_VERSIONS: - session_id = "tests_version({})".format(version) - session.log("Notify session {}".format(session_id)) + session_id = f"tests_compiler({version})" + session.log(f"Notify session {session_id}") session.notify(session_id) @nox.session @nox.parametrize("version", [nox.param(v, id=v) for v in GCC_VERSIONS]) -def tests_version(session: "nox.session", version: str) -> None: +def tests_compiler(session: nox.session, version: str) -> None: + """Run the test with a specifiv GCC version.""" session.install( "jinja2", "lxml", @@ -130,150 +137,144 @@ def tests_version(session: "nox.session", version: str) -> None: session.run("python", "--version") session.run(session.env["CC"], "--version", external=True) session.run(session.env["CXX"], "--version", external=True) - session.run( - session.env["GCOV"].replace(" gcov", "") - if "llvm-cov" in session.env["GCOV"] - else session.env["GCOV"], - "--version", - external=True, - ) + session.run(*shlex.split(session.env["GCOV"]), "--version", external=True) - session.run("bash", "-c", "cd gcovr/tests && make --silent clean", external=True) + session.chdir("gcovr/tests") + session.run("make", "--silent", "clean", external=True) + session.chdir("../..") args = ["-m", "pytest"] args += coverage_args args += session.posargs + # For docker tests + if "NOX_POSARGS" in os.environ: + args += shlex.split(os.environ["NOX_POSARGS"]) if "--" not in args: args += ["--", "gcovr", "doc/examples"] session.run("python", *args) @nox.session -def build_wheel(session: "nox.session") -> None: +def build_wheel(session: nox.session) -> None: + """Build a wheel.""" session.install("wheel", "twine") session.run("python", "setup.py", "sdist", "bdist_wheel") session.run("twine", "check", "dist/*", external=True) @nox.session -def upload_wheel(session: "nox.session") -> None: +def upload_wheel(session: nox.session) -> None: + """Upload the wheel.""" session.install("twine") session.run("twine", "upload", "dist/*", external=True) -def docker_container_id(version: str) -> None: - return "gcovr-qa-{}".format(version) +def docker_container_id(version: str) -> str: + """Get the docker container ID.""" + return f"gcovr-qa-{version}-uid_{os.geteuid()}" -@nox.session -def docker_qa_build(session: "nox.session") -> None: - session_id = "docker_qa__build_version({})".format(GCC_VERSION2USE) - session.log("Notify session {}".format(session_id)) +@nox.session(python=False) +def docker_qa_build(session: nox.session) -> None: + """Build the docker container for the default GCC version.""" + session_id = f"docker_qa_build_compiler({GCC_VERSION2USE})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session -def docker_qa_build_all_versions(session: "nox.session") -> None: +@nox.session(python=False) +def docker_qa_build_all_compiler(session: nox.session) -> None: + """Build the docker containers vor all GCC versions.""" for version in GCC_VERSIONS: - session_id = "docker_qa_build_version({})".format(version) - session.log("Notify session {}".format(session_id)) + session_id = f"docker_qa_build_compiler({version})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session +@nox.session(python=False) @nox.parametrize("version", [nox.param(v, id=v) for v in GCC_VERSIONS]) -def docker_qa_build_version(session: "nox.session", version: str) -> None: +def docker_qa_build_compiler(session: nox.session, version: str) -> None: + """Build the docker container for a specific GCC version.""" set_environment(session, version, False) session.run( - "bash", - "-c", - " ".join( - [ - "docker", - "build", - "--tag", - docker_container_id(version), - "--build-arg", - "USERID={}".format(os.geteuid()), - "--build-arg", - "CC=${CC}", - "--build-arg", - "CXX=${CXX}", - "--file", - "admin/Dockerfile.qa", - ".", - ] - ), + "docker", + "build", + "--tag", + docker_container_id(version), + "--build-arg", + f"USERID={os.geteuid()}", + "--build-arg", + f"CC={session.env['CC']}", + "--build-arg", + f"CXX={session.env['CXX']}", + "--file", + "admin/Dockerfile.qa", + ".", external=True, ) -@nox.session -def docker_qa_run(session: "nox.session") -> None: - session_id = "docker_qa_run_version({})".format(GCC_VERSION2USE) - session.log("Notify session {}".format(session_id)) +@nox.session(python=False) +def docker_qa_run(session: nox.session) -> None: + """Run the docker container for the default GCC version.""" + session_id = f"docker_qa_run_compiler({GCC_VERSION2USE})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session -def docker_qa_run_all_versions(session: "nox.session") -> None: +@nox.session(python=False) +def docker_qa_run_all_compiler(session: nox.session) -> None: + """Run the docker container for the all GCC versions.""" for version in GCC_VERSIONS: - session_id = "docker_qa_run_version({})".format(version) - session.log("Notify session {}".format(session_id)) + session_id = f"docker_qa_run_compiler({version})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session +@nox.session(python=False) @nox.parametrize("version", [nox.param(v, id=v) for v in GCC_VERSIONS]) -def docker_qa_run_version(session: "nox.session", version: str) -> None: +def docker_qa_run_compiler(session: nox.session, version: str) -> None: + """Run the docker container for a specific GCC version.""" set_environment(session, version, False) + session.env["NOX_POSARGS"] = " ".join([repr(a) for a in session.posargs]) session.run( - "bash", - "-c", - " ".join( - [ - "docker", - "run", - "--rm", - "-e", - "TESTOPTS", - "-e", - "CC", - "-v", - "{}:/gcovr".format(os.getcwd()), - docker_container_id(version), - ] - ), + "docker", + "run", + "--rm", + "-e", + "CC", + "-e", + "NOX_POSARGS", + "-v", + f"{os.getcwd()}:/gcovr", + docker_container_id(version), external=True, ) -@nox.session -def docker_qa(session: "nox.session") -> None: - session_id = "docker_qa_build_version({})".format(GCC_VERSION2USE) - session.log("Notify session {}".format(session_id)) - session.notify(session_id) - session_id = "docker_qa_run_version({})".format(GCC_VERSION2USE) - session.log("Notify session {}".format(session_id)) +@nox.session(python=False) +def docker_qa(session: nox.session) -> None: + """Build and run the docker container for the default GCC version.""" + session_id = f"docker_qa_compiler({GCC_VERSION2USE})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session -def docker_qa_all_versions(session: "nox.session") -> None: +@nox.session(python=False) +def docker_qa_all_compiler(session: nox.session) -> None: + """Build and run the docker container for the all GCC versions.""" for version in GCC_VERSIONS: - session_id = "docker_qa_build_version({})".format(version) - session.log("Notify session {}".format(session_id)) - session.notify(session_id) - session_id = "docker_qa_run_version({})".format(version) - session.log("Notify session {}".format(session_id)) + session_id = f"docker_qa_compiler({version})" + session.log(f"Notify session {session_id}") session.notify(session_id) -@nox.session +@nox.session(python=False) @nox.parametrize("version", [nox.param(v, id=v) for v in GCC_VERSIONS]) -def docker_qa_version(session: "nox.session", version: str) -> None: - session_id = "docker_qa_build_version({})".format(version) - session.log("Notify session {}".format(session_id)) +def docker_qa_compiler(session: nox.session, version: str) -> None: + """Build and run the docker container for a specific GCC version.""" + session_id = "docker_qa_build_compiler({})".format(version) + session.log(f"Notify session {session_id}") session.notify(session_id) - session_id = "docker_qa_run_version({})".format(version) - session.log("Notify session {}".format(session_id)) + session_id = f"docker_qa_run_compiler({version})" + session.log(f"Notify session {session_id}") session.notify(session_id)