gperf/HACKING

All you need to know when hacking (modifying) GNU gperf or when building
it off the git repository.


Requirements
============

You will need reasonably recent versions of the build tools:

  * A C and a C++ compiler. Such as GNU GCC.
    + Homepage:
      https://gcc.gnu.org/
    + Pre-built package name:
      - On Debian and Debian-based systems: gcc, gcc-doc,
      - On Red Hat distributions: gcc.
      - Other: https://repology.org/project/gcc/versions

  * GNU automake
    + Homepage:
      https://www.gnu.org/software/automake/
    + Pre-built package name:
      - On Debian and Debian-based systems: automake,
      - On Red Hat distributions: automake.
      - Other: https://repology.org/project/automake/versions

  * GNU autoconf
    + Homepage:
      https://www.gnu.org/software/autoconf/
    + Pre-built package name:
      - On Debian and Debian-based systems: autoconf, autoconf-doc,
      - On Red Hat distributions: autoconf.
      - Other: https://repology.org/project/autoconf/versions

  * GNU m4
    + Homepage:
      https://www.gnu.org/software/m4/
    + Pre-built package name:
      - On Debian and Debian-based systems: m4, m4-doc,
      - On Red Hat distributions: m4.
      - Other: https://repology.org/project/m4/versions

  * GNU texinfo
    + Homepage:
      https://www.gnu.org/software/texinfo/
    + Pre-built package name:
      - On Debian and Debian-based systems: texinfo,
      - On Red Hat distributions: texinfo.
      - Other: https://repology.org/project/texinfo/versions

  * Perl
    + Homepage:
      https://www.perl.org/
    + Pre-built package name:
      - On Debian and Debian-based systems: perl, perl-doc,
      - On Red Hat distributions: perl.
      - Other: https://repology.org/project/perl/versions

  * TeX (for making the doc in .dvi, .ps or .pdf format)
    + Homepage:
      https://tug.org/texlive/
    + Pre-built package name:
      - On Debian and Debian-based systems: texlive-base, texlive-latex-base,
      - On Red Hat distributions: texlive-base.
      - Other: https://repology.org/project/texlive/versions

  * Either an internet connection or a recent copy of GNU gnulib.
    + Homepage:
      https://www.gnu.org/software/gnulib/

  * GNU tar (for creating distributable tarballs)
    + Homepage:
      https://www.gnu.org/software/tar/
    + Pre-built package name:
      - On Debian and Debian-based systems: tar, tar-doc,
      - On Red Hat distributions: tar.
      - Other: https://repology.org/project/tar/versions

And, of course, the packages listed in the DEPENDENCIES file.


Building off the Git repository
===============================

Access to the Git repository is described at
https://savannah.gnu.org/git/?group=gperf .

After fetching the sources from the Git repository, peek at the comments in
autogen.sh, then run
  ./autopull.sh
  ./autogen.sh
Then you can proceed with "./configure" as usual.

Each time you want to update the source, do not only "git pull".  Instead do
  git pull && ./autopull.sh
  ./autogen.sh


Continuous integration
======================

The package is built automatically, at regular intervals.  You find the latest
build results here:
  https://gitlab.com/gnu-gperf/ci-distcheck/pipelines
  https://gitlab.com/gnu-gperf/ci-distcheck/-/jobs?scope=finished


Submitting patches
==================

Patches should be sent to bug-gperf@gnu.org, the bug/feature mailing
list.  You can subscribe to the mailing list, or see the list
archives, by following links from
https://savannah.gnu.org/mail/?group=gperf .

To email a patch you can use a shell command like 'git format-patch -1'
to create a file, and then attach the file to your email.

For the style of a ChangeLog entry, see the "Change Logs" section of
the GNU coding standards:

  https://www.gnu.org/prep/standards/html_node/Change-Logs.html


Avoid use of the C++ Standard Library
=====================================

In this package, we avoid use of the C++ Standard Library, except for
low-level facilities that are tied with the C++ language (such as
placement-new or 'throw std::bad_alloc()'). The reasons are:

  * My general experience with C++ is that the more features from
    the language I use, the more it turns into a waste of time, and
    I have the suspicion that with the C++ library it would be
    the same.

  * There are several implementations of the C++ Standard Library,
    and I'm not inclined to start adding workarounds here and there,
    like we did with C library bugs before Gnulib was invented.

  * I hate bloat, and the C++ Standard Library is bloated. Even
    if a large amount of this bloat goes away through inlining and
    compiler optimizations, I hate to read through the x86_64 instructions
    generated by the compiler in order to understand what a certain
    piece of code actually does. (Reading the libstdc++ code is not
    an alternative, because the abuse of templates in C++ — originally
    invented for containers — makes that code unreadable. For
    comparison, the D language has similar amounts of bloat as C++,
    but it's at least halfway readable.)

  * I hate to have duplicate code at the binary level. The C++ library
    often instantiates the same code once for each set of template
    parameters. Instead, I want to have control over which function
    occurs only once.

  * The C++ Standard Library does not evolve monotonically. Up until
    C++11, they added things in backwards compatible ways. But when
    you peruse cppreference.com, you realize that starting with C++17
    they remove features [1] or reorganize features in non-backward-
    compatible ways [2].
    [1] https://lists.gnu.org/archive/html/bug-gnulib/2023-09/msg00054.html
    [2] https://git.savannah.gnu.org/gitweb/?p=gettext.git;a=blob;f=gettext-tools/examples/hello-c%2B%2B20/hello.cc