[Translation] Build Latex documents using Waf
This is a revised and enlarged translation of the article on a multi-purpose build system Waf.
From the start of use of the service Dropbox to store my research and projects I was looking for a solution that will allow me to build a LaTeX document without clogging the directory with the document. Normally, I just ignore such files, but under Dropbox, each time after you build the document files are synchronized with the server. Since Dropbox is not possible to specify files to ignore (if someone from the company reads this message, please make a file .dropboxignore), I started looking for another solution.
In the beginning I used the Makefile with the command sequence which did copy the project directory moved to a temporary directory, and then perform the required command.
Although this solution worked, but it was not allowed to do anything non-trivial. I could instead move the project to a temporary directory to use one of the big Makefile for Latex performing more complex tasks such as automatic detection of dependencies, etc. However, the combination of the temporary directory for the Assembly with the trivial make-a halyard is a very difficult task.
A few months ago I saw blog post Alan LaMielle, in which he talked about the experience of using the build system waf. Waf is written in Python and positives as boldova system supporting this programming language and is a powerful tool that in my opinion completely untrue. Waf is distributed as a single python script that when first run, unpacks the library to a hidden directory and starts working. It comes with support for several programming languages, including Go, Python, LaTeX and even good old C. Scripts described below should work with waf, starting with version 1.6, which includes all the required features.
Setting 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 a LaTeX document that I'm writing, I use wscript with the following content:
Before you start to build a document for the first time, I run
to set the build directory. If I want to look at the resulting PDF, then I simply add the option --view.
Its typical file wscript contains the configuration feature configure, which is invoked when the user performs a waf configure. In our function we see that there are tools to work with tex (it is in the line conf.check_tool('tex')) and the tool pdflatex. In addition, for the Assembly we need a command-line dot, which we also check. Here is an example of a typical output of waf configure:
As you see the configuration script found all the necessary programs and made the setup of the build system.
The function of the Assembly is quite straightforward and clear: first, we iterate over all .dot-files in the directory adding build rule for each of them. This rule creates a mapping of .dot-file in .pdf file and everywhere where these .pdf files are included in the original LaTeX document boldova system adds the dependency. As a result, when you change the source .dot file will be automatically rebuilt .pdf files for this image and the master document.
The call to bld.add_group() says that the elements of the first group needs to be constructed before the elements of the second. The second group contains the build rules, using the program package Latex. Determined by the Assembly tool (pdflatex) and the name of the source document.
The final touch of the build process — check option view. If this option is present, then we indicate a system that, after Assembly, you must call a user-defined function view_pdf. This function simply runs a system command and opens the resulting PDF file.
Option view is defined inside the function options (options) and is specified by the user through command line argument --view.
If you want to use the above wscript, then you need to change the name of the source document. Next, you must perform waf configure, and after the waf build to build the document. Your document will probably be easier so you can find an example wscript for LaTeX from the waf repository.
The advantage of building a document by using the Waf that are automatically tracked based on the original document (the system scans the source tex files), so any changes to files that affect the document (including files with graphics) will cause a restructuring of the final pdf.
Links:
the
Article based on information from habrahabr.ru
From the start of use of the service Dropbox to store my research and projects I was looking for a solution that will allow me to build a LaTeX document without clogging the directory with the document. Normally, I just ignore such files, but under Dropbox, each time after you build the document files are synchronized with the server. Since Dropbox is not possible to specify files to ignore (if someone from the company reads this message, please make a file .dropboxignore), I started looking for another solution.
the Dark ages: Makefile
In the beginning I used the Makefile with the command sequence which did copy the project directory moved to a temporary directory, and then perform the required command.
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, but it was not allowed to do anything non-trivial. I could instead move the project to a temporary directory to use one of the big Makefile for Latex performing more complex tasks such as automatic detection of dependencies, etc. However, the combination of the temporary directory for the Assembly with the trivial make-a halyard is a very difficult task.
New alternative: Waf
A few months ago I saw blog post Alan LaMielle, in which he talked about the experience of using the build system waf. Waf is written in Python and positives as boldova system supporting this programming language and is a powerful tool that in my opinion completely untrue. Waf is distributed as a single python script that when first run, unpacks the library to a hidden directory and starts working. It comes with support for several programming languages, including Go, Python, LaTeX and even good old C. Scripts described below should work with waf, starting with version 1.6, which includes all the required features.
Setting 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 a LaTeX document that I'm writing, 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/>
def build a(bld):<br/>
# Create a rule that converts any .dot file to 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/>
# Add the command line option<br/>
opt.add_option('--view', action='store_true', default=False help='View the document')<br/>
Description: waf configure
Before you start to build a document for the first time, I run
python waf configure
to set the build directory. If I want to look at the resulting PDF, then I simply add the option --view.
Its typical file wscript contains the configuration feature configure, which is invoked when the user performs a waf configure. In our function we see that there are tools to work with tex (it is in the line conf.check_tool('tex')) and the tool pdflatex. In addition, for the Assembly we need a command-line dot, which we also check. Here is an example of a typical output of waf configure:
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.088 s)
As you see the configuration script found all the necessary programs and made the setup of the build system.
Description: waf build
The function of the Assembly is quite straightforward and clear: first, we iterate over all .dot-files in the directory adding build rule for each of them. This rule creates a mapping of .dot-file in .pdf file and everywhere where these .pdf files are included in the original LaTeX document boldova system adds the dependency. As a result, when you change the source .dot file will be automatically rebuilt .pdf files for this image and the master document.
The call to bld.add_group() says that the elements of the first group needs to be constructed before the elements of the second. The second group contains the build rules, using the program package Latex. Determined by the Assembly tool (pdflatex) and the name of the source document.
The final touch of the build process — check option view. If this option is present, then we indicate a system that, after Assembly, you must call a user-defined function view_pdf. This function simply runs a system command and opens the resulting PDF file.
Option view is defined inside the function options (options) and is specified by the user through 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. Next, you must perform waf configure, and after the waf build to build the document. Your document will probably be easier so you can find an example wscript for LaTeX from the waf repository.
The advantage of building a document by using the Waf that are automatically tracked based on the original document (the system scans the source tex files), so any changes to files that affect the document (including files with graphics) will cause a restructuring of the final pdf.
Links:
the
Комментарии
Отправить комментарий