| Simon Glass | feafc61 | 2021-11-21 20:48:40 -0700 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | |
| 3 | Python code quality |
| 4 | =================== |
| 5 | |
| 6 | U-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 |
| 16 | strings and double quote for doc strings. All non-trivial functions should be |
| 17 | commented. |
| 18 | |
| 19 | Pylint is used to help check this code and keep a consistent code style. The |
| 20 | build system tracks the current 'score' of the source code and detects |
| 21 | regressions in any module. |
| 22 | |
| 23 | To 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 | |
| 32 | You 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 | |
| 38 | Note that if your distribution is a year or two old, you make need to use `pip3` |
| 39 | instead. |
| 40 | |
| 41 | To 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 | |
| 46 | Once everything is ready, use this to check the code:: |
| 47 | |
| 48 | make pylint |
| 49 | |
| 50 | This creates a directory called `pylint.out` which contains the pylint output |
| 51 | for 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 | |
| 65 | This file is in alphabetical order. The build system compares the score of each |
| 66 | module to `scripts/pylint.base` (which must also be sorted and have exactly the |
| 67 | same modules in it) and reports any files where the score has dropped. Use |
| 68 | pylint to check what is wrong and fix up the code before you send out your |
| 69 | patches. |
| 70 | |
| 71 | New 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 | |
| 76 | If the pylint version is updated in CI, this may result in needing to regenerate |
| 77 | `scripts/pylint.base`. |
| 78 | |
| 79 | |
| 80 | .. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/ |