In Parts 1, 2 and 2a I made reference to such things as “environment variables” and a file called texmf.cnf. I this section of the tutorial I will try to bring these concepts together and get down to some practical details. But first we need to set the scene with a very important topic: Kpathsea.

Kpathsea, what’s that?

The name Kpathsea originates from Karl’s path searching, named after the author of the library, Karl Berry. As discussed on the Kpathsea web pages, it was written to provide a number of programs with a unified method for path-searching: finding files and resources that those programs needed during the course of execution. TeX and related programs are designed to run on very many different platforms (Windows, Linux, Mac…) and one of the keys to doing this successfully is ensure that the underlying source code from which they are built is as platform-independent as is possible to achieve.

So, in essence, Kpathsea is a path-searching library which is built into the TeX executable file (“TeX engine”) to provide unified methods for path-searching (finding files) that will work on many different computer platforms. When looking for font metric files, .tex files, .sty files, graphics and many other file resources, the “TeX engine” (e.g., LuaTeX) is using the Kpathsea library to find what it needs to typeset your document.

LuaTeX offers an alternative: a primer
For LuaTeX this is just one part of the story. With LuaTeX you can implement your own Lua code to replace the Kpathsea file searching methods via LuaTeX’s “callback” methods. That’s for another day, here we’ll stick to using Kpathsea. If you are interested to read more about the powerful LuaTeX callbacks, consult The LuaTeX Reference Manual.

Kpathsea, texmf.cnf and environment variables

So, at long last you may say :-), we’ve finally reached the point where the various components start to come together.

• texmf.cnf is the name given to the runtime configuration files used by the Kpathsea path-searching library to locate resources (find files) on your computer and tell the “TeX engine”, including LuaTeX, where the “TeX engine” can locate the file(s) it needs in order to typeset your document.
• a TeX installation may use multiple texmf.cnf files to configure the installation. The use of multiple texmf.cnf files is discussed in the main Kpathsea documention.
• In addition to using texmf.cnf files, Kpathsea also uses environment variables to find resources. In essence, Kpathsea uses a mixture of environment variables and values stored in texmf.cnf files as a way to locate resources.

Kpathsea also sets environment variables

In addition to reading environment variables from your computer, Kpathsea also
sets some environment variables too: SELFAUTOLOC, SELFAUTODIR and SELFAUTOPARENT to the location, parent and grandparent directory of the executable (LuaTeX in our case).

A simple example

If you are reading this and already have a working LuaTeX installation, the following LuaTeX example will typeset the values of SELFAUTOLOC, SELFAUTODIR and SELFAUTOPARENT from your LuaTeX configuration.

\documentclass[11pt,twoside]{article}
\begin{document}
\pagestyle{empty}
\let\temp\\%
\let\\\relax
\directlua{
         tex.print("SELFAUTOLOC = "..os.getenv("SELFAUTOLOC").."\\par")
         tex.print("SELFAUTODIR = "..os.getenv("SELFAUTODIR").."\\par") 
         tex.print("SELFAUTOPARENT = "..os.getenv("SELFAUTOPARENT").."\\par")  
}
\end{document}

I have a working LuaTeX installation but copied the luatex.exe file to a directory

c:\luatexblog\dir1\dir2\luatex.exe

Putting the above LuaTeX code into a file called test.tex produced this pdf file, showing that

SELFAUTOLOC = c:/luatexblog/dir1/dir2
SELFAUTODIR = c:/luatexblog/dir1
SELFAUTOPARENT = c:/luatexblog