Project Detection

Discovery

Whenever you open a TeX file in the editor, texlab tries to find out all files that are part of the same project, meaning they are compiled into the same document. The server needs this information to implement most of its features. For example, packages imported in the preamble should be visible in other project files as well. In particular, the project is also used determine the root document, which is passed to the TeX engine when compiling.

Algorithm

The server does the following steps to figure out the project:

• Walk up the directory tree until we either reach the file system root (/), the home directory or a root directory (see below). For each directory along the way, we load all contained TeX files that we have not opened yet.
• Next, we build a dependency tree by resolving include commands such as \input or \import. The referenced files are added to the workspace.
• Repeat this procedure until there are no more changes to the workspace

Root directory

Due to the way, the TeX engine is designed, commands such as \input operate on the working directory of the TeX engine instead on the directory of the parent source file. That's why we need to determine the root directory in the server. texlab walks up the directory tree of the document and tries the following steps in this order:

1. Check if there is a .texlabroot/texlabroot file. Then, the server uses the texlab.build.auxDirectory, texlab.build.logDirectory and texlab.build.pdfDirectory settings to find the build artifacts and auxiliary files.
2. Check if there is a Tectonic.toml manifest. Then, the server uses the src and build directories and adds _preamble.tex and _postamble.tex to the project (if present).
3. Check if there is a .latexmkrc/latexmkrc file. Then, the server uses the settings defined inside the latexmkrc. If failing to do so, then texlab.build.auxDirectory, texlab.build.logDirectory and texlab.build.pdfDirectory are used as fallback.
4. Use the directory of the root source file. A root source file is a TeX document that has a document environment. Documents with \documentclass{subfiles} are excluded.