Re: groff-1.23.0.rc4 - no ./configure?

[Bertrand Garrigues]

Hi Oliver,

On mar., avril 25 2023 at 08:15:06 , Oliver Corff <oliver.corff@email.de> wrote:
> thank you for directing me to the documentation buried in the two
> INSTALL.* files.
>
> May I suggest that the information along the way of obtaining the
> tarball may be augmented?

I've just seen that Branden has added some clarifications on the groff
site, but here are some extra explanations: most of the GNU packages (at
least GNU packages working with autotools) work the same way:

- The tarballs are stored on ftp://ftp.gnu.org/gnu/ or
  https://alpha.gnu.org/gnu/ , these tarballs have the 'configure'
  script and are "ready for distribution", that is, ready to be built on
  most platforms.  They are good if you just want to install a package
  on your distribution (as 'configure' is there, the only dependency to
  launch the build is the shell, and you won't need to install lots of
  developments tools), but they cannot be used for serious development.

- The source code is hosted on Savannah, and is mainly for developers.
  In order to build groff from the git repo you will need some extra dev
  tools (ex: autotools).  Some files are generated by the build system
  (the configure script, but also Makefile.in, config.hin and so on) and
  not commited; this is because developers may have different versions
  of autotools on their machine, so if we commited these files there
  would be regularly changed, causing noise for nothing.

> My steps were:
>
> 1. I went to https://www.gnu.org/software/groff/#downloading
>
> There the text reads: The development version is available from groff's
> git repository <https://savannah.gnu.org/git/?group=groff>. Read the
> INSTALL.extra and INSTALL.REPO files within for build requirements and
> instructions.
>
> Which reconfirms your point, but
>
> 2. I went to the repository: https://savannah.gnu.org/git/?group=groff
>
> It says: Browse Sources Repository
>
> https://git.savannah.gnu.org/cgit/groff.git

Unfortunately this page says that first, but the best would be to follow
the next section and clone:

  git clone https://git.savannah.gnu.org/git/groff.git

> 3. I saw a list of tar.gz files, with the lates development version on
> top. So I downloaded that and unpacked it locally.
>
> 4. Only then I saw the two INSTALL.* files and the instructions, but
> executing ./bootstrap just resulted in
>
> 5. fatal: not a git repository (or any parent up to mount point /)

The tar.gz files here are not tarballs ready for distribution, they are
just the source code corresponding to a given tag.  You have the same
thing on for example Github were you can click to download a zip of the
tip of the main branch or of zip of a particular tag.  As there is no
.git in there, they are useless -- as explained by Branden -- because of
the git submodules.

But even if you were looking for a package without git submodule, I
advise you to always 'git clone' the package, and never download a zip
or tar.gz from the source code repository.  Suppose you need to submit a
patch or to discuss of some particular change, you won't be able to do
so if you haven't got a proper git repo.  Also, if for some reasons the
build fails and you need some assistance, you can check which files are
generated with a simple 'git status --ignored'.  If you were using a
source tree from a tar.gz, all the normal files and generated files
would be mixed up.

> You may consider me being naive --- why do I stumble at things which are
> "taken for granted"?
>
> Is it possible to insert a phrase somewhere either in
> https://www.gnu.org/software/groff/#downloading or in
> https://savannah.gnu.org/git/?group=groff that these tarballs cannot be
> used as is, but must be treated differently?

I've tried to find some detailed explanations on the main GNU site (for
example here https://www.gnu.org/software/software.en.html), but -- how
embarrassing -- I haven't found much details.

So to sum up:

- If you want to install a GNU package on your system and to play around
  as a user, download an official tarball from GNU's main FTP or from
  the alpha FTP. It should build smoothly on most platforms.

- If you want to make some development, or if you need a more recent
  version than the tarball version (in which case you have no other
  option than to switch to "developer mode"), use the git repo of the
  package and clone it.  You will have to follow the detailed
  instruction of the package, and you may have to install more
  development tools.


Regards,

Bertrand Garrigues