Overridding Build Settings

Tarn Burton edited this page Jan 3, 2017 · 4 revisions

Many of the build settings in the settings page of the latex package can be overridden on a per file basis. One way to override specific build settings is to use "magic" TeX comments in the form of % !TEX <name> = <value>. Another way to override build settings is to use a YAML formatted file with the same name as your root LaTeX file, but with an extension of .yaml. The settings and values that can overridden via either method are listed in the table below. If multiple setting names are listed then the first is preferred and following names are available for compatibility.

Name Value Use
cleanPatterns comma separated patterns, e.g. **/*.blg, foo Specify patterns to use for latex:clean
enableSynctex yes, no, true or false Override SyncTeX setting
enableExtendedBuildMode yes, no, true or false Override extended build mode setting
enableShellEscape yes, no, true or false Override shell escape setting
engine or program pdflatex, lualatex, etc. Override the LaTeX engine to use for build.
moveResultToSourceDirectory yes, no, true or false Override move result to source directory setting
outputFormat or format dvi, ps or pdf Override the output format
jobNames, jobnames or jobname comma separated names, e.g. foo, bar Control the number and names of build jobs. Only a single name can be used for jobname.
outputDirectory or output_directory directory path, e.g. build Specify the output directory that should be used.
producer dvipdf, dvipdfmx, xdvipdfmx or ps2pdf Override the PDF producer
root file path, e.g. ../file.tex Specify the root file that should be built. Only available via "magic" TeX comments.

Examples of TeX Magic Comments

All TeX magic comments should occur before \documentclass and may start with either % !TEX or % !TeX. There should be no space after the exclamation point but the space before the exclamation point is optional.

TeX magic comments are only loaded from the root document with the exception of the root setting. For example, if the following is the contents of bar.tex then only the root setting will be used and the engine setting will be ignored.

% !TEX root = ../foo.tex
% !TEX engine = xelatex
\begin{enum}
  \item wibble
  \item quux
\end{enum}

If the following is the contents of foo.tex then the actual LaTeX engine used will be uplatex and the outputDirectory will be build. The setting outputFormat will be ignored since it occurs after \documentclass. Because of the jobNames setting the build will be run twice with a job name of quux the first time and a job name of name with spaces the second time.

% !TEX engine = uplatex
% !TEX outputDirectory = build
% !TEX jobNames = quux, name with spaces
\documentclass{article}
% !TEX outputFormat = dvi

\begin{document}
\input{wibble/bar.tex}
\end{document}

Examples of YAML Build Settings

In order to accomplish the same overridden settings using a YAML settings file the contents of bar.tex should be the following since the root setting is still needed to identify the root document.

% !TEX root = ../foo.tex
\begin{enum}
  \item wibble
  \item quux
\end{enum}

All magic comments in foo.tex can be removed and instead a file foo.yaml is created with the contents below.

engine: uplatex
outputDirectory: build
jobNames:
- quux
- name with spaces

If TeX magic comments are left in foo.tex then they will be processed before the YAML file is read and processed. In other words, the YAML build settings will take precedence over the TeX magic comments.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.