source: general/prog/swig.xml@ 875b3b57

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY swig-download-http "&sourceforge-dl;/swig/swig-&swig-version;.tar.gz">
  <!ENTITY swig-download-ftp  " ">
  <!ENTITY swig-md5sum        "c7d55a1bca26752f3846c85b43c1a69c">
  <!ENTITY swig-size          "8.2 MB">
  <!ENTITY swig-buildsize     "82 MB (2.1 GB with tests)">
  <!ENTITY swig-time          "0.1 SBU (add 7.8 SBU for tests; both using parallelism=4)">
]>

<sect1 id="swig" xreflabel="SWIG-&swig-version;">
  <?dbhtml filename="swig.html"?>


  <title>SWIG-&swig-version;</title>

  <indexterm zone="swig">
    <primary sortas="a-swig">SWIG</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to SWIG</title>

    <para>
       <application>SWIG</application> (Simplified Wrapper and Interface
       Generator) is a compiler that integrates <application>C</application>
       and <application>C++</application> with languages including
       <application>Perl</application>,
       <application>Python</application>,
       <application>Tcl</application>,
       <application>Ruby</application>,
       <application>PHP</application>,
       <application>Java</application>,
       <application>C#</application>,
       <application>D</application>,
       <application>Go</application>,
       <application>Lua</application>,
       <application>Octave</application>,
       <application>R</application>,
       <application>Scheme</application>, and
       <application>Ocaml</application>.
       <application>SWIG</application> can
       also export its parse tree into <application>Lisp</application>
       s-expressions and <application>XML</application>.
    </para>
    <para>
       <application>SWIG</application> reads annotated
       <application>C/C++</application> header files and creates wrapper
       code (glue code) in order to make the corresponding
       <application>C/C++</application> libraries available to the listed
       languages, or to extend <application>C/C++</application> programs
       with a scripting language.
    </para>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&swig-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&swig-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &swig-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &swig-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &swig-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &swig-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">SWIG Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="pcre2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="boost"/> for tests, and any of the languages mentioned
      in the introduction, as run-time dependencies
    </para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of SWIG</title>

    <para>
      Install <application>SWIG</application> by running the following
      commands:
    </para>

<screen><userinput>./configure --prefix=/usr                      \
            --without-javascript               \
            --without-maximum-compile-warnings &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>PY3=1 make -k check TCL_INCLUDE=</command>.
      The unsetting of the variable <envar>TCL_INCLUDE</envar> is
      necessary since it is not correctly set by
      <emphasis>configure</emphasis>. The tests are only executed for the
      languages installed on your machine, so the disk space and SBU values
      given for the tests may vary, and should be considered as mere orders of
      magnitude. According to
      <application>SWIG</application>'s documentation, the failure of some
      tests should not be considered harmful. The go tests are buggy and may
      generate a lot of meaningless output.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/swig-&swig-version; &amp;&amp;
cp -v -R Doc/* /usr/share/doc/swig-&swig-version;</userinput></screen>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--without-maximum-compile-warnings</parameter>: disables
      compiler ansi conformance enforcement, which triggers errors in
      the <application>Lua</application> headers (starting with Lua 5.3).
    </para>

    <para>
      <option>--without-&lt;language&gt;</option>: allows disabling the
      building of tests and examples for &lt;language&gt;, but all the
      languages capabilities of <application>SWIG</application> are always
      built. <!--We use it for <application>Clisp</application>, because the
      SWIG implementation is very incomplete and a lot of tests fail. -->
      <!-- Now used for JavaScript because of node CLI changes -->
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          swig and ccache-swig
        </seg>
        <seg>
          None
        </seg>
        <seg>
          /usr/share/doc/swig-&swig-version; and
          /usr/share/swig
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="swig-prog">
        <term><command>swig</command></term>
        <listitem>
          <para>
            takes an interface file containing C/C++ declarations and
            SWIG special instructions, and generates the corresponding
            wrapper code needed to build extension modules
          </para>
          <indexterm zone="swig swig-prog">
            <primary sortas="b-swig">swig</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ccache-swig">
        <term><command>ccache-swig</command></term>
        <listitem>
          <para>
            is a compiler cache, which speeds up re-compilation of
            C/C++/SWIG code
          </para>
          <indexterm zone="swig ccache-swig">
            <primary sortas="b-ccache-swig">ccache-swig</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>
  </sect2>

</sect1>