Custom Builders

Custom Builders

This is a work-in-progress to add some documentation on how to write custom builders for LaTeXTools.

Since the release on March 13, 2014 (v3.1.0), LaTeXTools has had support for custom build systems, in addition to the default build system, called "traditional". Support for custom builders is provided using small Python scripts, called builders, that interact with the LaTeXTools build system. It is recommended that you have some basic familiarity with the Python language. It's quite simple and is the language virtually all Sublime Text plugins are written in.

LaTeXTools comes packaged with a small sample builder to demonstrate the basics of the builder system, called SimpleBuilder which can be used as a reference for what a builder might look like.

The Basics

Every builder consists of a single Python class called "WhateverBuilder" (so, for example, "TraditionalBuilder", "SimpleBuilder", etc.) which is a sub-class of a class called "PdfBuilder". Note that the class name should be unique (i.e., it can't share a name with any of the built-in builders) and it must end with "Builder". Each builder class implements a single generator function called commands() which is responsible for generating a list of commands to be run.

Below is a really simple builder that does nothing to demonstrate the basic structure of a builder:

# the pdfBuilder module will always be available on the PYTHONPATH
from pdfBuilder import PdfBuilder

class ReallySimpleBuilder(PdfBuilder):
    # for now, we are ignoring all of the arguments passed to the builder
    def __init__(self, *args):
        # call the __init__ method of PdfBuilder
        super(ReallySimpleBuilder, self).__init__(*args)
        
        # now we do the initialization for this builder
        # the only thing that must be set here is the builder name
        self.name = "Really Simple Builder"
    
    # commands is a generator function that yields the commands to be run
    def commands(self):
        # display a message in the build output console
        self.display("\n\nReallySimpleBuilder")
        
        # yield is how we pass the command to be run back to LaTeXTools
        #
        # each yield should yield a tuple consisting of the command to be run
        # and a message to be displayed, if any
        #
        # for the ReallySimpleBuilder, we yield ("", None) which tells
        # LaTeXTools there is no command to be run and no message to be
        # displayed
        yield ("", None)

To use this, save it to a file called "reallySimpleBuilder.py" in your LaTeXTools User package (you can find this folder by selecting Preferences|Browse Packages... or running the Preferences: Browse Packages command). Then, in your LaTeXTools preferences, change the "builder" setting to "reallySimple" and change the "builder_path" setting to "User". Try compiling a document. You should see a message that says [Compiling ...] and then the message we generated using self.display above.