What is kpsetool, kpsexpand, and kpsepath?

Question

When trying to manage my on LaTeX distribution, I frequently come across the commands kpsetool, kpsexpand, and kpsepath. They seem to have a similar purpose. What is it?

Answer 1

When TeX started to spread around the world and the operating systems, a necessity arose, namely standardizing the directory structure where TeX and the sister programs such as METAFONT, could find files they needed.

For instance, fonts were available only in bitmap form and it was necessary to generate the bitmaps on the fly for coping with different printers or magnifications. Or formats needed to be regenerated and, most important, files had to be found without having to call their path explicitly. Of course, the original programs already had some sort of built-in abilities for finding files.

The standard that emerged was the kpathsea library (Karl's path search) written by Karl Berry (we can't thank him enough for this gift) as part of the Web2C program: the Web sources of TeX and friends were first extracted in the original Pascal language, then translated to C and compiled; during this compilation the programs could be linked to libraries such as kpathsea.

This library uses some configuration files to set up (pseudo) environment variables that are used for a large lot of tasks. Why “pseudo”? Because these variables are added to the environment only when a program linked to kpathsea is launched.

The most important is SELFAUTOLOC: if I launch tex from the command line (or via a front-end), this variable is automatically set to the directory that contains the executable; this allows for setting up other SELF... variables that in turn load the configuration files that set up the other variables, making them known to the shell the program is executed in. The most important variable is perhaps TEXINPUTS.

To make an example, on my machine I keep TeX Live distributions from 2012 to the current 2023. If I want to test a file to see when a problem started to appear, I can launch from the shell, say,

/usr/local/texlive/2022/bin/universal-darwin/pdflatex

or even

/usr/local/texlive/2012/bin/x86_64-darwin/pdflatex

and, automatically, packages and so on will be loaded from the 2022 or 2012 respectively.

There are a number of tools for interrogating kpathsea:

kpseaccess    kpsereadlink  kpsetool      kpsewhich
kpsepath      kpsestat      kpsewhere     kpsexpand

Actually, kpsepath and kpsexpand are alias for kpsetool, but all programs linked with kpathsea have the ability of taking different actions according to the name they're called with.

For instance, pdflatex is just a symbolic link to the executable pdftex, but calling it pdflatex allows kpathsea to set up the variables as wanted for pdflatex: path precedences are different for LaTeX and plain TeX. Indeed, in the main configuration file you can read

TEXINPUTS.pdflatex      = $TEXMFDOTDIR;$TEXMF/tex/{latex,generic,}//
TEXINPUTS.xelatex       = $TEXMFDOTDIR;$TEXMF/tex/{xelatex,latex,xetex,generic,}//

Actually kpsetool is a script that eventually runs either kpsewhich or kpsepath and kpsewhere is a script that eventually runs kpsewhich. Thus kpsewhich and kpsepath are the real workhorses.

As an example, kpsexpand will take as argument the name of a pseudovariable with the escaped $ in front:

> kpsexpand \$SELFAUTOLOC
/usr/local/texlive/2023/bin/universal-darwin

but directly with kpsewhich one can do better

> kpsewhich -var-value SELFAUTOLOC
/usr/local/texlive/2023/bin/universal-darwin

without the need to escape the $ (this feature is very useful when dealing with Windows, that uses a different way to expand variables).

Just to show what happens when calling a different executable

> /usr/local/texlive/2012/bin/x86_64-darwin/kpsewhich -var-value TEXMFROOT
/usr/local/texlive/2012```
If you want to find where the system thinks a file resides in, you can use kpsewhich:
> kpsewhich story.tex
/usr/local/texlive/2023/texmf-dist/tex/plain/knuth-lib/story.tex
</code></pre>
<p>Another example:</p>
<pre class="lang-bash prettyprint-override"><code>&gt; kpsereadlink $(type -p pdflatex)
pdftex
</code></pre>
<p>You should be able to find the man pages on your system, but you can also do</p>
<pre class="lang-bash prettyprint-override"><code>&gt; texdoc kpsexpand
</code></pre>
<p>and you'll get the PDF version of the relevant man page.</p>
<p>Have a nice read!</p>

Answer 2

After delving into this topic, I kinda found what they are. The commands I mentioned—kpsetool, kpsexpand, and kpsepath—are part of the Kpathsea library, which is used by TeX distributions to locate files in a TeX system.

• kpsetool:

  • This command is used to manage Kpathsea tools.
  • Example: kpsetool --help will show the available options.

• kpsexpand:

  • This command is used to expand variables in file and directory names.
  • For example, you can use kpsexpand \$TEXMFHOME to expand the variable $TEXMFHOME to its actual value.

• kpsepath:

  • This command is used to show elements of the TeX search path.
  • For example, kpsepath tex will show the directories in the TeX path where TeX looks for .tex files.

These commands are part of the Kpathsea library, which is responsible for file searching and path management in TeX distributions. They are useful for understanding and troubleshooting issues related to the TeX environment, such as locating files, checking search paths, and expanding variables.