source: networking/netlibs/curl.xml@ b115946

<?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        "aad71c74c5a66eb7eaff6507c22d5615">
  <!ENTITY curl-size          "2.4 MB">
  <!ENTITY curl-buildsize     "79 MB (add 16 MB for tests)">
  <!ENTITY curl-time          "0.3 SBU (add 15 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>

    &lfs91_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>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Patch to fix DNS resolution issues: <ulink
        url="&patch-root;/curl-7.65.1-fix_dns_segfaults-2.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref role="runtime" linkend="make-ca"/> (runtime) 
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="brotli"/>,
      <xref linkend="c-ares"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="libidn2"/>,
      <xref linkend="libpsl"/>,
      <xref linkend="libssh2"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="nghttp2"/>,
      <xref linkend="openldap"/>,
      <xref linkend="samba"/>,
      <ulink url="https://launchpad.net/libmetalink/">libmetalink</ulink>,
      <ulink url="http://rtmpdump.mplayerhq.hu/">librtmp</ulink>, and
      <!--<ulink url="https://tls.mbed.org/">mbed TLS</ulink> (formerly known as
      PolarSSL), and -->
      <!-- mbedTLS/PolarSSL support was removed in 7.65.1 -->
      <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 and may cause failures.)
    </para>

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

  <sect2 role="installation">
    <title>Installation of cURL</title>
<!--
    <para>
      First, apply a patch to fix DNS resolution issues:
    </para>

<screen><userinput>patch -Np1 -i ../curl-7.65.1-fix_dns_segfaults-2.patch</userinput></screen>
-->

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

    2018-08-01 - renodr
    No test failures, but I didn't have any of the optional dependencies except
    for c-ares and libidn2. I might re-run this test suite before release with
    all of the optional deps, but right now, it isn't a priority - rather
    the security fix is.
-->

    <para>
       To run the test suite, issue: <command>make test</command>. 
       Tests 323, 1139, 1140, 1173, and 1560 are known to fail.  
       A few other tests may fail randomly for unknown reasons.
    </para>
<!-- Two (of 857) tests
fail for unknown reasons, and all tests fail is valgrind is installed. Moving
valgrind out of $PATH is recommended if you wish to run the test suite while
it is installed. 

Added by Pierre for curl-7.59.0:
no stunnel, no valgrind, no options
Warning: smb server unexpectedly alive
Warning: dict server unexpectedly alive
TESTDONE: 950 tests out of 951 reported OK: 99%
TESTFAIL: These test cases failed: 1148 
TESTDONE: 1189 tests were considered during 362 seconds.
__________

         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. 
__________
Added by Bruce for curl-7.60.0:
TESTDONE: 957 tests out of 959 reported OK: 99%
TESTFAIL: These test cases failed: 1139 1140 
TESTDONE: 1196 tests were considered during 1184 seconds.
From the logs, both appear to be ipv6 releated.

==========
Added by Douglas for curl-7.61.0:
TESTDONE: 961 tests out of 961 reported OK: 100%
TESTDONE: 1202 tests were considered during 338 seconds.
I only have c-ares and libidn2 installed, I will likely try before release
with all optional dependencies in the book installed.

=========
7.61.1 NOTE: The test suite is extremely noisy, complaining about verification errors.
It's possible this is due to openssl-1.1.1, BUT 79/79 tests report as 100% OK. I had
c-ares, libpsl, and libidn1/2 installed. - Doug

========
7.62.0: All tests passed. libpsl, c-ares, libssh2, libidn2 installed.
All 1098 tests report OK.

=======
Added by Douglas for curl-7.64.0:
TESTDONE: 1022 tests out of 1023 reported OK: 99%
TESTFAIL: These tests cases failed: 323
TESTDONE: 1235 tests were considered during 1279 seconds.
For dependencies, I had c-ares, gnutls, libidn2, libpsl, krb5, libssh2, nghttp2,
OpenLDAP, Samba, stunnel, and Valgrind installed.
=======
Added by bdubbs for curl-7.64.1:
TESTDONE: 1022 tests out of 1025 reported OK: 99%
TESTFAIL: These test cases failed: 323 1139 1140
TESTDONE: 1242 tests were considered during 1483 seconds

=======
Added by renodr for curl-7.65.1:
TESTDONE: 996 tests out of 997 reported OK: 99%
TESTFAIL: These test cases failed: 1560
TESTDONE: 1249 tests were considered during 1091 seconds.
All dependencies except for externals installed.
=======
Added by bdubbs for curl-7.65.2:
TESTDONE: 1034 tests out of 1036 reported OK: 99%
TESTFAIL: These test cases failed: 323 1560
TESTDONE: 1254 tests were considered during 1362 seconds.
Time above does not include test build time.
All dependencies except for externals installed.
=======
Added by bdubbs for curl-7.65.3:
TESTDONE: 1031 tests out of 1036 reported OK: 99%
TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
TESTDONE: 1254 tests were considered during 1364 seconds.

The tests that fail seem to be somewhat random.  What happened between 
yesterday and today that that tests 1139 1140 1173 now fail?

=======
Added by bdubbs for curl-7.68.0:
TESTDONE: 1066 tests out of 1071 reported OK: 99%
TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
TESTDONE: 1290 tests were considered during 1515 seconds.

=======
Added by bdubbs for curl-7.69.0:
TESTDONE: 074 tests out of 1079 reported OK: 99%
TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
TESTDONE: 1320 tests were considered during 1514 seconds.

-->

    <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 Certificate Authority store.
    </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/pki/tls/certs/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>
      <option>--with-libssh2</option>: This paramater adds
      <application>SSH</application> support to cURL. This is disabled
      by default.
    </para>

    <para>
      <option>--enable-ares</option>: This paramater adds
      support for DNS resolution through the c-ares library. It is disabled
      by default, but does speed up DNS resolution queries.
    </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>