Skip to content

Latest commit

 

History

History
384 lines (269 loc) · 17.4 KB

Compile.md

File metadata and controls

384 lines (269 loc) · 17.4 KB
Raw

Compiling features

Building the document

A LaTeX file is typically built by calling the command Build LaTeX project from the Command Palette or from the TeX badge. This command is bind to ctrl+alt+b. If you cannot use ctrl+alt in a keybinding, see the FAQ. The recipe called by this command is defined by latex-workshop.latex.recipe.default.

If you have a multi-file project, see multi-files-projects for more details on how the root file is discovered.

You can define several compiling toolchains to build LaTeX projects using LaTeX recipes and then call the command Build with recipe to choose the appropriate toolchain for actually building the project. Alternatively, you can directly select the appropriate recipe from the TeX badge.

The following settings are helpful to customize how to build a project and how to deal with failures.

Setting key Description Default Type
latex-workshop.latex.autoBuild.run When the extension shall auto build LaTeX project using the default (first) recipe. onFileChange string
latex-workshop.latex.recipes Sequence of tools to run for building JSON object
latex-workshop.latex.tools Tools available for building JSON object
latex-workshop.latex.magic.args Arguments for the TeX program array of strings
latex-workshop.latex.magic.bib.args Arguments for the BIB program array of strings
latex-workshop.latex.build.forceRecipeUsage Force the use of recipes false boolean

A progress bar indicates the building progress. It can be customized using the following configuration variables

Terminating the current compilation

It is possible to terminate the current compilation by calling Kill LaTeX compiler process from the Command Palette or calling Terminate current compilation from the TeX badge in the Build LaTeX project item.

Auto build LaTeX

Besides manually calling the Build LaTeX Project command to compile a document, you may also let the extension automatically start compiling it upon file change. This can be defined in latex-workshop.latex.autoBuild.run. The recipe called by auto build is defined by latex-workshop.latex.recipe.default.

latex-workshop.latex.autoBuild.run

When to trigger automatic building.

type default value possible values
string "onFileChange" "never","onFileChange"
  • "never": Disable the auto build feature
  • "onFileChange": Build the project upon detecting a file change in any of the dependencies. The file can even be modified outside vscode. See here for explanations on what dependencies are and how some of them can be ignored.

latex-workshop.latex.autoBuild.interval

The minimal time interval between two consecutive auto builds in milliseconds.

type default value
integer 1000

Cleaning generated files

LaTeX compilation typically generates several auxiliary files. They can be removed by calling Clean up auxiliary files from the Command Palette or from the TeX badge. This command is bind to ctrl+alt+c. If you cannot use ctrl+alt in a keybinding, see the FAQ.

Setting key Description Default Type
latex-workshop.latex.autoBuild.cleanAndRetry.enabled Enable cleaning and building once more after errors in the build toolchain true boolean
latex-workshop.latex.autoClean.run Define when LaTeX auxillary files should be deleted. "never" string
latex-workshop.latex.clean.fileTypes Extensions of files to clean array of strings
latex-workshop.latex.clean.subfolder.enabled Clean LaTeX auxillary files recursively in sub-folders of latex-workshop.latex.outDir false boolean

latex-workshop.latex.autoClean.run

type default value possible values
string "never" "never","onFailed", "onBuilt"
  • "never": Disable the auto cleaning feature
  • "onFailed": Clean the project upon failed compilation.
  • "onBuilt": Clean the project upon completing a compilation, whether it is successful or not.

LaTeX recipes

A LaTeX recipe refers to a sequence/array of commands which LaTeX Workshop executes sequentially when building LaTeX projects. It is defined by latex-workshop.latex.recipes. By default, LaTeX Workshop includes two basic recipes defined by the variables latex-workshop.latex.recipes and latex-workshop.latex.tools:

  • The first one simply relies on the latexmk command
  • The second one run the following sequence of commands pdflatex → bibtex → pdflatex → pdflatex.
[
  {
    "name": "latexmk 🔃",
    "tools": [
      "latexmk"
    ]
  },
  {
    "name": "pdflatex ➞ bibtex ➞ pdflatex`×2",
    "tools": [
      "pdflatex",
      "bibtex",
      "pdflatex",
      "pdflatex"
    ]
  }
]

and each tool appearing in the tools field is defined latex-workshop.latex.tools. Its default value is given by

[
  {
    "name": "latexmk",
    "command": "latexmk",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "-pdf",
      "-outdir=%OUTDIR%",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "pdflatex",
    "command": "pdflatex",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "bibtex",
    "command": "bibtex",
    "args": [
      "%DOCFILE%"
    ],
    "env": {}
  }
]

You can create multiple recipes with different tools. Each recipe is an object in the configuration list, consisting of a name field and a list of tools to be invoked in the recipe.

The tools in recipes can be defined in latex-workshop.latex.tools, in which each command is a tool. Each tool is an object consisting of a name, a command to be spawned, its arguments (args) and some specific environment variables (env). The env entry is a dictionary. Imagine you want to use a texmf subdirectory local to your home project, just write

  "env": {
      "TEXMFHOME": "%DIR%/texmf"
  }

You can also override PATH environment variable.

To include a tool in a recipe, the tool's name should be included in the recipe's tools list.

When building the project, the magic comments in the root file is used if given, otherwise the first recipe is used. You can compile with another recipe by command latex-workshop.recipes. By default latexmk is used. This tool is bundled in most LaTeX distributions, and requires perl to execute. For non-perl users, the following texify toolchain from MikTeX may worth a try:

"latex-workshop.latex.recipes": [{
  "name": "texify",
  "tools": [
    "texify"
  ]
}],
"latex-workshop.latex.tools": [{
  "name": "texify",
  "command": "texify",
  "args": [
    "--synctex",
    "--pdf",
    "--tex-option=\"-interaction=nonstopmode\"",
    "--tex-option=\"-file-line-error\"",
    "%DOC%.tex"
  ],
    "env": {}
}]

The args and env parameters can contain symbols surrounded by %. These placeholders are replaced on-the-fly. LaTeX Workshop registers the following placeholders:

Placeholder Replaced by
%DOC% The LaTeX root file path and name without the .tex extension
%DOCFILE% The LaTeX root file name without the .tex extension
%DIR% The LaTeX root file path
%TMPDIR% A temporary folder for storing ancillary files
%OUTDIR% The output directory configured in latex-workshop.latex.outDir

Alternatively, you can also set your commands without the placeholder, just like what you may input in a terminal. As most LaTeX compiler accepts root file name without extension, %DOC% and %DOCFILE% do not include .tex extension. Meanwhile, texify requires the extension. So in the above tool %DOC% and .tex are concatenated for completeness.

latex-workshop.latex.recipe.default

Define which recipe is used by the Build LaTeX project command.

type default value possible values
string "first" "first","lastUsed"
  • "first": Use the first recipe defined in latex-workshop.latex.recipes.
  • "lastUsed": Use the last used recipe by the command LaTeX Workshop: Build with recipe.

latex-workshop.latex.build.forceRecipeUsage

Force the use of the recipe system even when a magic comment defines a TeX command.

type default value
boolean false

External build command

Versatile though the recipe mechanism described above may be, it may fail to match your needs when building the whole LaTeX project is done by a personal script or a Makefile. For this particular case, we provide an external build command mechanism, which completely bypasses the recipe machinery. Just define your command along with its arguments using the following two configuration variables

latex-workshop.latex.external.build.command

The external command to execute when calling latex-workshop.build.

This is useful when compiling relies on a Makefile or a bespoke script. When defined, it completely bypasses the recipes and root file detection mechanism.

type default value
string ""

latex-workshop.latex.external.build.args

The arguments of latex-workshop.latex.external.build.command when calling latex-workshop.build

type default value
string[] []

Magic comments

TeX programm and options

LaTeX Workshop supports % !TEX program magic comment to specify the compiler program. However, it is advised to use the recipe system instead of magic program to define the building process, since the latter is only implemented for backward compatibility.

For % !TEX program magic comment, its arguments are defined in latex-workshop.latex.magic.args:

"latex-workshop.latex.magic.args": [
  "-synctex=1",
  "-interaction=nonstopmode",
  "-file-line-error",
  "%DOC%"
]

Alternatively, you can directly define the args in the .tex file by using the magic comment ! %TEX options, which overrides latex-workshop.latex.magic.args. Note that it must contain the file to proceed. For instance, to reproduce the default behavior, you should use

% !TEX options = -synctex=1 -interaction=nonstopmode -file-line-error "%DOC%"

Suppose there is a line % !TEX program = xelatex in the root file. Upon building the project, LaTeX Workshop will parse the root file and figure out that xelatex should be used.

BIB program and options

When using % !TEX program with bibliographies, a bib compiler must be defined with % !BIB program comment, e.g., % !BIB program = bibtex. Otherwise the extension will only run one-pass compilation with the specified LaTeX compiler. If needed, you can pass extra arguments to the !BIB program using the latex-workshop.latex.magic.bib.args variable:

"latex-workshop.latex.magic.bib.args": [
  "%DOCFILE%"
]

Alternatively, you can directly define the args in the .tex file by using the magic comment ! %BIB options, which overrides latex-workshop.latex.magic.bib.args. Note that it must contain the file to proceed. For instance, to reproduce the default behavior, you should use ! %BIB options = "%DOCFILE%".

Catching errors and warnings

The warnings and errors issued by the compiling toolchain are rendered in the Problems Pane. The following settings enable you to customize what you want to get in that panel. If the messages displayed in the panel seem to be wrong, see the FAQ.

The raw compiler logs can be accessed in the Output Pane, choose LaTeX Compiler. The default is to clear the logs before calling every tool of a recipe. If you prefer to keep the logs from all the tools of a recipe, set latex-workshop.latex.build.clearLog.everyRecipeStep.enabled to false.

Settings Details

latex-workshop.message.log.show

Display LaTeX Workshop debug log in output panel.

This property defines whether LaTeX Workshop will output its debug log to the log panel.

type default value
boolean true

latex-workshop.message.badbox.show

Show badbox information in the problems panel.

type default value
boolean true

latex-workshop.message.latexlog.exclude

Exclude log messages that matches the given regexp from the problems panel.

type default value
array of strings []

latex-workshop.message.information.show

Display information messages in popup notifications.

type default value
boolean false

latex-workshop.message.warning.show

Display warning messages in popup notifications.

type default value
boolean true

latex-workshop.message.error.show

Display error messages in popup notifications.

type default value
boolean true

latex-workshop.message.update.show

Display LaTeX Workshop update message on new versions.

type default value
boolean true

latex-workshop.latex.build.clearLog.everyRecipeStep.enabled

Clear the LaTeX Compiler logs before every step of a recipe.

Set this property to false to keep the logs of all tools in a recipe.

type default value
boolean true

latex-workshop.progress.runIconType

The style of number to use to indicate the run number"

type default value
enum "Parenthesised"

The possible values are

  • "Parenthesised": "⑴ ⑵ ⑶ …",
  • "Circled": "① ② ③ …",
  • "Solid Circled": "❶ ❷ ❸ …",
  • "Full Stop": "⒈ ⒉ ⒊ …"

latex-workshop.progress.barLength

The length in characters of the progress bar.

type default value
number 15

latex-workshop.progress.barStyle

type default value
enum "Block Shading

The possible values are

  • "Block Width": "█████▋░░░ (8 levels per block)",
  • "Block Shading": "█████▓░░░ (4 levels per block)",
  • "Block Quadrants": "█████▙░░░ (4 levels per block)",
  • "none": No bar.