All you need to know when hacking (modifying) GNU libunistring or when building
it off a git checkout.


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

You will need reasonably recent versions of the build tools:

  * A C compiler. Such as GNU GCC.
    + Homepage:
      https://gcc.gnu.org/

  * GNU automake 1.16.4 or newer
    + Homepage:
      https://www.gnu.org/software/automake/

  * GNU autoconf
    + Homepage:
      https://www.gnu.org/software/autoconf/

  * GNU m4
    + Homepage:
      https://www.gnu.org/software/m4/

  * GNU gperf
    + Homepage:
      https://www.gnu.org/software/gperf/

  * GNU sed
    + Homepage:
      https://www.gnu.org/software/sed/

  * Perl
    + Homepage:
      https://www.perl.org/

  * Either an internet connection or a recent copy of GNU gnulib.
    In order to work with the HEAD of libunistring development, you need the
    HEAD of the gnulib development.
    In order to work with the version of libunistring at a given date, you need
    the version of gnulib of the same date.
    In order to work with a released tarball of libunistring, you need the
    particular version of gnulib which is indicated in the GNULIB_GIT_COMMIT
    variable in version.sh.
    + Homepage:
      https://www.gnu.org/software/gnulib/

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


Additional requirements for maintainers
---------------------------------------

If you are a maintainer, you will want to minimize the number of tests that
are skipped. To this effect, you need to install a couple of locales, used by
the tests. By default, only those enabled in /etc/locale.gen are preinstalled.

$ sudo localedef -i ar_SA -f ISO-8859-6 ar_SA.ISO-8859-6
$ sudo localedef -i fr_FR -f ISO-8859-1 fr_FR.ISO-8859-1
$ sudo localedef -i fr_FR -f UTF-8 fr_FR.UTF-8
$ sudo localedef -i ja_JP -f EUC-JP ja_JP.EUC-JP
$ sudo localedef -i zh_CN -f GB18030 zh_CN.GB18030


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

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

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


Sources
=======

Most of the sources have their origin in gnulib.


Building
========

See the INSTALL file for generic instructions.

To speed up the build:
  1) You can use the configure option --disable-namespacing.  The speed up is
     by a factor of 1.5.  The resulting library is not namespace-clean and
     therefore should not be installed (if you don't want to risk collisions
     with other libraries) and should certainly not be distributed.
  2) You can use the configure option --disable-static.  The speed up is by
     a factor of 1.6.  The resulting library cannot be used for static
     linking and therefore should certainly not be distributed.


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

There are two continuous integrations that regularly build and test
libunistring:
* On a Linux/glibc system only:
  https://gitlab.com/gnu-libunistring/ci-distcheck/pipelines
  https://gitlab.com/gnu-libunistring/ci-distcheck/-/jobs?scope=finished
  This one will catch only the most blatant mistakes.
* On many platforms:
  https://github.com/gnu-libunistring/ci-check/actions
  This one catches platform-specific bugs.


Running the testsuite in valgrind
=================================

To run the test suite with a memory access checker and leak detector such as
valgrind,
  1) configure with the options --disable-shared and CFLAGS="-g",
  2) run "make",
  3) edit tests/Makefile to uncomment the appropriate definition of the CHECKER
     macro,
  4) run "make check".


Acceptable use of LLM generated code
====================================

General-purpose LLMs as well as LLMs specialized for software programming
can produce ready-to-use and, in many cases, actually working code.

We need to avoid two problems with that:

  * Copyright and license issue: An LLM may regurgitate a piece of copyrighted
    code without the copyright header, thus violating the code's license.
    (Most code licenses require that the copyright header remains intact when
    the code is copied or becomes the basis of derivative works.)

  * Maintainability issues: Such generated code has initially not been
    reviewed by a human programmer. It is often greater in size than what a
    careful programmer would write. Sometimes it also lacks comments.
    People who use "vibe coding" often also observe that the code is of
    lower quality.
    Where software in general can be qualified as for long-term use vs.
    short-term use, vibe coding tends to be more suitable for short-term used
    software.

To this end:

  1) Code included in this package that comes from a single LLM prompt
     must be limited in size: it must be at most 5 lines long.

  2) As a submitter, you assert that you have reviewed such code that you
     submit.

Rule 1 guarantees that the LLM generated code size is smaller than the
"legally significant for copyright purposes" threshold, see
https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html

Rule 2 encourages you to not submit unreviewed garbage.
