Linting » History » Version 12
osmith, 01/19/2023 08:12 AM
add section: Interpreting multi-line comments as code
1 | 1 | osmith | h1. Linting |
---|---|---|---|
2 | |||
3 | Patches submitted to [[Gerrit]] are automatically linted to ensure patches follow our [[coding standards]] and to catch common spelling errors. Jenkins runs @checkpatch.pl@ from the Linux kernel (with an Osmocom specific configuration) against the diff of the current patch. |
||
4 | |||
5 | 2 | osmith | h2. Run locally |
6 | 1 | osmith | |
7 | 2 | osmith | Go to the directory above your Osmocom sources, then run the following: |
8 | |||
9 | <pre> |
||
10 | 9 | laforge | $ git clone https://gitea.osmocom.org/osmocom/osmo-ci |
11 | 11 | osmith | $ cd libosmocore |
12 | 2 | osmith | $ ../osmo-ci/lint/lint_diff.sh |
13 | </pre> |
||
14 | |||
15 | h2. Pre-commit hook |
||
16 | |||
17 | 1 | osmith | The linting script is very fast, it makes sense to configure it locally as pre-commit hook. Then it will run whenever attempting to @git commit@. |
18 | |||
19 | 3 | osmith | After cloning osmo-ci.git (see above), go to the directory above your Osmocom sources again and run the following. Replace libosmocore with any checked out Osmocom project. |
20 | 1 | osmith | <pre> |
21 | $ ln -sv $PWD/osmo-ci/lint/lint_diff.sh libosmocore/.git/hooks/pre-commit |
||
22 | </pre> |
||
23 | |||
24 | h2. Osmocom specific configuration |
||
25 | |||
26 | Find the Osmocom specific configuration in @osmo-ci/lint/checkpatch/checkpatch_osmo.sh@. |
||
27 | |||
28 | 6 | osmith | h3. Project specific configuration |
29 | |||
30 | It is possible to have project specific ignores for linter checks, by creating a <code>.checkpatch.conf</code> file inside the top directory of the git repository. In that file, each line is a command-line argument to checkpatch.pl. |
||
31 | |||
32 | 8 | osmith | Examples: |
33 | 1 | osmith | <pre> |
34 | 8 | osmith | --exclude ^src/sbcap/(skel|gen)/.*\.(c|h)$ |
35 | --exclude ^src/sbcap/.*\.asn$ |
||
36 | 6 | osmith | --ignore OPEN_BRACE |
37 | --ignore POINTER_LOCATION |
||
38 | --ignore SPACING |
||
39 | </pre> |
||
40 | |||
41 | 12 | osmith | h2. Notes on linter behavior |
42 | |||
43 | h3. Interpreting multi-line comments as code |
||
44 | |||
45 | If a multi-line comment gets linted as code, then it is probably missing the star at the beginning of each comment line. |
||
46 | |||
47 | <pre> |
||
48 | /* Multi-line |
||
49 | * comment |
||
50 | * example */ |
||
51 | </pre> |
||
52 | |||
53 | 1 | osmith | h2. Testing |
54 | |||
55 | Run @osmo-ci/lint/lint_all.sh@ in a git repository to run the script against all files in that repository and to report the total amount of errors. It is also possible to run only a specific check of @checkpatch.pl@ by passing it as argument. For example: |
||
56 | |||
57 | <pre> |
||
58 | $ cd libosmocore |
||
59 | $ ../osmo-ci/lint/lint_all.sh CODE_INDENT |
||
60 | </pre> |
||
61 | 4 | osmith | |
62 | 7 | osmith | h2. Ignoring lint failures |
63 | 4 | osmith | |
64 | 7 | osmith | If a reported failure from the linter does not make sense, and it is trivial, consider submitting a patch against osmo-ci.git to fix it yourself. Otherwise create an issue and assign it to osmith. |
65 | 4 | osmith | |
66 | The linter job runs separately from the build verification job. If building a patch succeeds, but the linter fails on it, jenkins will leave a comment like the following in the gerrit review: |
||
67 | |||
68 | <pre> |
||
69 | Build Failed |
||
70 | |||
71 | https://jenkins.osmocom.org/jenkins/job/gerrit-osmo-mgw/.../ : SUCCESS |
||
72 | |||
73 | https://jenkins.osmocom.org/jenkins/job/gerrit-osmo-mgw-lint/.../ : FAILURE |
||
74 | </pre> |
||
75 | |||
76 | So from looking at this comment, it's clear that building did succeed any only linting failed. If that is the case and the linter's output isn't helpful, remove the -1 build verification vote from jenkins and add your own +1 build verification. Then it can be merged regardless of the linting errors. |
||
77 | 1 | osmith | |
78 | h2. See also |
||
79 | |||
80 | * #5087 |
||
81 | 6 | osmith | * #5399 |