diff --git a/ChangeLog b/ChangeLog index 7966fcd..0a3e733 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2025-04-20 Bruno Haible + + Add some developer documentation. + * DEPENDENCIES: New file. + * HACKING: New file. + * Makefile.in (SOURCE_FILES): Add them. + 2025-04-20 Bruno Haible Release gperf-3.3. diff --git a/DEPENDENCIES b/DEPENDENCIES new file mode 100644 index 0000000..2a505c7 --- /dev/null +++ b/DEPENDENCIES @@ -0,0 +1,80 @@ +The following packages should be installed before GNU gperf is installed +(runtime dependencies that are also build dependencies): None. + + +The following packages should be installed when GNU gperf is installed +(runtime dependencies, but not build dependencies): + +* The Gnulib localizations. + + Recommended. + Needed for localization to the user's language. + + Documentation: + https://www.gnu.org/software/gnulib/manual/html_node/Localization.html + + Download: + https://ftp.gnu.org/gnu/gnulib/gnulib-l10n-* + + +The following should be installed when GNU gperf is built, but are not +needed later, once it is installed (build dependencies, but not runtime +dependencies): + +* A C and C++ runtime, compiler, linker, etc. + + Mandatory. + Either the platform's native 'cc' and 'c++', or GCC 3.1 or newer. + + GCC Homepage: + https://gcc.gnu.org/ + + Download: + https://ftp.gnu.org/gnu/gcc/ + +* A 'make' utility. + + Mandatory. + Either the platform's native 'make' (for in-tree builds only), + or GNU Make 3.79.1 or newer. + + GNU Make Homepage: + https://www.gnu.org/software/make/ + + Download: + https://ftp.gnu.org/gnu/make/ + +* A shell + + Mandatory. + Either the platform's native 'sh', or Bash. + + Homepage: + https://www.gnu.org/software/bash/ + + Download: + https://ftp.gnu.org/gnu/bash/ + +* Core POSIX utilities, including: + [ basename cat chgrp chmod chown cp dd echo expand expr + false hostname install kill ln ls md5sum mkdir mkfifo + mknod mv printenv pwd rm rmdir sleep sort tee test touch + true uname + + Mandatory. + Either the platform's native utilities, or GNU coreutils. + + Homepage: + https://www.gnu.org/software/coreutils/ + + Download: + https://ftp.gnu.org/gnu/coreutils/ + +* The comparison utilities 'cmp' and 'diff'. + + Mandatory. + Either the platform's native utilities, or GNU diffutils. + + Homepage: + https://www.gnu.org/software/diffutils/ + + Download: + https://ftp.gnu.org/gnu/diffutils/ + +* Grep. + + Mandatory. + Either the platform's native grep, or GNU grep. + + Homepage: + https://www.gnu.org/software/grep/ + + Download: + https://ftp.gnu.org/gnu/grep/ + +* Awk. + + Mandatory. + Either the platform's native awk, mawk, or nawk, or GNU awk. + + Homepage: + https://www.gnu.org/software/gawk/ + + Download: + https://ftp.gnu.org/gnu/gawk/ diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..bf78d97 --- /dev/null +++ b/HACKING @@ -0,0 +1,161 @@ +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 diff --git a/Makefile.in b/Makefile.in index 4d73577..5dbb54c 100644 --- a/Makefile.in +++ b/Makefile.in @@ -65,7 +65,7 @@ maintainer-clean : force # List of source files. SOURCE_FILES = \ - README INSTALL.windows NEWS AUTHORS JOIN-GNU \ + README INSTALL.windows NEWS AUTHORS DEPENDENCIES HACKING JOIN-GNU \ autogen.sh configure.ac aclocal.m4 Makefile.in \ Makefile.devel ChangeLog # List of distributed files imported from other packages.