source: networking/netlibs/curl.xml@ bfc3945

<?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 curl-download-http "https://curl.haxx.se/download/curl-&curl-version;.tar.xz">
  <!ENTITY curl-download-ftp  " ">
  <!ENTITY curl-md5sum        "e332347fc0b80cabf9c42f310be040c5">
  <!ENTITY curl-size          "2.2 MB">
  <!ENTITY curl-buildsize     "36 MB (add 11 MB for tests)">
  <!ENTITY curl-time          "0.3 SBU (add 3.2 SBU for tests)">
]>

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

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

  <title>cURL-&curl-version;</title>

  <indexterm zone="curl">
    <primary sortas="a-cURL">cURL</primary>
  </indexterm>

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

    <para>
      The <application>cURL</application> package contains an utility
      and a library used for transferring files with URL syntax to any of
      the following protocols: FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP,
      TELNET, DICT, LDAP, LDAPS and FILE. Its ability to both download
      and upload files can be incorporated into other programs to support
      functions like streaming media.
    </para>

    &lfs81_checked;

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

<!-- Tests seem to pass without any patch
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/curl-&curl-version;-valgrind_filter-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">cURL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref role="runtime" linkend="cacerts"/> (runtime) and
      <xref linkend="openssl"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="c-ares"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="libidn2"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="nghttp2"/>,
      <xref linkend="openldap"/>,
      <xref linkend="samba"/>,
      <ulink url="https://launchpad.net/libmetalink/">libmetalink</ulink>,
      <ulink url="https://github.com/rockdaboot/libpsl">libpsl</ulink>,
      <ulink url="http://rtmpdump.mplayerhq.hu/">librtmp</ulink>,
      <ulink url="http://www.libssh2.org">libssh2</ulink>,
      <ulink url="https://tls.mbed.org/">mbed TLS</ulink> (formerly known as
      PolarSSL), and
      <ulink url="http://spnego.sourceforge.net/"> SPNEGO</ulink>
    </para>

    <bridgehead renderas="sect4">Optional for Running the Test Suite</bridgehead>
    <para role="optional">
      <xref linkend="stunnel"/> (for the HTTPS and FTPS tests) and
      <xref linkend="valgrind"/>
    </para>

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

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

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

<screen><userinput>./configure --prefix=/usr                           \
            --disable-static                        \
            --enable-threaded-resolver              \
            --with-ca-path=/etc/ssl/certs &amp;&amp;
make</userinput></screen>

<!--
   For version 7.54.1 I got:
   TESTDONE: 869 tests out of 869 reported OK: 100%
   TESTDONE: 1092 tests were considered during 1080 seconds

    <para>
      Running the test suite is optional. About 2% of the tests fail. Increase
      in test time by each failed test is about 10%. Tests SBU above was
      obtained disabling failing tests, with:
    </para>

    2017-10-29 - bdubbs
    For version 7.56.1 I had a lot of test failures which included long
    timeouts.  Could not determine the cause of the timeouts or failures,
    but I was missing c-ares, MIT Kerberos, ldap, samba, and the six
    external packages.
-->
    <note>
      <para>
      To run the tests for this package, valgrind requires a version of the
      /lib/ld-2.23.so (or later) library with debugging symbols present.
      </para>

      <para>Current versions of LFS does not strip /lib/ld-2.23.so but
      previous versions of LFS stripped these debugging symbols at the end of
      Chapter 6. To get this library on oldeer systems, glibc must be rebuilt 
      with the current
      glibc version using the same compiler that was used to build LFS. The
      ld-2.23.so can then be renamed to ld-2.23.so.dbg and copied to /lib. Then
      a symlink needs to be changed: 
      </para>

      <screen role="nodump"><userinput>ln -sfv ld-2.23.so.dbg /lib/ld-linux-x86-64.so.2</userinput></screen>

      <para>
      Adjust the above instruction as needed for a 32-bit system
      or for a different version of glibc.
      </para>
    </note>

    <para>
      To run the test suite, issue: <command>make test</command>. Many tests 
      may fail that depend on optional dependencies that may not be installed.
      Test time may be significantly increase due to hanging tests that fail.
    </para>

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

<screen role="root"><userinput>make install &amp;&amp;

rm -rf docs/examples/.deps &amp;&amp;

find docs \( -name Makefile\* \
          -o -name \*.1       \
          -o -name \*.3 \)    \
          -exec rm {} \;      &amp;&amp;
install -v -d -m755 /usr/share/doc/curl-&curl-version; &amp;&amp;
cp -v -R docs/*     /usr/share/doc/curl-&curl-version;</userinput></screen>

    <para>
      Simple tests to the new installed <command>curl</command>:
      <command>curl --trace-ascii debugdump.txt http://www.example.com/</command>
      and
      <command>curl --trace-ascii d.txt --trace-time http://example.com/</command>.
      Inspect the locally created trace files <filename>debugdump.txt</filename>
      and <filename>d.txt</filename>, which contain version downloaded
      files information, etc. One file has the time for each action logged.
    </para>
  </sect2>

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

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

    <para>
      <parameter>--enable-threaded-resolver</parameter>: This switch enables
      <application>cURL</application>'s builtin threaded DNS resolver.
    </para>

    <para>
      <parameter>--with-ca-path=/etc/ssl/certs</parameter>: This
      switch sets the location of the BLFS <xref linkend="cacerts"/>.
    </para>

    <para>
      <option>--with-gssapi</option>: This parameter adds
      <application>Kerberos 5</application> support to
      <filename class="libraryfile">libcurl</filename>.
    </para>

    <para>
      <option>--without-ssl --with-gnutls</option>: Use to
      build with <application>GnuTLS</application> support
      instead of <application>OpenSSL</application> for SSL/TLS.
    </para>

    <para>
      <option>--with-ca-bundle=/etc/ssl/ca-bundle.crt</option>: Use
      this switch instead of <parameter>--with-ca-path</parameter> if
      building with <application>GnuTLS</application> support
      instead of <application>OpenSSL</application> for SSL/TLS.
    </para>

    <para>
      <command>find docs ... -exec rm {} \;</command>: This command removes
      <filename>Makefiles</filename> and man files from the documentation
      directory that would otherwise be installed by the commands that follow.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
           curl, and curl-config
        </seg>
        <seg>
           libcurl.so
        </seg>
        <seg>
          /usr/include/curl and
          /usr/share/doc/curl-&curl-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="curl-prog">
        <term><command>curl</command></term>
        <listitem>
         <para>
           is a command line tool for transferring files with URL syntax.
         </para>
          <indexterm zone="curl curl-prog">
            <primary sortas="b-curl">curl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="curl-config">
        <term><command>curl-config</command></term>
        <listitem>
          <para>
            prints information about the last compile, like libraries
            linked to and prefix setting.
          </para>
          <indexterm zone="curl curl-config">
            <primary sortas="b-curl-config">curl-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcurl">
        <term><filename class="libraryfile">libcurl.so</filename></term>
        <listitem>
          <para>
            provides the API functions required by
            <command>curl</command> and other programs.
          </para>
          <indexterm zone="curl libcurl">
            <primary sortas="c-libcurl">libcurl.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>