doc/automake.mom

   1 .\" -*- mode: text; coding: utf-8; -*-
   2 .\"
   3 .\" Copyright ©2014, 2017 Free Software Foundation
   4 .\" 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
   5 .\"
   6 .\" Permission is hereby granted, free of charge, to any person
   7 .\" obtaining a copy of this software and associated documentation
   8 .\" files (the "Software"), to deal in the Software without restriction,
   9 .\" including, without limitation, the rights to use, copy, modify,
  10 .\" merge, publish, distribute, sublicense, and sell copies of
  11 .\" the Software, and to permit persons to whom the Software is
  12 .\" furnished to do so, subject to the following conditions:
  13 .\"
  14 .\" The above copyright notice and this permission notice shall be
  15 .\" included in all copies, or substantial portions, of the Software;
  16 .\"
  17 .\" THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND,
  18 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  19 .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
  20 .\" NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  21 .\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
  22 .\" WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
  23 .\" FROM, OUT OF, OR IN CONNECTION WITH, THE SOFTWARE, OR THE USE OF,
  24 .\" OR OTHER DEALINGS IN, THE SOFTWARE.
  25 .\"
  26 .\"  Formatted with the mom macros
  27 .\" .RW (reduce) and .EW (expand) control track kerning
  28 .\" .WS controls word spacing
  29 .\"  Hanging punctuation and hyphens are inserted manually
  30 .\"
  31 .TITLE     "Using Automake in the Groff project"
  32 .AUTHOR    "Bertrand Garrigues"
  33 .COPYRIGHT "2014, 2017 Free Software Foundation"
  34 .COVER     TITLE AUTHOR DOCTYPE COPYRIGHT
  35 .
  36 .PAPER      LETTER
  37 .PRINTSTYLE TYPESET
  38 .
  39 .HEADING_STYLE 1 NUMBER
  40 .HEADING_STYLE 2 NUMBER
  41 .HEADING_STYLE 3 NUMBER
  42 .HEADING_STYLE 4 NUMBER
  43 .
  44 .QUOTE_INDENT 2m
  45 .CODE_FONT CB
  46 .
  47 \# Table of contents
  48 .TOC_PADDING 2
  49 .SPACE_TOC_ITEMS
  50 .AUTO_RELOCATE_TOC
  51 .TOC_ENTRY_STYLE 2 FONT I
  52 .TOC_LEAD 14
  53 .
  54 .NO_SHIM \" Flex-spaced
  55 .
  56 .START
  57 .
  58 .PP
  59 This is a quick overview of how to use `automake' in the groff
  60 project, and is intended to help the developers and contributors
  61 find their way when they have to make changes to the sources files
  62 or to the data that are installed.  If you need more details on
  63 `automake', here are some reading suggestions:
  64 .
  65 .LEFT
  66 .SP 3p
  67 .
  68 .LIST
  69 .SHIFT_LIST 1m
  70 .ITEM
  71 The Automake Manual:
  72 \*[FWD 1m]\c
  73 .PDF_WWW_LINK https://www.gnu.org/software/automake/manual/automake.html
  74 .SP 3p
  75 .ITEM
  76 A book by John Calcote, with good practical examples:
  77 \*[FWD 1m]\c
  78 .PDF_WWW_LINK http://fsmsh.com/2753
  79 .SP 3p
  80 .ITEM
  81 This site, by Diego Petteno, with good practical examples too:
  82 \*[FWD 1m]\c
  83 .PDF_WWW_LINK https://autotools.io/index.html
  84 .LIST OFF
  85 .
  86 .JUSTIFY
  87 .HY DEFAULT
  88 .
  89 .HEADING 1 "Overview, the initial build"
  90 .
  91 .HEADING 2 "First build"
  92 .
  93 .PP
  94 Groff integrates the `gnulib' and uses its `bootstrap' script.  When
  95 compiling from the git repository, you should first invoke this
  96 script:
  97 .QUOTE
  98 .CODE
  99 $ ./bootstrap
 100 .CODE OFF
 101 .QUOTE OFF
 102 This will:
 103 .
 104 .QUAD LEFT
 105 .HY OFF
 106 .
 107 .LIST
 108 .SHIFT_LIST 1m
 109 .ITEM
 110 .SP 3p
 111 Clone the gnulib repository as a git submodule in 'gnulib',
 112 add the needed gnulib sources files in `lib',
 113 add the needed gnulib m4 macros in `gnulib_m4'.
 114 .SP 3p
 115 .ITEM
 116 Invoke autoreconf that will call all the `GNU autotools' (`aclocal',
 117 `autoheader', `autoconf', `automake') in the right order for
 118 creating the following files:
 119 .LIST DASH
 120 .SHIFT_LIST .5m
 121 .SP 3p
 122 .ITEM
 123 INSTALL (a symlink to gnulib's INSTALL file)
 124 .ITEM
 125 Makefile.in
 126 .ITEM
 127 aclocal.m4
 128 .ITEM
 129 autom4te.cache/
 130 .ITEM
 131 build-aux/ (that contains all the helper scripts)
 132 .ITEM
 133 configure
 134 .ITEM
 135 src/include/config.hin
 136 .LIST BACK
 137 .LIST OFF
 138 .
 139 .SP 3p
 140 .JUSTIFY
 141 .HY DEFAULT
 142 .
 143 .WS +2
 144 .EW .5
 145 Note that aclocal.m4 is generated and the groff m4 macros are
 146 included via the acinclude.m4 file.
 147 .WS DEFAULT
 148 .EW 0
 149 .
 150 .PP
 151 At this point you can invoke the `configure' script and call `make'
 152 to build the groff project.  You can do it in the source tree:
 153 .QUOTE
 154 .CODE
 155 $ ./configure
 156 $ make
 157 .CODE OFF
 158 .QUOTE OFF
 159 You can also build groff in an out-of-source build tree, which is
 160 cleaner:
 161 .QUOTE
 162 .CODE
 163 $ mkdir build
 164 $ cd build
 165 $ ../configure
 166 $ make
 167 .CODE OFF
 168 .QUOTE OFF
 169 Note that parallel build is also supported and `make' can be invoked
 170 with the -j option, which will greatly speed up the build.
 171 .
 172 .HEADING 2 "Automake in the autotools process"
 173 .
 174 .PP
 175 Automake's main job is to generate a Makefile.in file (this file is
 176 maintained manually on projects using only autoconf).  The main file
 177 processed by `automake' is the Makefile.am file, which eventually
 178 generates a Makefile.  The (simplified) process is:
 179 .
 180 .SP 3p
 181 .QUAD LEFT
 182 .HY OFF
 183 .
 184 .LIST
 185 .SHIFT_LIST 1m
 186 .ITEM
 187 `aclocal' generates the `aclocal.m4' file from `configure.ac' and
 188 the user-defined macros in `acinclude.m4'.
 189 .ITEM
 190 `autoheader' generates config.h.in.
 191 .ITEM
 192 `autoconf' generates the `configure' script from `aclocal.m4' and `configure.ac'
 193 .ITEM
 194 `automake' generates Makefile.in from Makefile.am and the
 195 `configure.ac' file.  It also generates some helper scripts, on the
 196 groff project they are located in build-aux.
 197 .ITEM
 198 `configure' generates `config.status'
 199 .ITEM
 200 `config.status' generates the Makefile and config.h.
 201 .LIST OFF
 202 .
 203 .SP 3p
 204 .JUSTIFY
 205 .HY DEFAULT
 206 .
 207 .WS -2
 208 .RW .16
 209 Finally, `autoreconf' is the program that can be used to call these
 210 various tools in the correct order.
 211 .RW 0
 212 .WS DEFAULT
 213 .
 214 .PP
 215 Automake defines a set of special variables that are used to
 216 generate various build rules in the final Makefile.  Note however
 217 that if Automake's pre-defined rules are not enough, you still have
 218 the possibility of adding handwritten standard `make' rules in a
 219 Makefile.am; these rules will be copied verbatim in the Makefile.in
 220 and then in the final Makefile.
 221 .
 222 .HEADING 2 "Modification of autotools files"
 223 .
 224 .PP
 225 Previously, when groff used `autoconf' only and not `automake',
 226 you had to invoke manually the autotools, depending on what you
 227 modified.  For example, to change the file `aclocal.m4', you had
 228 to run the shell command 'aclocal -I m4'; to recreate the files
 229 `configure' and `Makefile', you had to use the command 'autoreconf
 230 - I m4'.
 231 .PP
 232 Now, as groff uses `automake', you don't need to run `autoreconf'.
 233 If you make some changes in Makefile.am or configure.ac, all the
 234 files that need to be updated will be regenerated when you execute
 235 `make'.
 236 .
 237 .HEADING 1 "Building a program"
 238 .
 239 .HEADING 2 "A program and its source files"
 240 .
 241 .PP
 242 Generally speaking, when using `automake' you will have to write a
 243 Makefile.am file and use the variable \*[CODE]bin_PROGRAMS\*[CODE OFF]
 244 to declare a program that should be built, and then list the
 245 sources of this program in a variable that starts with the name of
 246 your program and ends with \*[CODE]_SOURCES\*[CODE OFF]\&.  In the
 247 groff project we have only 1 top-level Makefile.am that includes
 248 several .am files.
 249 .PP
 250 Take for example the build of grolbp, in src/devices/grolbp/grolbp.am.
 251 The file starts with:
 252 .QUOTE ADJUST -4p
 253 .CODE
 254 bin_PROGRAMS += grolbp
 255 .CODE OFF
 256 .QUOTE OFF
 257 This says that a program named `grolbp' is added to the list of the
 258 programs that should be built.  Note that \*[CODE]bin_PROGRAMS\*[CODE OFF]
 259 is initialized to an empty string in the top-level Makefile.am,
 260 which includes grolbp.am.  (We will see later why we don't write
 261 directly
 262 \*[CODE]bin_PROGRAMS\~=\~grolbp\*[CODE OFF] in a Makefile.am in the
 263 grolbp directory.)
 264 .PP
 265 Then, we list the sources of grolbp like this:
 266 .QUOTE ADJUST -4p
 267 .IL 1m
 268 .HI 1m
 269 .CODE
 270 grolbp_SOURCES = \\
 271 src/devices/grolbp/lbp.cpp \\
 272 src/devices/grolbp/lbp.h \\
 273 src/devices/grolbp/charset.h
 274 .CODE OFF
 275 .QUOTE OFF
 276 .ILQ
 277 As you added `grolbp' to \*[CODE]bin_PROGRAMS\*[CODE OFF],
 278 you need to define the sources of grolbp in the variable
 279 \*[CODE]grolbp_SOURCES\*[CODE OFF]\&.  If you write in another file
 280 \*[CODE]bin_PROGRAMS += foo\*[CODE OFF] you will list the sources
 281 of `foo' in \*[CODE]foo_SOURCES\*[CODE OFF]\&.
 282 .PP
 283 With these two statements, the resulting generated Makefile
 284 will contain everything that is needed to build, clean,
 285 install and uninstall the `grolbp' binary when invoking the
 286 adequate `make' command.  Also, the source files listed in
 287 \*[CODE]grolbp_SOURCES\*[CODE OFF] will automatically be included in
 288 the distribution tarball.  That is why the headers are also listed
 289 in \*[CODE]grolbp_SOURCES\*[CODE OFF]: it is not necessary to add
 290 them in order to correctly build `grolbp', but this way the headers
 291 will be distributed.  Note that:
 292 .
 293 .SP 3p
 294 .QUAD LEFT
 295 .HY OFF
 296 .
 297 .LIST
 298 .SHIFT_LIST 1m
 299 .ITEM
 300 The path to the files are relative to the top-level directory.
 301 .ITEM
 302 The binaries are generated in the top-level build directory.
 303 .ITEM
 304 The .o files are generated in the directory where the source files
 305 are located, or, in the case of an out-of-source build tree, in a
 306 directory that is the replication of the source tree directory.
 307 For example if you built groff in a `build' directory, lbp.o
 308 (object file from src/devices/grolbp/lbp.cpp) will be located in
 309 build/src/devices/grolbp/lbp.o.
 310 .LIST OFF
 311 .
 312 .SP 3p
 313 .JUSTIFY
 314 .HY DEFAULT
 315 .
 316 We will also see later the reasons; this is due to the non-recursive
 317 make design.
 318 .
 319 .HEADING 2 "Linking against a library"
 320 .
 321 .PP
 322 To list which libraries grolbp needs to link against, we just write:
 323 .QUOTE
 324 .IL
 325 .HI
 326 .CODE
 327 grolbp_LDADD = $(LIBM) \\
 328 libdriver.a \\
 329 libgroff.a \\
 330 lib/libgnu.a
 331 .CODE OFF
 332 .QUOTE OFF
 333 .ILQ
 334 Again, we use the variable \*[CODE]grolbp_LDADD\*[CODE OFF] because
 335 we added a program named `grolbp'.  This will also automatically
 336 set build dependencies between `grolbp' and the libraries it needs:
 337 `libdriver.a' and `libgroff.a', that are convenience libraries built
 338 within the groff project, will be compiled before grolbp.
 339 .
 340 .HEADING 2 "Preprocessor flags"
 341 .
 342 .PP
 343 Preprocessor flags that are common to all the binaries are listed
 344 in the variable \*[CODE]AM_CPPFLAGS\*[CODE OFF] in the top-level
 345 Makefile.am.  If a `foo' binary needs specific preprocessor
 346 flags, use \*[CODE]foo_CPPFLAGS\*[CODE OFF], for example, in
 347 src/devices/xditview/xditview.am, extra flags are needed to build
 348 gxditview and are added like this:
 349 .QUOTE
 350 .IL
 351 .HI
 352 .CODE
 353 gxditview_CPPFLAGS = $(AM_CPPFLAGS) $(X_CFLAGS) -Dlint \\
 354 -I$(top_builddir)/src/devices/xditview
 355 .CODE OFF
 356 .QUOTE OFF
 357 .ILQ
 358 .PP
 359 The use of specific CPPFLAGS changes the name of the generated objects:
 360 the .o object files are prefixed with the name of the program.
 361 For example, the .o file corresponding to src/devices/xditview/device.c
 362 will be src/devices/xditview/gxditview-device.o.
 363 .
 364 .HEADING 2 "Cleaning"
 365 .
 366 .PP
 367 You don't need to write rules to clean the programs listed in
 368 \*[CODE]bin_PROGRAMS\*[CODE OFF], `automake' will write them for
 369 you.  However, some programs might have generated sources that
 370 should be cleaned.  In this case, you have mainly two special
 371 variables to list extra files that should be cleaned:
 372 .
 373 .SP 3p
 374 .QUAD LEFT
 375 .HY OFF
 376 .
 377 .LIST
 378 .SHIFT_LIST 1m
 379 .ITEM
 380 \*[CODE]MOSTLYCLEANFILES\*[CODE OFF] for files that should be
 381 cleaned by `make mostlyclean'
 382 .ITEM
 383 \*[CODE]CLEANFILES\*[CODE OFF ] for files that should be cleaned by
 384 `make clean'
 385 .LIST OFF
 386 .
 387 .JUSTIFY
 388 .HY DEFAULT
 389 .SP 3p
 390 .
 391 There is also the possibility of writing custom rules.  We will see
 392 that later.
 393 .
 394 .HEADING 2 "Dependencies"
 395 .
 396 .PP
 397 We have already seen that when linking against a convenience
 398 library, the dependencies are already created by `automake'.
 399 However, some dependencies still need to be manually added, for
 400 example when a source file includes a generated header.  In this
 401 case, the easiest way is to add a plain-make dependency.  For
 402 example, src/roff/groff/groff.cpp includes defs.h, which is a
 403 generated header.  We just add in src/roff/groff/groff.am:
 404 .QUOTE
 405 .CODE
 406 src/roff/groff/groff.$(OBJEXT): defs.h
 407 .CODE OFF
 408 .QUOTE OFF
 409 .
 410 .HEADING 2 "Scripts"
 411 .
 412 .PP
 413 Apart from \*[CODE]bin_PROGRAMS\*[CODE OFF], there is another
 414 similar special variable for scripts:  \*[CODE]bin_SCRIPTS\*[CODE OFF]\&.
 415 The scripts listed in this variable will automatically be
 416 built (of course you have to provide your custom rule to build the
 417 script), installed and uninstalled when invoking 'make', 'make
 418 install' and 'make uninstall'.  The main difference is that unlike
 419 the programs listed in \*[CODE]bin_PROGRAMS\*[CODE OFF], the scripts
 420 will not be cleaned by default.  They are not distributed by default
 421 either.  In the groff project, \*[CODE]bin_SCRIPTS\*[CODE OFF] are
 422 cleaned because they are added to \*[CODE]MOSTLYCLEANFILES\*[CODE OFF]
 423 in the top-level Makefile.am.
 424 .PP
 425 A simple example are the gropdf and pdfmom scripts in
 426 src/devices/gropdf/gropdf.am:
 427 .CODE_SIZE 84
 428 .QUOTE_INDENT 1
 429 .QUOTE
 430 .CODE
 431 bin_SCRIPTS += gropdf pdfmom
 432   [...]
 433 gropdf: $(gropdf_dir)/gropdf.pl $(SH_DEPS_SED_SCRIPT)
 434         rm -f $@
 435         sed -f $(SH_DEPS_SED_SCRIPT) \\
 436             -e "s|[@]VERSION[@]|$(VERSION)|" \\
 437             -e "s|[@]PERL[@]|$(PERL)|" \\
 438             -e "s|[@]GROFF_FONT_DIR[@]|$(fontpath)|" \\
 439             -e "s|[@]RT_SEP[@]|$(RT_SEP)|" $(gropdf_dir)/gropdf.pl >$@
 440         chmod +x $@
 441
 442 pdfmom: $(gropdf_dir)/pdfmom.pl $(SH_DEPS_SED_SCRIPT)
 443         rm -f $@
 444         sed -f $(SH_DEPS_SED_SCRIPT) \\
 445             -e "s|[@]VERSION[@]|$(VERSION)|" \\
 446             -e "s|[@]PERL[@]|$(PERL)|" $(gropdf_dir)/pdfmom.pl >$@
 447         chmod +x $@
 448 .QUOTE OFF
 449 .QUOTE_INDENT 2m
 450 .CODE_SIZE 100
 451 Note that in this example the '@' symbol is protected by square
 452 brackets to prevent the substitution of the variable by `automake'.
 453 .
 454 .HEADING 1 "Non-recursive make schema"
 455 .
 456 .PP
 457 There are two possibilities for organizing the Makefile.am of a
 458 large project, using a recusive or a non-recursive `make'.
 459 .
 460 .HEADING 2 "1st possibility: make recursion"
 461 .
 462 .PP
 463 A top level Makefile.am includes another Makefile.am, using the
 464 \*[CODE]SUBDIRS\*[CODE OFF] directive, and the Makefile.am of each
 465 sub-directory lists the programs that should be built.  If we had
 466 chosen this type of organization, we would have a Makefile.am in
 467 src/devices/grolbp and in each directory that contain sources to
 468 build a program (tbl, eqn, troff etc ...).  We would write in the
 469 top-level Makefile.am:
 470 .QUOTE
 471 .IL
 472 .HI
 473 .CODE
 474 SUBDIRS = src/devices/grolbp \\
 475 \&... (and all the dir that build a program or a script)
 476 .CODE OFF
 477 .QUOTE OFF
 478 and in src/devices/grolbp, we would have a file Makefile.am that
 479 contains:
 480 .QUOTE
 481 .CODE
 482 bin_PROGRAMS = grolbp
 483 grolbp_SOURCES = lbp.cpp lbp.h charset.h
 484 .CODE OFF
 485 .QUOTE OFF
 486 .PP
 487 Only `grolbp' is affected to the variable \*[CODE]bin_PROGRAMS\*[CODE OFF]\&.
 488 It would be the same in, say, src/roff/troff: you would have a Makefile.am
 489 with \*[CODE]bin_PROGRAMS = troff\*[CODE OFF]\&.  We would have
 490 one generated Makefile per Makefile.am file: in the build tree
 491 you will have the top-level Makefile, grolbp's Makefile in
 492 src/devices/grolbp, troff's Makefile in src/roff/troff, and so on.
 493 When calling `make' to build everything, `make' will be recursively
 494 called in all the directories that have a Makefile.  Thus, the
 495 paths are logically relative to the directory that contains the
 496 Makefile.am.
 497 .PP
 498 This approach has the disadvantage of making dependencies harder
 499 to resolve: each Makefile does not know the targets of the other
 500 Makfiles.  It also makes the build slower.
 501 .
 502 .HEADING 2 "Non-recursive make used by the Groff project"
 503 .
 504 .PP
 505 The second possibility, which was chosen for the groff project, is to use
 506 a non-recursive make schema.  It is described in paragraph 7.3 of
 507 the Automake manual ("An Alternative Approach to Subdirectories"),
 508 based on the following paper from Peter Miller:
 509 .PDF_WWW_LINK http://miller.emu.id.au/pmiller/books/rmch/ \
 510   SUFFIX . "\*[IT]Recursive Make Considered Harmful\*[PREV]"
 511 .PP
 512 The idea is to have a single Makefile that contains all the rules.
 513 That is why we have only a single Makefile.am in the top-level
 514 directory which includes all the .am files that define rules
 515 to build the various programs.  The inclusion is done with the
 516 \*[CODE]include\*[CODE OFF] directive, not \*[CODE]SUBDIRS\*[CODE OFF]\&.
 517 Using 'include' is like copying the contents of the included
 518 file into the top-level Makefile.am, and will not generate other
 519 Makefile.
 520 .PP
 521 We first say in this top-level Makefile.am:
 522 .QUOTE
 523 .CODE
 524 bin_PROGAMS =
 525 .CODE OFF
 526 .QUOTE OFF
 527 and then all the .am files that define a program to be built (e.g.
 528 src/devices/grolbp/grolbp.am, src/roff/troff/troff.am, and so on)
 529 overload this variable, so that at the end, all the programs that
 530 should be built are listed in this \*[CODE]bin_PROGRAMS\*[CODE OFF]
 531 variable.  This is the reason why all the paths in the various .am
 532 files are relative to the top-level directory: at the end we will
 533 have only one Makefile in the top-level directory of the build tree.
 534 .PP
 535 As the resulting single Makefile knows all the targets, the
 536 dependencies are easier to manage.  The build is also faster,
 537 particularly when compiling a single file: `make' is called once only
 538 and the file will be instantly rebuilt, while on a recursive make
 539 system, `make' will have to be invoked in all the sub-directories.
 540 .PP
 541 Note also that in order to make `gnulib' work with this
 542 non-recursive schema, the `non-recursive-gnulib-prefix-hack'
 543 configuration should be selected in bootstrap.conf.
 544 .
 545 .HEADING 1 "Installing data"
 546 .
 547 .PP
 548 Variables that end with \*[CODE]_DATA\*[CODE OFF] are special
 549 variables used to list files that should be installed in a
 550 particular location.  The prefix of the variables should refer to
 551 another previously defined variable that ends with a `dir' suffix.
 552 This varibale that ends with `dir' defines where the files should be
 553 installed.
 554 .
 555 .HEADING 2 "A simple case"
 556 .
 557 .PP
 558 For example, in font/devX100/devX100.am, we can see this:
 559 .QUOTE
 560 .CODE
 561 if !WITHOUT_X11
 562 devX100fontdir = $(fontdir)/devX100
 563 devX100font_DATA = $(DEVX100FONTS)
 564 endif
 565 .SP
 566 EXTRA_DIST += $(DEVX100FONTS)
 567 .CODE OFF
 568 .QUOTE OFF
 569 .WS -4
 570 \*[CODE]DEVX100FONTS\*[CODE OFF] is just a list of font files,
 571 defined at the begining of devX100.am.  \*[CODE]fontdir\*[CODE OFF]
 572 is where all the font directories are installed, it is defined
 573 in the top-level Makefile.am.  The conditional
 574 \*[CODE]if\~!WITHOUT_X11\*[CODE OFF]
 575 is used to prevent the installation of
 576 these files if X11 is not available.
 577 .WS DEFAULT
 578 .PP
 579 We first define where we wants to install the devX100 fonts with:
 580 .QUOTE
 581 .CODE
 582 devX100fontdir = $(fontdir)/devX100
 583 .CODE OFF
 584 .QUOTE OFF
 585 Because we declared a variable ending with `dir', we are allowed
 586 to define \*[CODE]devX100font_DATA\*[CODE OFF] (you remove the
 587 `dir' suffix and add \*[CODE]_DATA\*[CODE OFF]).  Note that
 588 wildcards are not supported in the special variable that end with
 589 \*[CODE]_DATA\*[CODE OFF]\&.
 590 .PP
 591 With these two lines, `make install' will install the files
 592 listed in \*[CODE]DEVX100FONTS\*[CODE OFF] and `make uninstall'
 593 will uninstall them.  \*[CODE]devX100fontdir\*[CODE OFF] will be
 594 automatically created if missing during the installation
 595 process, but not removed during the uninstall.  The complete
 596 \*[CODE]fontdir\*[CODE OFF] is removed by a custom uninstall rule
 597 (uninstall_groffdirs in Makefile.am).
 598 .PP
 599 Because the files listed in \*[CODE]devX100font_DATA\*[CODE OFF]
 600 are not distributed by default, we explicitely added them to the
 601 \*[CODE]EXTRA_DIST\*[CODE OFF] variable, which lists all the files
 602 that should be distributed and that are not taken into account by
 603 the default automake rules.
 604 .QUOTE
 605 .CODE
 606   EXTRA_DIST += $(DEVX100FONTS)
 607 .CODE OFF
 608 .QUOTE OFF
 609 Another possibility would have been to add a `dist' prefix to the
 610 \*[CODE]devX100font_DATA\*[CODE OFF] variable, in this case the use
 611 of \*[CODE]EXTRA_DIST\*[CODE OFF] is useless (except of course if
 612 \*[CODE]WITHOUT_X11\*[CODE OFF] is true, in this case we don't
 613 install the files but we still have to distribute them):
 614 .QUOTE
 615 .CODE
 616 if !WITHOUT_X11
 617 devX100fontdir = $(fontdir)/devX100
 618 dist_devX100font_DATA = $(DEVX100FONTS)
 619 else
 620 EXTRA_DIST += $(DEVX100FONTS)
 621 endif
 622 .CODE OFF
 623 .QUOTE OFF
 624 .
 625 .HEADING 2 "Dealing with generated files"
 626 .
 627 .PP
 628 In the previous example, all the font files that must be installed
 629 were already present in the source tree.  But in some cases,
 630 you need to generate the files you intend to install.  In this
 631 case, the files should be installed but not distributed.  A
 632 simple way to deal with this is to add a `nodist' prefix to your
 633 \*[CODE]xxx_DATA\*[CODE OFF] variable.
 634 .PP
 635 For example in font/devps/devps.am, we have a list of
 636 font files already present in the source tree, defined
 637 by \*[CODE]DEVPSFONTFILES\*[CODE OFF], and another list
 638 of font files that are generated, listed in the variable
 639 \*[CODE]DEVPSFONTFILES_GENERATED\*[CODE OFF]\&.  They should all
 640 by installed in a `devps' directory under the fontdir.  Thus
 641 the following three lines, where we use the `dist' and `nodist'
 642 prefixes:
 643 .QUOTE
 644 .CODE
 645 devpsfontdir = $(fontdir)/devps
 646 dist_devpsfont_DATA = $(DEVPSFONTFILES)
 647 nodist_devpsfont_DATA = $(DEVPSFONTFILES_GENERATED)
 648 .CODE OFF
 649 .QUOTE OFF
 650 The generated files are not cleaned by default, thus we add:
 651 .QUOTE
 652 .CODE
 653 MOSTLYCLEANFILES += $(DEVPSFONTFILES_GENERATED)
 654 .CODE OFF
 655 .QUOTE OFF
 656 .
 657 .HEADING 1 "Extending Automake's rules"
 658 .
 659 .HEADING 2 "Local clean rules"
 660 .
 661 .PP
 662 In most of the cases, the files that need to be cleaned are
 663 automatically determined by `automake', or were added to the
 664 \*[CODE]MOSTCLEANFILES\*[CODE OFF] or \*[CODE]CLEANFILES\*[CODE OFF]
 665 variables.  However, you might need to define a specific rule
 666 to clean some files that were not added to any list.  Automake
 667 defines a set of targets to extend the clean targets with your
 668 own rules: clean-local, mostlyclean-local, distclean-local or
 669 maintainerclean-local.  An example of such extension exists in
 670 font/devpdf/devpdf.am: because some fonts are not explicitely listed
 671 in a \*[CODE]xxx_DATA\*[CODE OFF] variable but generated by a custom
 672 rule, we define an extra rule to extend the `mostlyclean' target:
 673 .CODE_SIZE 92
 674 .QUOTE
 675 .CODE
 676 mostlyclean-local: mostlyclean_devpdf_extra
 677 mostlyclean_devpdf_extra:
 678         @echo Cleaning font/devpdf
 679         rm -rf $(top_builddir)/font/devpdf/enc \\
 680           $(top_builddir)/font/devpdf/map;
 681         if test -d $(top_builddir)/font/devpdf; then \\
 682           for f in $(GROFF_FONT_FILES); do \\
 683             rm -f $(top_builddir)/font/devpdf/$$f; \\
 684           done; \\
 685         fi
 686 .CODE OFF
 687 .QUOTE OFF
 688 .
 689 .NO_FLEX OFF \" Prevent upcoming NEWPAGE from disabling flex-spacing.
 690 .HEADING 2 "Local install/uninstall rules and hooks"
 691 .
 692 .PP
 693 Similarly to the clean rules, there are extensions to install and
 694 uninstall rules.  They come with two flavous, local rules and hooks.
 695 .
 696 .SP 3p
 697 .QUAD LEFT
 698 .HY OFF
 699 .
 700 .LIST
 701 .SHIFT_LIST 1m
 702 .ITEM
 703 There are 2 rules to extend install commands: `install-exec-local'
 704 for binaries and `install-data-local' for data.
 705 .ITEM
 706 There is 1 uninstall local rule: `uninstall-local'.
 707 .LIST OFF
 708 .
 709 .SP 3p
 710 .JUSTIFY
 711 .HY DEFAULT
 712 .
 713 There are no garantees on the order of execution of these local
 714 rules.  An example of local rule is the installation of GXditview.ad
 715 and GXditview-color.ad files in src/devices/xditview/xditview.am: if
 716 theses files are already installed, the old files are first saved.
 717 Also, the final file that is installed is stripped from its .ad
 718 suffix.  Thus the usage of a custom rule rather than the definition
 719 of a \*[CODE]xxx_DATA\*[CODE OFF] variable:
 720 .FLEX
 721 .QUOTE
 722 .CODE
 723 # Custom installation of GXditview.ad and GXditview-color.ad
 724 install-data-local: install_xditview
 725 uninstall-local: uninstall_xditview
 726 .SP
 727 [...]
 728 install_xditview: $(xditview_srcdir)/GXditview.ad
 729         -test -d $(DESTDIR)$(appresdir) \\
 730           || $(mkinstalldirs) $(DESTDIR)$(appresdir)
 731         if test -f $(DESTDIR)$(appresdir)/GXditview; then \\
 732           mv $(DESTDIR)$(appresdir)/GXditview \\
 733             $(DESTDIR)$(appresdir)/GXditview.old; \\
 734         fi
 735         [...]
 736         $(INSTALL_DATA) $(xditview_srcdir)/GXditview.ad \\
 737           $(DESTDIR)$(appresdir)/GXditview
 738 .CODE OFF
 739 .QUOTE OFF
 740 .PP
 741 Hooks, on the other hand, are garanteed to be executed after all the
 742 standard targets have been executed.
 743 .BR
 744 .SP 3p
 745 .QUAD LEFT
 746 .HY OFF
 747 .
 748 .LIST
 749 .SHIFT_LIST 1m
 750 .SP 3p
 751 .ITEM
 752 There are 2 install hooks: `install-exec-hook' and
 753 `install-data-hook'.
 754 .ITEM
 755 There is 1 uninstall hook: `unintall-hook'
 756 .LIST OFF
 757 .
 758 .SP 3p
 759 .JUSTIFY
 760 .HY DEFAULT
 761 .
 762 .PP
 763 An example of hook is the `uninstall_groffdirs' rule in the
 764 top-level Makefile.am.  This hook is used to remove all the
 765 directories specific to groff introduced by the installation
 766 process.  Obviously it could not be a local extension of `uninstall'
 767 because the order of execution is not guaranteed.
 768 .QUOTE
 769 .CODE
 770 # directories specific to groff
 771 uninstall-hook: uninstall_groffdirs
 772 uninstall_groffdirs:
 773         if test -d $(DESTDIR)$(datasubdir); then \\
 774           rm -rf $(DESTDIR)$(fontdir); \\
 775           rm -rf $(DESTDIR)$(oldfontdir); \\
 776           rmdir $(DESTDIR)$(datasubdir); \\
 777         fi
 778         [...]
 779 .CODE OFF
 780 .QUOTE OFF
 781 .TOC
 782 .\" Local Variables:
 783 .\" mode: nroff
 784 .\" End:
 785 .\" vim: filetype=groff: