[Translation] Building Latex Documents with Waf
This is a revised and updated translation of an article about the multifunctional Waf assembly system.
From the very beginning of using Dropbox to store my research and projects, I began to look for a solution that will allow me to build LaTeX documents without clogging the document catalog. Under normal conditions, I simply ignore such files, but under Dropbox, every time after building a document, files start to synchronize with the server. Since there is no way to specify the files to be ignored in Dropbox (if someone from the company reads this message, please make a .dropboxignore file), I started looking for another solution.
In the beginning, I used a Makefile with a sequence of commands that made a copy of the project directory, moved to a temporary directory, and then executed the required commands.
Although this solution worked, it didn’t allow doing anything non-trivial. Instead of moving the project to a temporary directory, I could use one of the large Latex Makefiles that perform more complex tasks, such as automatic dependency determination, etc. However, combining a temporary build directory with a nontrivial makefile is a very difficult task.
A few months ago, I saw a blog post by Alan LaMielle, in which he talked about the experience of using the waf assembly system . Waf is written in Python and is positioned as a build system that supports this programming language and is a powerful tool, which in my opinion is completely untrue. Waf is distributed as a single python script, which, when first started, unpacks the library into a hidden directory and starts working. It comes with support for several programming languages, including Go, Python, LaTeX, and even the good old C. The scripts described below should work without problems with waf, starting with version 1.6, which includes all the required features.
')
Setting up waf is to write a python script named wscript , which is placed in the directory with your project. The file contains details regarding the assembly of your project. For the LaTeX document I am writing now, I use wscript with the following content:
Before I start building a document for the first time, I run
to set the build directory. If I want to see the resulting PDF, then I just add the option --view .
A typical wscript file contains the configure configuration function, which is called when the user executes waf configure . In our function, we make sure that there are tools for working with tex (the line conf.check_tool ('tex') is responsible for this) and the utility pdflatex. In addition, to build, we need the dot command line utility, the existence of which we also check. Here is an example of a typical output from the waf configure operation:
As you can see the configuration script found all the necessary programs and set up the build system.
The build function is fairly straightforward and straightforward: first, we iterate through all the .dot files in the directory, adding an assembly rule for each of them. This rule creates a mapping from a .dot file to a .pdf file and wherever these .pdf files are included in the original LaTeX document, the build system adds a dependency. As a result, when the source .dot file is modified, the .pdf files for this image and the main document will be automatically rebuilt.
The call to bld.add_group () says that the elements of the first group should be built before the elements of the second. The second group contains build rules that use programs from the Latex package. The build tool (pdflatex) and the source document name are determined.
The final touch of the build process is checking the view option. If this option is present, then we indicate to the system that after the assembly it is necessary to call the user function view_pdf . This function simply starts the system command and opens the resulting PDF file.
The view option is defined inside the options function ( options ) and is set by the user with the command line argument --view .
If you want to use the above wscript , then you need to change the name of the source document in it. Next you have to run waf configure , and after waf build to build the document. Your document may be simpler, so you can read an example of the corresponding wscript for LaTeX from the waf repository.
The advantage of building a document with Waf is that the dependencies of the original document are automatically tracked (the system scans the original tex files), so any changes to the files on which the document depends (including files with graphics) will cause the restructuring of the final pdf.
References:
From the very beginning of using Dropbox to store my research and projects, I began to look for a solution that will allow me to build LaTeX documents without clogging the document catalog. Under normal conditions, I simply ignore such files, but under Dropbox, every time after building a document, files start to synchronize with the server. Since there is no way to specify the files to be ignored in Dropbox (if someone from the company reads this message, please make a .dropboxignore file), I started looking for another solution.
Dark Times: Makefile
In the beginning, I used a Makefile with a sequence of commands that made a copy of the project directory, moved to a temporary directory, and then executed the required commands.
PROJECTNAME := thesisIntro<br/>
TMPDIR := / tmp / latexBuild.$ ( PROJECTNAME ) / <br/>
<br/>
view: pdf<br/>
-cd $ ( TMPDIR ) && open -a Preview introduction.pdf<br/>
<br/>
pdf: setup<br/>
-cd $ ( TMPDIR ) && pdflatex introduction<br/>
<br/>
setup:<br/>
-rm -fr $ ( TMPDIR ) <br/>
-mkdir $ ( TMPDIR ) <br/>
-cp -R * $ ( TMPDIR ) <br/>
<br/>
clean:<br/>
-rm -fr $ ( TMPDIR ) <br/>
Although this solution worked, it didn’t allow doing anything non-trivial. Instead of moving the project to a temporary directory, I could use one of the large Latex Makefiles that perform more complex tasks, such as automatic dependency determination, etc. However, combining a temporary build directory with a nontrivial makefile is a very difficult task.
New Alternative: Waf
A few months ago, I saw a blog post by Alan LaMielle, in which he talked about the experience of using the waf assembly system . Waf is written in Python and is positioned as a build system that supports this programming language and is a powerful tool, which in my opinion is completely untrue. Waf is distributed as a single python script, which, when first started, unpacks the library into a hidden directory and starts working. It comes with support for several programming languages, including Go, Python, LaTeX, and even the good old C. The scripts described below should work without problems with waf, starting with version 1.6, which includes all the required features.
')
Setting up waf is to write a python script named wscript , which is placed in the directory with your project. The file contains details regarding the assembly of your project. For the LaTeX document I am writing now, I use wscript with the following content:
#! /usr/bin/env python <br/>
<br/>
top = '.' <br/>
out = '/tmp/wafbuild-dphilconf' <br/>
<br/>
def configure ( conf ) :<br/>
conf. check_tool ( 'tex' ) <br/>
conf. find_program ( 'dot' , var= "DOT" ) <br/>
if not conf. env . PDFLATEX :<br/>
conf. fatal ( 'could not find the program pdflatex' ) <br/>
<br/>
def view_pdf ( bld ) :<br/>
bld. exec_command ( "open -a Preview \" {0}/dphilconf2010.pdf \" " . format ( out ) ) <br/>
<br/>
def build ( bld ) :<br/>
# , .dot- pdf <br/>
for x in bld. path . ant_glob ( '*.dot' ) :<br/>
tg = bld ( rule= '${DOT} -Tpdf -o${TGT[0].get_bld().abspath()} ${SRC[0].abspath()}' , source=x, target=x. change_ext ( '.pdf' ) ) <br/>
<br/>
bld. add_group ( ) <br/>
<br/>
obj = bld ( <br/>
features = 'tex' ,<br/>
type = 'pdflatex' ,<br/>
source = 'dphilconf2010.tex' ,<br/>
) <br/>
<br/>
if bld. options . view :<br/>
bld. add_post_fun ( view_pdf ) <br/>
<br/>
def options ( opt ) :<br/>
opt. tool_options ( 'tex' ) <br/>
<br/>
# <br/>
opt. add_option ( '--view' , action= 'store_true' , default= False , help = 'View the document' ) <br/>
Description: waf configure
Before I start building a document for the first time, I run
python waf configure
to set the build directory. If I want to see the resulting PDF, then I just add the option --view .
A typical wscript file contains the configure configuration function, which is called when the user executes waf configure . In our function, we make sure that there are tools for working with tex (the line conf.check_tool ('tex') is responsible for this) and the utility pdflatex. In addition, to build, we need the dot command line utility, the existence of which we also check. Here is an example of a typical output from the waf configure operation:
Setting top to: / Users / jnwhiteh / Dropbox / Academic / DPhilConf2010 Setting out to: / tmp / wafbuild-dphilconf Checking for program tex: / usr / texbin / tex Checking for program latex: / usr / texbin / latex Checking for program pdflatex: / usr / texbin / pdflatex Checking for program bibtex: / usr / texbin / bibtex Checking for program dvips: / usr / texbin / dvips Checking for program dvipdf: not found Checking for program ps2pdf: not found Checking for program makeindex: / usr / texbin / makeindex Checking for program pdf2ps: not found Checking for program dot: / usr / local / bin / dot 'configure' finished successfully (0.088s)
As you can see the configuration script found all the necessary programs and set up the build system.
Description: waf build
The build function is fairly straightforward and straightforward: first, we iterate through all the .dot files in the directory, adding an assembly rule for each of them. This rule creates a mapping from a .dot file to a .pdf file and wherever these .pdf files are included in the original LaTeX document, the build system adds a dependency. As a result, when the source .dot file is modified, the .pdf files for this image and the main document will be automatically rebuilt.
The call to bld.add_group () says that the elements of the first group should be built before the elements of the second. The second group contains build rules that use programs from the Latex package. The build tool (pdflatex) and the source document name are determined.
The final touch of the build process is checking the view option. If this option is present, then we indicate to the system that after the assembly it is necessary to call the user function view_pdf . This function simply starts the system command and opens the resulting PDF file.
The view option is defined inside the options function ( options ) and is set by the user with the command line argument --view .
Putting it all together
If you want to use the above wscript , then you need to change the name of the source document in it. Next you have to run waf configure , and after waf build to build the document. Your document may be simpler, so you can read an example of the corresponding wscript for LaTeX from the waf repository.
The advantage of building a document with Waf is that the dependencies of the original document are automatically tracked (the system scans the original tex files), so any changes to the files on which the document depends (including files with graphics) will cause the restructuring of the final pdf.
References:
Source: https://habr.com/ru/post/111623/
All Articles