How to build groff (was: Install hiccups with groff 1.23.0 tarball)

[G. Branden Robinson]

Hi, Oliver!

I'm not an expert on our build system; while I build groff with great
frequency, I do so in fairly controlled and constrained circumstances.

That said, I'm afraid most of the news about the status quo for the
scenario you raise is bad.  I recommend some alternatives near the end
of this message.

At 2021-05-20T09:34:36+0200, Oliver Corff wrote:
> Dear All,
> 
> I wanted to have a better understanding of the current state of groff,
> and downloaded groff-1.23.0 from
> https://git.savannah.gnu.org/cgit/groff.git, following the link from
> https://www.gnu.org/software/groff/#downloading.
> 
> So far so good, I downloaded the tarball, unpacked it, wanted to
> configure everything, found no ./configure file. Found no INSTALL
> instructions either.

Right.  When you retrieve one of these Git repository snapshots, you're
in "maintainer mode", and you get only what's in the repository.  That's
(ideally) just human-maintained stuff, and not any of the files produced
by the GNU Autotools for consumption by people outside the project.

For better or worse, the INSTALL file itself seems to have become an
artifact that is no longer customized to a specific project.  In our Git
repo, it is a symbolic link into the gnulib directory, which is managed
as a Git "submodule".  While it may not "officially" enjoy that status,
gnulib seems to be steadily becoming part of the GNU build
system/Autotools.[1]

> It did not come to my mind that the necessary information is contained
> in INSTALL.REPO (my usual experience being that all suffixed
> INSTALL.{xxx} files only contain typically platform-specific
> information).

Yes.  The problem here is that you're neither bootstrapping _from a Git
repository_, nor from a distribution tarball.  A snapshot archive is
neither fish nor fowl and apparently we have no documentation
instructing people how to build from it.  I'm a bit curious what the
story is behind the prominence of Savannah's offering of this service
given that probably next to no one builds software from the archives it
produces.  (But see below.)

> That hurdle taken, I ./bootstrap -ped, duly installing all missing
> software which was required (among others, git and libtool;

Yes, this part I would expect from any supported build scenario.

> I haven't done any compiling of source code since around 2005, exactly
> when git entered the scene, so I completely missed that).

I don't think unfamiliarity with Git is part of the problem here.

> Finally, no more complaints about missing pieces of software, but ... :
> 
> ./bootstrap: Bootstrapping from checked-out troff sources...
> ./bootstrap: getting gnulib files...  fatal: not a git repository (or
> any parent up to mount point /) Stopping at filesystem boundary
> (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
> 
> Here I've reached the end of my road. Dave suggested that I post this
> message here.

I _guess_ what you're supposed to do is grab a similar archive from the
'#downloading' link of gnulib's Savannah project--

Is there one?  Let me go see.  Yes, there is.

https://savannah.gnu.org/projects/gnulib

...and if you go to its online-browsable Git repository, you can
presumably obtain a gnulib archive corresponding to the tag for it we
have recorded in groff's Git repository for the gnulib submodule--a
configuration of gnulib that is known and expected to work.  There
appears to be no search feature by commit number, so it's not clear to
me how a human is supposed to find the correct one[3].

This is way too much of a pain to support in its current state, and I
was just about to piteously lament the Savannah web site leading you
on this snipe hunt, but then something puzzled me...

> I wanted to have a better understanding of the current state of groff,
> and downloaded groff-1.23.0 from
> https://git.savannah.gnu.org/cgit/groff.git, following the link from
> https://www.gnu.org/software/groff/#downloading.

How did you get from the second URL to the first?

The "Download" link in the horizontal menu at the top of the groff
Savannah page, and the "Download Area" under the "Quick Overview"
heading below, both go here:

https://ftp.gnu.org/gnu/groff/

...which is a repository for _distribution archives_, which do indeed
contain "configure" scripts.

Screenshot attached.

Now, it's fair to say that the newest archive available there, 1.22.4,
isn't the "current state" of groff that you're interested in.  There
have been hundreds of commits since 1.22.4 was released.

To get closer to what you want, try the 1.23.0.rc1 archive that Bertrand
announced last year[4].  When Bertrand has some free cycles, it's hoped
we'll see an .rc2.

In the meantime, if you want to build the bleeding edge of development,
I think probably the wisest course is to clone the Git repository and
build from there.

To passively observe a Git project, all you need is "git clone" once and
then "git pull" as often as you like thereafter.  "git log" shows you
the whys and wherefores, and you can add "-p" to it to see the actual
diffs that comprise each commit.

I've think I've shared some of my personal recipes before, but here's
the meat of one I call "make-groff-fast" (it skips generation of a
distribution archive).

        test -d ./build && (cd build && make distclean)
        test -d build && rm -r build

        ./bootstrap && \
            mkdir build && \
            cd build && \
            ../configure && \
            make -j $CORES && \
            make check && \
            make doc

The above builds groff, runs its tests, generates all the documentation
formats Texinfo supports (that will mean more build dependencies), and
tries to recover an interrupted or broken build.  (When I screw up
something in the build system, often things are so broken they won't
even clean, so I `rm -r build` by hand to force a complete restart.)

Let me know if this helps or how I could improve it.

Regards,
Branden

[1] For a far afield but interesting discussion regarding the state and
    future of the GNU build system, see the thread begun by Zack
    Weinberg's post of 20 January of this year to the autoconf list.[2]
[2] https://lists.gnu.org/archive/html/autoconf/2021-01/msg00049.html
[3] I see that you could probably manually construct a URL for it,
    knowing the full checksum of the relevant tag, but that's in no way
    a user-friendly procedure.
[4] https://lists.gnu.org/archive/html/groff/2020-11/msg00068.html

groff_savannah_page.png
Description: PNG image

signature.asc
Description: PGP signature