.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CATKIN_LINT 1" .TH CATKIN_LINT 1 "2021-01-12" "1.6.12" "Robot OS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" catkin_lint \- check catkin packages for common errors .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBcatkin_lint\fR [\fB\-\-config\fR \fI\s-1FILE\s0\fR] [\fB\-\-quiet\fR | \fB\-\-no\-quiet\fR] [\fB\-\-severity\-level\fR \fI\s-1LEVEL\s0\fR] [\fB\-\-notice\fR \fI\s-1ID\s0\fR] [\fB\-\-warning\fR \fI\s-1ID\s0\fR] [\fB\-\-error\fR \fI\s-1ID\s0\fR] [\fB\-\-ignore\fR \fI\s-1ID\s0\fR] [\fB\-\-show\-ignored\fR] [\fB\-\-strict\fR | \fB\-\-no\-strict\fR] [\fB\-\-pkg\fR \fI\s-1PKG\s0\fR] [\fB\-\-skip\-pkg\fR \fI\s-1PKG\s0\fR] [\fB\-\-package\-path\fR \fI\s-1PATH\s0\fR] [\fB\-\-skip\-path\fR \fI\s-1MATCH\s0\fR] [\fB\-\-rosdistro\fR \fI\s-1DISTRO\s0\fR] [\fB\-\-offline\fR] [\fB\-\-no\-offline\fR] [\fB\-\-resolve\-env\fR | \fB\-\-no\-resolve\-env\fR] [\fB\-\-output\fR \fI\s-1FORMAT\s0\fR | \fB\-\-text\fR | \fB\-\-explain\fR | \fB\-\-xml\fR | \fB\-\-json\fR] [\fB\-\-color\fR \fI\s-1MODE\s0\fR] [\fI\s-1PATH\s0\fR [\fI\s-1PATH\s0\fR ...]] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBcatkin_lint\fR checks package configurations for the \fBcatkin\fR build system of \fB\s-1ROS\s0\fR. It runs a static analysis of the \f(CW\*(C`package.xml\*(C'\fR and \f(CW\*(C`CMakeLists.txt\*(C'\fR files in your package, and it will detect and report a number of common problems. .PP All diagnosed problems come in one of three possible severities: .PP \&\fIErrors\fR are severe enough to break the build and/or produce unintended side effects. Usually, they violate the rules outlined in the \fBcatkin\fR manual. .PP \&\fIWarnings\fR are potential errors which may indicate a bug in your package but may be justified for reasons \fBcatkin_lint\fR cannot discern. Constructs which trigger a warning can usually be modified in a way that is functionally equivalent but more robust. .PP \&\fINotices\fR 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 \fBcatkin\fR manual. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-config\fR \fI\s-1FILE\s0\fR" 4 .IX Item "--config FILE" Read configuration settings from \fI\s-1FILE\s0\fR. This option can be used multiple times. See \*(L"\s-1CONFIGURATION FILE FORMAT\*(R"\s0 for details. .IP "\fB\-\-quiet\fR, \fB\-q\fR" 4 .IX Item "--quiet, -q" Suppress all outputs expect for the detected problems, in particular, do not show the summary at the end. .IP "\fB\-\-no\-quiet\fR" 4 .IX Item "--no-quiet" Show a summary of the findings at the end. This is the default setting. .IP "\fB\-\-severity\-level\fR \fI\s-1LEVEL\s0\fR, \fB\-W\fR \fI\s-1LEVEL\s0\fR" 4 .IX Item "--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 \fB\-W1\fR. .IP "\fB\-\-notice\fR \fI\s-1ID\s0\fR, \fB\-\-warning\fR \fI\s-1ID\s0\fR, \fB\-\-error\fR \fI\s-1ID\s0\fR" 4 .IX Item "--notice ID, --warning ID, --error ID" Override the default severity of certain problems. See \*(L"\s-1PROBLEM IDS\*(R"\s0 for details on the available IDs. .IP "\fB\-\-ignore\fR \fI\s-1ID\s0\fR" 4 .IX Item "--ignore ID" Ignore a problem. This is mostly useful to work around a known bug in \fBcatkin_lint\fR, because problems tend to not go away if you ignore them. See \*(L"\s-1PROBLEM IDS\*(R"\s0 for details on the available IDs. .IP "\fB\-\-show\-ignored\fR" 4 .IX Item "--show-ignored" Show all problems you ignored. Use this if an ignored problem did not go away, but you forgot which one. .IP "\fB\-\-strict\fR" 4 .IX Item "--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 \fB\-W2\fR to turn even notices into errors, if you are exceptionally pedantic and/or have a high pain tolerance. .IP "\fB\-\-no\-strict\fR" 4 .IX Item "--no-strict" This will undo the effects of your rash decision to put \f(CW\*(C`strict=yes\*(C'\fR in your configuration file. This is also the default setting. .IP "\fB\-\-pkg\fR \fI\s-1PKG\s0\fR" 4 .IX Item "--pkg PKG" Check the package \fI\s-1PKG\s0\fR for problems. The package must be in the \fB\s-1ROS\s0\fR package search path. .IP "\fB\-\-skip\-pkg\fR \fI\s-1PKG\s0\fR" 4 .IX Item "--skip-pkg PKG" Skip the package \fI\s-1PKG\s0\fR when processing a package subtree. The package will not be linted, but it will be treated as a known package for dependency resolutions. .IP "\fB\-\-package\-path\fR \fI\s-1PATH\s0\fR[:\fI\s-1PATH\s0\fR[...]]" 4 .IX Item "--package-path PATH[:PATH[...]]" Add one or more additional locations to the \fB\s-1ROS\s0\fR package search path. Separate multiple locations with \f(CW\*(C`:\*(C'\fR. \fBcatkin_lint\fR will use this path list and the \fB\s-1ROS_PACKAGE_PATH\s0\fR environment variable to resolve the \fB\-\-pkg\fR option and dependencies of linted packages. .IP "\fB\-\-skip\-path\fR \fI\s-1MATCH\s0\fR" 4 .IX Item "--skip-path MATCH" Skip packages if their location contains \fI\s-1MATCH\s0\fR. No wildcards or pattern matching allowed, only proper substrings are recognized. .IP "\fB\-\-rosdistro\fR \fI\s-1DISTRO\s0\fR" 4 .IX Item "--rosdistro DISTRO" Assume that all packages are supposed to work with the \fB\s-1ROS\s0\fR distribution \fI\s-1DISTRO\s0\fR. By default, this value is taken from the \fB\s-1ROS_DISTRO\s0\fR environment variable. \fBcatkin_lint\fR will use this to query the \fB\s-1ROS\s0\fR database for packages which are not locally installed. .IP "\fB\-\-offline\fR" 4 .IX Item "--offline" Forbid metadata queries to the \fB\s-1ROS\s0\fR 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 \fB\s-1ROS\s0\fR package search path. .IP "\fB\-\-no\-offline\fR" 4 .IX Item "--no-offline" Allow metadata queries to the \fB\s-1ROS\s0\fR package index. This is the default. .IP "\fB\-\-resolve\-env\fR" 4 .IX Item "--resolve-env" Resolve environment variables \fB\f(CB$ENV\fB{}\fR in CMake scripts. By default, \fBcatkin_lint\fR will treat all environment variables like empty strings and issue a warning. .IP "\fB\-\-no\-resolve\-env\fR" 4 .IX Item "--no-resolve-env" Do not resolve environment variables \fB\f(CB$ENV\fB{}\fR in CMake scripts and issue a warning if they are used. This is the default. .IP "\fB\-\-output\fR \fI\s-1FORMAT\s0\fR" 4 .IX Item "--output FORMAT" Select the output format for the diagnosed problems. Valid output formats are \fBtext\fR, \fBexplain\fR, \&\fBjson\fR, and \fBxml\fR. See \*(L"\s-1OUTPUT FORMATS\*(R"\s0 for more details. .IP "\fB\-\-text\fR, \fB\-\-explain\fR, \fB\-\-json\fR, \fB\-\-xml\fR" 4 .IX Item "--text, --explain, --json, --xml" These are deprecated aliases for \fB\-\-output\fR \fI\s-1FORMAT\s0\fR. .IP "\fB\-\-color\fR \fI\s-1MODE\s0\fR" 4 .IX Item "--color MODE" Configure the colorization of the \fBtext\fR and \fBexplain\fR output formats. The default mode is \fBauto\fR, which will use \s-1ANSI\s0 colors if \fBcatkin_lint\fR detects a terminal as output. The modes \fBalways\fR and \&\fBnever\fR will override the detection and output \s-1ANSI\s0 colors always or never, respectively. .SH "OUTPUT FORMATS" .IX Header "OUTPUT FORMATS" \&\fBcatkin_lint\fR supports a variety of output formats as argument for the \fB\-\-output\fR option: .IP "\fBtext\fR" 4 .IX Item "text" This is the default format, which outputs a short, human-readable description of all problems. .IP "\fBexplain\fR" 4 .IX Item "explain" This is an extended \fBtext\fR format, which will show an additional explanation when a problem type occurs for the first time. It will also mention the message \s-1ID\s0 which you need to change the severity or ignore a problem. .IP "\fBjson\fR" 4 .IX Item "json" Outputs all problems in \s-1JSON\s0 format. .IP "\fBxml\fR" 4 .IX Item "xml" Outputs all problems in \s-1XML\s0 format. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" \&\fBcatkin_lint\fR uses \fB\s-1ROS_PACKAGE_PATH\s0\fR to find locally available packages and \fB\s-1ROS_DISTRO\s0\fR to determine the installed \fB\s-1ROS\s0\fR distribution when querying the \fB\s-1ROS\s0\fR package index or the \fBrosdep\fR database. All other environment variables will be ignored, unless \fBcatkin_lint\fR is instructed to resolve them in CMake scripts by \fB\-\-resolve\-env\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" .IP "\fB0\fR" 4 .IX Item "0" All packages were linted successfully and no errors occurred. .IP "\fB1\fR" 4 .IX Item "1" An error occurred. .IP "\fB66\fR" 4 .IX Item "66" No packages found. .SH "CONFIGURATION FILE FORMAT" .IX Header "CONFIGURATION FILE FORMAT" \&\fBcatkin_lint\fR will look for configuration options in the following files: .IP "\(bu" 4 Files explicitly specified using \fB\-\-config\fR .IP "\(bu" 4 \&\fI.catkin_lint\fR files in all locations from \fB\s-1ROS_PACKAGE_PATH\s0\fR .IP "\(bu" 4 \&\fI\f(CI$XDG_CONFIG_HOME\fI/catkin_lint\fR .IP "\(bu" 4 \&\fI~/.config/catkin_lint\fR if \fB\s-1XDG_CONFIG_HOME\s0\fR is unset or empty .IP "\(bu" 4 \&\fI~/.catkin_lint\fR .PP \&\fBcatkin_lint\fR 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. .SS "[catkin_lint] section" .IX Subsection "[catkin_lint] section" The main section is called \f(CW\*(C`[catkin_lint]\*(C'\fR and will take the following \&\fBcatkin_lint\fR specific options: .IP "\fBcolor\fR = \fBauto\fR | \fBnever\fR | \fBalways\fR" 4 .IX Item "color = auto | never | always" Determine output colorization mode. The default setting \fBauto\fR will enable colorization if and only if standard output is connected to terminal. The modes \fBalways\fR and \fBnever\fR will override the detection and output \s-1ANSI\s0 colors always or never, respectively. .IP "\fBoffline\fR = \fBno\fR | \fByes\fR" 4 .IX Item "offline = no | yes" Allow or forbid metadata queries to the \fB\s-1ROS\s0\fR 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 \fB\s-1ROS\s0\fR package search path. The default setting is \fBno\fR. .IP "\fBoutput\fR = \fBtext\fR | \fBexplain\fR | \fBjson\fR | \fBxml\fR" 4 .IX Item "output = text | explain | json | xml" Select the output format for problem reports. See \*(L"\s-1OUTPUT FORMATS\*(R"\s0 for details. The default setting is \fBtext\fR. .IP "\fBpackage_path\fR = \fI\s-1PATH\s0\fR[:\fI\s-1PATH\s0\fR[...]]" 4 .IX Item "package_path = PATH[:PATH[...]]" Prepend the specified \fI\s-1PATH\s0\fRs to \fB\s-1ROS_PACKAGE_PATH\s0\fR in order to find locally available packages and/or package dependencies. .IP "\fBquiet\fR = \fBno\fR | \fByes\fR" 4 .IX Item "quiet = no | yes" Select output verbosity. The default setting \fBno\fR allows \fBcatkin_lint\fR to print some additional information to standard error, such as a final summary of all detected problems. .IP "\fBresolve_env\fR = \fBno\fR | \fByes\fR" 4 .IX Item "resolve_env = no | yes" Allow or forbid resolution of environment variables. The default setting \fBno\fR lets \fBcatkin_lint\fR ignore environment variables and issue a warning whenever a CMake command references the environment using \fB\f(CB$ENV\fB{}\fR. .IP "\fBrosdistro\fR = \fI\s-1DISTRO\s0\fR" 4 .IX Item "rosdistro = DISTRO" Assume that all packages are supposed to work with the \fB\s-1ROS\s0\fR distribution \fI\s-1DISTRO\s0\fR. By default, this value is taken from the \fB\s-1ROS_DISTRO\s0\fR environment variable. \&\fBcatkin_lint\fR will use this to query the \fB\s-1ROS\s0\fR database for packages which are not locally installed. .IP "\fBseverity_level\fR = \fB0\fR | \fB1\fR | \fB2\fR" 4 .IX Item "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 \fB1\fR. .IP "\fBstrict\fR = \fBno\fR | \fByes\fR" 4 .IX Item "strict = no | yes" In strict mode, \fBcatkin_lint\fR will treat every reported problem as error and return with exit code 1 (see \*(L"\s-1RETURN VALUES\*(R"\s0). 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 \fBseverity_level\fR will not be considered failures. .SS "Package-specific severity overrides" .IX Subsection "Package-specific severity overrides" All section names besides \f(CW\*(C`[catkin_lint]\*(C'\fR are interpreted as package names and will override the reported severities of problems. As a special case, the section \f(CW\*(C`[*]\*(C'\fR will apply to all packages. The overrides are specified in the format \f(CW\*(C`ID = Severity\*(C'\fR, where the severity can be one of \&\fBignore\fR, \fBerror\fR, \fBwarning\fR, \fBnotice\fR, or \fBdefault\fR. See \*(L"\s-1PROBLEM IDS\*(R"\s0 for details on the available IDs. .PP Unlike \fB\-\-strict\fR, this gives you very fine-grained control over which problems are supposed to be fatal, so you are encouraged to integrate \fBcatkin_lint\fR into your \s-1CI\s0 test pipeline and tune the settings in a way that fits your project. .SH "PROBLEM IDS" .IX Header "PROBLEM IDS" You can run \fBcatkin_lint \-\-help\-problem\fR to get a list of all problem IDs, and \&\fBcatkin_lint \-\-help\-problem \f(BI\s-1ID\s0\fB\fR for a more detailed explanation of each problem. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Command line arguments" .IX Subsection "Command line arguments" .IP "\fBcatkin_lint ~/catkin_ws/src\fR" 4 .IX Item "catkin_lint ~/catkin_ws/src" Check all packages in \fI~/catkin_ws/src\fR for problems. .IP "\fBcatkin_lint \-\-pkg foo \-\-pkg bar\fR" 4 .IX Item "catkin_lint --pkg foo --pkg bar" Check the packages \f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`bar\*(C'\fR for problems, assuming that they can be found in one of the locations listed in \fB\s-1ROS_PACKAGE_PATH\s0\fR. .IP "\fBcatkin_lint \-\-pkg foo \-\-pkg bar \-\-package\-path ~/my_other_ws/src\fR" 4 .IX Item "catkin_lint --pkg foo --pkg bar --package-path ~/my_other_ws/src" Check the packages \f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`bar\*(C'\fR for problems when the former assumption turned out to be false. .IP "\fBcatkin_lint ~/catkin_ws/src \-\-skip\-path unstable\fR" 4 .IX Item "catkin_lint ~/catkin_ws/src --skip-path unstable" Check all packages in \fI~/catkin_ws/src\fR, but skip all packages in a path that contains the string \f(CW\*(C`unstable\*(C'\fR. .IP "\fBcatkin_lint ~/catkin_ws/src \-\-skip\-pkg baz\fR" 4 .IX Item "catkin_lint ~/catkin_ws/src --skip-pkg baz" Check all packages except \f(CW\*(C`baz\*(C'\fR in \fI~/catkin_ws/src\fR. .SS "Configuration file" .IX Subsection "Configuration file" The following configuration file will instruct \fBcatkin_lint\fR to output its results in \s-1JSON\s0 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): .PP .Vb 3 \& [catkin_lint] \& output = json \& quiet = yes \& \& [*] \& unknown_package = ignore \& unsorted_list = warning \& \& [foo] \& unknown_package = default .Ve .SH "REFERENCES" .IX Header "REFERENCES"