|
|
|
|
|
|
|
|
Most Linux users have at least heard of Makefiles, but many do not know how powerful a program make is. It is thought of as a tool for maintaining other programs, but it is far more. It can make sense out of chaos in any project where some files are created from other files, whether the end product is a program or a book or an automated post to Usenet. Even if you have never written a makefile, this tutorial will set you on your way to using make effectively.
by Michael K. Johnson
Many people are confused by make: maybe you are too. You know that it is hard to use, because it has a weird syntax unlike any other program you use. If you are lucky, you have been warned that it is important to have tab characters (not spaces) in certain places, and you know that if you mess up a makefile you won't be able to fix it.
Writing a makefile of your own is out of the question. It is difficult, and besides, you aren't really a programmer, anyway. What could this programmer's maintenance program do for you, and why should you learn its weird syntax? Or maybe you are a programmer, and you don't want to learn this tool called make, which has a syntax different from any language you have ever learned.
The reason for the weird syntax is that make does a job very different from normal programming tools, and it is well-suited to that very different job. Understanding the job is the first step to understanding make. Once you understand the job, and have learned a little bit about make, you will be able to write short, powerful makefiles.
We will pretend for the moment that you are writing a book, although the exact same ideas apply to writing a program. (I just want to emphasize that make isn't just for Real Programmers.) You are using LaTeX. Each chapter has several figures. These figures are done in xfig, and need to be converted to PostScript format with fig2dev before being included in your book.
Here comes the problem. You are occasionally editing the figures with xfig, and forgetting to make a PostScript copy of each figure when you are done, so you write a large shell script that converts xfig to encapsulated PostScript (EPS) for each figure. It is large, bulky, and inflexible, but you get the job done right each time you print. Unfortunately, it takes a while to convert all the files from xfig to encapsulated PostScript. Even if you have only made a minor change in one figure, it re-converts all of your figures. This is annoying, and takes a while for it to convert your 80 or so figures.
The intelligence of make is summarized by two concepts: dependencies and rules. You need to tell make that the dvi file (we'll call it book.dvi) needs to be created from the main LaTeX file (book.tex), and from the encapsulated PostScript files (*.eps). In make terminology, book.dvi depends on book.tex and *.eps. Also, each of the .eps files depends on the corresponding .fig file. You also need to give make rules for turning book.tex into book.dvi, and for turning the .fig files into .eps files.
Newbie Note:
All lines containing shell commands in your makefile must start with the TAB
character.
Here is an example of a makefile that will do everything that is necessary:
0: # This is a makefile to create book.dvi 1: EPSFIGS = fig1.eps fig2.eps fig3.eps fig4.eps \ 2: fig5.eps fig6.eps fig7.eps fig8.eps fig9.eps \ 3: <... more .eps files, too many to print ...> \ 4: fig78.eps fig79.eps fig80.eps fig81.eps 5: 6: book.dvi: book.tex $(EPSFIGS) 7: latex book.tex 8: 9: fig1.eps: fig1.fig 10: fig2dev -Lps fig1.fig fig1.eps 11: 12: fig2.eps: fig2.fig 13: fig2dev -Lps fig2.fig fig1.eps 14: <many more similar rules that you can imagine> 220:
This file can be saved as makefile or Makefile; either will work. If you have both files in the same directory, makefile will be used instead of Makefile. In addition, there are other names that can be used and rules to control that. See the GNU Make manual if you care (you usually won't). People almost always use Makefile because capital letters show up at the top of directory listings.
The first line, line 0, is a comment. Line 1 starts to define the variable EPSFIGS. The backslashes continue the line, so the EPSFIGS variable contains the names of all the EPS files from fig1.eps through fig81.eps, and logically all those lines are really one long line. Line 6 tells make that if book.tex or any of the .eps files are newer than book.dvi, then book.dvi has to be recreated. Line 7 explains how to do this. It is very important that this line start with a TAB character. This is how make knows that this is a shell command to be executed to update the dependency that preceeds it. Eight spaces will not work. Spaces can follow a tab, but the first character on that line must be a TAB. The rest of the lines work the same way: line 9 says that fig1.eps depends on fig1.fig, and line 10 tells make how to update fig1.eps from fig1.fig if fig1.fig has been updated since the last time fig1.eps was created.
Simply typing make will automatically make book.dvi, because the first target in the makefile (here consisting of lines 6 and 7) is the default target. You could conceivably type "make fig1.eps" to just update fig1.eps from fig1.fig, and that only if necessary. If it is not necessary, make will tell you "fig1.eps is up to date."
The basic syntax of a makefile can be simplified to this:
This makefile works until you define fig82.fig and forget to translate it into fig82.eps. It is also far longer than it needs to be. I will rewrite it to be much smaller, and at the same time work better. I'm going to assume that you are using GNU make, which is the standard make on Linux and some other systems. It is very easy to build on most other systems that you may have.
0: # This is an improved version of the makefile for 1: # making book.dvi 2: # FIG is a list of all the native xfig drawings 3: FIG = $(wildcard *.fig) 4: # EPS is a list of EPS files to create from the xfig files 5: EPS = $(subst .fig,.eps,$(FIG)) 6: 7: %.fig : %.eps 8: fig2dev -Lps $< $@ 9: 10: book.dvi: book.tex $(FIG) 11: latex book.tex 12: 13: print: book.dvi 14: dvips -r -Z -q book.dvi
This makefile does everything that the previous one did, and more. It introduces several new concepts along the way, some of which are unique to GNU make. The first, and perhaps the most obvious, is that I did not explicitly list all the .fig or .eps files. Listing all the files requires me to update the makefile each time I add a figure, which is rather error-prone. Using the GNU make wildcard function allows the makefile to automatically update the files correctly, no matter how many figures you add. If you choose to use it, be careful that you really mean to list all the files, and be aware that it will not work under most commercial vendors' versions of make.
GNU make has many functions like wildcard. Like variables, they are enclosed in $(...) (or ${...}), but you can distinguish functions from variables because the functions have embedded spaces. The name of the function comes first, with the argument, or comma-seperated list of arguments, following. They are all documented in Chapter 9, "Functions for Transforming Text", in the GNU Make manual. wildcard is equivalent to the shell "globbing" that you use every day on the command line (like ls *.fig) and subst works like a very simple version of sed (like sed 's/\.fig/\.eps/g'), replacing each instance of one substring in a string by a different substring.
Another GNU make feature used is called a "pattern rule". This is like a "suffix rule" as used in all versions of make (suffix rules still work in GNU make, don't worry), but is more powerful. The example given here is equivalent to the suffix rule
.fig.eps: fig2dev -Lps $< $@
but the pattern rule is a more general construct. Pattern rules may by preferable if you are writing makefiles for yourself or for projects where you can guarantee that GNU make will be used, and suffix rules are preferable if you are trying to write portable makefiles for all platforms.
The reason pattern rules are more powerful than suffix rules is they can match any sort of pattern, not just suffixes. For example:
foo.% : bar.%
would be a "prefix rule", which does not exist in other forms of make. Patterns are a more general concept than suffixes, and can be used in other ways in other kinds of rules. The GNU Make manual has examples of this.
The variables $< and $@ are special variables that can be used in rules. The $@ variable stands for the file that is being updated, the target which depends on the files that follow the ":" in the dependency. The $< variable stands for the files upon which the target depends. This is a standard make facility, and does not require GNU make.
Finally, this makefile uses a standard trick of defining a target that doesn't exist. Typing make print will print a copy of your book with everything up-to-date, even though there is no file called print. Similarily, since the first target is the default target, many makefiles have the first rule be a rule called "all:" which does whatever seems right when "everything" is to be built. In fact, the practice of typing "make all" instead of just "make" is so common that even when there is only one program to be built by default, some people will add an all target to their makefile even though it is not at all necessary:
0: all: foo
1:
2: foo: foo.o bar.o baz.o
<and so on>
instead of
0: foo: foo.o bar.o baz.o
<and so on>
This is only a taste of make. The GNU Make manual is a gentle, but much more thorough and correct introduction to GNU make, and is distributed with the GNU make source code. It does not assume that you already know how to use any version of make. On a properly installed system, it is available through the info system. The info files can be read from within Emacs (type C-h i from within Emacs) or from a standalone info reader such as info or tkinfo. Alternately, the book can be printed with the TeX typesetting system or ordered from the Free Software Foundation.
Michael K. Johnson is the editor of Linux Journal, but that doesn't keep him from hacking. He can be reached at ljeditor@ssc.com.
