summaryrefslogtreecommitdiff
path: root/support/pkgcheck/docs/pkgcheck.tex
blob: ab96cc390a18ad7637819d60241889b99d7306a5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
\listfiles
\documentclass[fontsize=10pt,paper=a4,abstract=on]{scrartcl}

\DeclareTOCStyleEntry[dynnumwidth=true]{default}{subsection}

\usepackage{unicode-math}

\usepackage[RM={StylisticSet=3}]{plex-otf}

\usepackage[english]{babel}
\usepackage[autostyle]{csquotes}

\usepackage{array,multido}
\usepackage{booktabs} % for examples
%\usepackage{xltabular} % for examples
\usepackage{listings}
\lstset{columns=fixed,basicstyle=\ttfamily\small}
\usepackage[table]{xcolor}
\usepackage{xspace}

\usepackage{longtable}

\usepackage{minted}
\usemintedstyle{emacs}

\pagestyle{headings}

\usepackage[colorlinks, pdfusetitle, hyperfootnotes=false]{hyperref}
% define \code for url-like breaking of typewriter fragments.
\ifx\nolinkurl\undefined \let\code\url \else \let\code\nolinkurl \fi

% Define \cs to prepend a backslash, and be unbreakable:
\DeclareRobustCommand\cs[1]{\mbox{\texttt{\char`\\#1}}}


\newcommand{\pkgcheck}{\texttt{pkgcheck}\xspace}
\newcommand{\msg}[1]{\texttt{#1}\xspace}

\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

%  \pdfinfo{
%    /Author (Manfred Lotz)
%    /Title  pkgcheck Utility
% } 

%\title{pkgcheck utility}
\include{title}
\author{Manfred Lotz}


\begin{document}
\maketitle
\tableofcontents

\begin{abstract}
  This document describes the \pkgcheck command line utility which is used by the
  author when checking uploaded packages to CTAN.
\end{abstract}


\section{Introduction}

Uploaded packages to CTAN must satisfy various requirements in order to get
installed on CTAN.

A first introduction is given here \url{https://ctan.org/help/upload-pkg}.

Even more details are to be found in the excellent CTAN-upload addendum
\url{https://ctan.org/file/help/ctan/CTAN-upload-addendum} written by Petra Rübe-Pugliese. 

The \pkgcheck utility which runs on Linux systems only checks those requirements
which can be checked by a program.

\section{pkgcheck utility}

The \pkgcheck utility is a compiled program written in the Rust programming
language. It runs in a Linux environment. Currently, Windows is not supported.
Simply, because the author doesn't use Windows at all.

It will be invoked from the command line, and any error or
warning message has a certain message id. \pkgcheck offers an option to get more
information for a certain error.

\section{Requirements}

\pkgcheck doesn't have any special runtime requirements.

The \pkgcheck is a 64-bit statically linked binary, and should work an any 64-bit Linux.
It is available in the repository in directory \verb|bin/|.

Currently, the only external programs required are:
\begin{itemize}
\item \verb|/usr/bin/unzip|

Used only, when a TDS zip archive will be extracted.

\item \verb|/usr/bin/pdfinfo|

Used only, when a PDF document will be checked. 
  
\end{itemize}

\section{Installation}

Copy the binary from \verb|bin/pkgcheck| to a suitable location on your hard disk, and 
(recommended) make sure the directory is in the \verb|PATH| or call \verb|pkgcheck| using an 
absolute path name.

\section{Utility usage}


\subsection{Help option}

Running \verb|pkgcheck --help| shows the available command line options.

Here a sample output:

\begin{verbatim}
pkgcheck 1.0.0
Manfred Lotz <manfred@ctan.org>
A checker for uploaded packages to CTAN.

USAGE:
    pkgcheck [FLAGS] [OPTIONS]

FLAGS:
    -L, --correct-crlf         Correct CRLF line endings
    -C, --correct-perms        Correct permissions
        --explain-all          Explains all error or warning messages
    -h, --help                 Prints help information
    -I, --ignore-dupes         Ignore dupes
        --no-colors            Don't display messages in color
        --show-temp-endings    Show file endings for temporary files
        --urlcheck             Check URLs found in README files
    -V, --version              Prints version information
    -v, --verbose              Verbose operation?

OPTIONS:
    -e, --explain <explain>        Explain error or warning message
    -d, --package-dir <pkg_dir>    Package directory
    -T, --tds-zip <tds_zip>        tds zip archive

\end{verbatim}


\subsection{Check a package}

A package for CTAN is supposed to be uploaded as a ZIP or a g-zipped
tar archive. The package must have a top level directory.

After unpacking the archive of a package \texttt{mypkg} into directory
\texttt{mypkg/} it can be checked by running \pkgcheck with
option verb|--package-dir| or shorter \verb|-d|.


\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
  pkgcheck -d mypkg
\end{minted}

\pkgcheck returns 1 if there are any errors, otherwise 0.


 
\subsection{Check a package which has a TDS archive}

If a package contains a TDS ZIP archive it is supposed to be in the
top level directory of a package.

In order to check the TDS ZIP archive the option 
\verb|-T <tds_zip>| or \verb|--tds-zip <tds_zip>| can be used.

Please note that a TDS ZIP archive will always be checked together with
the non-install tree of the package which means that
\verb|--tds-zip| requires option \verb|--package-dir| as well.  
   
Checking package \texttt{mypkg} \pkgcheck will be invoked like follows:

\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
  pkgcheck -d mypkg -T mypkg.tds.zip
\end{minted}


As before \pkgcheck returns 1 if there are any errors, otherwise 0.


\subsection{Pkgcheck messages}

\pkgcheck issues three kind of messages

\begin{itemize}
\item Information messages
\item Warning messages
\item Error messages
\end{itemize}

Messages have unique ids and the detailed explanation of a message can be either
looked up in this document, or it can be displayed by using command line option
\verb|--explain| or \verb|-e|.


\begin{minted}[linenos=true,label=Example,frame=single,fontsize=\footnotesize]{sh}
  pkgcheck --explain e0012
\end{minted}



\subsection{Duplicate files}

By default, \pkgcheck detects duplicate files in a package. This could be
disabled by using command line switch \verb|--ignore-dups| or shorter \verb|-I|.

\subsection{Permissions}

\pkgcheck offers the option \verb|--correct-crlf| or shorter \verb|-L| to
correct wrong permissions in a package.


\subsection{CRLF line endings}

\pkgcheck detects CRLF line endings in text files as good as it can.
It reads up to 1 MB to check for CRLF line endings.

Option \verb|--correct-crlf| or for short \verb|-L| can be used to convert a
file from CRLF to LF line endings.

\subsection{Help options}

\begin{itemize}
\item \verb|-V|

  Outputs \pkgcheck's version number.
  
\item \verb|--help|

  \verb|--help| shows the available command line options.

\begin{verbatim}
pkgcheck 1.0.0
Manfred Lotz <manfred@ctan.org>
A checker for uploaded packages to CTAN.

USAGE:
    pkgcheck [FLAGS] [OPTIONS]

FLAGS:
    -L, --correct-crlf         Correct CRLF line endings
    -C, --correct-perms        Correct permissions
        --explain-all          Explains all error or warning messages
    -h, --help                 Prints help information
    -I, --ignore-dupes         Ignore dupes
        --no-colors            Don't display messages in color
        --show-temp-endings    Show file endings for temporary files
        --urlcheck             Check URLs found in README files
    -V, --version              Prints version information
    -v, --verbose              Verbose operation?

OPTIONS:
    -e, --explain <explain>        Explain error or warning message
    -d, --package-dir <pkg_dir>    Package directory
    -T, --tds-zip <tds_zip>        tds zip archive

\end{verbatim}

\item  \verb|--explain <explain| 

  This option explains an error message in more detail.

  Example:

\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
  pkgcheck -e e0012
\end{minted}


\item  \verb|--explain-all| 

Outputs a list of explanations of all messages.

\item \verb|--show-temp-endings|

  Outputs a list of all file name endings which \pkgcheck uses to detect
  temporary files.
\end{itemize}

%\subsection{Other options}

\section{About checking file types}

\pkgcheck determines, similar to the UNIX \verb|file| command, the type of file.
This is required before for example checking permissions or complaining that a
text file has CRLF line endings.

It is very important to note that determining file types is not bullet proof.
So, it might happen in some cases that \pkgcheck makes mistakes when determining
a file type. This could lead to a subseqent mistake when complaining about an
x-bit, or complaining about CRF line ending.






\section{About permissions checking}

From an installation point of view the files and directories of a package
\begin{itemize}
\item must be at least world readable
\item must be writable by owner or group 
\item must not have the x-bit on for the owner if the file isn't an executable,
  i.e. a script or binary
\end{itemize}

The reason for this minimal requirement is that the installation utility used by
the CTAN team (which by the way was written by Rainer Schöpf a long time ago)
sets permissions correctly if the owner permission is set correctly.
 
Examples:

\begin{itemize}
\item \verb|README.md| with \texttt{666} is ok because the installation utility converts
  the permission to 664
\item \verb|README.md| with \texttt{660} is wrong because the installation utility
  wouldn't have access to the file
\item \verb|some.pdf| with \texttt{744} would be wrong because a PDF document must not
  have the x-bit on for the owner
\end{itemize}

Because of the smartness of the installation utility \pkgcheck does check
minimal requirements only, i.e some weird looking permissions like the \texttt{666} above
are accepted.

\section{Different kind of messages}

\begin{description}
\item[Innnn] Informational messages

  These are message which announce \pkgcheck actions.
  
\item[Fnnnn] Fatal messages

  Fatal messages report unrecoverable errors. In this case \pkgcheck's only
  option is to terminate. If for example, the package directory specified at
  the command line doesn't exist then the only option is to terminate.
  
\item[Ennnn] Error messages

  Error messages report errors which must be fixed before installing a package.
  
\item[Wnnnn] Warning messages

  Warning messages denote possible errors depending upon the situation.

  For example, for a font package having many duplicate files might be ok. For
  another package it could be regarded as an error.

  

  
\end{description}
\section{Informational messages}
\input{informationd}

\section{Warning messages}
\input{warningsd}

\section{Error messages}
\input{errorsd}

\section{Fatal messages}
\input{fatald}

\end{document}