source: networking/netlibs/curl.xml@ 94b42903

<?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        "fcf429f28adddf9295ed0c42e79cb097">
  <!ENTITY curl-size          "2.2 MB">
  <!ENTITY curl-buildsize     "43 MB (add 11 MB for tests without valgrind)">
  <!ENTITY curl-time          "0.4 SBU (add 11+ 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) 
    </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 if Running the Test Suite</bridgehead>
    <para role="optional">
      <!-- stunnel is still listed in the docs as required, but 7.58.0
       tests completed happily without it, although the test for unit1323
       reported that the tool set in the test case does not exist - ken -->
      <xref linkend="stunnel"/> (for the HTTPS and FTPS tests) and
      <xref linkend="valgrind"/> (this will slow the tests down)
    </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.

    2017-12-01 - bdubbs 
    Still a lot of test failures.  I did have c-ares, Kerberos, and ldap
    installed this time.  Best guess is that servers are not available.
-->
    <note>
      <para>
      If running the tests for this package with valgrind, it will require a
      version of /lib/ld-2.[MINORVERSION].so library
      with debugging symbols present.
      </para>

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

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

      <para>
      Adjust the above instruction as needed for a 32-bit system
      and to match your installed version of glibc.
      </para>
    </note>

    <para>
      To run the test suite, issue: <command>make test</command>. <!--
         if stunnel and valgrind are not installed, and also most options
         (I had rtmpdump), the tests complete without problems.
Warning: smb server unexpectedly alive
Warning: dict server unexpectedly alive
TESTDONE: 938 tests out of 938 reported OK: 100%
TESTDONE: 1175 tests were considered during 355 seconds.
         and no. I don't have smb - so commenting the rest of this:
      To run the test suite, issue: <command>make test</command>. Many tests 
      may fail that depend on optional dependencies that may not be installed
      or upstream servers that may not be available, especially for tests 
      numbered 700 and above.
      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>