<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE refentry PUBLIC "-//Sun Microsystems//DTD SolBook-XML 3.7//EN" "xsolbook.dtd" [

<!ENTITY % ent SYSTEM "entities.ent">

%ent;

]>

<refentry id="pkglint-1">

<refmeta><refentrytitle>pkglint</refentrytitle><manvolnum>1</manvolnum>

<refmiscinfo class="date">29 Apr 2014</refmiscinfo>

<refmiscinfo class="sectdesc">&man1;</refmiscinfo>

<refmiscinfo class="software">&release;</refmiscinfo>

<refmiscinfo class="arch">generic</refmiscinfo>

<refmiscinfo class="copyright">Copyright (c) 2007, 2016, Oracle and/or its affiliates. All rights reserved.</refmiscinfo>

</refmeta>

<refnamediv>

<refname>pkglint</refname><refpurpose>Image Packaging System package lint</refpurpose>

</refnamediv>

<refsynopsisdiv><title></title>

<synopsis>/usr/bin/pkglint [-c <replaceable>cache_dir</replaceable>] [-r <replaceable>

repo_uri</replaceable>]... [-p <replaceable>regexp</replaceable>]

[-f <replaceable>config_file</replaceable>] [-b <replaceable>build_no</replaceable>] [-v]

[-l <replaceable>lint_uri</replaceable>]... | <replaceable>manifest</replaceable> ...

</synopsis>

<synopsis>/usr/bin/pkglint -L [-v]</synopsis>

</refsynopsisdiv>

<refsect1 role="description"><title></title>

<para><command>pkglint</command> runs a series of checks on one or more package

manifests, optionally referencing another repository.</para>

<para><command>pkglint</command> should be used during the package authoring

process, prior to package publication. <command>pkglint</command> performs

exhaustive testing on the manifests that might be too expensive to perform

during normal operation of <command>pkgsend</command> or <command>pkg.depotd</command>. <command>

pkglint</command> checks include tests for duplicate actions, missing attributes,

and unusual file permissions.</para>

<para>Manifests for linting can be passed as a space-separated list of local

files on the command line, or manifests can be retrieved from a repository.</para>

<para>When retrieving manifests from repositories, on first run <command>pkglint</command> creates

and populates <literal>pkg</literal>(7) user images in the specified cache

directory. If the <option>r</option> option is supplied, a user image named <replaceable>

cache_dir</replaceable><literal>/ref_image</literal> is created for the reference

repository. If the <option>l</option> option is supplied, a user image named <replaceable>

cache_dir</replaceable><literal>/lint_image</literal> is created for the lint

repository. No content is installed in these images. These images are only

used by <command>pkglint</command> to retrieve manifests from the repositories.</para>

<para>Subsequent invocations of <command>pkglint</command> can reuse the cache

directory and can omit any <option>r</option> or <option>l</option> arguments.</para>

<para><command>pkglint</command> provides limited support for configuring

publishers in the cache directory. Use <command>pkg</command> to perform more

complex publisher configuration on these images.</para>

<para><command>pkglint</command> allows package authors to bypass checks for

a given manifest or action. A manifest or action that contains the attribute <literal>

pkg.linted</literal> set to <literal>True</literal> does not produce any lint

output for that manifest or action.</para>

<para>More granular <literal>pkg.linted</literal> settings can be made using

substrings of <command>pkglint</command> check names. For example, <literal>pkg.linted.<replaceable>

check</replaceable>.<replaceable>id</replaceable></literal> set to <literal>True</literal> bypasses

all checks with the name <literal><replaceable>check</replaceable>.<replaceable>id

</replaceable></literal> for the given manifest or action.</para>

<para>The behavior of <command>pkglint</command> can be configured by specifying

a<filename>pkglintrc</filename> file. By default, <command>pkglint</command> searches

in <filename>/usr/share/lib/pkg/pkglintrc</filename> and <filename>$HOME/.pkglintrc

</filename> for configuration options. Use the <option>f</option> option to

specify a different configuration file.</para>

<para>During the lint run, any errors or warnings encountered are printed

to <filename>stderr</filename>.</para>

</refsect1>

<refsect1 role="options"><title></title>

<para>The following options are supported:</para>

<variablelist termlength="wholeline">

<varlistentry><term><option>h</option></term><term><option>-help</option></term>

<listitem><para>Display a usage message.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>b</option> <replaceable>build_no</replaceable></term>

<listitem><para>Specify a build number used to narrow the list of packages

used during linting from lint and reference repositories. If no <option>b</option> option

is specified, the latest versions of packages are used. See also the <literal>version.pattern

</literal> configuration property.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>c</option> <replaceable>cache_dir</replaceable></term>

<listitem><para>Specify a local directory used for caching package metadata

from the lint and reference repositories.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>l</option> <replaceable>lint_uri</replaceable></term>

<listitem><para>Specify a URI representing the location of the lint repository.

Both HTTP and file system based publication are supported. If you specify

<option>l</option>, then you must also specify <option>c</option>. The

<option>l</option> option can be specified multiple times.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>L</option></term>

<listitem><para>List the known and excluded lint checks and then exit. Display

the short name and description of each check. When combined with the <option>v</option> flag,

display the method that implements the check instead of the description.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>f</option> <replaceable>config_file</replaceable></term>

<listitem><para>Configure the <command>pkglint</command> session using the <replaceable>

config_file</replaceable> configuration file.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>p</option> <replaceable>regexp</replaceable></term>

<listitem><para>Specify a regular expression used to narrow the list of packages

to be checked from the lint repository. All manifests from the reference repository

are loaded (assuming they match the value for <option>b</option>, if supplied),

ignoring this pattern.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>r</option> <replaceable>repo_uri</replaceable></term>

<listitem><para>Specify a URI representing the location of the reference repository.

If you specify <option>r</option>, then you must also specify <option>c</option>.

The <option>r</option> option can be specified multiple times.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>v</option></term>

<listitem><para>Run <command>pkglint</command> in a verbose mode, overriding

any <literal>log_level</literal> settings in the configuration file.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="files"><title></title>

<para>The <filename>pkglintrc</filename> configuration file takes the following

key/value arguments:</para>

<variablelist termlength="wholeline">

<varlistentry><term><literal>log_level</literal></term>

<listitem><para>The minimum level at which to emit lint messages. Lint messages

lower than this level are discarded. The default value is <literal>INFO</literal>.

</para>

<para>Log levels in order of least to most severe are <literal>DEBUG</literal>, <literal>

INFO</literal>, <literal>WARNING</literal>, <literal>ERROR</literal>, and <literal>

CRITICAL</literal>.</para>

</listitem>

</varlistentry>

<varlistentry><term><literal>do_pub_checks</literal></term>

<listitem><para>If <literal>True</literal>, perform checks that might only

make sense for published packages. The default value is <literal>True</literal>.</para>

</listitem>

</varlistentry>

<varlistentry><term><literal>pkglint.ext.</literal>*</term>

<listitem><para>The plugin mechanism of <command>pkglint</command> allows

for additional lint modules to be added at runtime. Any key that starts with <literal>

pkglint.ext.</literal> takes a value that must be a fully-specified Python

module. See the &ldquo;Developers&rdquo; section for more information.</para>

</listitem>

</varlistentry>

<varlistentry><term><literal>pkglint.exclude</literal></term>

<listitem><para>A space-separated list of fully specified Python modules,

classes, or function names to omit from the set of checks performed.</para>

</listitem>

</varlistentry>

<varlistentry><term><literal>use_progress_tracker</literal></term>

<listitem><para>If <literal>True</literal>, use a progress tracker when iterating

over manifests during lint runs. The default value is <literal>True</literal>.</para>

</listitem>

</varlistentry>

<varlistentry><term><literal>version.pattern</literal></term>

<listitem><para>A version pattern, used when specifying a build number to

lint against (<option>b</option>). If not specified in the configuration file,

the <option>b</option> option uses the pattern <literal>*,5.11-0.</literal>,

matching all components of the 5.11 build, with a branch prefix of 0.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="other"><title>Developers</title>

<para>To extend the set of checks performed by <command>pkglint</command>,

subclass <literal>pkg.lint.base.Checker</literal> and its subclasses, <literal>ManifestChecker

</literal>, <literal>ActionChecker</literal>, and <literal>ContentChecker</literal>.

Add the Python module name that contains those classes to a new <literal>pkglint.ext.

</literal> key in the configuration file.</para>

<para>Instances of those new subclasses are created by <command>pkglint</command> on

startup. Methods inside each subclass with the special keyword argument <literal>

pkglint_id</literal> are invoked during the course of the lint session. Those

methods should have the same signature as the corresponding <function>check</function> method

in the super class. Methods should also be assigned a <literal>pkglint_desc</literal> attribute,

which is used as the description printed by <command>pkglint -L</command>.</para>

<para>Parameters are available to <literal>Checker</literal> subclasses, allowing

them to tune their behavior. The recommended parameter naming convention is <literal><replaceable>

pkglint_id</replaceable>.<replaceable>name</replaceable></literal>. Parameter

values can be stored in the configuration file, or accessed in manifests or

actions retrieved using the <function>LintEngine.get_param</function> method.

When accessing parameters from the manifest, the prefix <literal>pkg.lint</literal> is

prepended to the key name to ensure that <command>pkglint</command> parameters

do not overlap with any existing action or manifest values.</para>

</refsect1>

<refsect1 role="examples"><title></title>

<example><title>First Run on a Particular Repository</title>

<para>Running a <command>pkglint</command> session for the first time on a

given repository.</para>

<screen>$ <userinput>pkglint -c /space/cache -r http://localhost:10000 mymanifest.mf</userinput></screen>

</example>

<example><title>Subsequent Run on the Same Repository</title>

<para>A subsequent run against the same repository used in Example 1.</para>

<screen>$ <userinput>pkglint -c /space/cache mymanifest-fixed.mf</userinput></screen>

</example>

<example><title>Using a Lint Repository With a Narrowed Manifest Set</title>

<para>Running a <command>pkglint</command> session with a lint repository

and specifying a subset of manifests to check.</para>

<screen>$ <userinput>pkglint -c /space/othercache -l http://localhost:10000 &bsol;</userinput>

<userinput>-p '.*firefox.*'</userinput></screen>

</example>

<example><title>Specifying a Build</title>

<para>Running a <command>pkglint</command> session against a given build in

verbose mode.</para>

<screen>$ <userinput>pkglint -c /space/cache -r http://localhost:10000 &bsol;</userinput>

<userinput>-l http://localhost:12000 -b 147 -v</userinput></screen>

</example>

<example><title>Modifying a Configuration File</title>

<para>A configuration file with a new lint module, excluding some checks.</para>

<screen>$ <userinput>cat ~/.pkglintrc</userinput>

[pkglint]

log_level = DEBUG

# log_level = INFO

pkglint.ext.mycheck = org.timf.mychecks

pkglint.ext.opensolaris = pkg.lint.opensolaris

pkglint.exclude: pkg.lint.opensolaris.OpenSolarisActionChecker

pkg.lint.pkglint.PkgActionChecker.unusual_perms pkg.lint.pkglint.PkgManifestChecker

pkg.lint.opensolaris.OpenSolarisManifestChecker</screen>

</example>

</refsect1>

<refsect1 role="exit-status"><title></title>

<para>The following exit values are returned:</para>

<variablelist>

<varlistentry><term><returnvalue>0</returnvalue></term>

<listitem><para>Command succeeded.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>1</returnvalue></term>

<listitem><para>One or more package manifests contain lint errors.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>2</returnvalue></term>

<listitem><para>An error occurred that is not a lint error in a manifest. For example, an invalid command line option might have been specified.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>99</returnvalue></term>

<listitem><para>An unanticipated exception occurred.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="attributes"><title></title>

<para>See <literal>attributes</literal>(7) for descriptions of the following

attributes:</para>

<informaltable frame="all" orient="port">

<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="col1" colwidth="198*"

align="left"/><colspec colname="col2" colwidth="198*" align="left"/><thead>

<row>

<entry align="center">

<para>ATTRIBUTE TYPE</para>

</entry>

<entry align="center">

<para>ATTRIBUTE VALUE</para>

</entry>

</row>

</thead>

<tbody>

<row>

<entry align="left">

<para>Availability</para>

</entry>

<entry align="left">

<para><literal>package/pkg</literal></para>

</entry>

</row>

<row>

<entry align="left">

<para>Interface Stability</para>

</entry>

<entry align="left">

<para>Uncommitted</para>

</entry>

</row>

</tbody>

</tgroup>

</informaltable></refsect1>

<refsect1 role="see-also"><title></title>

<para><olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg

</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>, <olink

targetdoc="refman" targetptr="pkg.depotd-8"><citerefentry><refentrytitle>pkg.depotd

</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink>, <olink

targetdoc="refman" targetptr="pkgsend-1"><citerefentry><refentrytitle>pkgsend</refentrytitle>

<manvolnum>1</manvolnum></citerefentry></olink>, <olink targetdoc="refman"

targetptr="pkg-7"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>7</manvolnum>

</citerefentry></olink></para>

<para><literal>https://java.net/projects/ips/pages/Home</literal></para>

</refsect1>

</refentry>