-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtexbuildpkg.tex
120 lines (97 loc) · 3.98 KB
/
texbuildpkg.tex
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
% -*- coding: utf-8 -*-
\documentclass[oneside,12pt]{article}
\usepackage[a4paper,margin=2cm]{geometry}
\newcommand*{\myversion}{2025@}
\newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
\setlength{\parindent}{0pt}
\setlength{\parskip}{4pt plus 1pt minus 1pt}
\usepackage{codehigh}
\usepackage{tabularray}
\UseTblrLibrary{booktabs}
\usepackage{hyperref}
\hypersetup{
colorlinks=true,
urlcolor=blue3,
linkcolor=green3,
}
\NewDocumentCommand\mypkg{m}{\textcolor{blue3}{\mbox{\ttfamily#1}}}
\NewDocumentCommand\myopt{m}{\textcolor{brown3}{\mbox{#1}}}
\NewDocumentCommand\mycmd{m}{\textcolor{green3}{\ttfamily\fakeverb{#1}}}
\NewDocumentCommand\myfile{m}{\textcolor{purple3}{\mbox{#1}}}
\NewDocumentCommand\myprg{m}{\textcolor{cyan3}{\mbox{#1}}}
\begin{document}
\title{\sffamily
\textcolor{green3}{The \texttt{TeXBuildPkg} tool}\\
{\large Another testing and building system for TeX}%
}
\author{%
Jianrui Lyu ([email protected])%
%\\\url{https://github.com/lvjr/texbuildpkg}
}
\date{\mydate}
\maketitle
The \mypkg{l3build} system is a useful and powerful tool for regression testing.
With \mypkg{l3build} you normally print the contents of some boxes from \myfile{.lvt} files
to corresponding \myfile{.tlg} files. Sometimes \LaTeX{} kernel or some package your package
depends on adds a whatisit or \mycmd{\kern0pt}, and your test files will fail even if
the PDF files look the same as before and are still correct.
This \mypkg{TeXBuildPkg} tool provides an alternative way for regression testing:
Instead of printing box contents in \myfile{.lvt} files, you could just convert PDF files
to PNG files and compare PNG files after \mypkg{l3build} finishes its job.
\section{Installation}
Normally your TeX distribution will copy \mypkg{TeXBuildPkg} files and
create a binary file \myfile{texbuildpkg} when you install this package.
If a manual installation is needed, you could copy \mypkg{TeXBuildPkg} files to TEXMF tree as follows:
\noindent\begin{tblr}{X[font=\ttfamily]X[2,font=\ttfamily]}
\toprule
Package file & Where to install it \\
\midrule
texbuildpkg.1 & TEXMF/doc/man/man1/texbuildpkg.1 \\
README.txt & TEXMF/doc/support/texbuildpkg/README.txt \\
texbuildpkg.lua & TEXMF/scripts/texbuildpkg/texbuildpkg.lua \\
\bottomrule
\end{tblr}
Then create a symbolic link from \myfile{/usr/local/bin/texbuildpkg} to \myfile{path/to/texbuildpkg.lua} on Linux or MacOS,
or create a batch file \myfile{texbuildpkg.bat} in binary folder of the TeX distribution with these lines on Windows:
\begin{codehigh}
@echo off
texlua path\to\texbuildpkg.lua %*
\end{codehigh}
The \mypkg{TeXBuildPkg} tool uses \myprg{pdftoppm} program for image converting.
This program is installed by default on MiKTeX. For TeX Live, you can install it by running
\begin{codehigh}
tlmgr install wintools.windows
\end{codehigh}
on Windows, or running
\begin{codehigh}
sudo apt-get install poppler-utils
\end{codehigh}
on Ubuntu/Debian Linux.
\section{Usages}
You could call \myopt{check} target of \mypkg{TeXBuildPkg} with the folllowing commands
\begin{codehigh}
texbuildpkg check
\end{codehigh}
The first run of \mypkg{TeXBuildPkg} will save image and md5 files to \myfile{testfiles} folder,
and the subsequent runs of it will compare new md5 values with existing md5 values.
You could force \mypkg{TeXBuildPkg} to save new image and md5 files of failed tests to
\myfile{testfiles} folder by calling \myopt{save} option of it:
\begin{codehigh}
texbuildpkg save
\end{codehigh}
Both \myopt{check} and \myopt{save} targets accept \myopt{-c} option, which sets the config to used.
\section{Customizations}
The \myprg{pdftoppm} program supports several types of image files.
By default the \mypkg{TeXBuildPkg} tool will use \myfile{.png} file,
and you could change it in \myfile{tbpconfig.lua} file like this:
\begin{codehigh}
imgext = ".ppm"
\end{codehigh}
\begin{codehigh}
imgext = ".pgm"
\end{codehigh}
\begin{codehigh}
imgext = ".pbm"
\end{codehigh}
\end{document}