path: root/sbopkglint.1

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "SBOPKGLINT 1"
.TH SBOPKGLINT 1 "2022-04-04" "0.4" "sbo-maintainer-tools"
.\" 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"
sbopkglint \- check Slackware binary packages for common errrors.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBsbopkglint\fR [\-k] [\-i] [package.t?z ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBsbopkglint\fR installs a Slackware package to a temporary directory, then
examines the contents. It finds lots of common problems that aren't
always noticed by SBo script maintainers or the admins.
.PP
This is for built packages. If you want to lint your build scripts,
use \fBsbolint\fR(1) instead.
.PP
With no package arguments, it looks for a SlackBuild in the current
directory, extracts the \s-1PRINT_PACKAGE_NAME\s0 information, and tries
to find a package in \f(CW$OUTPUT\fR (/tmp by default). If found, it checks
that package. It's up to you to know whether the package needs to be
rebuilt (e.g. if you've edited the SlackBuild since the package was
built).
.PP
With arguments, it checks the given packages. These must be
supported Slackware package files (.tgz, .txz, .tlz, etc). There's no
requirement that these have to be SBo packages, but a couple of the
tests (e.g. the check for \f(CW$PRGNAM\fR.SlackBuild in the doc dir) might not
apply to non-SBo builds.
.PP
Diagnostics will be logged to stdout and stderr. Exit status will
be 0 if all tests passed, non-zero otherwise.
.PP
This script must run as root. If you run it as a normal user, it tries
to re-execute itself via \fBsudo\fR\|(8).
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-k\fR" 4
.IX Item "-k"
Keep the temporary package install directory instead of deleting it on exit.
.IP "\fB\-i\fR" 4
.IX Item "-i"
Disable the \*(L"useless-looking install instructions\*(R" test. This is
intended for SBo admins mass-linting a ton of packages. \s-1INSTALL\s0 in
the doc dir is something that exists in thousands of existing builds,
and it's not a major problem. New builds and updates should be linted
without this option, however.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Show the short built-in help.
.IP "\fB\-\-doc\fR" 4
.IX Item "--doc"
View this documentation using \fBperldoc\fR\|(1), which generally uses your
pager (e.g. \fBless\fR\|(1) or \fBmore\fR\|(1)) to display it.
.IP "\fB\-\-man\fR" 4
.IX Item "--man"
Convert this documentation to a man page, on stdout.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
0 (success) if all tests passed for all packages, non-zero if there
were any test failures (or if installpkg failed for some reason).
.SH "FILES"
.IX Header "FILES"
.IP "\fBsbolint.d/*.t.sh\fR" 4
.IX Item "sbolint.d/*.t.sh"
These are the actual tests. They're installed to
\&\fI\s-1PREFIX\s0\fR/share/sbo\-maintainer\-tools, and they're sourced by
\&\fBsbopkglint\fR at runtime. Each test script begins with (hopefully)
useful comments that go into more detail than the documentation here.
.SH "TESTS"
.IX Header "TESTS"
.SS "basic-sanity"
.IX Subsection "basic-sanity"
.IP "\fB\-\fR" 4
.IX Item "-"
Top-level directories inside the package must be recognized ones,
such as /bin /etc /usr /opt. Packages shouldn't be installing files
in /tmp, /dev, or /home... and they really shouldn't be inventing
new top-level directories.
.IP "\fB\-\fR" 4
.IX Item "-"
The documentation directory must exist and be correctly named, as
/usr/doc/$PRGNAM\-$VERSION. It must contain \f(CW$PRGNAM\fR.SlackBuild, too.
.IP "\fB\-\fR" 4
.IX Item "-"
The directories /usr/local, /usr/share/doc, /usr/share/man, /usr/etc
are not allowed in SBo packages.
.IP "\fB\-\fR" 4
.IX Item "-"
Some directories (e.g. /usr/bin) may not contain subdirectories.
.IP "\fB\-\fR" 4
.IX Item "-"
Some directories (e.g. /usr/share) must *only* contain subdirectories.
.IP "\fB\-\fR" 4
.IX Item "-"
Some directories (e.g. /usr/man, /usr/share/applications) must not
contain files with executable permissions. /usr/doc is not in this
list; neither is /etc (too many existing packages install +x files
there).
.IP "\fB\-\fR" 4
.IX Item "-"
Broken symlinks may not exist.
.IP "\fB\-\fR" 4
.IX Item "-"
Absolute symlinks may not exist (they should be converted to
relative symlinks). This may seem like nitpicking, but packages
may be installed somewhere besides / (the root dir) with the
\&\-root option to installpkg. If /usr/bin/foo is a link to /usr/bin/bar,
it should be a link to just bar.
.SS "docs"
.IX Subsection "docs"
.IP "\fB\-\fR" 4
.IX Item "-"
Documentation must be installed to /usr/doc/$PRGNAM\-$VERSION. If
there's any other directory under /usr/doc, it's incorrect. Some
builds use mis-named doc directories (if it hasn't been fixed by
now, an example is gcc5, which installs docs to /usr/doc/gcc\-$VERSION
when it should be gcc5\-$VERSION).
.IP "\fB\-\fR" 4
.IX Item "-"
Documentation files must be readable by everyone, and owned by root:root.
.IP "\fB\-\fR" 4
.IX Item "-"
Doc dir shouldn't contain empty files (0 bytes in length).
.IP "\fB\-\fR" 4
.IX Item "-"
Doc dir shouldn't contain install instructions. Specifically, files
named \s-1INSTALL, INSTALL\s0.*, or install.txt are flagged (it's impossible
to make this test 100% perfect).
.SS "noarch"
.IX Subsection "noarch"
.IP "\fB\-\fR" 4
.IX Item "-"
If a package has its architecture set to \*(L"noarch\*(R", it must not contain
any \s-1ELF\s0 binaries/libraries.
.SS "arch"
.IX Subsection "arch"
.IP "\fB\-\fR" 4
.IX Item "-"
If a package has its architecture set to i?86 or x86_64, all \s-1ELF\s0
binaries/libraries must be for the correct arch (no 32\-bit code in
64\-bit packages, and vice versa).
.IP "\fB\-\fR" 4
.IX Item "-"
If a package is i?86, it must not contain /usr/lib64.
.IP "\fB\-\fR" 4
.IX Item "-"
If a package is x86_64 and contains shared libraries, they must be
in /lib64 or /usr/lib64 (not /lib or /usr/lib).
.SS "lafiles"
.IX Subsection "lafiles"
.IP "\fB\-\fR" 4
.IX Item "-"
Packages are no longer allowed to contain libtool archive files (.la)
in /lib, /lib64, /usr/lib, or /usr/lib64. However, subdirectories
such as /usr/lib64/someprogram/ are not checked, since some applications
which use plugins actually use the .la files.
.SS "manpages"
.IX Subsection "manpages"
.IP "\fB\-\fR" 4
.IX Item "-"
All man pages must be readable by everyone, and owned by root:root.
.IP "\fB\-\fR" 4
.IX Item "-"
All man pages must be gzipped.
.IP "\fB\-\fR" 4
.IX Item "-"
All man pages must be in /usr/man/man[1\-9n] or /usr/man/<lang>/man[1\-9n].
.IP "\fB\-\fR" 4
.IX Item "-"
Man page directories must be mode 755, owned by root:root.
.IP "\fB\-\fR" 4
.IX Item "-"
The section numbers in man page filenames must match the section number
in the directory name (e.g. /usr/man/man1/ls.1.gz is \s-1OK,\s0
/usr/man/man1/tetris.6.gz is an error).
.IP "\fB\-\fR" 4
.IX Item "-"
Man pages must actually be man pages (troff markup).
.SS "desktop"
.IX Subsection "desktop"
.IP "\fB\-\fR" 4
.IX Item "-"
If there are .desktop files, doinst.sh must run update-desktop-database.
.IP "\fB\-\fR" 4
.IX Item "-"
\&.desktop files must be mode 644, owned by root:root. Slackware's \s-1KDE\s0
packages actually break this rule (they install executable .desktop
files), but SBo packages are not allowed to.
.IP "\fB\-\fR" 4
.IX Item "-"
Only .desktop files are allowed in /usr/share/applications.
.IP "\fB\-\fR" 4
.IX Item "-"
\&.desktop files must be valid, according to the desktop-file-validate
command. Only actual errors count; warnings don't cause this test to
fail.
.SS "newconfig"
.IX Subsection "newconfig"
.IP "\fB\-\fR" 4
.IX Item "-"
Any files (outside of /usr/doc) with names ending in .new are flagged.
This might be a bit too restrictive (possibly only check /etc and
/usr/share?)
.SS "doinst"
.IX Subsection "doinst"
.IP "\fB\-\fR" 4
.IX Item "-"
If there are icons in /usr/share/icons, .desktop files in /usr/share/applications,
or glib2 schemas in /usr/share/glib\-2.0/schemas, there must be a doinst.sh
with appropriate command(s), e.g. update-desktop-database, gtk-update-icon-cache,
glib-compile-schemas.
.SH "BUGS"
.IX Header "BUGS"
Probably many. This is still a work in progress.
.PP
One known problem is that the same file can fail multiple tests. E.g.
if you have a man page that's installed executable, it will fail both
the basic-sanity test and the manpages test. This isn't really a huge
problem, so it might not be fixed any time soon.
.SH "AUTHOR"
.IX Header "AUTHOR"
B. Watson <urchlay@slackware.uk>, \s-1AKA\s0 Urchlay on Libera \s-1IRC.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBsbolint\fR(1)