doc/develop/python_cq.rst

   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 Checking for errors
  81 -------------------
  82
  83 If you only want to check for pylint errors, use::
  84
  85    PYTHONPATH=/path/to/scripts/dtc/pylibfdt/ make pylint_err
  86
  87 This will show only pylint errors. Note that you must set PYTHONPATH to point
  88 to the pylibfdt directory build by U-Boot (typically the sandbox_spl board). If
  89 you have used `make qcheck` then it sill be in `board-sandbox_spl`.
  90
  91 .. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/