pkgcheck is developed alongside pkgcore and snakeoil. Running pkgcheck from git will often require both pkgcore and snakeoil from git as well.
For releases, see the required runtime dependencies.
There are also several optional runtime dependencies that add or extend check support in various ways if found on the host system including the following:
- git: supports historical queries for git-based repos and commit-related checks
- requests: supports various network-related checks
- Gentoo-PerlMod-Version: supports Perl package version checks
- tree-sitter-bash: used in checks that inspect the CST of ebuilds and eclasess. Must be language version >= 14.
Installing latest pypi release:
pip install pkgcheck
Installing from git:
pip install https://github.com/pkgcore/pkgcheck/archive/master.tar.gz
Installing from a tarball:
python setup.py install
Most users will use pkgcheck on the command line via pkgcheck scan
to
target ebuild repos. See the docs or the man page for more information on
running pkgcheck.
It's also possible to run pkgcheck natively from python. For example, to output the results for a given ebuild repo:
from pkgcheck import scan
for result in scan(['/path/to/ebuild/repo']):
print(result)
This allows third party tools written in python to leverage pkgcheck's scanning functionality for purposes such as CI or VCS commit support.
Normal pytest is used, just execute:
pytest
In addition, a tox config is provided so the testsuite can be run in a virtualenv setup against all supported python versions. To run tests for all environments just execute tox in the root directory of a repo or unpacked tarball. Otherwise, for a specific python version execute something similar to the following:
tox -e py311
Adding a new check consists of 2 main parts: writing the logic and documentation, and adding tests for the check.
- Select the best file for the check under
src/pkgcheck/checks/
. - Create new classes for the results:
- You would need to select the correct result level (style, info, warning, error) - you might want to consult QA team.
- You would need to select the correct context: category, package, version, profile, etc.
- Add long user friendly documentation for the result.
- Implement the
desc
property which is printed to the user.
- Create a new class for the check:
- Add long user friendly documentation for the result.
- Put the source of input for the check. This is hard, so best case is to find similar check and copy the code.
- Define the results it can return.
- Implement the
feed
function.
- Select one of the repos under
testdata/repos
. In most cases you would wantstandalone
. - Add the ebuild/category/test case you want to catch.
cd
into this directory, and runpkgcheck scan --cache-dir /tmp -R JsonStream
. This should yield the results you want to catch (filter out what you expect).- Add the results to the test case under:
testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/expected.json
- If you want to check the fix for the test case,
git add
the files undertestdata/repos/${REPO}
, modify to fix the results, and usinggit diff testdata/repos/${REPO}
collect the diff. - Copy similar patch, add the diff to the patch file, and fix file names, under:
testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/fix.patch