PKGLINT(1) User Commands PKGLINT(1)

pkglint — Image Packaging System package lint

pkglint [-c cache_dir] [-r repo_uri]... [-p regexp] [-e extension_path] [-f config_file] [-b build_no] [-v] [-l lint_uri]... manifest...


pkglint -L [-v]

pkglint runs a series of checks on one or more package manifests, optionally referencing another repository.

pkglint should be used during the package authoring process, prior to package publication. pkglint performs exhaustive testing on the manifests that might be too expensive to perform during normal operation of pkgsend(1) or pkg.depotd(8). pkglint checks include tests for duplicate actions, missing attributes, and unusual file permissions.

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.

When retrieving manifests from repositories, on first run pkglint creates and populates pkg(7) user images in the specified cache directory. If the -r option is supplied, a user image named cache_dir is created for the reference repository. If the -l option is supplied, a user image named cache_dir is created for the lint repository. No content is installed in these images. These images are only used by pkglint to retrieve manifests from the repositories.

Subsequent invocations of pkglint can reuse the cache directory and can omit any -r or -l arguments.

pkglint provides limited support for configuring publishers in the cache directory. Use pkg(1) to perform more complex publisher configuration on these images.

pkglint allows package authors to bypass checks for a given manifest or action. A manifest or action that contains the attribute pkg.linted set to True does not produce any lint output for that manifest or action.

More granular pkg.linted settings can be made using substrings of pkglint check names. For example, pkg.linted.. set to True bypasses all checks with the name check.id for the given manifest or action.

The behaviour of pkglint can be configured by specifying a pkglintrc file. By default, pkglint searches in /usr/share/lib/pkg/pkglintrc and $HOME/.pkglintrc for configuration options. Use the -f option to specify a different configuration file.

During the lint run, any errors or warnings encountered are printed to stderr.

The following options are supported:

, --help
Display a usage message.
build_no
Specify a build number used to narrow the list of packages used during linting from lint and reference repositories. If no -b option is specified, the latest versions of packages are used. See also the version.pattern configuration property.
cache_dir
Specify a local directory used for caching package metadata from the lint and reference repositories.
lint_uri
Specify a URI representing the location of the lint repository. Both HTTP and file system based publication are supported. If you specify -l, then you must also specify -c. The -l option can be specified multiple times.
List the known and excluded lint checks and then exit. Display the short name and description of each check. When combined with the -v flag, display the method that implements the check instead of the description.
extension_path
Directory to add to the Python search path when loading pkglint extensions.
config_file
Configure the pkglint session using the config_file configuration file.
regexp
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 -b, if supplied), ignoring this pattern.
repo_uri
Specify a URI representing the location of the reference repository. If you specify -r, then you must also specify -c. The -r option can be specified multiple times.
Run pkglint in a verbose mode, overriding any log_level settings in the configuration file.

The pkglintrc configuration file takes the following key/value arguments:

The minimum level at which to emit lint messages. Lint messages lower than this level are discarded. The default value is INFO.

Log levels in order of least to most severe are , INFO, , , and .

If True, perform checks that might only make sense for published packages. The default value is True.
The plugin mechanism of pkglint allows for additional lint modules to be added at runtime. Any key that starts with pkglint.ext. takes a value that must be a fully-specified Python module. See the Developers section for more information. The extension_path option specifies additional directory locations to search when loading extensions.
A list of directories, separated by ‘:’, to search for extension modules. If the -e flag is specified on the command line, it is added higher in the search order than this configuration file option.
A space-separated list of fully specified Python modules, classes, or function names to omit from the set of checks performed.
If True, use a progress tracker when iterating over manifests during lint runs. The default value is True.
A version pattern, used when specifying a build number to lint against (-b). If not specified in the configuration file, the -b option uses the pattern , matching all components of the 5.11 build, with a branch prefix of 0.

To extend the set of checks performed by pkglint, subclass and its subclasses, and . Add the Python module name that contains those classes to a new pkglint.ext. key in the configuration file.

Instances of those new subclasses are created by pkglint on startup. Methods inside each subclass with the special keyword argument pkglint_id are invoked during the course of the lint session. Those methods should have the same signature as the corresponding method in the super class. Methods should also be assigned a attribute, which is used as the description printed by .

Parameters are available to subclasses, allowing them to tune their behaviour. The recommended parameter naming convention is pkglint_id. name. Parameter values can be stored in the configuration file, or accessed in manifests or actions retrieved using the method. When accessing parameters from the manifest, the prefix is prepended to the key name to ensure that pkglint parameters do not overlap with any existing action or manifest values.

The following exit values are returned:

0
Command succeeded.
1
One or more package manifests contain lint errors.
2
An error occurred that is not a lint error in a manifest. For example, an invalid command line option might have been specified.
99
An unanticipated exception occurred.

Example 1 First Run on a Particular Repository

Running a pkglint session for the first time on a given repository.

pkglint -c /space/cache -r http://localhost:10000 mymanifest.mf

Example 2 Subsequent Run on the Same Repository

A subsequent run against the same repository used in Example 1.

pkglint -c /space/cache mymanifest-fixed.mf

Example 3 Using a Lint Repository With a Narrowed Manifest Set

Running a pkglint session with a lint repository and specifying a subset of manifests to check.

pkglint -c /space/othercache -l http://localhost:10000 \
    -p '.*firefox.*'

Example 4 Specifying a Build

Running a pkglint session against a given build in verbose mode.

pkglint -c /space/cache -r http://localhost:10000 \
    -l http://localhost:12000 -b 147 -v

Example 5 Modifying a Configuration File

A configuration file with a new lint module, excluding some checks.

cat ~/.pkglintrc
  [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

The command line interface of pkglint is . The output of pkglint is and may change at any time.

pkg(1), pkgsend(1), pkg(7), pkg.depotd(8)

February 17, 2022 OmniOS