diff options
Diffstat (limited to 'support/pkgcheck/docs/pkgcheck.tex')
| -rw-r--r-- | support/pkgcheck/docs/pkgcheck.tex | 181 |
1 files changed, 127 insertions, 54 deletions
diff --git a/support/pkgcheck/docs/pkgcheck.tex b/support/pkgcheck/docs/pkgcheck.tex index ab96cc390a..a41a7db1ad 100644 --- a/support/pkgcheck/docs/pkgcheck.tex +++ b/support/pkgcheck/docs/pkgcheck.tex @@ -42,7 +42,7 @@ % \pdfinfo{ % /Author (Manfred Lotz) % /Title pkgcheck Utility -% } +% } %\title{pkgcheck utility} \include{title} @@ -59,6 +59,8 @@ \end{abstract} +\newpage + \section{Introduction} Uploaded packages to CTAN must satisfy various requirements in order to get @@ -67,7 +69,7 @@ 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. +\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. @@ -89,22 +91,14 @@ information for a certain error. 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. +Currently, the only external program required is \verb|/usr/bin/pdfinfo|. It is +used when a PDF document will be checked. -\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 +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} @@ -116,32 +110,109 @@ Running \verb|pkgcheck --help| shows the available command line options. Here a sample output: +{\small + \begin{verbatim} -pkgcheck 1.0.0 +pkgcheck 3.0.0 Manfred Lotz <manfred@ctan.org> -A checker for uploaded packages to CTAN. +Command-line tool to check packages uploaded 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? + pkgcheck [OPTIONS] OPTIONS: - -e, --explain <explain> Explain error or warning message - -d, --package-dir <pkg_dir> Package directory - -T, --tds-zip <tds_zip> tds zip archive - + -C, --correct-perms Correct permissions + --config-file <CONFIG_FILE> Specify config file to use + -d, --package-dir <PKG_DIR> Package directory + -e, --explain <EXPLAIN> Explain error or warning message + --explain-all Explains all error or warning messages + --generate-completion <GENERATOR> [possible values: bash, elvish, fish, + powershell, zsh] + -h, --help Print help information + -I, --ignore-dupes Ignore dupes + --ignore-same-named Ignore same-named files + -L, --correct-le Correct line endings + --no-colors Don't display messages in color + --show-temp-endings Show file endings for temporary files + -T, --tds-zip <TDS_ZIP> tds zip archive + --urlcheck Check URLs found in README files + -v, --verbose Verbose operation? + -V, --version Print version information \end{verbatim} +} + +\subsection{Config file} + +It is now possible to have a config file for \pkgcheck which then is a YAML +file. A config file can be +specified by using the command line option \verb|--config-file|. If no config +file is specified during invocation of \pkgcheck then \pkgcheck checks two +locations for existence of a config file. + +\begin{itemize} + \item \verb|~/.ctan/pkgcheck.yml| + \item \verb|.config/ctan/pkgcheck.yml| +\end{itemize} + +Currently, the config file may contain only TDS path exceptions. For more +details see message +\hyperlink{i0009----updating-entry-pkgname---tpkg-with-pkgname---new-tpkg-from-config-file}{I0009x}. + + +\subsection{Generate shell completions} + +\pkgcheck offers an option to generate shell completions for various shells, +most notably \texttt{bash}, \texttt{zsh }and \texttt{fish}. + + + +\subsubsection{bash completion} + +In \texttt{bash} one recommendation is to put completions directly into +the \verb|~/.bash_completion| file. + +Example: + +\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh} +pkgcheck -generate-completion bash >> ~/.bash-completion +\end{minted} + +\subsubsection{zsh completion} + +\texttt{zsh} doesn't recommend a specific location for completions. One +possibility is the following: + + + +\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh} +# Prepare +mkdir -p ~/.zfunc/completions +pkgcheck -generate-completion zsh >> ~/.zfunc/completions/_pkgcheck +\end{minted} + +Put the following into \verb|~/.zshrc| + +\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh} +fpath+=~/.zfunc/completions +autoload -Uz compinit +zstyle ':completion:*' menu select +compinit +\end{minted} + +\subsubsection{fish completion} + +\texttt{fish} is pretty straight forward as it offers the \texttt{~/.config/fish/completions/} +directory for completions. + + +Run + +\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh} +pkgcheck -generate-completion fish > ~/.config/fish/completions/pkgcheck.fish +\end{minted} + + + \subsection{Check a package} @@ -151,7 +222,7 @@ 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|. +option \verb|--package-dir| or shorter \verb|-d|. \begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh} @@ -161,19 +232,19 @@ option verb|--package-dir| or shorter \verb|-d|. \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 +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. - +\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} @@ -230,7 +301,7 @@ file from CRLF to LF line endings. \item \verb|-V| Outputs \pkgcheck's version number. - + \item \verb|--help| \verb|--help| shows the available command line options. @@ -262,7 +333,7 @@ OPTIONS: \end{verbatim} -\item \verb|--explain <explain| +\item \verb|--explain <explain| This option explains an error message in more detail. @@ -273,7 +344,7 @@ OPTIONS: \end{minted} -\item \verb|--explain-all| +\item \verb|--explain-all| Outputs a list of explanations of all messages. @@ -293,7 +364,7 @@ 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 +a file type. This could lead to a subsequent mistake when complaining about an x-bit, or complaining about CRF line ending. @@ -306,7 +377,7 @@ x-bit, or complaining about CRF line ending. 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 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} @@ -314,7 +385,7 @@ From an installation point of view the files and directories of a package 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} @@ -335,29 +406,31 @@ are accepted. \begin{description} \item[Innnn] Informational messages - These are message which announce \pkgcheck actions. - + These are message which usually 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. - + Fatal messages are related to environmental issues and not related to + packages. They are usually unrecoverable errors, and \pkgcheck's only + option is to terminate. Fatal messages are written to standard error. + + If for example, the package directory specified at + the command line doesn't exist then the only option is to issue + a message and 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} - - -\end{description} \section{Informational messages} \input{informationd} |