blob: 78f0ce1523030d0cb2bced5789460409a213780c [file] [log] [blame]
Joey Armstronga9a16b62023-11-01 14:31:15 -04001======================================
2Makefile Lint Targets: Syntax Checking
3======================================
Joey Armstronga8bc8e12022-12-04 07:06:59 -05004
Joey Armstronga9a16b62023-11-01 14:31:15 -04005Targets
6=======
Joey Armstronga8bc8e12022-12-04 07:06:59 -05007
8.. code:: bash
9
10 git clone ssh://gerrit.opencord.org:29418/voltha-helm-charts.git
11 cd voltha-helm-charts
12
13 make help | grep lint
14 lint-chart chart_version_check.sh
Joey Armstrong4de98b72023-02-09 14:51:38 -050015 lint-doc8 Syntax check *.rst documentation files.
Joey Armstronga8bc8e12022-12-04 07:06:59 -050016 lint-helm Syntax check helm configs
17 lint-json Syntax check json sources
18 lint-license Verify sources contain a license block.
Joey Armstronga8bc8e12022-12-04 07:06:59 -050019 lint-robot Syntax check robot sources using rflint
20 lint-shell Syntax check bash,bourne,etc sources
21 lint-yaml Syntax check yaml source using yamllint
22 UNSTABLE= Build targets prone to failure (lint-helm)
23
Joey Armstrong4de98b72023-02-09 14:51:38 -050024 [PYTHON]
Joey Armstronga2fa6582023-04-07 11:03:36 -040025 lint-python Syntax check using available python tools
26 lint-flake8 Syntax check using tool flake8
27 lint-pylint Syntax check using tool pylint
Joey Armstrong4de98b72023-02-09 14:51:38 -050028
Joey Armstronga8bc8e12022-12-04 07:06:59 -050029|
30
31
32All Sources
Joey Armstronga9a16b62023-11-01 14:31:15 -040033===========
Joey Armstronga8bc8e12022-12-04 07:06:59 -050034
35The generic lint target can be used to invoke all defined lint targets.
36
37.. code:: bash
38
39 make clean
40 make lint 2>&1 | tee log
41
42|
43
Joey Armstrongb544dff2022-12-07 15:12:05 -050044
45Makefile help
Joey Armstronga9a16b62023-11-01 14:31:15 -040046=============
Joey Armstrongb544dff2022-12-07 15:12:05 -050047
Joey Armstrongbd6cc3d2023-01-09 19:52:12 -050048Individual Makefiles support a help target that will display a list of
Joey Armstrongb544dff2022-12-07 15:12:05 -050049targets and functionality supported.
50
51.. code:: bash
52
53 make help
Joey Armstronga9a16b62023-11-01 14:31:15 -040054 make help | grep {topic}
55
56.. list-table:: help
57 :widths: 20, 60
58 :header-rows: 1
59
60 * - Make Target
61 - Description
62 * - help
63 - Display available help for targets and flags
64 * - make help | lint-{topic}
65 - Display summary usage for lint-doc8, lint-license, lint-make
66 * - lint-{topic}-help
67 - Display extended help for a topic, supported makefile targets, etc
68
69Legacy Help Usage
70-----------------
71
72.. code:: bash
73
74 make help
Joey Armstrongb544dff2022-12-07 15:12:05 -050075 make help-verbose
76 make help VERBOSE=1
77
78|
79
80
Joey Armstronga9a16b62023-11-01 14:31:15 -040081doc8 / restructuredText (rst)
82=============================
Joey Armstrong4de98b72023-02-09 14:51:38 -050083
84Command: `doc8 <https://pypi.org/project/doc8/>`_
85
Joey Armstronga9a16b62023-11-01 14:31:15 -040086.. list-table:: Makefile Targets
87 :widths: 20, 60
88 :header-rows: 1
89
90 * - Target
91 - Description
92 * - help
93 - Display item ``lint-doc8`` as a summary help topic item.
94 * - lint-doc8-help
95 - Display extended help for ``lint-doc8`` targets
96 * -
97 -
98 * - lint-doc8
99 - Build system lint target used to syntax check restructuredText sources.
100 * - lint-doc8-all
101 - Filesystem traversal, check all ``*.rst`` sources.
102 * - lint-doc8-mod
103 - Syntax check locally modified files (~git status)
104 * - lint-doc8-src
105 - Syntax check a list of files passed in as an argument.
106 * -
107 -
108 * - lint-doc8-install
109 - Dependency driven installation of the doc8 tool.
110
Joey Armstrong4de98b72023-02-09 14:51:38 -0500111.. code:: bash
112
113 make clean
Joey Armstronga9a16b62023-11-01 14:31:15 -0400114 make lint-doc8 2>&1 | tee log
Joey Armstrong4de98b72023-02-09 14:51:38 -0500115
Joey Armstronga9a16b62023-11-01 14:31:15 -0400116 make lint # supported by repositories that define lint-doc8 as a default target.
Joey Armstrong4de98b72023-02-09 14:51:38 -0500117
Joey Armstronga9a16b62023-11-01 14:31:15 -0400118.. list-table:: Sources
119 :widths: 20, 60
120 :header-rows: 1
Joey Armstrong4de98b72023-02-09 14:51:38 -0500121
Joey Armstronga9a16b62023-11-01 14:31:15 -0400122 * - Source
123 - Description
124 * - `makefiles/lint/doc8/include.mk <http://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/doc8/include.mk>`_
125 - Main makefile logic for syntax checking RST sources.
126 * - `makefiles/lint/doc8/install.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/doc8/install.mk>`_
127 - Dependency logic to install the doc8 tool when needed.
128 * - `makefiles/lint/doc8/excl.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/doc8/install.mk>`_
129 - Common doc8 exclusion patterns for all repositories.
130
131See Also
132--------
Joey Armstrong4de98b72023-02-09 14:51:38 -0500133
Joey Armstrong1b8fdc32023-12-20 17:22:57 -0500134- lint-doc8-all target dependency will create a `python virtual env <https://wiki.opencord.org>`_
Joey Armstrong4de98b72023-02-09 14:51:38 -0500135- python 3.10+ requires `virtual env patching <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/patches/>`_ (dynamic, applied when needed).
Joey Armstrong644fb652023-10-02 13:12:20 -0400136- `makefiles/patches/include.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles-orig/patches/>`__
Joey Armstrong4de98b72023-02-09 14:51:38 -0500137
138|
139
140
141python: flake8
Joey Armstronga9a16b62023-11-01 14:31:15 -0400142==============
Joey Armstrong4de98b72023-02-09 14:51:38 -0500143
144Command: `flake8 <https://flake8.pycqa.org/en/latest>`_
145
146.. code:: bash
147
148 make clean
149 make lint 2>&1 | tee log
150 make lint-flake8-all 2>&1 | tee log
151 make lint-flake8-modified 2>&1 | tee log
152
153Sources:
154
Joey Armstrong644fb652023-10-02 13:12:20 -0400155- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
Joey Armstrong4de98b72023-02-09 14:51:38 -0500156- makefiles/lint/flake8.mk
157
158Notes:
159
Joey Armstrong1b8fdc32023-12-20 17:22:57 -0500160- lint-flake8-all target dependency will create a `python virtual env <https://wiki.opencord.org>`_
Joey Armstrong4de98b72023-02-09 14:51:38 -0500161- python 3.10+ requires `virtual env patching <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/patches/>`_ (dynamic, applied when needed).
Joey Armstrong644fb652023-10-02 13:12:20 -0400162- `makefiles/patches/include.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles-orig/patches/>`__
Joey Armstrong4de98b72023-02-09 14:51:38 -0500163
164|
165
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500166Helm Charts
Joey Armstronga9a16b62023-11-01 14:31:15 -0400167===========
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500168
169Command(s):
170- `helmlint.sh <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools/+/refs/heads/master/helmlint.sh>`_
171
172.. code:: bash
173
174 make clean
175 make lint-chart lint-helm 2>&1 | tee log
176
177Sources:
178
179- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master/makefiles/lint/>`__
Joey Armstrong2a687952023-02-01 13:10:12 -0500180- `makefiles/lint/helm/include.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master/makefiles/lint/helm/include.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500181- [`master <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools/+/refs/heads/master>`__] `helm-repo-tools <https://gerrit.opencord.org/plugins/gitiles/helm-repo-tools>`_
182
183|
184
185
186Golang
Joey Armstronga9a16b62023-11-01 14:31:15 -0400187======
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500188
189Command:
190
191Sources:
192
Joey Armstrong644fb652023-10-02 13:12:20 -0400193- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500194
195|
196
Joey Armstrongb544dff2022-12-07 15:12:05 -0500197
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500198JSON
Joey Armstronga9a16b62023-11-01 14:31:15 -0400199====
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500200
Joey Armstrong4de98b72023-02-09 14:51:38 -0500201Command: `json.tool <https://docs.python.org/3/library/json.html>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500202
203.. code:: bash
204
205 make clean
Joey Armstrong4de98b72023-02-09 14:51:38 -0500206 make lint 2>&1 | tee log
207 make lint-json-all 2>&1 | tee log
208 make lint-json-modified 2>&1 | tee log
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500209
210Sources:
211
Joey Armstrong644fb652023-10-02 13:12:20 -0400212- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
213- `makefiles/lint/json.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/json.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500214
215|
216
217
218License / Copyright notice
Joey Armstronga9a16b62023-11-01 14:31:15 -0400219==========================
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500220
221Command:
222
223.. code:: bash
224
225 make clean
226 make lint-license 2>&1 | tee log
227
228Sources:
229
230- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint>`__
Joey Armstrong8b426fc2023-11-14 16:09:11 -0500231- `makefiles/lint/license.mk <http://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/makefiles/lint/license/include.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500232
233|
234
235
Joey Armstrong4de98b72023-02-09 14:51:38 -0500236python: pylint
Joey Armstronga9a16b62023-11-01 14:31:15 -0400237==============
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500238
Joey Armstrong8b426fc2023-11-14 16:09:11 -0500239Command: `pylint <http://github.com/pylint-dev/pylint>`_, `pypi.org <https://pypi.org/project/pylint/>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500240
241.. code:: bash
242
243 make clean
Joey Armstrong4de98b72023-02-09 14:51:38 -0500244 make lint 2>&1 | tee log
245 make lint-pylint-all 2>&1 | tee log
246 make lint-pylint-modified 2>&1 | tee log
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500247
248Sources:
249
Joey Armstrong644fb652023-10-02 13:12:20 -0400250- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
Joey Armstrong4de98b72023-02-09 14:51:38 -0500251- makefiles/lint/pylint.mk
Joey Armstrong644fb652023-10-02 13:12:20 -0400252- `makefiles/patches/include.mk <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/makefiles-orig/patches/>`__
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500253
254Notes:
255
Joey Armstrongbd6cc3d2023-01-09 19:52:12 -0500256- pylint the --py3k option is no longer supported by v3.10+
Joey Armstrong1b8fdc32023-12-20 17:22:57 -0500257- lint-pylint-all target dependency will create a `python virtual env <https://wiki.opencord.org>`_
Joey Armstrongbd6cc3d2023-01-09 19:52:12 -0500258- python 3.10+ requires `virtual env patching <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master/patches/>`_ (dynamic, applied when needed).
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500259
260|
261
262
263Robot
Joey Armstronga9a16b62023-11-01 14:31:15 -0400264=====
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500265
Joey Armstrong4de98b72023-02-09 14:51:38 -0500266Command: rflint `robotframework-lint <https://pypi.org/project/robotframework-lint/>`_
267
268.. code:: bash
269
270 make clean
271 make lint 2>&1 | tee log
272 make lint-robot-all 2>&1 | tee log
273 make lint-robot-modified 2>&1 | tee log
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500274
275Sources:
276
Joey Armstrong644fb652023-10-02 13:12:20 -0400277- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
278- `makefiles/lint/robot.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/robot.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500279
280|
281
282
Joey Armstronga9a16b62023-11-01 14:31:15 -0400283Shell / Command Line Scripts
284============================
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500285
286Command: `shellcheck <https://github.com/koalaman/shellcheck>`_
287
Joey Armstrong4de98b72023-02-09 14:51:38 -0500288.. code:: bash
289
290 make clean
291 make lint 2>&1 | tee log
292 make lint-shell-all 2>&1 | tee log
293 make lint-shell-modified 2>&1 | tee log
294
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500295Sources:
296
Joey Armstrong644fb652023-10-02 13:12:20 -0400297- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
Joey Armstrong8b426fc2023-11-14 16:09:11 -0500298- `makefiles/lint/shell.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/shell/include.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500299
300|
301
302
303Yaml
Joey Armstronga9a16b62023-11-01 14:31:15 -0400304====
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500305
Joey Armstrong4de98b72023-02-09 14:51:38 -0500306Command: `yamllint <https://yamllint.readthedocs.io/en/stable/>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500307
308.. code:: bash
309
310 make clean
Joey Armstrong4de98b72023-02-09 14:51:38 -0500311 make lint 2>&1 | tee log
312 make lint-yaml-all 2>&1 | tee log
313 make lint--modified 2>&1 | tee log
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500314
315Sources:
316
Joey Armstrong644fb652023-10-02 13:12:20 -0400317- `makefiles/lint <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/>`__
318- `makefiles/lint/yaml.mk <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/lint/yaml.mk>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500319
320|
321
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500322
323Bugs
Joey Armstronga9a16b62023-11-01 14:31:15 -0400324====
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500325
326- `jira::VOLTHA <https://jira.opencord.org/projects/VOL>`-
327- Include repository URL
328- Include gerrit/github changeset if available.
329- A logfile snippet of the error and surrounding context.
330
Joey Armstrongb544dff2022-12-07 15:12:05 -0500331|
332
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500333
334Repositories
Joey Armstronga9a16b62023-11-01 14:31:15 -0400335============
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500336
337- [`master <https://gerrit.opencord.org/plugins/gitiles/bbsim/+/refs/heads/master>`__] `bbsim <https://gerrit.opencord.org/plugins/gitiles/bbsim>`_
338- [`master <https://gerrit.opencord.org/plugins/gitiles/pod-configs/+/refs/heads/master>`__] `pod-configs <https://gerrit.opencord.org/plugins/gitiles/pod-configs>`_
339- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master>`__] `voltha-docs <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
340- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts/+/refs/heads/master>`__] `voltha-helm-charts <https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts>`_
Joey Armstrong4de98b72023-02-09 14:51:38 -0500341- [`master <https://gerrit.opencord.org/plugins/gitiles/voltha-docs/+/refs/heads/master>`__] `voltha-docs <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500342
Joey Armstrongb544dff2022-12-07 15:12:05 -0500343|
344
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500345
346Notes
Joey Armstronga9a16b62023-11-01 14:31:15 -0400347=====
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500348
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500349- Volume problem reports require cleanup before linting can become a default.
Joey Armstrong4de98b72023-02-09 14:51:38 -0500350
351 - After bulk linting problems for a language source have been cleaned up
352 default linting can be enabled by modifing {project-root}/config.mk.
353
Joey Armstronga8bc8e12022-12-04 07:06:59 -0500354- Lint target support is globally available across repositories, given time
355 it will be. Submit patches as needed or open a jira ticket to request
356 linting support in specific repositories.
357- Makefile refactoring: yes absolutely! Baby steps are needed in the interim...
Joey Armstrongb544dff2022-12-07 15:12:05 -0500358
359|