LaTeXTools: a new, customizable build system

Edited 3/13/14: updated name of configuration file. Also, this code is now in the master branch! More details in a later post.

One of the requests I receive most frequently, especially from LaTeX power user, is the ability to customize the build process. In principle, this is possible. However, it requires modifying the LaTeX.sublime-build file. This is inconvenient for a number of reasons. First, the file must be copied to the User directory, or it will be clobbered by subsequent updates of the plugin. Second, the file also contains internal settings that cannot and must not be customized. Third, the Sublime Text build system is really designed to launch a single, command-line program, or else a “make”-like utility. Indeed, LaTeXTools uses it to invoke either texify or latexmk, which are essentially TeX-specific “make” utilities. In principle, one can write one’s own custom build script and use that in lieu of the default build command; however, most users will not want to do that. Also, one is somewhat limited by the fact that external scripts do not “know” about Sublime Text, and hence cannot meaningfully communicate with it.

Enter the new “master builder” system; you will find it in the mbuilder branch on GitHub. Here’s what’s new:

  1. All user settings are now in the LaTeXTools.sublime-settings file. This includes the path to tex & friends, and all the settings discussed below. With the new code, LaTeX.sublime-build becomes effectively just an internal file that users need not and, indeed, must not modify. NOTE: if you want to play with the mbuilder branch, make sure to delete any stray LaTeX.sublime-build files you may have in the User directory. Also, as for any Sublime Text settings file, LaTeXTools.sublime-settings should be placed in User directory and customized there.
  2. The build system is now split into two components. One is the “master builder,” which takes care of handling the Cmd/Ctrl-B command and manages the (delicate) threading infrastructure required to run external commands such as pdflatex or latexmk; this is the code in the file The other is the actual “builder” or “build engine,”  which examines the tex root file, decides how to process it, and tells the master builder which external commands to run. Indeed, there are currently two build engines (called “traditional” and “simple”), with a third (“script”) coming soon: you will find the code in the builders directory.
  3. The “traditional” build engine does exactly what the current code in the master branch does: it calls latexmk or texify (and also allows for the selection of a tex engine). The “simple” build engine, on the other hand, requires no external tools, and can be useful, for instance, if you don’t want to install latexmk on OS X or Linux. It runs pdflatex, then bibtex if needed, then pdflatex again, as needed, until references / citations are either resolved or just missing. Thus, the “simple” engine is an example of a (simple!) “make” tool for tex & friends that runs entirely in Python, within Sublime Text. I hope one day to write (or, better yet, receive as a user contribution…) an actual, robust replacement for texify / latexmk. For now, the “simple” engine serves as an example to aspiring contributors… Finally, the “script” engine, when ready, will simply invoke a user-specified external command.
  4. All parameters of the build engines are configurable in LaTeXTools.sublime-settings. Again, you can forget about In particular, the “builder” option selects your preferred build engine. When the “script” engine is ready, this is where you will specify which external script to use, and whether to set any environment variables, for instance.
  5. Techie note: the beauty of this system is that build engines can access the Sublime Text API, as well as the whole Python library, but they do not need to know anything about threading. Instead, builders use the powerful Python mechanism of generator functions. Each time a build engine wants to run an external command (pdflatex etc.), it uses the Python yield command to send it to the master builder. The master builder runs the external command, captures its output, and returns it to the build engine.

The code is still beta quality; I’m running it daily myself, but I’m interested in feedback from adventurous users. When I’m reasonably confident that things are working, I’ll merge it into the master branch.

About these ads

25 responses to “LaTeXTools: a new, customizable build system

  1. Hi, I have some problem with LatexTools on ST2 since the last update (or the one before)… it happened twice at least: I open a .tex file (it is recognized as Latex) but then I can not access to any latex comment in ST2 (for exqmple cmd+b do not do anything, or any command starting by cmd+L) … If I open an other tex file it works fine, but for one particular file I can not do anything …. I have no idea where this can come from. any clue ?

  2. it has apparently something to do with the encoding … All my files are in “western (windows 1252)”, if I save the problematic one witht he encoding UTF8 then I can compile, but if I save it back in windows1252 then I loose again every command … And it happens only with a few number of files …

  3. Hi, thanks very much for the nice plugin. I noticed that LaTeX.sublime-build assumes that if Windows is running then miktex is installed, and thus defines ‘texify …’ as the build command. However, if one has TeXLive 2013 installed under Windows, there is no texify, but there is latexmk. Can you tell me the easiest way to specify this as the build command without mucking up the rest of the configuration? Thanks again for a nice contribution.

  4. Hey there, got a Problem since the Update on LaTeXTools.
    Everytime when i try to compile i get the following message:

    [Compiling /home/foertsch/Dropbox/Uni/BAA/Text/Protokoll/Bachelorarbeit.tex]

    TraditionalBuilder: Invoking latexmk…


    Attempted command:latexmk -cd -e $pdflatex=’pdflatex -interaction=nonstopmode -synctex=1 %S %O’ -f -pdf Bachelorarbeit.tex
    Build engine: Traditional Builder

    so the crazy thing about this error ist, that if i try the command in the console by myself it works.
    I’m running fedora 20 with TeXLive and before the update it worked (last day i tried was yesterday ;-))

    Pls help, i don’t know what to do.

    • Check the “texpath” option in LaTeXTools.sublime-settings (which you must have in the User directory). It may be incorrect for your setup.

      On Thu, Mar 13, 2014 at 7:41 AM, Tech, TeX and Theory wrote:


      • Thank you,
        I am completely dumb and blind,
        I just edited the default-settings File :-(
        Now it works.

      • I get the same error on sublime text 3 on debian, when running the same command
        in terminal I get:
        $ latexmk -cd -e $pdflatex = ‘pdflatex -interaction=nonstopmode -synctex=1 %S %O’ -f -pdf mn_z03.tex

        Latexmk: Stopping because executing following code from command line
        gave an error:
        syntax error at (eval 10) line 1, near “=”

        Removing the spaces before and after ‘=’ following $pdflatex seems to solve this problem,
        i.e. latexmk compiles the file.

        I don’t know how to fix this, so that latextools would run the correct command, however.

      • You will need to edit the “command” option. Check the README (Settings section). Unfortunately some distros want a space, some don’t. Not sure why. So you need to fix it up yourself. On Mar 13, 2014 7:53 AM, “Tech, TeX and Theory” wrote:


  5. Yes indeed, i fixed this allready by myself.
    With the spaces between the = it doesnt work for me either when typing in the console.

  6. Hello, Since the new Latex update I get an error message when I open Sublime Text 2 on my Mac:
    “Error trying to parse file: Trailing comma before closing bracket in ~ / Library/Application Support/Sublime Text 2/ Packages/User/ Default (OSX).sublime keymap:290:3″
    I opened the sublime keymap file and I saw that it was empty with just a pair of brackets.
    I’m new to Sublime Text and LatexTools and am not sure what to do to fix this.

    • I pushed an update earlier today that should have fixed that…

      On Thu, Mar 13, 2014 at 4:48 PM, Tech, TeX and Theory wrote:


      • Hello,

        The problem does not seem to be resolved. I even uninstalled and reinstalled LatexTools but the message keeps coming back. It was even showing after LatexTools was uninstalled.

  7. Hi, before the update I was able to run the pdf viewer without having SumatraPDF by adding “–run-viewer” in the Windows-related cmd part in LaTeX.sublime-build. Any suggestions on what I should do after the update?

  8. hey I was wondering if there is a way to have set the output directory(for all the .log, .pdf, .aux etc). Before using your plugin I was using texshop and this script .
    Unfortunately I have no clue how to integrate this within your plugin.
    I hope you can point me in the right direction.

  9. Craig Hutchinson

    Thank you for this awesome tool. I’m trying to update the builder_settings portion of LaTeXTools.sublime-settings to use the xelatex compiler in OS X, but I’m not able to make the build do anything except pdflatex. Would you please post a snippet of “builder_settings” for OS X that shows the entire “program” and “command” structure appropriate for XeLaTeX? Thanks again.

    • Craig Hutchinson

      As a follow up, I am able to switch to XeLaTeX if I put the “command” configuration `”command” : [ "latexmk", "-cd", "-xelatex", "-f", "-pdf"]` above the platform-specific settings, but if I put it inside the “osx” section, the build reverts to pdflatex.

  10. Tyler Standish

    If you go to advanced setting in SumatraPDF and place the line:

    InverseSearchCmdLine = “C:\Program Files\Sublime Text 3\sublime_text.exe” “%f:%l”

    would this not satisfy the inverse search command without having to load a specific file or run the command line? I only found this after running the command line so I’m not sure if the advanced options feature is available prior to it, but thought I would raise the question.

    Thank you for LaTeXTools, it is fantastic!

    Tyler Standish

  11. Any ideas why when using “simple” the builder cannot recognize the new citation entry (just a bold text) while “default” does (show correct citaion). I want to use “simple” builder since it seems require less computer resources (On Ubuntu 14).

  12. shriram srinivasan
    • Unfortunately what you need to do is not feasible at the moment. The new build code bypasses the variants mechanism. If there is enough demand, I could implement it though.

      On Sun, Jun 22, 2014 at 6:20 PM, Tech, TeX and Theory wrote:


  13. Hi, thanks for sharing your knowledge with us!
    I recently migrated from Notepad++ to Sublime Text and I use LaTeX very extensively.

    Just like bibtex, I’d suggest makeindex should also be an out-of-the-box feature for LaTeX! Could you help in making it possible to build glossaries via LaTeXTools without the user necessarily writing a custom build to achieve this?

    I currently use these settings [ ] with Notepad++ to achieve this!



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s