Reproducible research documents using GNU make

Matthias Schwab and Joel Schroeder

matt@sep.Stanford.EDU, schroedr@sccm.Stanford.EDU

ABSTRACT

The Stanford Exploration Project (SEP) publishes scores of reproducible electronic research documents each year. Traditionally, researchers at SEP have used the makefile dialect cake to maintain their documents. Because of cake's limited distribution, we decided to replace it by GNU make. GNU make is an alternative make dialect that is widely used in software maintenance and is well documented. To allow an author to cope with document maintenance as opposed to software maintenance, Richard Stallman amended the original GNU make source code: a new GNU make special built-in target, .SECONDARY, enables the author to specify how to deal with missing files when checking if a target is up-to-date. Furthermore, the maintenance rules common to all reproducible documents were rethought when we translated them from cake to GNU make. The most significant change is the introduction of three result lists that distinguish between easily-reproducible, conditionally-reproducible, and non-reproducible results. A declaration of the results' reproducibility in the makefile simplified most of the crucial reproducibility rules (such as make burn, which removes all easily-reproducible results). We tested the new GNU make rules by translating Claerbout's three most recent textbooks. SEP plans to publish all its future reproducible documents using GNU make.