source: general/prog/swig.xml@ 10f9bb45

<?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-repo;/swig/swig-&swig-version;.tar.gz">
  <!ENTITY swig-download-ftp  " ">
  <!ENTITY swig-md5sum        "c96a1d5ecb13d38604d7e92148c73c97">
  <!ENTITY swig-size          "7.6 MB">
  <!ENTITY swig-buildsize     "93 MB (1.1 GB with tests)">
  <!ENTITY swig-time          "0.4 SBU (6.2 SBU for the tests, using -j4)">
]>

<!-- Try to keep the indentation used in this file-->
<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>

  <!--Required section-->
  <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>

    &lfs78_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 mentionned
      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>
      Install <application>SWIG</application> by running the following
      commands:
    </para>

<!-- Spaces are significant in <screen> sections -->
<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</command>. Tests for
      many languages are executed, depending on which ones you have installed.
      Therefore, disk space and SBU values for the tests should be considered
      only indications of necessary space and time, but not even approximated
      values should they be considered. If you have both <xref
      linkend="python2"/> and <xref linkend="python3"/> 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>

  <!--Optional section-->
  <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/&swig-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <!-- If the program or library name conflicts (is the same) as the
      package name, add -prog or -lib to the varlistentry entity id
      and the 2nd entry of the indexterm zone entity -->

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