texinfo/util/swig/README
 
  Copyright 2025-2026 Free Software Foundation, Inc.
 
  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.
 
This directory contains a SWIG (https://www.swig.org/) interface designed
to connect high-level programming languages to GNU Texinfo texi2any C code.
The build system is integrated with the main Texinfo build system based on
autoconf, automake and libtool.

Two interfaces are available, a Python and a Perl interface.  The interfaces
are setup and built in their own subdirectories.

For installing Perl modules, the following variables can be set on
the "configure" command line:

  perl_install_mode       Perl SWIG interface install mode site/vendor/custom
                          (default: site)
  perl_installsitearch    Perl installsitearch directory (default: Perl
                          default)
  perl_installsitelib     Perl installsitelib directory (default: Perl
                          default)
  perl_installvendorarch  Perl installvendorarch directory (default: Perl
                          default)
  perl_installvendorlib   Perl installvendorlib directory (default: Perl
                          default)

There is a MakeMaker based distribution in the perl directory.  It depends on
the files generated by swig to be already present.  It is not suitable for
installing when building from the source directory if the texi2any C libraries
are in the build tree as the relinking needed to find the installed Texinfo C
libraries is not performed.  Outside of the build tree, the texi2any libraries
are only found in /usr/local as the directory is hardcoded in Makefile.PL.
The build requires the header files found in the source directory.  Installing
with the MakeMaker based distribution therefore requires:
* an installation of texi2any in /usr/local
* being in the source directory
* having the swig generated files present
* not having the texi2any libraries in the build tree (for example after
  make clean in tta/C).

For the Python interface, there is no built-in determination of the location of
the binary objects that are hidden by libtool in the .libs directory.  To find
the Python module extension from the python/ subdirectory to run scripts from
the build directory, you can add the .libs directory to PYTHONPATH.  For
example, with bash:

$ export PYTHONPATH=.libs

For the Perl interface, finding the Perl module and extension from the build
directory is built-in the scripts and test files.

In addition to the build and test system, this distribution includes the
following files:
    README                    This file.
    texinfo.i                 The SWIG interface file.
    python/test_Texinfo.py    Example of use of the Python interface
    perl/parse_refold.pl      Script recreating the original Texinfo code
                              based on a parsed tree
