mirandacong / bazel-latex

Bazel build system rules for LaTeX

Bazel rules for LaTeX

This repository provides Bazel rules for LaTeX, inspired by Klaus Aehlig's blog post on the matter.

Instead of depending on the host system's copy of LaTeX, these rules download a modular copy of TeXLive from GitHub. By using fine-grained dependencies, you will only download portions of TeXLive that are actually used in your documents.

As the output of the LaTeX tools is unnecessarily verbose, these build rules invoke LaTeX using latexrun. Errors and warnings are formatted simlar to those generated by Clang.

Using these rules

Add the following to WORKSPACE:

http_archive(
    name = "bazel_latex",
    sha256 = "<checksum>",
    strip_prefix = "bazel-latex-<release>",
    url = "https://github.com/ProdriveTechnologies/bazel-latex/archive/v<release>.tar.gz",
)

load("@bazel_latex//:repositories.bzl", "latex_repositories")

latex_repositories()

And add the following load() directive to your BUILD files:

load("@bazel_latex//:latex.bzl", "latex_document")

You can then use latex_document() to declare documents that need to be built. Commonly reused sources (e.g., templates) can be placed in filegroup() blocks, so that they don't need to be repeated.

latex_document(
    name = "my_report",
    srcs = glob([
        "chapters/*.tex",
        "figures/*",
    ]) + [":company_style"],
    main = "my_report.tex",
)

filegroup(
    name = "company_style",
    srcs = glob([
        ...
    ]),
)

As lualatex is effectively invoked as if within the root of the workspace, all imports of resources (e.g., images) must use the full path relative to the root.

A PDF can be built by running:

bazel build :my_report

It can be viewed using your system's PDF viewer by running:

bazel run :my_report_view

Using packages

By default, latex_document() only provides a version of TeXLive that is complete enough to build the most basic documents. Whenever you use \usepackage{} in your documents, you must also add a corresponding dependency to your latex_document(). This will cause Bazel to download and expose those packages for you. Below is an example of how a document can be built that depends on the Hyperref package.

latex_document(
    name = "hello",
    srcs = ["@bazel_latex//packages:hyperref"],
    main = "hello.tex",
)

This repository provides bindings for most commonly used packages. Please send pull requests if additional bindings are needed.

Platform support

These rules have been tested to work on:

• FreeBSD 11.2, building locally.
• macOS Mojave 10.14, building locally.
• Ubuntu 18.04, building locally.
• Ubuntu 18.04, building on a Debian 8 based Buildbarn setup.
• Windows 10 1803, building on a Debian 8 based Buildbarn setup.

These rules are known not to work on:

• Windows 10 1803, building locally.