source: general/prog/swig.xml@ 9d725222

<?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        "82133dfa7bba75ff9ad98a7046be687c">
  <!ENTITY swig-size          "7.8 MB">
  <!ENTITY swig-buildsize     "91 MB (1.7 GB with tests)">
  <!ENTITY swig-time          "0.3 SBU (26 SBU for tests)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <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>, <application>Ocaml</application>,
       <application>Modula-3</application>,
       <application>Common Lisp</application>, and
       <application>Pike</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>

    &lfs84_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="pcre"/>
    </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>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/swig"/>
    </para>
  </sect2>

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

    <para>
      If you plan to run the tests, some fixes are needed for using Perl-5.26:
    </para>

<screen><userinput>sed -i 's/\$(PERL5_SCRIPT/-I. &amp;/' Examples/Makefile.in &amp;&amp;
sed -i 's/\$command 2/-I. &amp;/' Examples/test-suite/perl5/run-perl-test.pl</userinput></screen>

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

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

    <para>
      To test the results, issue:
      <command>make -k check TCL_INCLUDE= GOGCC=true</command>. The (un)setting
      of the two variables <envar>GOGCC</envar> and <envar>TCL_INCLUDE</envar>
      is necessary, since they are 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. If you have <xref linkend="python2"/> 
      installed, the Python-3 tests are not run.
      You can run tests for Python-3 by issuing
      <command>PY3=1 make check-python-examples</command> followed by
      <command>PY3=1 make check-python-test-suite</command>.  According to
      <application>SWIG</application>'s documentation, the failure of some
      tests should not be considered harmful.
    </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.
    </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>