1.. SPDX-License-Identifier: GPL-2.0+
2
3Python code quality
4===================
5
6U-Boot has about 60k lines of Python code, mainly in the following areas:
7
8- tests
9- pytest hooks
10- patman patch submission tool
11- buildman build / analysis tool
12- dtoc devicetree-to-C tool
13- binman firmware packaging tool
14
15`PEP 8`_ is used for the code style, with the single quote (') used by default for
16strings and double quote for doc strings. All non-trivial functions should be
17commented.
18
19Pylint is used to help check this code and keep a consistent code style. The
20build system tracks the current 'score' of the source code and detects
21regressions in any module.
22
23To run this locally you should use this version of pylint::
24
25    # pylint --version
26    pylint 2.11.1
27    astroid 2.8.6
28    Python 3.8.10 (default, Sep 28 2021, 16:10:42)
29    [GCC 9.3.0]
30
31
32You should be able to select and this install other required tools with::
33
34    pip install pylint==2.11.1
35    pip install -r test/py/requirements.txt
36    pip install asteval pyopenssl
37
38Note that if your distribution is a year or two old, you make need to use `pip3`
39instead.
40
41To configure pylint, make sure it has docparams enabled, e.g. with::
42
43    echo "[MASTER]" >> .pylintrc
44    echo "load-plugins=pylint.extensions.docparams" >> .pylintrc
45
46Once everything is ready, use this to check the code::
47
48    make pylint
49
50This creates a directory called `pylint.out` which contains the pylint output
51for each Python file in U-Boot. It also creates a summary file called
52`pylint.cur` which shows the pylint score for each module::
53
54    _testing 0.83
55    atf_bl31 -6.00
56    atf_fip 0.49
57    binman.cbfs_util 7.70
58    binman.cbfs_util_test 9.19
59    binman.cmdline 7.73
60    binman.control 4.39
61    binman.elf 6.42
62    binman.elf_test 5.41
63    ...
64
65This file is in alphabetical order. The build system compares the score of each
66module to `scripts/pylint.base` (which must also be sorted and have exactly the
67same modules in it) and reports any files where the score has dropped. Use
68pylint to check what is wrong and fix up the code before you send out your
69patches.
70
71New or removed files results in an error which can be resolved by updating the
72`scripts/pylint.base` file to add/remove lines for those files, e.g.::
73
74    meld pylint.cur scripts/pylint.base
75
76If the pylint version is updated in CI, this may result in needing to regenerate
77`scripts/pylint.base`.
78
79
80Checking for errors
81-------------------
82
83If you only want to check for pylint errors, use::
84
85   PYTHONPATH=/path/to/scripts/dtc/pylibfdt/ make pylint_err
86
87This will show only pylint errors. Note that you must set PYTHONPATH to point
88to the pylibfdt directory build by U-Boot (typically the sandbox_spl board). If
89you have used `make qcheck` then it sill be in `board-sandbox_spl`.
90
91.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
92