[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 42/45: Fixes after final complete tests and documentation update
|
From: |
Bertrand Garrigues |
|
Subject: |
[groff] 42/45: Fixes after final complete tests and documentation update. |
|
Date: |
Tue, 11 Nov 2014 21:26:04 +0000 |
bgarrigues pushed a commit to branch automake3
in repository groff.
commit db92c1159c6c2074c449273c705d3988dbadb070
Author: Bertrand Garrigues <address@hidden>
Date: Sun Sep 21 20:50:12 2014 +0200
Fixes after final complete tests and documentation update.
Added a quick guide on the usage of automake in groff
(doc/automake.mom, must be manually generated with pdfmom).
* Makefile.am: distribute TESTS. and font/util/make-Rproto.
* contrib/hdtbl/hdtbl.am: contrib/hdtbl/examples/fonts_n.in and
fonts_x.in were not distributed. Examples (.ps files) of were
mistakenly distributed.
* contrib/mom/mom.am: Mom examples (pdf files) were mistakenly
distributed.
* contrib/pdfmark/pdfmark.am: pdfmark.pdf was mistakenly distributed.
* doc/doc.am: unprotected '@' in sed command symbols caused missing
substitution of @VERSION@ in some generated files.
* font/devpdf/devpdf.am: font/devpdf/util/BuildFoundries (generated)
was mistakenly distributed.
* src/preproc/pic/pic.am: .n was mistakenly distributed, pic.man was
not distributed.
* tmac/tmac.am: some generated files were mistakenly distributed.
* Updated INSTALL.REPO.
* doc/automake.mom: new file.
---
INSTALL.REPO | 101 +++++--
Makefile.am | 4 +-
TESTS | 108 ++++++--
contrib/hdtbl/hdtbl.am | 11 +-
contrib/mom/mom.am | 1 -
contrib/pdfmark/pdfmark.am | 4 +-
doc/automake.mom | 675 ++++++++++++++++++++++++++++++++++++++++++++
doc/doc.am | 4 +-
font/devpdf/devpdf.am | 2 +-
src/preproc/pic/pic.am | 4 +-
tmac/tmac.am | 3 +-
11 files changed, 865 insertions(+), 52 deletions(-)
diff --git a/INSTALL.REPO b/INSTALL.REPO
index 4cd6557..6e2a5c1 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -5,31 +5,65 @@
the copyright notice and this notice are preserved.
This file contains information that supplements the generic
-installation instructions in file `INSTALL.gen'. It is meant for
+installation instructions in file `INSTALL'. It is meant for
people building directly from the development repository, rather than
a release or snapshot tarball.
If you want to start compiling the `groff' system with an existing
-script `configure' you won't need the information in this file.
-
-But if you want to use the `GNU autotools' (`aclocal', `autoreconf')
-for creating the following and some more files:
-
- aclocal.m4
- configure
- Makefile
-
+script `configure' you won't need the information in this file. You
+need them only if you want to build groff from the git repository.
+
+1. Initial build
+----------------
+
+First invoke the bootstrap script:
+
+ $ ./bootstrap
+
+This will:
+
+ - clone the gnulib repository as a git submodule in 'gnulib', add
+ the needed gnulib sources files in 'lib', add the needed gnulib m4
+ macros in 'gnulib_m4'
+
+ - Invoke autoreconf that will call all the `GNU autotools'
+ (`aclocal', `autoconf', `automake') in the right order for
+ creating the following files:
+
+ -- INSTALL (a symlink to gnulib's INSTALL file)
+ -- Makefile.in
+ -- aclocal.m4
+ -- autom4te.cache/
+ -- build-aux/ (that contains all the helper scripts)
+ -- configure
+ -- src/include/config.hin
+
+Note that aclocal.m4 is generated and the groff m4 macros are included
+via the acinclude.m4 file.
+
+At this point you can invoke the `configure' script (that generates
+the `config.status' script; it is the `config.status' script generates
+the Makefile) and call 'make' to build the groff project. You can do
+it in the source tree:
+
+<<<<<<< HEAD
To update file `aclocal.m4', run the shell command
+=======
+ $ ./configure
+ $ make
+>>>>>>> Fixes after final complete tests:
- $ aclocal -I m4
+You can also build groff in an out of source build tree, which is cleaner:
-To recreate the files `configure' and `Makefile', use the shell
-command
+ $ mkdir build
+ $ cd build
+ $ ../configure
+ $ make
- $ autoreconf -I m4
+Note that parallel build is also supported and make can be invoked
+with the -j option, which will greatly speed up the build.
-The option `-I m4' is necessary. It refers to the subdirectory `m4'
-that has files with m4 macro definitions needed by the `autotools'.
+Notes:
If you use an old `autoreconf' version < 2.69, there might be an error
warning like:
@@ -44,18 +78,37 @@ warning like:
Just ignore this. It doesn't occur in the actual versions of
`autoreconf'.
-You may even use the shell command
+<<<<<<< HEAD
$ autoconf -I m4
+=======
+>>>>>>> Fixes after final complete tests:
+
+2. Modification of autotools files
+----------------------------------
+
+Previously, when groff used `autoconf' only and not `automake', you
+had to invoke manually the autotools, depending on what you
+modified. For example, to change the file `aclocal.m4', you had to run
+the shell command 'aclocal -I m4', to recreate the files `configure'
+and `Makefile', you had to use the command 'autoreconf -I m4'.
+
+Now, as groff uses `automake', you don't need to run `autoreconf'. If
+you make some changes in Makefile.am or configure.ac, all the files
+that need to be updated will be regenerated when you execute `make'.
+
+
+
+3. Quick start on the usage of `automake' in groff
+--------------------------------------------------
-instead of `autoreconf', but that will ignore some features. So
-`autoreconf' is better.
+A little document explaining the basics of automake and its usage in
+groff is available in doc/automake.mom. It is currently not
+automatically generated, to build it:
-`automake' is not used currently, however, we plan to convert the
-build system accordingly. If you have experience in creating
-`Makefile.am' files we would be glad if you could help us in the
-conversion process. Please contact the groff mailing list.
+pdfmom automake.mom > automake.pdf
+<<<<<<< HEAD
After the use of the `GNU autotools', the usual compilation should
work. If the run of `configure' produces error reports you have
produced errors in the `autotools' modification.
@@ -64,3 +117,5 @@ produced errors in the `autotools' modification.
Local Variables:
mode: text
End:
+=======
+>>>>>>> Fixes after final complete tests:
diff --git a/Makefile.am b/Makefile.am
index 8e5f95d..6ece629 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -807,7 +807,9 @@ EXTRA_DIST += \
PROBLEMS \
PROJECTS \
README.MinGW \
- arch/djgpp
+ TESTS \
+ arch/djgpp \
+ font/util/make-Rproto
MOSTLYCLEANFILES += $(prefixexecbin_SCRIPTS) $(bin_SCRIPTS) \
$(man1_MANS) $(man5_MANS) $(man7_MANS) \
diff --git a/TESTS b/TESTS
index 5c556ab..a7104f3 100644
--- a/TESTS
+++ b/TESTS
@@ -26,9 +26,80 @@ Current status
Tests
-----
+0. Sum up of a full test pass
+-----------------------------
+
+0.1. Build
+
+ ./bootstrap
+ mkdir build
+ cd build
+ ../configure
+ make -j
+
+0.2 Install
+
+ mkdir -p ~/tmp/automake
+ make install DESTDIR=~/tmp/automake
+
+-> Comparison with the tree installed by the the reference version
+
+ make uninstall DESTDIR=~/tmp/automake
+
+-> Check what is left in the installation tree
+
+ make uninstall DESTDIR=~/tmp/automake
+
+-> Check that this same command did not fail
+
+0.3 Distcheck
+
+ mkdir -p ~/tmp/distcheck
+ make distcheck DESTDIR=~/tmp/distcheck
+
+-> Will attempt to untar the dist, make an out-of-source build, clean
+ and check that nothing is level, install, uninstall and check that
+ nothing is left in the install tree. This should not fail.
+
+0.4 Dist
+
+ make dist
+
+-> Comparison of the generated tarball with the git tree
+-> Manually build an install from the tarball and compare the
+ installation tree with the reference version's installation tree.
+
+Note that discheck checks that install does not fail, uninstall does
+not leave any file, but cannot check if a generated file that should
+not be distributed was distributed, or that files are missing in the
+installation tree.
+
+0.5 Check
+
+ make check
+
+-> All tests should pass
+
+0.6 Clean
+
+ make mostlyclean
+
+-> Check what is left in the build tree.
+
+ make clean
+
+-> Check what is left in the build tree. This is also automatically
+ checked by 'distcheck'.
+
+ make distclean
+
+-> Check what is left in the build tree
+
+
1. Generation of build system files
+-----------------------------------
-./bootstrap
+ ./bootstrap
Generated the following files and directories:
INSTALL
@@ -42,6 +113,7 @@ Generated the following files and directories:
src/include/config.hin
2. Tests of various targets
+---------------------------
Tests done in 2 configurations:
@@ -382,15 +454,11 @@ Differences with former build system:
-- picXX.html files
-- info file from groff.texinfo
-Diff with previous build system:
+Diff with previous build system after final (full tree comparison):
- devcp1047 fonts are installed $(DESTDIR)/usr/local/groff/1.22.3/font
-
-TODO:
-
- - When contrib and doc will be completed, full installation tree
- comparison with the tree installed by the old build system. Note:
- to ease tree comparison, it is usefull to touch all .man files in
- order to get rid of the date difference.
+ - devpdf fonts (not identical at each build)
+ - in hdbtbl, parts of some .ps are not identical at each build.
+ - timetamp in man files or html files
2.7 make uninstall
@@ -433,13 +501,12 @@ TODO:
groff-1.22.3.tar.gz is generated.
- Files/directories that are not distributed on purpose:
- .gitignore
+ all .gitignore files
.gitmodules
bootstrap
bootstrap.conf
gnulib/
README.git
- TESTS
- Files/directories not present in the git tree that are
distributed:
@@ -482,6 +549,7 @@ in the install tree).
- All phases now succeed
3. Additional tests
+-------------------
3.1 Build without X support
@@ -508,9 +576,6 @@ in the install tree).
-- The only texinfo documentation installed by default is:
$(DESTDIR)/usr/local/share/info/groff.info
--> TODO: Check if the texinfo doc in other formats, if built, should
- be installed.
-
- Passing to configure option: --with-doc=no
No doc is built nor installed, $(DESTDIR)/usr/local/share/doc
@@ -563,20 +628,27 @@ in the install tree).
3.4 Build in presence of system tmac files
- - Create 3 dummy files in /usr/lib/tmac: tmac.an, tmac.m, tmac.s, that all
contain:
+ - Create 3 dummy files in /usr/lib/tmac: tmac.an, tmac.m, tmac.s,
+ that all contain:
.if
- Build and install as usual:
- -- $(DESTDIR)/usr/local/lib/groff/site-tmac/ contains 3 files: an.tmac,
m.tmac, s.tmac
+ -- $(DESTDIR)/usr/local/lib/groff/site-tmac/ contains 3 files:
+ an.tmac, m.tmac, s.tmac.
-- In $(DESTDIR)/usr/local/share/groff/1.22.3/tmac 6 files have a
'g' prefix: gan.tmac, gm.tmac, gmm.tmac, gmmse.tmac, gmse.tmac,
gs.tmac.
-Notes
------
+3.5 Parallel build
+
+ - Checked that usage of option -j when invoking `make' works correctly.
+
+4. Notes
+--------
- Gnulib: some files of src/libs/libgroff could be replaced by their
gnulib equivalent
+
- Gnulib: git-version-gen could be used
diff --git a/contrib/hdtbl/hdtbl.am b/contrib/hdtbl/hdtbl.am
index e54fb14..608977f 100644
--- a/contrib/hdtbl/hdtbl.am
+++ b/contrib/hdtbl/hdtbl.am
@@ -47,6 +47,9 @@ hdtbltmac_DATA = $(HDTBLSTRIPFILES)
HDTBLGENFILES = \
contrib/hdtbl/examples/fonts_n.roff \
contrib/hdtbl/examples/fonts_x.roff
+EXTRA_DIST += \
+ contrib/hdtbl/examples/fonts_n.in \
+ contrib/hdtbl/examples/fonts_x.in
HDTBLEXAMPLEFILES = \
contrib/hdtbl/examples/common.roff \
@@ -77,7 +80,10 @@ hdtblexampledir = $(exampledir)/hdtbl
if BUILD_EXAMPLES
dist_hdtblexample_DATA = $(HDTBLEXAMPLEFILES)
-nodist_hdtblexample_DATA = $(HDTBLGENFILES) $(HDTBLPROCESSEDEXAMPLEFILES)
gnu.eps
+nodist_hdtblexample_DATA = \
+ $(HDTBLGENFILES) \
+ $(HDTBLPROCESSEDEXAMPLEFILES) \
+ gnu.eps
else
EXTRA_DIST += $(HDTBLEXAMPLEFILES)
endif
@@ -91,8 +97,7 @@ EXTRA_DIST += \
contrib/hdtbl/TODO \
contrib/hdtbl/groff_hdtbl.man \
contrib/hdtbl/hdtbl.tmac-u \
- contrib/hdtbl/hdmisc.tmac-u \
- contrib/hdtbl/examples
+ contrib/hdtbl/hdmisc.tmac-u
# Rule to generate ps and roff files
SUFFIXES += .roff .in .ps
diff --git a/contrib/mom/mom.am b/contrib/mom/mom.am
index 238a6ca..886a455 100644
--- a/contrib/mom/mom.am
+++ b/contrib/mom/mom.am
@@ -114,7 +114,6 @@ EXTRA_DIST += $(MOMHTMLDOCFILES) $(MOMEXAMPLEFILES) \
contrib/mom/NEWS \
contrib/mom/TODO \
contrib/mom/copyright \
- contrib/mom/examples \
contrib/mom/groff_mom.man \
contrib/mom/om.tmac-u
diff --git a/contrib/pdfmark/pdfmark.am b/contrib/pdfmark/pdfmark.am
index 0942acf..64a1197 100644
--- a/contrib/pdfmark/pdfmark.am
+++ b/contrib/pdfmark/pdfmark.am
@@ -33,11 +33,11 @@ pdfmarktmacdir = $(tmacdir)
dist_pdfmarktmac_DATA = $(TMACFILES)
# Files installed in $(pdfdocdir)
-if BUILD_PDFDOC
PDFDOCFILES = \
contrib/pdfmark/pdfmark.pdf
+if BUILD_PDFDOC
pdfmarkpdfdocdir = $(pdfdocdir)
-dist_pdfmarkpdfdoc_DATA = $(PDFDOCFILES)
+nodist_pdfmarkpdfdoc_DATA = $(PDFDOCFILES)
MOSTLYCLEANFILES += $(PDFDOCFILES)
else
EXTRA_DIST += $(PDFDOCFILES)
diff --git a/doc/automake.mom b/doc/automake.mom
new file mode 100644
index 0000000..1ed18ee
--- /dev/null
+++ b/doc/automake.mom
@@ -0,0 +1,675 @@
+.\" Copyright ©2014 Free Software Foundation
+.\" 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
+.\"
+.\" Permission is hereby granted, free of charge, to any person
+.\" obtaining a copy of this software and associated documentation
+.\" files (the "Software"), to deal in the Software without restriction,
+.\" including, without limitation, the rights to use, copy, modify,
+.\" merge, publish, distribute, sublicense, and sell copies of
+.\" the Software, and to permit persons to whom the Software is
+.\" furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be
+.\" included in all copies, or substantial portions, of the Software;
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+.\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+.\" WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+.\" FROM, OUT OF, OR IN CONNECTION WITH, THE SOFTWARE, OR THE USE OF,
+.\" OR OTHER DEALINGS IN, THE SOFTWARE.
+.\"
+.\" Formatted with the mom macros
+.\" .RW (reduce) and .EW (expand) control track kerning
+.\" .WS controls word spacing
+.\" Hanging punctuation and hyphens are inserted manually
+.\"
+.TITLE "Using Automake in the Groff project"
+.AUTHOR "Bertrand Garrigues"
+.DOCTYPE DEFAULT
+.PRINTSTYLE TYPESET
+.PAPER LETTER
+.COPYRIGHT "Free Software Foundation 2014"
+.DOC_COVERTITLE "Using Automake in the Groff project"
+.DOC_COVER DOC_COVERTITLE
+.COVER TITLE AUTHOR DOCTYPE COPYRIGHT
+
+.HEADING_STYLE 1 NUMBER
+.HEADING_STYLE 2 NUMBER
+.HEADING_STYLE 3 NUMBER
+.HEADING_STYLE 4 NUMBER
+
+\# Table of contents
+.TOC_PADDING 2
+.SPACE_TOC_ITEMS
+.AUTO_RELOCATE_TOC
+.TOC_ENTRY_STYLE 2 FONT I
+.TOC_LEAD 14
+
+.QUOTE_INDENT 1m
+.START
+
+.PP
+This is a quick overview of how to use `automake' in the groff project,
+and is intended to help the developers and contributors to find their way
+when they have to make some changes to the sources files or to the data that
are installed.
+If you need more details on `automake',
+here are some reading suggestions:
+.LIST
+.ITEM
+the Automake Manual:
+.BR
+.PDF_WWW_LINK http://www.gnu.org/software/automake/manual/automake.html.
+.ITEM
+A book by John Calcote, with good practical examples:
+.BR
+.PDF_WWW_LINK http://fsmsh.com/2753
+.ITEM
+This site, by Diego Petteno, with good practical examples too:
+.BR
+.PDF_WWW_LINK https://autotools.io/index.html
+.LIST OFF
+
+
+.HEADING 1 "Overview, the initial build"
+
+.HEADING 2 "First build"
+
+.PP
+Groff integrates the `gnulib' and uses its `bootstrap' script.
+When compiling from the git repository, you should first invoke this script:
+.QUOTE
+.CODE
+$ ./bootstrap
+.CODE OFF
+.QUOTE OFF
+This will:
+.LIST
+.ITEM
+Clone the gnulib repository as a git submodule in 'gnulib',
+add the needed gnulib sources files in `lib',
+add the needed gnulib m4 macros in `gnulib_m4'.
+.ITEM
+Invoke autoreconf that will call all the `GNU autotools' (`aclocal',
`autoheader', `autoconf', `automake')
+in the right order for creating the following files:
+.LIST DASH
+.ITEM
+INSTALL (a symlink to gnulib's INSTALL file)
+.ITEM
+Makefile.in
+.ITEM
+aclocal.m4
+.ITEM
+autom4te.cache/
+.ITEM
+build-aux/ (that contains all the helper scripts)
+.ITEM
+configure
+.ITEM
+src/include/config.hin
+.LIST OFF
+.LIST OFF
+
+Note that aclocal.m4 is generated and the groff m4 macros are included via the
acinclude.m4 file.
+
+.PP
+At this point you can invoke the `configure' script and call `make' to build
the groff project.
+You can do it in the source tree:
+.QUOTE
+.CODE
+$ ./configure
+$ make
+.CODE OFF
+.QUOTE OFF
+You can also build groff in an out of source build tree,
+which is cleaner:
+.QUOTE
+.CODE
+$ mkdir build
+$ cd build
+$ ../configure
+$ make
+.CODE OFF
+.QUOTE OFF
+Note that parallel build is also supported and make can be invoked with the -j
option,
+which will greatly speed up the build.
+
+.HEADING 2 "Automake in the autotools process"
+
+.PP
+Automake's main job is to generate a Makefile.in file
+(this file is maintained manually on projects using only autoconf).
+The main file processed by `automake' is the Makefile.am file,
+which eventually generates a Makefile.
+The (simplified) process is:
+.LIST
+.ITEM
+`aclocal' generates the `aclocal.m4' file from `configure.ac' and the
user-defined macros in `acinclude.m4'.
+.ITEM
+`autoheader' generates config.h.in.
+.ITEM
+`autoconf' generates the `configure' script from `aclocal.m4' and
`configure.ac'
+.ITEM
+`automake' generates Makefile.in from Makefile.am and the `configure.ac' file.
+It also generates some helper scripts, on the groff project they are located
in build-aux.
+.ITEM
+`configure' generates `config.status'
+.ITEM
+`config.status' generates the Makefile and config.h.
+.LIST OFF
+Finally, `autoreconf' is the program that can be used to call these various
tools in the correct order.
+
+.PP
+.PP
+Automake defines a set of special variables that are used to generate various
build rules in the final Makefile.
+Note however that if Automake's pre-defined rules are not enough,
+you still have the possibility to add handwritten standard `make' rules in a
Makefile.am:
+these rules will be copied verbatim in the Makefile.in and then in the final
Makefile.
+
+.HEADING 2 "Modification of autotools files"
+
+.PP
+Previously, when groff used `autoconf' only and not `automake',
+you had to invoke manually the autotools,
+depending on what you modified.
+For example, to change the file `aclocal.m4', you had to run the shell command
'aclocal -I m4';
+to recreate the files `configure' and `Makefile',
+you had to use the command 'autoreconf -I m4'.
+
+.PP
+Now, as groff uses `automake', you don't need to run `autoreconf'.
+If you make some changes in Makefile.am or configure.ac,
+all the files that need to be updated will be regenerated when you execute
`make'.
+
+.HEADING 1 "Building a program"
+
+.HEADING 2 "A program and its source files"
+
+.PP
+Generally speaking, when using `automake'
+you will have to write a Makefile.am file and use the variable
\*[CODE]bin_PROGRAMS\*[CODE OFF]
+to declare a program that should be built,
+and then list the sources of this program in a variable
+that starts with the name of your program and ends with
\*[CODE]_SOURCES\*[CODE OFF] .
+In the groff project we have only 1 top-level Makefile.am that includes
several .am files.
+
+.PP
+Take for example the build of grolbp, in src/devices/grolbp/grolbp.am.
+The file starts with:
+.QUOTE
+.CODE
+bin_PROGRAMS += grolbp
+.CODE OFF
+.QUOTE OFF
+This says that a program named `grolbp' is added to the list of the programs
that should be built.
+Note that \*[CODE]bin_PROGRAMS\*[CODE OFF]
+is initialized to an empty string in the top-level Makefile.am,
+which includes grolbp.am.
+We will see later why we don't write directly
+.BR
+\*[CODE]bin_PROGRAMS = grolbp\*[CODE OFF] in a Makefile.am in the grolbp
directory.
+
+Then, we list the sources of grolbp like this:
+.QUOTE
+.CODE
+.ESC_CHAR %
+grolbp_SOURCES = \
+ src/devices/grolbp/lbp.cpp \
+ src/devices/grolbp/lbp.h \
+ src/devices/grolbp/charset.h
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+As you added `grolbp' to \*[CODE]bin_PROGRAMS \*[CODE OFF]
+you need to define the sources of grolbp in the variable
\*[CODE]grolbp_SOURCES\*[CODE OFF] .
+If you write in another file \*[CODE]bin_PROGRAMS += foo\*[CODE OFF],
+you will list the sources of `foo'
+in \*[CODE]foo_SOURCES\*[CODE OFF] .
+
+.PP
+With these two statements,
+the resulting generated Makefile will contain everything that is needed to
+build, clean, install and uninstall the `grolbp' binary
+when invoking the adequate make command.
+Also, the source files listed in \*[CODE]grolbp_SOURCES\*[CODE OFF]
+will automatically be included in the distribution tarball.
+That is why the headers are also listed in \*[CODE]grolbp_SOURCES\*[CODE OFF]:
+it is not necessary to add them in order to correctly build `grolbp',
+but this way the headers will be distributed.
+
+.PP
+Note that:
+.LIST
+.ITEM
+The path to the files are relative to the top-level directory.
+.ITEM
+The binaries are generated in the top-level build directory.
+.ITEM
+The .o files are generated in the directory where the source files are located,
+or, in the case of an out-of-source build tree,
+in a directory that is the replication of the source tree directory.
+For example if you built groff in a `build' directory,
+lbp.o (object file from src/devices/grolbp/lbp.cpp) will be located in
+build/src/devices/grolbp/lbp.o.
+.LIST OFF
+We will also see later the reasons, this is due to the non-recursive make
design.
+
+.HEADING 2 "Linking against a library"
+
+.PP
+To list which libraries grolbp needs to link against, we just write:
+.QUOTE
+.CODE
+.ESC_CHAR %
+grolbp_LDADD = $(LIBM) \
+ libdriver.a \
+ libgroff.a \
+ lib/libgnu.a
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+Again, we use the variable \*[CODE]grolbp_LDADD\*[CODE OFF] because we added a
program named `grolbp'.
+This will also automatically set build dependencies between `grolbp' and the
libraries it needs:
+`libdriver.a' and `libgroff.a',
+that are convenience libraries built within the groff project,
+will be compiled before grolbp.
+
+.HEADING 2 "Preprocessor flags"
+
+.PP
+Preprocessor flags that are common to all the binaries are listed in
+the variable \*[CODE]AM_CPPFLAGS\*[CODE OFF] in the top-level Makefile.am.
+If a `foo' binary needs specific preprocessor flags,
+use \*[CODE]foo_CPPFLAGS\*[CODE OFF],
+for example, in src/devices/xditview/xditview.am,
+extra flags are needed to build gxditview and are added like this:
+.QUOTE
+.CODE
+.ESC_CHAR %
+gxditview_CPPFLAGS = $(AM_CPPFLAGS) $(X_CFLAGS) -Dlint \
+ -I$(top_builddir)/src/devices/xditview
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+.PP
+The use of specific CPPFLAGS changes the name of the generated objects:
+the .o object files are prefixed with the name of the program.
+For example, the .o file corresponding to src/devices/xditview/device.c
+will be src/devices/xditview/gxditview-device.o.
+
+.HEADING 2 "Cleaning"
+
+.PP
+You don't need to write rules to clean the programs listed in
\*[CODE]bin_PROGRAMS\*[CODE OFF],
+`automake' will write them for you.
+However, some programs might have generated sources that should be cleaned.
+In this case, you have mainly two special variables to list extra files that
should be cleaned:
+.LIST
+.ITEM
+\*[CODE]MOSTLYCLEANFILES\*[CODE OFF] for files that should be cleaned by `make
mostlyclean'
+.ITEM
+\*[CODE]CLEANFILES\*[CODE OFF ] for files that should be cleaned by `make
clean'
+.LIST OFF
+
+.PP
+There is also the possibility to write custom rules,
+we will see that later.
+
+.HEADING 2 "Dependencies"
+
+.PP
+We have already seen that when linking against a convenience library,
+the dependencies are already created by `automake'.
+However, some dependencies still need to be manually added,
+for example when a source file includes a generated header.
+In this case, the easiest way is to add a plain-make dependency.
+For example, src/roff/groff/groff.cpp includes defs.h,
+which is a generated header.
+We just add in src/roff/groff/groff.am:
+.QUOTE
+.CODE
+src/roff/groff/groff.$(OBJEXT): defs.h
+.CODE OFF
+.QUOTE OFF
+
+.HEADING 2 "Scripts"
+
+.PP
+A part from \*[CODE]bin_PROGRAMS\*[CODE OFF],
+there is another similar special variable for scripts:
+\*[CODE]bin_SCRIPTS\*[CODE OFF] .
+The scripts listed in this variable will automatically be built
+(of course you have to provide your custom rule to build the script),
+installed and uninstalled when invoking 'make', 'make install' and 'make
uninstall'.
+The main difference is that unlike the programs listed in
\*[CODE]bin_PROGRAMS\*[CODE OFF],
+the scripts will not be cleaned by default.
+They are not distributed by default either.
+In the groff project, \*[CODE]bin_SCRIPTS\*[CODE OFF] are cleaned because they
are added to
+\*[CODE]MOSTLYCLEANFILES\*[CODE OFF] in the top-level Makefile.am.
+
+.PP
+A simple example are the gropdf and pdfmom scripts in
src/devices/gropdf/gropdf.am:
+.QUOTE
+.CODE
+.ESC_CHAR %
+bin_SCRIPTS += gropdf pdfmom
+ [...]
+gropdf: $(gropdf_dir)/gropdf.pl $(SH_DEPS_SED_SCRIPT)
+ rm -f $@
+ sed -f $(SH_DEPS_SED_SCRIPT) \
+ -e "s|address@hidden@]|$(VERSION)|" \
+ -e "s|address@hidden@]|$(PERL)|" \
+ -e "s|address@hidden@]|$(fontpath)|" \
+ -e "s|address@hidden@]|$(RT_SEP)|" $(gropdf_dir)/gropdf.pl >$@
+ chmod +x $@
+
+pdfmom: $(gropdf_dir)/pdfmom.pl $(SH_DEPS_SED_SCRIPT)
+ rm -f $@
+ sed -f $(SH_DEPS_SED_SCRIPT) \
+ -e "s|address@hidden@]|$(VERSION)|" \
+ -e "s|address@hidden@]|$(PERL)|" $(gropdf_dir)/pdfmom.pl >$@
+ chmod +x $@
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+
+Note that in this example the '@' symbol is protected by square brackets to
prevent
+the substitution of the variable by `automake'.
+
+.HEADING 1 "Non-recursive make schema"
+
+.PP
+There are two possibilities to organize the Makefile.am of a large project,
+using a recusive or a non-recursive `make'.
+
+.HEADING 2 "1st possibility: make recursion"
+
+.PP
+A top level Makefile.am includes other Makefile.am,
+using the \*[CODE]SUBDIRS\*[CODE OFF] directive,
+and the Makefile.am of each sub-directory lists the programs that should be
built.
+If we had
+chosen this type of organization, we would have a Makefile.am in
+src/devices/grolbp and in each directory that contain sources to build
+a program (tbl, eqn, troff etc ...). We would write in the top-level
+Makefile.am:
+.QUOTE
+.CODE
+.ESC_CHAR %
+SUBDIRS = src/devices/grolbp \
+ ... (and all the dir that build a program or a script)
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+and in src/devices/grolbp, we would have a file Makefile.am that contains:
+.QUOTE
+.CODE
+bin_PROGRAMS = grolbp
+grolbp_SOURCES = lbp.cpp lbp.h charset.h
+.CODE OFF
+.QUOTE OFF
+.PP
+Only `grolbp' is affected to the variable \*[CODE]bin_PROGRAMS\*[CODE OFF] .
+It would be the same in, say, src/roff/troff:
+you would have a Makefile.am with \*[CODE]bin_PROGRAMS = troff\*[CODE OFF] .
+We would have 1 generated Makefile per Makefile.am file:
+in the build tree you will have the top-level Makefile,
+grolbp's Makefile in src/devices/grolbp,
+troff's Makefile in src/roff/troff, and so on.
+When calling `make' to build everything,
+make will be recursively called in all the directories that have a Makefile.
+Thus, the paths are logically relative to the directory that contains the
Makefile.am.
+
+.PP
+This approach has the disadvantage of making dependencies harder to solve:
+each Makefile does not know the targets of the other Makfiles.
+It also makes the build slower.
+
+.HEADING 2 "Non-recursive make used by the Groff project"
+
+.PP
+The second possibility, that was chosen on groff project,
+is to use a non-recursive make schema.
+It is described in paragraph 7.3 of the Automake manual ("An Alternative
Approach to Subdirectories"),
+based on the following parper from Peter Miller: Recursive Make Considered
+Harmful
+.PDF_WWW_LINK http://miller.emu.id.au/pmiller/books/rmch/
+
+.PP
+The idea is to have a single Makefile that contains all the rules.
+That is why we have only a single Makefile.am in the top-level directory
+which includes all the .am files that define rules to build the various
programs.
+The inclusion is done with the \*[CODE]include\*[CODE OFF] directive, not
\*[CODE]SUBDIRS\*[CODE OFF] .
+Using 'include' is like copying the content of the included file into the
top-level Makefile.am,
+and will not generate other Makefile.
+We first say in this top-level Makefile.am:
+.QUOTE
+.CODE
+ bin_PROGAMS =
+.CODE OFF
+.QUOTE OFF
+and then all the .am files that define a program to be built
+(e.g. src/devices/grolbp/grolbp.am, src/roff/troff/troff.am, and so on)
+overload this variable,
+so that at the end, all the programs that should be built are listed in this
\*[CODE]bin_PROGRAMS\*[CODE OFF] variable.
+This is the reason why all the paths in the various .am files are relative to
the top-level directory:
+at the end we will have only one Makefile in the top-level directory of the
build tree.
+
+.PP
+As the resulting single Makefile knows all the targets,
+the dependencies are easier to manage.
+The build is also faster, particularly when compiling a single file:
+make is called once only and the file will be instantly rebuilt,
+while on a recursive make system, make will have to be invoked in all the
sub-directories.
+
+.PP
+Note also that in order to make `gnulib' work with this non-recursive schema,
+the `non-recursive-gnulib-prefix-hack' configuration should be selected in
bootstrap.conf.
+
+.HEADING 1 "Installing data"
+
+.PP
+Variables that end with \*[CODE]_DATA\*[CODE OFF] are special variables used
to list files that should be installed in a particular location.
+The prefix of the variables should refer to another previously defined
variable that ends with a `dir' suffix.
+This varibale that ends with `dir' defines where the files should be installed.
+
+.HEADING 2 "A simple case"
+
+.PP
+For example, in font/devX100/devX100.am, we can see this:
+
+.QUOTE
+.CODE
+if !WITHOUT_X11
+devX100fontdir = $(fontdir)/devX100
+devX100font_DATA = $(DEVX100FONTS)
+endif
+
+EXTRA_DIST += $(DEVX100FONTS)
+.CODE OFF
+.QUOTE OFF
+\*[CODE]DEVX100FONTS\*[CODE OFF] is just a list font files,
+defined at the begining of devX100.am.
+\*[CODE]fontdir\*[CODE OFF] is where all the font directories are installed,
+it is defined in the top-level Makefile.am.
+The conditional \*[CODE]if !WITHOUT_X11\*[CODE OFF]
+is used to prevent the installation of these files if X11 is not available.
+
+We first define where we wants to install the devX100 fonts with:
+
+.QUOTE
+.CODE
+devX100fontdir = $(fontdir)/devX100
+.CODE OFF
+.QUOTE OFF
+Because we declared a variable ending with `dir',
+we are allowed to define \*[CODE]devX100font_DATA\*[CODE OFF]
+(you remove the `dir' suffix and add \*[CODE]_DATA\*[CODE OFF]).
+Note that wildcards are not supported in the special variable that end with
\*[CODE]_DATA\*[CODE OFF].
+
+.PP
+With these two lines, `make install' will install the files listed in
\*[CODE]DEVX100FONTS \*[CODE OFF]
+and `make uninstall' will uninstall them.
+\*[CODE]devX100fontdir\*[CODE OFF] will be automatically created if missing
during the installation process,
+but not removed during the uninstall.
+The complete \*[CODE]fontdir \*[CODE OFF] is removed by a custom uninstall
rule
+(uninstall_groffdirs in Makefile.am).
+
+.PP
+Because the files listed in \*[CODE]devX100font_DATA \*[CODE OFF] are not
distributed by default,
+we explicitely added them to the \*[CODE]EXTRA_DIST\*[CODE OFF] variable,
+which lists all the files that should be distributed and that are not taken
into account by the default automake rules.
+.QUOTE
+.CODE
+ EXTRA_DIST += $(DEVX100FONTS)
+.CODE OFF
+.QUOTE OFF
+Another possibility would have being to add a `dist' prefix to the
\*[CODE]devX100font_DATA\*[CODE OFF] variable,
+in this case the use of \*[CODE]EXTRA_DIST\*[CODE OFF] is useless
+(except of course if
+.BR
+\*[CODE]WITHOUT_X11\*[CODE OFF] is true,
+in this case we don't install the files but we still have to distribute them):
+.QUOTE
+.CODE
+if !WITHOUT_X11
+devX100fontdir = $(fontdir)/devX100
+dist_devX100font_DATA = $(DEVX100FONTS)
+else
+EXTRA_DIST += $(DEVX100FONTS)
+endif
+.CODE OFF
+.QUOTE OFF
+
+.HEADING 2 "Dealing with generated files"
+
+.PP
+In the previous example, all the font files that must be installed were
already present in the source tree.
+But in some cases, you need to generate the files you intend to install.
+In this case, the files should be installed but not distributed.
+A simple way to deal with this is to add a `nodist' prefix to your
\*[CODE]xxx_DATA\*[CODE OFF] variable.
+
+.PP
+For example in font/devps/devps.am, we have a list of font files already
present in the source tree,
+defined by \*[CODE]DEVPSFONTFILES\*[CODE OFF],
+and another list of font files that are generated,
+listed in the variable \*[CODE]DEVPSFONTFILES_GENERATED\*[CODE OFF] .
+They should all by installed in a `devps' directory under the fontdir.
+Thus the following three lines, where we use the `dist' and `nodist' prefixes:
+.QUOTE
+.CODE
+devpsfontdir = $(fontdir)/devps
+dist_devpsfont_DATA = $(DEVPSFONTFILES)
+nodist_devpsfont_DATA = $(DEVPSFONTFILES_GENERATED)
+.CODE OFF
+.QUOTE OFF
+
+The generated files are not cleaned by default, thus we add:
+.QUOTE
+.CODE
+MOSTLYCLEANFILES += $(DEVPSFONTFILES_GENERATED)
+.CODE OFF
+.QUOTE OFF
+
+.HEADING 1 "Extending Automake's rules"
+
+.HEADING 2 "Local clean rules"
+
+.PP
+In most of the cases, the files that need to be cleaned are automatically
determined by `automake',
+or were added to the \*[CODE]MOSTCLEANFILES\*[CODE OFF] or
\*[CODE]CLEANFILES\*[CODE OFF] variables.
+However, you might need to define a specific rule to clean some files that
were not added to any list.
+Automake defines a set of targets to extend the clean targets with your own
rules:
+clean-local, mostlyclean-local, distclean-local or maintainerclean-local.
+An example of such extension exists in font/devpdf/devpdf.am:
+because some fonts are not explicitely listed in a \*[CODE]xxx_DATA\*[CODE
OFF] variable but generated by a custom rule,
+we define an extra rule to extend the `mostlyclean' target:
+.QUOTE
+.CODE
+.ESC_CHAR %
+mostlyclean-local: mostlyclean_devpdf_extra
+mostlyclean_devpdf_extra:
+ @echo Cleaning font/devpdf
+ rm -rf $(top_builddir)/font/devpdf/enc \
+ $(top_builddir)/font/devpdf/map;
+ if test -d $(top_builddir)/font/devpdf; then \
+ for f in $(GROFF_FONT_FILES); do \
+ rm -f $(top_builddir)/font/devpdf/$$f; \
+ done; \
+ fi
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+
+.HEADING 2 "Local install/uninstall rules and hooks"
+
+.PP
+Similarly to the clean rules, there are extensions to install and uninstall
rules.
+They come with two flavous, local rules and hooks.
+.LIST
+.ITEM
+There are 2 rules to extend install commands:
+`install-exec-local' for binaries and `install-data-local' for data.
+.ITEM
+There is 1 uninstall local rule: `uninstall-local'.
+.LIST OFF
+There are no garantee on the order of execution of these local rules.
+An example of local rule is the installation of GXditview.ad and
GXditview-color.ad files in
+src/devices/xditview/xditview.am:
+if theses files are already installed, the old files are first saved.
+Also, the final file that is installed is stripped from its .ad suffix.
+Thus the usage of a custom rules rather than the definition of a
\*[CODE]xxx_DATA\*[CODE OFF] variable:
+.QUOTE
+.CODE
+.ESC_CHAR %
+# Custom installation of GXditview.ad and GXditview-color.ad
+install-data-local: install_xditview
+uninstall-local: uninstall_xditview
+
+[...]
+install_xditview: $(xditview_srcdir)/GXditview.ad
+ -test -d $(DESTDIR)$(appresdir) \
+ || $(mkinstalldirs) $(DESTDIR)$(appresdir)
+ if test -f $(DESTDIR)$(appresdir)/GXditview; then \
+ mv $(DESTDIR)$(appresdir)/GXditview \
+ $(DESTDIR)$(appresdir)/GXditview.old; \
+ fi
+ [...]
+ $(INSTALL_DATA) $(xditview_srcdir)/GXditview.ad \
+ $(DESTDIR)$(appresdir)/GXditview
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+
+.PP
+Hooks, on the other hand, are garanteed to be executed after all the standard
targets have been executed.
+.LIST
+.ITEM
+There are 2 install hooks: `install-exec-hook' and `install-data-hook'.
+.ITEM
+There is 1 uninstall hook: `unintall-hook'
+.LIST OFF
+
+.PP
+An example of hook is the `uninstall_groffdirs' rule in the top-level
Makefile.am.
+This hook is used to remove all the directories specific to groff introduced
by the installation process.
+Obviously it could not be a local extension of `uninstall' because the order
of execution is not guaranteed.
+.QUOTE
+.CODE
+.ESC_CHAR %
+# directories specific to groff
+uninstall-hook: uninstall_groffdirs
+uninstall_groffdirs:
+ if test -d $(DESTDIR)$(datasubdir); then \
+ rm -rf $(DESTDIR)$(fontdir); \
+ rm -rf $(DESTDIR)$(oldfontdir); \
+ rmdir $(DESTDIR)$(datasubdir); \
+ fi
+ [...]
+.ESC_CHAR \
+.CODE OFF
+.QUOTE OFF
+.TOC_RV_SWITCH
+.TOC
diff --git a/doc/doc.am b/doc/doc.am
index f2dccbb..bf3feb0 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -21,7 +21,7 @@
doc_srcdir = $(abs_top_srcdir)/doc
doc_builddir = $(abs_top_builddir)/doc
-DOC_SED = sed -e "s;@VERSION@;$(VERSION);"
+DOC_SED = sed -e "s;address@hidden@];$(VERSION);"
DOC_GROFF_ONLY=\
GROFF_COMMAND_PREFIX= \
@@ -103,6 +103,7 @@ exampleimagedir = $(exampledir)/img
MOSTLYCLEANFILES += doc/examples.stamp
EXTRA_DIST += \
+ doc/automake.mom \
doc/gnu.xpm \
doc/fixinfo.sh \
doc/txi-en.tex
@@ -130,6 +131,7 @@ SUFFIXES += .me .ms .ps .html .txt .texinfo .dvi .pdf .xhtml
$(PROCESSEDEXAMPLEFILES): $(bin_PROGRAMS) $(prefixexecbin_PROGRAMS) gnu.eps
$(PROCESSEDEXAMPLEFILES): $(dist_devpsfont_DATA) $(nodist_devpsfont_DATA)
$(hdtbltmac_DATA)
+$(PROCESSEDEXAMPLEFILES): $(dist_tmac_DATA) $(nodist_tmac_DATA)
$(PROCESSEDDOCFILES): $(bin_PROGRAMS) $(prefixexecbin_PROGRAMS) gnu.eps
doc/pic.html: $(bin_PROGRAMS) $(prefixexecbin_PROGRAMS)
diff --git a/font/devpdf/devpdf.am b/font/devpdf/devpdf.am
index 1122102..a680468 100644
--- a/font/devpdf/devpdf.am
+++ b/font/devpdf/devpdf.am
@@ -55,7 +55,7 @@ nodist_devpdffontutil_DATA = font/devpdf/util/BuildFoundries
EXTRA_DIST += \
font/devpdf/DESC.in \
font/devpdf/Foundry.in \
- font/devpdf/util
+ font/devpdf/util/BuildFoundries.pl
font/devpdf/enc/text.enc:
@$(MKDIR_P) $(top_builddir)/font/devpdf/enc
diff --git a/src/preproc/pic/pic.am b/src/preproc/pic/pic.am
index 94dd1ed..e0896db 100644
--- a/src/preproc/pic/pic.am
+++ b/src/preproc/pic/pic.am
@@ -39,7 +39,9 @@ pic_CPPFLAGS = $(AM_CPPFLAGS) \
PREFIXMAN1 += src/preproc/pic/pic.n
src/preproc/pic/pic-lex.$(OBJEXT): src/preproc/pic/pic.hpp
-EXTRA_DIST += src/preproc/pic/pic.n src/preproc/pic/TODO
+EXTRA_DIST += \
+ src/preproc/pic/pic.man \
+ src/preproc/pic/TODO
CLEANFILES += \
src/preproc/pic/pic.cpp \
src/preproc/pic/pic.hpp \
diff --git a/tmac/tmac.am b/tmac/tmac.am
index 08edc0c..b422b15 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -97,7 +97,8 @@ TMACSPECIALFILES = tmac/an.tmac tmac/s.tmac tmac/www.tmac
TMACSTRIPFILES = tmac/e.tmac tmac/doc.tmac tmac/doc-old.tmac
# Files installed in tmacdir
-dist_tmac_DATA = $(TMACNORMALFILES) $(TMACSPECIALFILES) $(TMACSTRIPFILES)
+dist_tmac_DATA = $(TMACNORMALFILES) tmac/an.tmac tmac/s.tmac
+nodist_tmac_DATA = $(TMACSTRIPFILES) tmac/www.tmac
TMACMDOCFILES = \
tmac/doc-common \
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 42/45: Fixes after final complete tests and documentation update.,
Bertrand Garrigues <=