All you need to know when hacking (modifying) GNU libffcall 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.15 or newer
    + 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 groff 1.17 or newer
    + Homepage:
      https://www.gnu.org/software/groff/

  * 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/

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


Cross-compilation tools
=======================

The Makefile.devel has rules to regenerate some *.s and *.S files, using
GCC cross-compiler builds. You find a table of these cross-compilers in
the file cross-tools/cross.conf.

To build all these cross-compilers, use the file cross-tools/cross-build.sh.
See the comments at the top of cross-tools/cross-build.sh for how to use it.
When done, copy the generated 'cross' script into your $PATH so that
Makefile.devel will find it.

Alternatively, if you are running Linux/x86_64, you can use a premade Docker
image that contains these cross-compilers. The command to fetch and use it is:
docker run --rm -t -i registry.gitlab.com/gnu-libffcall/ci-buildtools:ubuntu2004


Building off the git repository
===============================

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

After fetching the sources from the repository:

1. Create the cross-compilation tools, as described above.

2. Regenerate the *.s and *.S files, by running
     make -f Makefile.devel

3. Run
     ./autopull.sh
     ./autogen.sh

4. 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-libffcall/ci-distcheck/pipelines
  https://gitlab.com/gnu-libffcall/ci-distcheck/-/jobs?scope=finished


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.

