HACKING

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


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.x
    + Homepage:
      https://www.gnu.org/software/automake/

  * GNU autoconf 2.69 or newer
    + 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 groff 1.17 or newer
    + Homepage:
      https://www.gnu.org/software/groff/

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

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

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=libiconv .

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


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.


Adding new encodings
====================

For an indication which encodings are acceptable in the official version of
GNU libiconv, take a look at NOTES.

For an indication which files need to be modified when adding a new encoding,
look for example at the 2007-05-25 ChangeLog entry for RK1048.  The lib/*.h
file for an encoding is usually generated by one of the tools in the tools/
directory.  All you need to provide is the conversion table in the format of
the many *.TXT files.