This file gives information on the tests that were made during the
Automake migration.

Environment
-----------
Arch Linux x64 with:
  - Autoconf 2.69
  - Automake 1.14.1
  - GNU Make 4.0

Current status
--------------
  - Gnulib integrated
  - Automake support
  - Build src/libs/*
  - Build src/utils/*
  - Build src/preproc/*
  - Build src/devices/*
  - Build src/roff/*
  - Build font/*
  - man files from 'man' directory installed
  - tmac files from 'tmac' directory installed
  - Build and installation of contrib
  - Build and installation of doc, including texinfo doc

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 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

Generated the following files and directories:
  INSTALL
  Makefile.in
  aclocal.m4
  autom4te.cache/
  build-aux/
  configure
  gnulib_m4/
  lib/
  src/include/config.hin

2. Tests of various targets
---------------------------

Tests done in 2 configurations:

  - Out-of source build mode

    mkdir build
    cd build
    ../configure

  - In source build:
    ../configure

2.1 make

Following files are generated:

  - src/include/config.h
  - lib/libgnu.a

from arch/misc:
  - shdeps.sed

from src/libs:
  - libbib.a
  - libdriver.a
  - libgroff.a, version.cpp and extra files (charset.alias,
    ref-add.sed, ref-del.sed)
  - libxutils.a

from src/utils:
  - addftinfo
  - afmtodit
  - hpftodit
  - indxbib
  - lkbib
  - lookbib
  - pfbtops
  - tfmtodit
  - xtotroff
  - man files (.n) in src/utils

from src/preproc:
  - eqn
  - grn
  - pre-grohtml
  - pic
  - preconv
  - refer
  - soelim
  - tbl
  - Yacc and Lex support: the following files are generated:
    -- eqn/eqn.cpp
    -- eqn/eqn.hpp (previously eqn_tab.h)
    -- pic/pic.cpp
    -- pic/pic.hpp (previously pic_tab.h)
    -- pic/pic.output
    -- refer/label.cpp
    -- refer/label.hpp
    Compared to the previous build system, the only relevant diff is
    an extra protection #define in label.cpp
#ifndef YY_YY_SRC_PREPROC_REFER_LABEL_HPP_INCLUDED
# define YY_YY_SRC_PREPROC_REFER_LABEL_HPP_INCLUDED

from src/devices:
  - grodvi
  - pre-grohtml
  - post-grohtml
  - grolbp
  - grolj4
  - gropdf
  - pdfmom
  - grops
  - grotty
  - gxditview

from src/roff
  - groff
  - grog
  - nroff
  - troff

from font: font files in 
  - devascii
  - devcp1047
  - devdvi
  - devhtml
  - devlatin1
  - devlbp
  - devlj4
  - devpdf
  - devps
  - devutf8

from contrib/chem:
  - `chem' script and 3 README files

from contrib/eqn2graph:
  - `eqn2graph' script

from contrib/gdiffmk:
  - `gdiffmk' script

from contrib/gperl
  - `gperl' script  

from contrib/gpinyin
  - `gpinyin' script

from contrib/grap2graph
  - `grap2graph' script

from contrib/pic2graph
  - `pic2graph' script

from contrib/glilypond
  - `glilypond' script

from contrib/groffer
  - `groffer' script, all the man files.

from contrib/hdtbl
  - hdtbl examples and tmac files

from contrib/mm
  - .n files

from contrib/pdfmark
  - pdfmark.pdf
  - pdfroff

from contrib/mom
  - pdfmom
  - 4 .pdf example files

from doc
  - gnu.eps
  - html and doc files

from doc, texinfo files:

  - By default, only doc/groff.info is built, as GNU standards require
    to install only info doc.

  - Additional optional targets are available to build the doc in various formats:
    -- make doc_txt
    -- make doc_dvi
    -- make doc_pdf
    -- make doc_html (this will build the html in 2 directories: all
       in 1 .html file, and 1 file per node). Note also that if
       texinfo version is < 5.0, the resulting (mono) file will be
       patched by fixinfo.sh
    -- make doc_all will build all the 4 previous formats

In order to check and improve the dependencies, the following targets
were built from a clean environment:
  - make lib/libgnu.a
  - make libbib.a
  - make libdriver.a
  - make libgroff.a
  - make libxutil.a
  - make addftinfo
  - make  afmtodit
  - make hpftodit
  - make indxbib
  - make lkbib
  - make lookbib
  - make pfbtops
  - make tfmtodit
  - make xtotroff
  - make eqn
  - make grn
  - make pre-grohtml
  - make pic
  - make preconv
  - make refer
  - make soelim
  - make tbl
  - make grodvi
  - make post-grohtml
  - make grolbp
  - make grolj4
  - make gropdf
  - make pdfmom
  - make grops
  - make grotty
  - make gxditview
  - make groff
  - make grog
  - make nroff
  - make troff
  - make chem
  - make eqn2graph
  - make gdiffmk
  - make gperl
  - make gpinyin
  - make grap2graph
  - make pic2graph
  - make glilypond
  - make groffer
  - make pdfroff
  - make contrib/pdfmark/pdfmark.pdf 
  - make pdfmom
  - make contrib/mom/examples/mom-pdf.pdf

2.2 make clean

The following files remain (this is expected):
  - Makefile
  - config.status
  - config.log
  - doc/groff.info-1
  - doc/groff.info-3
  - src/include/config.h
  - src/include/stamp-h1
  - .deps directories and .dirstamp files

2.3 make mostlyclean

  Like 'make clean', but the following files also remain (expected):
  - lib*.a
  - libgroff.a's charset.alias, ref-add.sed, ref-del.sed, and
    version.cpp.
  - gnulib's charset.alias, ref-add.sed, ref-del.sed and configmake.h
  - src/preproc generated .cpp, hpp, and .output files
  - Scripts (listed in bin_SCRIPTS) are added to the MOSTLYCLEANFILES
    list.

Differences with former build system:

  - Programs (listed in bin_PROGRAMS) are not cleaned by 'make
    mostlyclean'. This could be changed if needed (MOSTLYCLEANFILES +=
    $(bin_PROGRAMS)).

2.4 make distclean

  Like 'make clean', but the following files are also cleaned:
  - Makefile
  - config.status
  - config.log
  - src/include/config.h
  - src/include/stamp-h1
  - .deps directories and .dirstamp files

  In a out-of-source build, nothing remains in the build directory
  expect empty directories.

  The files generated by bootstrap and needed by the configure script
  are untouched:
  INSTALL
  Makefile.in
  aclocal.m4
  build-aux/
  configure
  gnulib_m4/
  lib/
  src/include/config.hin

2.5 make maintainer-clean

  Like 'make distclean'

2.6 make install

  mkdir -p ~/tmp/automake
  make install DESTDIR=~/tmp/automake

  - If file charset.alias is always present in
    $(DESTDIR)/usr/local/lib, make install update it by adding 'groff'
    to the list of programs using it. Otherwise nothing is installed.

  - Programs from 'src' installed in $(DESTDIR)/usr/local/bin: 

  - man files from man, src are installed in
    $(DESTDIR)/usr/local/share/man/man1, man5 and man7.

  - $(DESTDIR)/usr/local/share/groff/1.22.3/eign (from src/utils/indxbib)

  - In $(DESTDIR)/usr/local/lib/X11/app-defaults: GXditview and
    GXditview-color. If these files are already present, they are
    first moved to GXditview.old and GXditview-color.old.

  - usr/local/lib/groff:
    -- groff_opts_no_arg.txt and groff_opts_with_arg.txt are installed
    -- grog/sub.pl

  - font files are installed in $(DESTDIR)/usr/local/groff/1.22.3/font
    and oldfont and identical to the one installed with the previous
    build system, except the fonts from devpdf which are not generated
    identically at each build.

  - tmac files from 'tmac' dir are installed in
    $(DESTDIR)/usr/local/groff/1.22.3/tmac. Some files are first
    stripped (comments removed) at build time. Checked that they are
    strictly identical to the one install by the original build
    system.
  
  - contrib scripts installed in $(DESTDIR)/usr/local/bin

  - contrib/chem:

    -- chem.pic installed in
    $(DESTDIR)/usr/local/share/groff/1.22.3/pic/chem.pic

    -- other chem files installed in
    $(DESTDIR)/usr/local/share/doc/groff-1.22.3/examples, identical to
    the old build system.
    
    -- contrib/chem/README is strangely build but not installed, this
       is the behaviour on the old build system.

  - contrib/hdtbl:
   
    -- example files in
      $(DESTDIR)/usr/local/share/doc/groff-1.22.3/examples/hdtbl

    -- hdtbl.tmac and hdmisc.tmac installed in 
       $(DESTDIR)/usr/local/share/groff-1.22.3/tmac

  - contrib/mm
    
    -- tmac files in tmacdir, misc files in
       $(DESTDIR)/usr/local/share/groff/1.22.3/tmac/mm

    -- refer-mm.tmac in tmacdir

  - contrib/pdfmark

    -- tmac files
    -- pdfmark.pdf

  - contrib/mom
     -- example files in $(DESTDIR)/usr/local/share/doc/groff-1.22.3/examples/mom
     -- html files in $(DESTDIR)/usr/local/share/doc/groff-1.22.3/html/mom

  - doc

    -- webpageXX.html files
    -- picXX.html files
    -- info file from groff.texinfo

Diff with previous build system after final (full tree comparison):
  - devcp1047 fonts are installed $(DESTDIR)/usr/local/groff/1.22.3/font
  - 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

  - Note: target 'uninstall_groffdirs' is a dependency of standard
    target uninstall-hook, and removes groff's specific directories
    (exampledir, libprogramdir etc ...). contrib that create
    sub-directories in these groff specific directories should also
    add a custom rule that is a dependency of uninstall_groffdirs to
    remove the directories it created, otherwise uninstall-hook will
    fail du to the impossibility to remove non-empty dir.

  - Tree after uninstall:
.
└── usr
    └── local
        ├── bin
        ├── lib
        │   └── X11
        │       └── app-defaults
        └── share
            ├── doc
            ├── info
            │   └── dir
            └── man
                ├── man1
                ├── man5
                └── man7

13 directories, 1 file

  - Notes:
    -- $(DESTDIR)/usr/local/lib/charset.alias is removed if exists
    -- $(DESTDIR)/usr/local/lib/X11/app-defaults/GXditview and
    GXditview-color are removed. However, GXditview.old and
    GXditview-color.old are not removed (this is the behaviour on the
    old build system)
  
2.8 make dist

  groff-1.22.3.tar.gz is generated.

  - Files/directories that are not distributed on purpose:
    all .gitignore files
    .gitmodules
    bootstrap
    bootstrap.conf
    gnulib/
    README.git

  - Files/directories not present in the git tree that are
    distributed:
    build-aux/
    gnulib_m4/
    lib/
    src/include/config.hin
    INSTALL
    Makefile.in
    aclocal.m4
    configure   
    src/preproc/eqn/eqn.cpp
    src/preproc/eqn/eqn.hpp
    src/preproc/pic/pic.cpp
    src/preproc/pic/pic.hpp 
    src/preproc/refer/label.hpp
    src/preproc/refere/label.cpp
    doc/gnu.eps

Note: when building from a tarball, we will use doc/gnu.eps.

2.9 make check
  
  (manually called automake --add-missing to add build-aux/test-driver)
  - gdiffmk's test script is now plugged to the 'make check'
    target. The original runtests.in is renamed to runtests.sh with
    absolute paths. The new script gdiffmk_tests.sh is used to call
    runtests.sh in $(top_builddir)/contrib/gdiff/tests, because
    runtest.sh will generate some result files.
  
2.10 make distcheck
  
  This will attempt to make a tarball, and from this tarball, build
the package(out-of-source build), check it, clean it (checking that no
file remains), install it, uninstall it (checking that no file remains
in the install tree).

  make distcheck

  - All phases now succeed

3. Additional tests
-------------------

3.1 Build without X support

  Calling configure with option --without-x doesn't build:
  - gxidview
  - libxutil.a
  - xtotroff

  The following fonts are not installed: 
  - dev/X100
  - devX100-12
  - devX75
  - devX75-12
  
  'make distcheck' passes correctly, and the tarball generated by
  'make dist' is identical to the one generated with X support.

3.2 Options to build the doc

  - Default behavour
    -- By default all the documentation (except texinfo documents)
       will be installed in:
       $(DESTDIR)/usr/local/share/doc/groff-1.22.3/
    -- The only texinfo documentation installed by default is:
       $(DESTDIR)/usr/local/share/info/groff.info

  - Passing to configure option: --with-doc=no

    No doc is built nor installed, $(DESTDIR)/usr/local/share/doc
    is not even created. groff.info is not installed.

  - Passing to configure option: --with-doc=examples

    Only $(DESTDIR)/usr/local/share/doc/groff-1.22.3/examples is
    present, and contain files in format other than html and pdf
    formats.

  - Passing to configure option: --with-doc=html

    Only $(DESTDIR)/usr/local/share/doc/groff-1.22.3/html/ is present.

  - Passing to configure option: --with-doc=pdf
    Only
    $(DESTDIR)/usr/local/share/doc/groff-1.22.3/pdf/pdfmark.pdf
    is present

  - Passing to configure option: --with-doc=other

    Only .me and .ps files are present in
    $(DESTDIR)/usr/local/share/doc/groff-1.22.3/

  - Passing to configure option: --with-doc=info
    $(DESTDIR)/usr/local/share/doc is not created.
    Only $(DESTDIR/usr/local/share/info/ is installed

  - Note that pre-built HTML doc in contrib/mom is installed even if
    the tools needed to build html doc are not available.


3.3 Build in presence of an non-GNU Troff installation 

  - To simulate the existence of a non-GNU Troff, removed any existing
    troff, and added a dummy troff script in /usr/bin/troff that
    contains:

    #!/bin/sh
    echo 0

    and built groff as usuall.

  - Programs listed in prefixexecbin_PROGRAMS, scripts listed in
    prefixecbin_SCRIPTS and man pages listed in PREFIXMAN1 are
    correctly installed with a 'g' prefix. All targets (clean,
    install/uninstall, distcheck) work as usual. No diff with the old
    build system.

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:

.if
  
  - Build and install as usual:

    -- $(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.

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
