Use CMake to easily compiles Latex documents into PDF

Everyone who compiles Latex documents by hand knows that it is not a panacea. You have to compile the file several times to handle the references. Moreover, if you have a glossary or an index, you have to run others commands between Latex commands so that everything is correctly resolved. The better way to handle Latex compilation is to write a MakeFile compiling each part. However, writing a Latex MakeFile by hand is not easy and especially not interesting.

Using CMake for most of my development projects, I tried to find a CMake script to generates a MakeFile easily. I did found a good script for that, but I wanted to add some features and change some things, so I forked it to Github: The CMakeLatex repository.

Usage

Here is an example using all the features of the script for one of my Latex documents.

PROJECT(master_project NONE)
cmake_minimum_required(VERSION 2.8)
SET(LATEX_OUTPUT_PATH build)
INCLUDE(UseLATEX.cmake)

file(GLOB_RECURSE contents_files RELATIVE ${CMAKE_SOURCE_DIR} contents/*.tex)

ADD_LATEX_DOCUMENT(
    master.tex
    INPUTS ${contents_files}
    IMAGE_DIRS images
    BIBFILES bibliography.bib
    USE_INDEX
    USE_GLOSSARY
    FILTER_OUTPUT
    )

To use it, you have to download the files of the repository and put them aside your Latex files (or just make symlinks to the files in a clone of the repository for easy update). Then, the UseLATEX.cmake file has to be included in your CMakeLists.txt file.

I think that it is a good practice to generates the Latex files in another directory. This directory can be set using the LATEX_OUTPUT_PATH variable.

Then, to add a latex document, you can use the ADD_LATEX_DOCUMENT function. The first parameter is the name of the main Latex file. After that, you have to give several parameters:

• INPUTS: It needs the list of Latex files that are included in master file. I use the GLOB_RECURSE function to find all of them in a contents subfolder.
• IMAGE_DIRS: The directory where the image are stored. They will be copied to the build folder and automatically converted if necessary.
• BIBFILES: If you have a bibliography, you just have to list all the .bib files of your project.
• USE_INDEX: Necessary only if your document use an index.
• USE_GLOSSARY: Necessary only if your document use a glossary.
• FILTER_OUTPUT: This option activates the filtering of pdflatex output to the console. For now, the option is quite limited, but it allows you to have a smoother output. It has to be taken into account that this option hides the overflow and underflow warnings.
• CONFIGURE: You can use the CMake configuration feature on some of your files if you want CMake variables to be replaced in the documents.

Once your Latex document is configured, you can just run cmake on your project. After that, you can use targets to generate pdf:

• make pdf: This will generate the Latex file using several passes and running all the necessary commands.
• make fast: This will generate a pdf in only one pass. This can be useful if you want to see a rough draft of your document quickly.

I already use this script for several of my documents. I hope that it will be useful for some of you. If you want any problem in the script or in the generate make file or if you have an idea for improvement, don't hesitate to let a command or to publish an Issue or a Pull Request in the CMakeLatex repository.

This script only support pdflatex and can only generates pdf directly. If you want latex support with dvi/ps/pdf generation, you should take a look at the original project: CMakeUserUseLATEX

Related articles