forked from paulmckrcu/perfbook
-
Notifications
You must be signed in to change notification settings - Fork 0
/
FAQ-BUILD.txt
296 lines (220 loc) · 10.4 KB
/
FAQ-BUILD.txt
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
1. I have installed the Steel City Comic font referring to item 1
in FAQ.txt, and rebuilt "perfbook.pdf". But it doesn't seem to
have any effect. What am I missing?
A. If you built "perfbook.pdf" before installing the font,
you need to rebuild cartoons whose sources are .svg
files. Typing "make touchsvg; make" will do the trick.
2. I prefer perfbook-1c.pdf than perfbook.pdf to read it on my
tablet. Typing "make perfbook-1c.pdf" every time is a little
bit cumbersome. Isn't there any simpler way?
A. Actually there is! Just type "make 1c".
3. Are there other short name targets?
A. "make hb" will build perfbook-hb.pdf that is useful
for making hard-bound printouts.
"make 2c" will build perfbook.pdf.
"make help" will show you the list of official targets.
"make help-full" will display all the available targets.
4. Isn't it possible to build perfbook-1c.pdf by just typing
"make"?
A. Yes, it is! Define an environment variable
"PERFBOOK_DEFAULT" in your shell and set its value as
"1c". Then, just typing "make" will build
perfbook-1c.pdf.
If you set "hb" to "PERFBOOK_DEFAULT", typing "make"
will build perfbook-hb.pdf mentioned in #3.
While you have the environment variable set, specifying
a specific target (or targets) always works.
5. The Makefile cannot find pdflatex. What is it and where can I
find it?
A. The "pdflatex" package is a variant of Don Knuth's
digital typesetting program, which you can install.
Alternatively, you can use the container image described
in #13 below. Otherwise, instructions follow.
On Ubuntu Bionic and Focal, the following list should cover
necessary packages (except for -doc packages):
texlive-publishers texlive-pstricks
texlive-science texlive-fonts-extra
xfig inkscape graphviz fig2ps
Ubuntu Bionic has a buggy/incompatible version of LaTeX
packages "cleveref" and "glossaries-extra".
See #10 below to install the latest one.
On Ubuntu Bionic, you also need to fetch a version of
a2ping which is compatible with updated Ghostscript.
See #7 below.
On Fedora, installing the following set of packages
suffices:
texlive-collection-plaingeneric
texlive-collection-binextra
texlive-collection-latexextra
texlive-collection-fontsextra
texlive-collection-fontutils
fig2ps graphviz inkscape
On other Linux distributions such as RHEL/CentOS and
Scientific Linux, where support of TeX Live packages
is insufficient, the aforementioned container image
provides the needed support. Again, see #14 below.
Of course, you can install upstream TeX Live.
See: https://www.tug.org/texlive/quickinstall.html
NOTE: In doing so, you might end up in having
redundant texlive packages of your choice
of distribution to satisfy dependency
of other packages.
Besides TeX Live, you need the following list of
packages:
fig2ps graphviz inkscape
6. I cannot build perfbook, and the perfbook.log file complains
about some obscure package being missing. What do I do?
A. Please see #5 above.
7. Building perfbook aborts with error "You need to update a2ping".
What can I do?
A. a2ping 2.77p has become incompatible with up-to-date
Ghostscript on most Linux distributions since September
2018 due to security fixes backported from Ghostscript
9.22 and later. a2ping 2.83p has lost compatibility with
Ghostscript 9.50 due to a change in default behavior.
A compatible a2ping (2.84p) is available at:
https://www.ctan.org/pkg/a2ping
Copy "a2ping.pl" as "a2ping" into a directory which
precedes /usr/bin in your PATH setting.
a2ping 2.84p is available in TeX Live 2020 or later
(Including TeX Live 2019/Debian).
8. When I try to build perfbook, it hangs after printing a line
reading "pdflatex 1". How can I fix this?
A. On UNIX-like systems, including Linux, type control-D.
Then look at the end of the perfbook.log file (or the
perfbook-1c.log file if you were building single-column).
The error message at the end of the log file should
indicate the source of the problem.
The build scripts are supposed to make this unnecessary,
so if it happens, please let me know. Please send me the
perfbook.log output (or perfbook-1c.log output, depending
on which you were building) so that I can fix the scripts.
9. Building perfbook or some of its experimental targets with
alternative fonts fails due to a lack of font packages such as
"nimbus15", "newtxtt", etc.; or an old version of font package
"newtx". How can I install or update them?
A. First of all, building perfbook requires TeX Live 2017/Debian
(Ubuntu Bionic) or later. If you are told you don't have
"glossaries-extra" package, you need to upgrade your TeX
installation.
For other optional font packages, upgrading TeX Live
to 2017/Debian (Ubuntu Bionic) or later should suffice.
Upgrading your Linux distribution (e.g. to Ubuntu Focal)
is one way to upgrade TeX Live (to 2019/Debian on Focal),
and might have many other benefits as well.
However, on modern TeX Live, installing -fonts-extra consumes
more than 1GB of your disk space. If you prefer to manually
install individual packages on Ubuntu, refer to "Method 3" in:
http://tex.stackexchange.com/questions/73016/
For font packages such as "newtxtt" and "nimbus15",
you must also update font-map database. See:
http://tex.stackexchange.com/questions/88423/
Following is a list of links to font packages perfbook
depends on as of October 2021 which are not included
in -fonts-recommended:
https://www.ctan.org/pkg/newtx
https://www.ctan.org/pkg/newtxtt
https://www.ctan.org/pkg/nimbus15
https://www.ctan.org/pkg/courier-scaled
https://www.ctan.org/pkg/inconsolata
https://www.ctan.org/pkg/newtxsf
https://www.ctan.org/pkg/gnu-freefont
https://www.ctan.org/pkg/dejavu
Note 1: Manually installing a font package newer than the one
already exists in your TeX installation is a tricky business
and should be avoided unless you have a very good knowledge
of the infamously complex TeX font system. In most cases,
upgrading TeX installation should be your way to go.
Note 2: Most font packages on the CTAN site provide .zip archives
which will automatically put the files in a relatively
right place. Note that font packages should be copied to the
TEXMFLOCAL directory rather than to the TEXMFHOME directory.
Note 3: On Fedora and upstream TeX Live, you can install font
packages one by one using the following command (example
of newtx).
On Fedora:
sudo dnf install texlive-newtx
On upstream TeX Live (assuming user mode installation):
tlmgr install newtx
10. Building perfbook fails with a warning of buggy cleveref or
version mismatch of epigraph.
What can I do?
A. They are known issues on Ubuntu Bionic (cleveref,
glossaries-extra), and TeX Live releases prior to 2020
(epigraph).
This answer assumes Ubuntu, but it should work on other
distros.
1. Download whichever package from CTAN mirror:
http://mirrors.ctan.org/macros/latex/contrib/cleveref.zip
http://mirrors.ctan.org/macros/latex/contrib/epigraph.zip
http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra.zip
2. Install it by following instructions at:
https://help.ubuntu.com/community/LaTeX#Installing_packages_manually
B. Instead of above manual steps, you could install the package
using a script in this repository,
'./utilities/install_latex_package.sh'. For example:
$ ./utilities/install_latex_package.sh epigraph
11. Is it possible to generate SyncTeX database file?
A. Yes, it is. Setting an environment variable:
$ export LATEX_OPT="-synctex=1"
and doing "make clean; make" will generate
perfbook.synctex.gz. This will enable SyncTeX search
(.pdf <-> .tex) with a SyncTeX-supporting combination of
pdf viewer and editor.
Notes:
- For an introduction of SyncTeX search (gedit <-> evince), see:
https://help.gnome.org/users/evince/stable/index.html.en#synctex
Other combinations of SyncTeX-supporting viewers and editors
may work.
- You need to install gedit-plugins and enable SyncTeX plugin
in gedit's preference.
- You need to open one of LaTeX sources (e.g. perfbook.tex)
in gedit before doing inverse search from evince.
- The environment variable LATEX_OPT works for other build
targets such as perfbook-1c.pdf, perfbook-hb.pdf, etc.
To enable forward search from gedit, run e.g.:
$ utilities/synctex-forward.sh 1c
- Changes made by utilities/synctex-forward.sh can be
reverted by running:
$ utilitied/synctex-forward.sh
Please make sure to revert the changes before doing
"git commit" of the other updates you've made.
12. After upgrading the userspace RCU library, and all of the code
samples making use of that library are now broken.
A. The userspace RCU library sometimes breaks ABI, which
requires that the binaries dynamically linking to it be
rebuilt.
Try removing the old binaries ("make clean") and then
rebuilding ("make").
13. I want a stable environment to build perfbook.pdf.
Can't I just use some container image?
A. You can find a template Dockerfile under the docker/
subdirectory. You can pull the container image built from
it as follows:
docker pull akiyks/perfbook-build-focal:latest
It can be run with the command:
docker run --rm -it -v <path to perfbook dir>:/work \
akiyks/perfbook-build-focal:latest
Note:
The prebuilt container image assumes <uid:pid> = <1000:1000>.
If you have different IDs, you can still run the image by
adding the option:
-u $(id -u):$(id -g)
to the "docker run" command. The bash prompt will be in the
form of "I have no name!@abcdef012345:/work$". Builds of
perfbook will nevertheless succeed. You can also build
a container image of your own:
cd docker
docker build -t <container image tag> \
--build-arg uid=$(id -u) --build-arg gid=$(id -g) .
For those prefer a Fedora-based container image,
akiyks/perfbook-build-fedora:latest is also available.
It is built from docker/Dockerfile.fedora.
If you have podman already installed, you can run the image
with podman. podman maps container's root to your host uid
by default.
Use the following command to run:
podman run --rm -it -v <path to perfbook dir>:/work:z \
-u 0:0 akiyks/perfbook-build-fedora:latest
You will see a prompt with a "#".
Your updates under /work will have your host uid in host's POV.