--- name: "catkin_lint" section: "1" platform: "linux" package: "catkin-lint" version: "1.6.25-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/catkin_lint" --- # catkin\_lint(1) check catkin packages for common errors ## NAME catkin\_lint - check catkin packages for common errors ## SYNOPSIS **catkin\_lint** \[**--config** *FILE*\] \[**--quiet** \| **--no-quiet**\]\ \[**--severity-level** *LEVEL*\]\ \[**--notice** *ID*\] \[**--warning** *ID*\] \[**--error** *ID*\]\ \[**--ignore** *ID*\] \[**--show-ignored**\]\ \[**--strict** \| **--no-strict**\]\ \[**--pkg** *PKG*\] \[**--skip-pkg** *PKG*\]\ \[**--package-path** *PATH*\] \[**--skip-path** *MATCH*\]\ \[**--rosdistro** *DISTRO*\] \[**--offline**\] \[**--no-offline**\]\ \[**--rosdep-cache-path** *PATH*\]\ \[**--resolve-env** \| **--no-resolve-env**\]\ \[**--output** *FORMAT* \| **--text** \| **--explain** \| **--xml** \| **--json**\]\ \[**--color** *MODE*\]\ \[*PATH* \[*PATH* ...\]\] ## DESCRIPTION **catkin\_lint** checks package configurations for the **catkin** build system of **ROS**. It runs a static analysis of the `"package.xml"` and `"CMakeLists.txt"` files in your package, and it will detect and report a number of common problems. All diagnosed problems come in one of three possible severities: *Errors* are severe enough to break the build and/or produce unintended side effects. Usually, they violate the rules outlined in the **catkin** manual. *Warnings* are potential errors which may indicate a bug in your package but may be justified for reasons **catkin\_lint** cannot discern. Constructs which trigger a warning can usually be modified in a way that is functionally equivalent but more robust. *Notices* are issues which are not objectionable from a technical view point but should be addressed to improve the quality of the package. Many notices highlight violations of the recommendations and best practises from the **catkin** manual. ## OPTIONS - **--config** *FILE* Read configuration settings from *FILE*. This option can be used multiple times. See "CONFIGURATION FILE FORMAT" for details. - **--quiet**, **-q** Suppress all outputs expect for the detected problems, in particular, do not show the summary at the end. - **--no-quiet** Show a summary of the findings at the end. This is the default setting. - **--severity-level** *LEVEL*, **-W** *LEVEL* Choose the severity level for diagnostic output. Level 0 displays errors only, level 1 displays errors and warnings, and level 2 displays everything. The default setting is **-W1**. - **--notice** *ID*, **--warning** *ID*, **--error** *ID* Override the default severity of certain problems. See "PROBLEM IDS" for details on the available IDs. - **--ignore** *ID* Ignore a problem. This is mostly useful to work around a known bug in **catkin\_lint**, because problems tend to not go away if you ignore them. See "PROBLEM IDS" for details on the available IDs. - **--show-ignored** Show all problems you ignored. Use this if an ignored problem did not go away, but you forgot which one. - **--strict** Treat any reported problem as a fatal error. Some people use the option to enforce that warnings get fixed, too. You can also combine this with **-W2** to turn even notices into errors, if you are exceptionally pedantic and/or have a high pain tolerance. - **--no-strict** This will undo the effects of your rash decision to put `"strict=yes"` in your configuration file. This is also the default setting. - **--pkg** *PKG* Check the package *PKG* for problems. The package must be in the **ROS** package search path. - **--skip-pkg** *PKG* Skip the package *PKG* when processing a package subtree. The package will not be linted, but it will be treated as a known package for dependency resolutions. - **--package-path** *PATH*\[:*PATH*\[...\]\] Add one or more additional locations to the **ROS** package search path. Separate multiple locations with `":"`. **catkin\_lint** will use this path list and the **ROS\_PACKAGE\_PATH** environment variable to resolve the **--pkg** option and dependencies of linted packages. - **--skip-path** *MATCH* Skip packages if their location contains *MATCH*. No wildcards or pattern matching allowed, only proper substrings are recognized. - **--rosdistro** *DISTRO* Assume that all packages are supposed to work with the **ROS** distribution *DISTRO*. By default, this value is taken from the **ROS\_DISTRO** environment variable. **catkin\_lint** will use this to query the **ROS** database for packages which are not locally installed. - **--offline** Forbid metadata queries to the **ROS** package index. This will disable certain diagnostics which rely on knowing details about all package dependencies. Metadata queries are not needed for packages which can be found locally through the **ROS** package search path. - **--no-offline** Allow metadata queries to the **ROS** package index. This is the default. - **--rosdep-cache-path** *PATH* Override the default location of the rosdep sources cache. This option has the same effect as setting the **ROSDEP\_CACHE\_PATH** environment variable. - **--resolve-env** Resolve environment variables **$ENV{}** in CMake scripts. By default, **catkin\_lint** will treat all environment variables like empty strings and issue a warning. - **--no-resolve-env** Do not resolve environment variables **$ENV{}** in CMake scripts and issue a warning if they are used. This is the default. - **--output** *FORMAT* Select the output format for the diagnosed problems. Valid output formats are **text**, **explain**, **json**, and **xml**. See "OUTPUT FORMATS" for more details. - **--text**, **--explain**, **--json**, **--xml** These are deprecated aliases for **--output** *FORMAT*. - **--color** *MODE* Configure the colorization of the **text** and **explain** output formats. The default mode is **auto**, which will use ANSI colors if **catkin\_lint** detects a terminal as output. The modes **always** and **never** will override the detection and output ANSI colors always or never, respectively. ## OUTPUT FORMATS **catkin\_lint** supports a variety of output formats as argument for the **--output** option: - **text** This is the default format, which outputs a short, human-readable description of all problems. - **explain** This is an extended **text** format, which will show an additional explanation when a problem type occurs for the first time. It will also mention the message ID which you need to change the severity or ignore a problem. - **json** Outputs all problems in JSON format. - **xml** Outputs all problems in XML format. ## ENVIRONMENT **catkin\_lint** uses **ROS\_PACKAGE\_PATH** to find locally available packages and **ROS\_DISTRO** to determine the installed **ROS** distribution when querying the **ROS** package index or the **rosdep** database. All other environment variables will be ignored, unless **catkin\_lint** is instructed to resolve them in CMake scripts by **--resolve-env**. ## RETURN VALUES - **0** All packages were linted successfully and no errors occurred. - **1** An error occurred. - **66** No packages found. ## CONFIGURATION FILE FORMAT **catkin\_lint** will look for configuration options in the following files: - • Files explicitly specified using **--config** - • *.catkin\_lint* files in all locations from **ROS\_PACKAGE\_PATH** - • *$XDG\_CONFIG\_HOME/catkin\_lint* - • *~/.config/catkin\_lint* if **XDG\_CONFIG\_HOME** is unset or empty - • *~/.catkin\_lint* **catkin\_lint** will read all available configuration files and merge them into a single configuration. Earlier entries in the above list will take precedence if conflicting options are found. Command line arguments will override any configuration file setting. Configuration files are in an INI-style format with one or more sections in it. ### \[catkin\_lint\] section The main section is called `"[catkin_lint]"` and will take the following **catkin\_lint** specific options: - **color** = **auto** \| **never** \| **always** Determine output colorization mode. The default setting **auto** will enable colorization if and only if standard output is connected to terminal. The modes **always** and **never** will override the detection and output ANSI colors always or never, respectively. - **offline** = **no** \| **yes** Allow or forbid metadata queries to the **ROS** package index. This will disable certain diagnostics which rely on knowing details about all package dependencies. Metadata queries are not needed for packages which can be found locally through the **ROS** package search path. The default setting is **no**. - **output** = **text** \| **explain** \| **json** \| **xml** Select the output format for problem reports. See "OUTPUT FORMATS" for details. The default setting is **text**. - **package\_path** = *PATH*\[:*PATH*\[...\]\] Prepend the specified *PATH*s to **ROS\_PACKAGE\_PATH** in order to find locally available packages and/or package dependencies. - **quiet** = **no** \| **yes** Select output verbosity. The default setting **no** allows **catkin\_lint** to print some additional information to standard error, such as a final summary of all detected problems. - **resolve\_env** = **no** \| **yes** Allow or forbid resolution of environment variables. The default setting **no** lets **catkin\_lint** ignore environment variables and issue a warning whenever a CMake command references the environment using **$ENV{}**. - **rosdistro** = *DISTRO* Assume that all packages are supposed to work with the **ROS** distribution *DISTRO*. By default, this value is taken from the **ROS\_DISTRO** environment variable. **catkin\_lint** will use this to query the **ROS** database for packages which are not locally installed. - **rosdep\_cache\_path** = *PATH* Override the default location of the rosdep sources cache. This option has the same effect as setting the **ROSDEP\_CACHE\_PATH** environment variable. - **severity\_level** = **0** \| **1** \| **2** Choose the severity level for diagnostic output. Level 0 displays errors only, level 1 displays errors and warnings, and level 2 displays everything. The default setting is **1**. - **strict** = **no** \| **yes** In strict mode, **catkin\_lint** will treat every reported problem as error and return with exit code 1 (see "RETURN VALUES"). By default, warnings and notices are informational only. This setting is mostly interesting for automated test runs, where the exit code is evaluated. Note that ignored problems and everything hidden by the chosen **severity\_level** will not be considered failures. ### Package-specific severity overrides All section names besides `"[catkin_lint]"` are interpreted as package names and will override the reported severities of problems. As a special case, the section `"[*]"` will apply to all packages. The overrides are specified in the format `"ID = Severity"`, where the severity can be one of **ignore**, **error**, **warning**, **notice**, or **default**. See "PROBLEM IDS" for details on the available IDs. Unlike **--strict**, this gives you very fine-grained control over which problems are supposed to be fatal, so you are encouraged to integrate **catkin\_lint** into your CI test pipeline and tune the settings in a way that fits your project. ## PROBLEM IDS You can run **catkin\_lint --help-problem** to get a list of all problem IDs, and **catkin\_lint --help-problem** ***ID*** for a more detailed explanation of each problem. ## EXAMPLES ### Command line arguments - **catkin\_lint ~/catkin\_ws/src** Check all packages in *~/catkin\_ws/src* for problems. - **catkin\_lint --pkg foo --pkg bar** Check the packages `"foo"` and `"bar"` for problems, assuming that they can be found in one of the locations listed in **ROS\_PACKAGE\_PATH**. - **catkin\_lint --pkg foo --pkg bar --package-path ~/my\_other\_ws/src** Check the packages `"foo"` and `"bar"` for problems when the former assumption turned out to be false. - **catkin\_lint ~/catkin\_ws/src --skip-path unstable** Check all packages in *~/catkin\_ws/src*, but skip all packages in a path that contains the string `"unstable"`. - **catkin\_lint ~/catkin\_ws/src --skip-pkg baz** Check all packages except `"baz"` in *~/catkin\_ws/src*. ### Configuration file The following configuration file will instruct **catkin\_lint** to output its results in JSON format, ignore any problems with unknown packages (except in the package foo), and elevate the notice about unsorted lists to a warning for all packages (including foo): ``` [catkin_lint] output = json quiet = yes [*] unknown_package = ignore unsorted_list = warning [foo] unknown_package = default ``` ## REFERENCES \