glfs/general/prog/gc.xml

<?xml version="1.0" encoding="UTF-8"?>
<!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 gc-download-http "https://github.com/ivmai/bdwgc/releases/download/v&gc-version;/gc-&gc-version;.tar.gz">
  <!ENTITY gc-download-ftp  " ">
  <!ENTITY gc-md5sum        "fc5351214bc2e854070ee3319181a467">
  <!ENTITY gc-size          "1.2 MB">
  <!ENTITY gc-buildsize     "11 MB (with tests)">
  <!ENTITY gc-time          "0.2 SBU (with tests)">
]>

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


  <title>GC-&gc-version;</title>

  <indexterm zone="gc">
    <primary sortas="a-GC">GC</primary>
  </indexterm>

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

    <para>
      The <application>GC</application> package contains the Boehm-Demers-Weiser
      conservative garbage collector, which can be used as a garbage collecting
      replacement for the C malloc function or C++ new operator. It allows you
      to allocate memory basically as you normally would, without explicitly
      deallocating memory that is no longer useful. The collector automatically
      recycles memory when it determines that it can no longer be otherwise
      accessed. The collector is also used by a number of programming language
      implementations that either use C as intermediate code, want to facilitate
      easier interoperation with C libraries, or just prefer the simple
      collector interface. Alternatively, the garbage collector may be used as a
      leak detector for C or C++ programs, though that is not its primary goal.
    </para>

    &lfs121_checked;

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="libatomic_ops"/>
    </para>

  </sect2>

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

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

<screen><userinput>./configure --prefix=/usr      \
            --enable-cplusplus \
            --disable-static   \
            --docdir=/usr/share/doc/gc-&gc-version; &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>.
    </para>

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

<screen role="root"><userinput>make install &amp;&amp;
install -v -m644 doc/gc.man /usr/share/man/man3/gc_malloc.3</userinput></screen>
  </sect2>

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

    <para>
      <parameter>--docdir=/usr/share/doc/gc-&gc-version;</parameter>:
      This option is used so the package will install the
      documentation in a versioned directory.
    </para>

    <para>
      <parameter>--enable-cplusplus</parameter>: This parameter enables the
      building and installing of the C++ library along with the standard
      C library.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

  </sect2>

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

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

      <seglistitem>
        <seg>
          None
        </seg>
        <seg>
          libcord.so,
          libgc.so,
          libgccpp.so, and
          libgctba.so
        </seg>
        <seg>
          /usr/include/gc and
          /usr/share/doc/gc-&gc-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="libcord">
        <term><filename class="libraryfile">libcord.so</filename></term>
        <listitem>
          <para>
            contains a tree-based string library
          </para>
          <indexterm zone="gc libcord">
            <primary sortas="c-libcord">libcord.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgc">
        <term><filename class="libraryfile">libgc.so</filename></term>
        <listitem>
          <para>
            contains a C interface to the conservative garbage collector,
            primarily designed to replace the C malloc function
          </para>
          <indexterm zone="gc libgc">
            <primary sortas="c-libgc">libgc.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgccpp">
        <term><filename class="libraryfile">libgccpp.so</filename></term>
        <listitem>
          <para>
            contains a C++ interface to the conservative garbage collector
          </para>
          <indexterm zone="gc libgccpp">
            <primary sortas="c-libgccpp">libgccpp.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgctba">
        <term><filename class="libraryfile">libgctba.so</filename></term>
        <listitem>
          <para>
            contains a C++ interface to throw bad allocations
          </para>
          <indexterm zone="gc libgctba">
            <primary sortas="c-libgctba">libgctba.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>