FAQ-BUILD.txt

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 jammy and later, the following list should cover
		necessary packages (except for -doc packages):
			texlive-publishers texlive-pstricks
			texlive-science texlive-fonts-extra
			xfig librsvg2-bin graphviz gnuplot

		On Ubuntu focal, install inkscape instead of librsvg2-bin.

		On Fedora, installing the following set of packages
		suffices:
			texlive-collection-plaingeneric
			texlive-collection-binextra
			texlive-collection-latexextra
			texlive-collection-fontsextra
			texlive-collection-fontutils
			transfig graphviz librsvg2-tools gnuplot

		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:
			fig2dev (or transfig) graphviz librsvg2-tools
			(or librsvg2-bin, rsvg-convert, etc.)
			gnuplot

	    Note: For building on Git repo prior to January 2024,  you need
		inkscape as well.

		Preferred SVG --> PDF converter is rsvg-convert >= v2.57.
		rsvg-convert v2.52 should also suffice.  If there is
		no inkscape installed, any version of rsvg-convert is
		used for the conversion, albeit there can be poor looking
		figures in the end.
		You can continue building perfbook without rsvg-convert
		if you have inkscape, that is, as long as command-line
		mode inkscape works reliably...

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-1.	First of all, building perfbook requires TeX Live 2019/Debian
		(Ubuntu Focal) or later.

		Upgrading your Linux distribution (e.g. to Ubuntu Jammy)
		is one way to upgrade TeX Live 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/libertine
			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

	A-2.	Figures drawn using Inkscape and added in the SVG format
		need fonts accessible via the fontconfig scheme.
		The "Steel City Comic" font mentioned in #1 of FAQ.txt
		is one of such fonts and is mandatory.
		There are SVG figures which use other font families
		listed below:

		  - DejaVu Sans
		  - DejaVu Sans Mono
		  - FreeMono
		  - Liberation Sans
		  - Liberation Mono

		These are treated as "nice-to-have" fonts and even if
		some of them are missing, conversion of those figures into
		PDF can go on using fallback fonts.
		You will see info-level messages from make runs:

		  Nice-to-have font family 'DejaVu Sans Mono' not found.

		in .svg --> .pdf conversions if that happens.

		As for Ubuntu, packages listed in #5 should cover all the
		font families listed above.

		As for Fedora, installing packages listed below should suffice:

		  - dejavu-fonts-all
		  - liberation-fonts

10.	Building perfbook fails with a warning of version mismatch of epigraph.
	What can I do?

	A.	It is a known issue of TeX Live releases prior to 2020.
		This answer assumes Ubuntu, but it should work on other
		distros.

	    1.	Download package archive from CTAN mirror:
		http://mirrors.ctan.org/macros/latex/contrib/epigraph.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:latest

		It can be run with the command:

		    docker run --rm -it -v <path to perfbook dir>:/work \
		      akiyks/perfbook-build:latest

		Note:
		The prebuilt container image assumes rootless mode.
		If you run root-mode docker, you can still run the image by
		adding the option:

		     -u $(id -u):$(id -g)

		to the "docker run" command.

		You can build a container image on 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 is also available.
		It is built from docker/Dockerfile.fedora.

		If you have podman already installed, you can run the image
		with podman. podman runs in rootless mode by default.
		Use the following command to run (Note the ":z" in the -v flag):

		    podman run --rm -it -v <path to perfbook dir>:/work:z \
		      akiyks/perfbook-build:fedora

		Your updates under /work will have your host uid in host's POV.

14.	It looks as if answers above all assume building under GNU/Linux
	hosts.	Wouldn't it be possible to build under non-GNU/Linux systems?

	A.	As you might expect, perfbook's build scripts have been
		developed and tested on GNU/Linux hosts, especially assuming
		utility	commands of FSF/GNU origin.  That said, it should be
		possible to build on non-GNU/Linux systems as long as GNU
		compatible utility commands are usable.

		Here is a list of requirements:

		  - GNU make
		  - /usr/bin/env
		  - date: format options of either GNU or BSD flavor
		  - sed: repeat patterns \? and \+
		  - grep: -z option (optional)

		Among requirements above, features of date and sed are checked
		automatically at the beginning of make runs after "make clean".

		The check can be done manually by running:

		    make precheck

		There may be cases where GNU compatible commands are installed
		with different names such as:

		  - GNU make: gmake
		  - GNU date: gdate
		  - GNU sed:  gsed
		  - GNU grep: ggrep

		Those alternative names can be specified via make variables:

		   gmake DATE=gdate SED=gsed GREP=ggrep

		or via environment variables:

		   export DATE=gdate; export SED=gsed; exprot GREP=ggrep; gmake

		Again, building under non-GNU/Linux systems is tested only
		sparingly and you might encounter errors we are not aware of.

		Code samples under CodeSamples/ were originally written for
		Linux and a QNX compat layer was added in 2022.  Compat layers
		for other OSes are more than welcome!