source: general/genlib/brotli.xml@ e556b03

<?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 brotli-download-http "https://github.com/google/brotli/archive/v&brotli-version;/brotli-&brotli-version;.tar.gz">
  <!ENTITY brotli-download-ftp  " ">
  <!ENTITY brotli-md5sum        "3a6a3dba82a3604792d3cb0bd41bca60">
  <!ENTITY brotli-size          "500 KB">
  <!ENTITY brotli-buildsize     "33 MB (with python3 bindings)">
  <!-- The python tests for this package are broken.  The tarball is missing a lot of test files -->
  <!ENTITY brotli-time          "0.3 SBU (with python3 bindings; parallelism=4)">
]>

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


  <title>brotli-&brotli-version;</title>

  <indexterm zone="brotli">
    <primary sortas="a-brotli">Brotli</primary>
  </indexterm>

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

    <para>
      <application>Brotli</application> provides a general-purpose lossless
      compression algorithm that compresses data using a combination of a
      modern variant of the LZ77 algorithm, Huffman coding and 2nd order
      context modeling. Its libraries are particularly used for WOFF2 fonts
      on webpages.
    </para>

    &lfs120_checked;

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

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

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <!--<xref linkend="pluggy"/> and-->
      <!-- Pluggy is a required dependency of pytest -->
      <xref linkend="pytest"/> (for testing Python3 bindings)
    </para>

  </sect2>

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

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

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

cmake -DCMAKE_INSTALL_PREFIX=/usr \
      -DCMAKE_BUILD_TYPE=Release  \
      ..  &amp;&amp;
make</userinput></screen>

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

<!--  These are broken
    <para>
      The python tests are missing most of the necessary testdata files and
      therefore 240 of 311 tests fail.
      If you nevertheless wish to test the bindings, go back to the top-level directory and
      issue: <command>python3 setup.py test</command>.
    </para>
-->
    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>
      If desired, build the <application>Python3</application>
      bindings:
    </para>

<screen><userinput>cd .. &amp;&amp;
sed "/c\/.*\.[ch]'/d;\
     /include_dirs=\[/\
     i libraries=['brotlicommon','brotlidec','brotlienc']," \
    -i setup.py &amp;&amp;
&build-wheel-cmd; $PWD</userinput></screen>

    <para>
      Install the <application>Python3</application>
      bindings as the &root; user:
    </para>

<screen role="root"><userinput>&install-wheel; Brotli</userinput></screen>

    <!-- "131 passed in 2.76s" for me with 1.1.0 -->
    <para>
      To test the <application>Python3</application> binding, issue:
      <command>pytest</command>.
    </para>
  </sect2>

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

    <!-- https://github.com/google/brotli/issues/933 -->
    <para>
      <command>sed ... -i setup.py</command>: Stop
      <filename>setup.py</filename> from rebuilding the entire package all
      over again, use the already installed libraries for the
      <application>Python3</application> binding instead.
    </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>
          brotli
        </seg>
        <seg>
          libbrotlicommon.so,
          libbrotlidec.so, and
          libbrotlienc.so
        </seg>
        <seg>
          /usr/include/brotli and
          /usr/lib/python&python3-majorver;/site-packages/Brotli-&brotli-version;.dist-info
          (if you built and installed the Python3 bindings)
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="brotli-prog">
        <term><command>brotli</command></term>
        <listitem>
          <para>
            can compress or decompress files, or test the integrity of
            compressed files
          </para>
          <indexterm zone="brotli brotli-prog">
            <primary sortas="b-brotli">brotli</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libbrotlicommon">
        <term><filename class="libraryfile">libbrotlicommon{-static.a,.so}</filename></term>
        <listitem>
          <para>
            is the Brotli common dictionary library
          </para>
          <indexterm zone="brotli libbrotlicommon">
            <primary sortas="c-libbrotlicommon">libbrotlicommon{,-static.a,.so}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libbrotlidec">
        <term><filename class="libraryfile">libbrotlidec{-static.a,.so}</filename></term>
        <listitem>
          <para>
            is the Brotli decoder library
          </para>
          <indexterm zone="brotli libbrotlidec">
            <primary sortas="c-libbrotlidec">libbrotlidec{,-static.a,.so}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libbrotlienc">
        <term><filename class="libraryfile">libbrotlienc{-static.a,.so}</filename></term>
        <listitem>
          <para>
            is the Brotli common encoder library
          </para>
          <indexterm zone="brotli libbrotlienc">
            <primary sortas="c-libbrotlienc">libbrotlienc{,-static.a,.so}</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>

  </sect2>

</sect1>