source: networking/netlibs/curl.xml@ 39f5848

lazarus
Last change on this file since 39f5848 was 39f5848, checked in by Thomas Trepl (Moody) <thomas@…>, 8 months ago

Merge trunk

  • Property mode set to 100644
File size: 16.8 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY curl-download-http "https://curl.se/download/curl-&curl-version;.tar.xz">
8 <!ENTITY curl-download-ftp " ">
9 <!ENTITY curl-md5sum "74d3c4ca8aaa6c0619806d6e246e65fb">
10 <!ENTITY curl-size "2.4 MB">
11 <!ENTITY curl-buildsize "102 MB (add 19 MB for tests)">
12 <!ENTITY curl-time "0.3 SBU (with parallelism=4; add 15 SBU for tests)">
13]>
14
15<sect1 id="curl" xreflabel="cURL-&curl-version;">
16 <?dbhtml filename="curl.html"?>
17
18 <sect1info>
19 <date>$Date$</date>
20 </sect1info>
21
22 <title>cURL-&curl-version;</title>
23
24 <indexterm zone="curl">
25 <primary sortas="a-cURL">cURL</primary>
26 </indexterm>
27
28 <sect2 role="package">
29 <title>Introduction to cURL</title>
30
31 <para>
32 The <application>cURL</application> package contains an utility
33 and a library used for transferring files with URL syntax to any of
34 the following protocols: FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP,
35 TELNET, DICT, LDAP, LDAPS and FILE. Its ability to both download
36 and upload files can be incorporated into other programs to support
37 functions like streaming media.
38 </para>
39
40 &lfs110a_checked;
41
42 <bridgehead renderas="sect3">Package Information</bridgehead>
43 <itemizedlist spacing="compact">
44 <listitem>
45 <para>
46 Download (HTTP): <ulink url="&curl-download-http;"/>
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 Download (FTP): <ulink url="&curl-download-ftp;"/>
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 Download MD5 sum: &curl-md5sum;
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Download size: &curl-size;
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Estimated disk space required: &curl-buildsize;
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Estimated build time: &curl-time;
72 </para>
73 </listitem>
74 </itemizedlist>
75<!--
76 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
77 <itemizedlist spacing="compact">
78 <listitem>
79 <para>
80 Required patch:
81 <ulink url="&patch-root;/curl-&curl-version;-function_naming-1.patch"/>
82 </para>
83 </listitem>
84 </itemizedlist>
85-->
86
87 <bridgehead renderas="sect3">cURL Dependencies</bridgehead>
88
89 <bridgehead renderas="sect4">Recommended</bridgehead>
90 <para role="recommended">
91 <xref role="runtime" linkend="make-ca"/> (runtime)
92 </para>
93
94 <bridgehead renderas="sect4">Optional</bridgehead>
95 <para role="optional">
96 <xref linkend="brotli"/>,
97 <xref linkend="c-ares"/>,
98 <xref linkend="gnutls"/>,
99 <xref linkend="libidn2"/>,
100 <xref linkend="libpsl"/>,
101 <xref linkend="libssh2"/>,
102 <xref linkend="mitkrb"/>,
103 <xref linkend="nghttp2"/>,
104 <xref linkend="openldap"/>,
105 <xref linkend="samba"/>,
106 <ulink url="https://www.secureauth.com/labs/open-source-tools/impacket/">impacket</ulink>,
107 <ulink url="https://launchpad.net/libmetalink/">libmetalink</ulink>,
108 <ulink url="http://rtmpdump.mplayerhq.hu/">librtmp</ulink>,
109 <ulink url="https://github.com/ngtcp2/ngtcp2/">ngtcp2</ulink>,
110 <!--<ulink url="https://tls.mbed.org/">mbed TLS</ulink> (formerly known as
111 PolarSSL), and -->
112 <!-- mbedTLS/PolarSSL support was removed in 7.65.1 -->
113 <ulink url="https://github.com/cloudflare/quiche">quiche</ulink>, and
114 <ulink url="http://spnego.sourceforge.net/">SPNEGO</ulink>
115 </para>
116
117 <bridgehead renderas="sect4">Optional if Running the Test Suite</bridgehead>
118 <para role="optional">
119 <!-- stunnel is still listed in the docs as required, but 7.58.0
120 tests completed happily without it, although the test for unit1323
121 reported that the tool set in the test case does not exist - ken -->
122 <xref linkend="stunnel"/> (for the HTTPS and FTPS tests) and
123 <xref linkend="valgrind"/> (this will slow the tests down and may cause failures.)
124 </para>
125
126 <para condition="html" role="usernotes">User Notes:
127 <ulink url="&blfs-wiki;/curl"/>
128 </para>
129 </sect2>
130
131 <sect2 role="installation">
132 <title>Installation of cURL</title>
133
134 <para>
135 Install <application>cURL</application> by running the following
136 commands:
137 </para>
138
139<screen><userinput>./configure --prefix=/usr \
140 --disable-static \
141 --with-openssl \
142 --enable-threaded-resolver \
143 --with-ca-path=/etc/ssl/certs &amp;&amp;
144make</userinput></screen>
145
146<!--
147 For version 7.54.1 I got:
148 TESTDONE: 869 tests out of 869 reported OK: 100%
149 TESTDONE: 1092 tests were considered during 1080 seconds
150
151 <para>
152 Running the test suite is optional. About 2% of the tests fail. Increase
153 in test time by each failed test is about 10%. Tests SBU above was
154 obtained disabling failing tests, with:
155 </para>
156
157 2017-10-29 - bdubbs
158 For version 7.56.1 I had a lot of test failures which included long
159 timeouts. Could not determine the cause of the timeouts or failures,
160 but I was missing c-ares, MIT Kerberos, ldap, samba, and the six
161 external packages.
162
163 2017-12-01 - bdubbs
164 Still a lot of test failures. I did have c-ares, Kerberos, and ldap
165 installed this time. Best guess is that servers are not available.
166
167 2018-08-01 - renodr
168 No test failures, but I didn't have any of the optional dependencies except
169 for c-ares and libidn2. I might re-run this test suite before release with
170 all of the optional deps, but right now, it isn't a priority - rather
171 the security fix is.
172-->
173
174 <para>
175 To run the test suite, issue: <command>make test</command>.
176<!-- Four tests, 1139, 1140, 1173, and 1177, are known to fail due to
177 missing executables from the optional dependencies.-->
178 </para>
179<!-- Two (of 857) tests
180fail for unknown reasons, and all tests fail is valgrind is installed. Moving
181valgrind out of $PATH is recommended if you wish to run the test suite while
182it is installed.
183
184Added by Pierre for curl-7.59.0:
185no stunnel, no valgrind, no options
186Warning: smb server unexpectedly alive
187Warning: dict server unexpectedly alive
188TESTDONE: 950 tests out of 951 reported OK: 99%
189TESTFAIL: These test cases failed: 1148
190TESTDONE: 1189 tests were considered during 362 seconds.
191__________
192
193 if stunnel and valgrind are not installed, and also most options
194 (I had rtmpdump), the tests complete without problems.
195Warning: smb server unexpectedly alive
196Warning: dict server unexpectedly alive
197TESTDONE: 938 tests out of 938 reported OK: 100%
198TESTDONE: 1175 tests were considered during 355 seconds.
199 and no. I don't have smb - so commenting the rest of this:
200 To run the test suite, issue: <command>make test</command>. Many tests
201 may fail that depend on optional dependencies that may not be installed
202 or upstream servers that may not be available, especially for tests
203 numbered 700 and above.
204 Test time may be significantly increase due to hanging tests that fail.
205__________
206Added by Bruce for curl-7.60.0:
207TESTDONE: 957 tests out of 959 reported OK: 99%
208TESTFAIL: These test cases failed: 1139 1140
209TESTDONE: 1196 tests were considered during 1184 seconds.
210From the logs, both appear to be ipv6 releated.
211
212==========
213Added by Douglas for curl-7.61.0:
214TESTDONE: 961 tests out of 961 reported OK: 100%
215TESTDONE: 1202 tests were considered during 338 seconds.
216I only have c-ares and libidn2 installed, I will likely try before release
217with all optional dependencies in the book installed.
218
219=========
2207.61.1 NOTE: The test suite is extremely noisy, complaining about verification errors.
221It's possible this is due to openssl-1.1.1, BUT 79/79 tests report as 100% OK. I had
222c-ares, libpsl, and libidn1/2 installed. - Doug
223
224========
2257.62.0: All tests passed. libpsl, c-ares, libssh2, libidn2 installed.
226All 1098 tests report OK.
227
228=======
229Added by Douglas for curl-7.64.0:
230TESTDONE: 1022 tests out of 1023 reported OK: 99%
231TESTFAIL: These tests cases failed: 323
232TESTDONE: 1235 tests were considered during 1279 seconds.
233For dependencies, I had c-ares, gnutls, libidn2, libpsl, krb5, libssh2, nghttp2,
234OpenLDAP, Samba, stunnel, and Valgrind installed.
235=======
236Added by bdubbs for curl-7.64.1:
237TESTDONE: 1022 tests out of 1025 reported OK: 99%
238TESTFAIL: These test cases failed: 323 1139 1140
239TESTDONE: 1242 tests were considered during 1483 seconds
240
241=======
242Added by renodr for curl-7.65.1:
243TESTDONE: 996 tests out of 997 reported OK: 99%
244TESTFAIL: These test cases failed: 1560
245TESTDONE: 1249 tests were considered during 1091 seconds.
246All dependencies except for externals installed.
247=======
248Added by bdubbs for curl-7.65.2:
249TESTDONE: 1034 tests out of 1036 reported OK: 99%
250TESTFAIL: These test cases failed: 323 1560
251TESTDONE: 1254 tests were considered during 1362 seconds.
252Time above does not include test build time.
253All dependencies except for externals installed.
254=======
255Added by bdubbs for curl-7.65.3:
256TESTDONE: 1031 tests out of 1036 reported OK: 99%
257TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
258TESTDONE: 1254 tests were considered during 1364 seconds.
259
260The tests that fail seem to be somewhat random. What happened between
261yesterday and today that that tests 1139 1140 1173 now fail?
262
263=======
264Added by bdubbs for curl-7.68.0:
265TESTDONE: 1066 tests out of 1071 reported OK: 99%
266TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
267TESTDONE: 1290 tests were considered during 1515 seconds.
268
269=======
270Added by bdubbs for curl-7.69.0:
271TESTDONE: 074 tests out of 1079 reported OK: 99%
272TESTFAIL: These test cases failed: 323 1139 1140 1173 1560
273TESTDONE: 1320 tests were considered during 1514 seconds.
274
275For curl-7.69.1, 1082 tests out of 1086 reported OK. 1560 now passes.
2761330 tests were considered during 1528 seconds.
277
278======
279Added by renodr for curl-7.70.0:
280TESTDONE: 1062 tests out of 1062 reported OK: 100%
281TESTDONE: 1352 tests were considered during 1218 seconds.
282Tests were ran with all dependencies present except for stunnel.
283impacket only seems to add one extra test to the mix as well.
284
285======
286Added by renodr for curl-7.71.0:
287TESTDONE: 1072 tests out of 1072 reported OK: 100%
288TESTDONE: 1364 tests were considered during 1202 seconds.
289Tests were run similarly to 7.70.0 - all deps except for stunnel.
290
291======
292Added by renodr for curl-7.71.1:
293TESTDONE: 1076 tests out of 1076 reported OK: 100%
294TESTDONE: 1368 tests were considered during 1207 seconds.
295Tests were run similarly to 7.71.0, including impacket, but no stunnel.
296
297======
298Added by renodr for curl-7.72.0:
299TESTDONE: 1094 tests out of 1097 reported OK: 99%
300TESTFAIL: These test cases failed: 1700 1701 1702
301TESTDONE: 1374 tests were considered during 1285 seconds.
302Tests have all BLFS dependencies with the exception of stunnel;
303and the optional impacket python module was installed.
304Tests seem to be failing due to a missing 'nghttpx' executable
305used to start a test server.
306
307======
308Added by renodr for curl-7.73.0:
309TESTDONE: 1121 tests out of 1121 reported OK: 100%
310TESTDONE: 1387 tests were considered during 1303 seconds.
311Tests have all BLFS dependencies installed with the exception of stunnel,
312as well as the optional impacket installed.
313
314======
315Added by renodr for curl-7.74.0:
316TESTDONE: 1119 tests out of 1119 reported OK: 100%
317TESTDONE: 1388 tests were considered during 1370 seconds.
318Tests have all BLFS dependencies installed, as well as impacket.
319stunnel not installed.
320
321======
322Added by bdubbs for curl-7.79.0:
323TESTDONE: 1432 tests were considered during 1543 seconds.
324TESTDONE: 1208 tests out of 1212 reported OK: 99%
325
326Tests have all BLFS dependencies installed but without impacket.
327
328======
329Added by plabs for curl-7.79.1:
330TESTDONE: 1434 tests were considered during 1652 seconds.
331TESTDONE: 1171 tests out of 1171 reported OK: 100%
332
333Tests have all BLFS dependencies installed except stunnel but without impacket.
334-->
335
336 <para>
337 Now, as the <systemitem class="username">root</systemitem>
338 user:
339 </para>
340
341<screen role="root"><userinput>make install &amp;&amp;
342
343rm -rf docs/examples/.deps &amp;&amp;
344
345find docs \( -name Makefile\* -o -name \*.1 -o -name \*.3 \) -exec rm {} \; &amp;&amp;
346
347install -v -d -m755 /usr/share/doc/curl-&curl-version; &amp;&amp;
348cp -v -R docs/* /usr/share/doc/curl-&curl-version;</userinput></screen>
349
350 <para>
351 Simple tests to the new installed <command>curl</command>:
352 <command>curl --trace-ascii debugdump.txt http://www.example.com/</command>
353 and
354 <command>curl --trace-ascii d.txt --trace-time http://example.com/</command>.
355 Inspect the locally created trace files <filename>debugdump.txt</filename>
356 and <filename>d.txt</filename>, which contain version downloaded
357 files information, etc. One file has the time for each action logged.
358 </para>
359 </sect2>
360
361 <sect2 role="commands">
362 <title>Command Explanations</title>
363
364 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
365 href="../../xincludes/static-libraries.xml"/>
366
367 <para>
368 <parameter>--enable-threaded-resolver</parameter>: This switch enables
369 <application>cURL</application>'s builtin threaded DNS resolver.
370 </para>
371
372 <para>
373 <parameter>--with-ca-path=/etc/ssl/certs</parameter>: This
374 switch sets the location of the BLFS Certificate Authority store.
375 </para>
376
377 <para>
378 <parameter>--with-openssl</parameter>: This parameter chooses
379 <application>OpenSSL</application> as SSL/TLS implementation.
380 This seems mandatory now.
381 </para>
382
383 <para>
384 <option>--with-gssapi</option>: This parameter adds
385 <application>Kerberos 5</application> support to
386 <filename class="libraryfile">libcurl</filename>.
387 </para>
388
389 <para>
390 <option>--without-ssl --with-gnutls</option>: Use to
391 build with <application>GnuTLS</application> support
392 instead of <application>OpenSSL</application> for SSL/TLS.
393 </para>
394
395 <para>
396 <option>--with-ca-bundle=/etc/pki/tls/certs/ca-bundle.crt</option>: Use
397 this switch instead of <parameter>--with-ca-path</parameter> if
398 building with <application>GnuTLS</application> support
399 instead of <application>OpenSSL</application> for SSL/TLS.
400 </para>
401
402 <para>
403 <option>--with-libssh2</option>: This parameter adds
404 <application>SSH</application> support to cURL. This is disabled
405 by default.
406 </para>
407
408 <para>
409 <option>--enable-ares</option>: This parameter adds
410 support for DNS resolution through the c-ares library. It is disabled
411 by default, but does speed up DNS resolution queries.
412 </para>
413
414 <para>
415 <command>find docs ... -exec rm {} \;</command>: This command removes
416 <filename>Makefiles</filename> and man files from the documentation
417 directory that would otherwise be installed by the commands that follow.
418 </para>
419
420 </sect2>
421
422 <sect2 role="content">
423 <title>Contents</title>
424
425 <segmentedlist>
426 <segtitle>Installed Programs</segtitle>
427 <segtitle>Installed Library</segtitle>
428 <segtitle>Installed Directories</segtitle>
429
430 <seglistitem>
431 <seg>
432 curl and curl-config
433 </seg>
434 <seg>
435 libcurl.so
436 </seg>
437 <seg>
438 /usr/include/curl and
439 /usr/share/doc/curl-&curl-version;
440 </seg>
441 </seglistitem>
442 </segmentedlist>
443
444 <variablelist>
445 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
446 <?dbfo list-presentation="list"?>
447 <?dbhtml list-presentation="table"?>
448
449 <varlistentry id="curl-prog">
450 <term><command>curl</command></term>
451 <listitem>
452 <para>
453 is a command line tool for transferring files with URL syntax
454 </para>
455 <indexterm zone="curl curl-prog">
456 <primary sortas="b-curl">curl</primary>
457 </indexterm>
458 </listitem>
459 </varlistentry>
460
461 <varlistentry id="curl-config">
462 <term><command>curl-config</command></term>
463 <listitem>
464 <para>
465 prints information about the last compile, like libraries
466 linked to and prefix setting
467 </para>
468 <indexterm zone="curl curl-config">
469 <primary sortas="b-curl-config">curl-config</primary>
470 </indexterm>
471 </listitem>
472 </varlistentry>
473
474 <varlistentry id="libcurl">
475 <term><filename class="libraryfile">libcurl.so</filename></term>
476 <listitem>
477 <para>
478 provides the API functions required by
479 <command>curl</command> and other programs
480 </para>
481 <indexterm zone="curl libcurl">
482 <primary sortas="c-libcurl">libcurl.so</primary>
483 </indexterm>
484 </listitem>
485 </varlistentry>
486
487 </variablelist>
488
489 </sect2>
490
491</sect1>
Note: See TracBrowser for help on using the repository browser.