Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/INSTALL.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 # how to install curl and libcurl
2
3 ## Installing Binary Packages
4
5 Lots of people download binary distributions of curl and libcurl. This
6 document does not describe how to install curl or libcurl using such a binary
7 package. This document describes how to compile, build and install curl and
8 libcurl from source code.
9
10 ## Building from git
11
12 If you get your code off a git repository instead of a release tarball, see
13 the `GIT-INFO` file in the root directory for specific instructions on how to
14 proceed.
15
16 # Unix
17
18 A normal Unix installation is made in three or four steps (after you've
19 unpacked the source archive):
20
21 ./configure
22 make
23 make test (optional)
24 make install
25
26 You probably need to be root when doing the last command.
27
28 Get a full listing of all available configure options by invoking it like:
29
30 ./configure --help
31
32 If you want to install curl in a different file hierarchy than `/usr/local`,
33 specify that when running configure:
34
35 ./configure --prefix=/path/to/curl/tree
36
37 If you have write permission in that directory, you can do 'make install'
38 without being root. An example of this would be to make a local install in
39 your own home directory:
40
41 ./configure --prefix=$HOME
42 make
43 make install
44
45 The configure script always tries to find a working SSL library unless
46 explicitly told not to. If you have OpenSSL installed in the default search
47 path for your compiler/linker, you don't need to do anything special. If you
48 have OpenSSL installed in `/usr/local/ssl`, you can run configure like:
49
50 ./configure --with-ssl
51
52 If you have OpenSSL installed somewhere else (for example, `/opt/OpenSSL`) and
53 you have pkg-config installed, set the pkg-config path first, like this:
54
55 env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-ssl
56
57 Without pkg-config installed, use this:
58
59 ./configure --with-ssl=/opt/OpenSSL
60
61 If you insist on forcing a build without SSL support, even though you may
62 have OpenSSL installed in your system, you can run configure like this:
63
64 ./configure --without-ssl
65
66 If you have OpenSSL installed, but with the libraries in one place and the
67 header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
68 environment variables prior to running configure. Something like this should
69 work:
70
71 CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
72
73 If you have shared SSL libs installed in a directory where your run-time
74 linker doesn't find them (which usually causes configure failures), you can
75 provide this option to gcc to set a hard-coded path to the run-time linker:
76
77 LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-ssl
78
79 ## More Options
80
81 To force a static library compile, disable the shared library creation by
82 running configure like:
83
84 ./configure --disable-shared
85
86 To tell the configure script to skip searching for thread-safe functions, add
87 an option like:
88
89 ./configure --disable-thread
90
91 If you're a curl developer and use gcc, you might want to enable more debug
92 options with the `--enable-debug` option.
93
94 curl can be built to use a whole range of libraries to provide various useful
95 services, and configure will try to auto-detect a decent default. But if you
96 want to alter it, you can select how to deal with each individual library.
97
98 ## Select TLS backend
99
100 The default OpenSSL configure check will also detect and use BoringSSL or
101 libressl.
102
103 - GnuTLS: `--without-ssl --with-gnutls`.
104 - wolfSSL: `--without-ssl --with-wolfssl`
105 - NSS: `--without-ssl --with-nss`
106 - PolarSSL: `--without-ssl --with-polarssl`
107 - mbedTLS: `--without-ssl --with-mbedtls`
108 - schannel: `--without-ssl --with-schannel`
109 - secure transport: `--without-ssl --with-secure-transport`
110 - MesaLink: `--without-ssl --with-mesalink`
111
112 # Windows
113
114 ## Building Windows DLLs and C run-time (CRT) linkage issues
115
116 As a general rule, building a DLL with static CRT linkage is highly
117 discouraged, and intermixing CRTs in the same app is something to avoid at
118 any cost.
119
120 Reading and comprehending Microsoft Knowledge Base articles KB94248 and
121 KB140584 is a must for any Windows developer. Especially important is full
122 understanding if you are not going to follow the advice given above.
123
124 - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)
125 - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
126 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
127
128 If your app is misbehaving in some strange way, or it is suffering from
129 memory corruption, before asking for further help, please try first to
130 rebuild every single library your app uses as well as your app using the
131 debug multithreaded dynamic C runtime.
132
133 If you get linkage errors read section 5.7 of the FAQ document.
134
135 ## MingW32
136
137 Make sure that MinGW32's bin dir is in the search path, for example:
138
139 set PATH=c:\mingw32\bin;%PATH%
140
141 then run `mingw32-make mingw32` in the root dir. There are other
142 make targets available to build libcurl with more features, use:
143
144 - `mingw32-make mingw32-zlib` to build with Zlib support;
145 - `mingw32-make mingw32-ssl-zlib` to build with SSL and Zlib enabled;
146 - `mingw32-make mingw32-ssh2-ssl-zlib` to build with SSH2, SSL, Zlib;
147 - `mingw32-make mingw32-ssh2-ssl-sspi-zlib` to build with SSH2, SSL, Zlib
148 and SSPI support.
149
150 If you have any problems linking libraries or finding header files, be sure
151 to verify that the provided `Makefile.m32` files use the proper paths, and
152 adjust as necessary. It is also possible to override these paths with
153 environment variables, for example:
154
155 set ZLIB_PATH=c:\zlib-1.2.8
156 set OPENSSL_PATH=c:\openssl-1.0.2c
157 set LIBSSH2_PATH=c:\libssh2-1.6.0
158
159 It is also possible to build with other LDAP SDKs than MS LDAP; currently
160 it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP
161 SDK. If you want to use these you need to set these vars:
162
163 set LDAP_SDK=c:\openldap
164 set USE_LDAP_OPENLDAP=1
165
166 or for using the Novell SDK:
167
168 set USE_LDAP_NOVELL=1
169
170 If you want to enable LDAPS support then set LDAPS=1.
171
172 ## Cygwin
173
174 Almost identical to the unix installation. Run the configure script in the
175 curl source tree root with `sh configure`. Make sure you have the `sh`
176 executable in `/bin/` or you'll see the configure fail toward the end.
177
178 Run `make`
179
180 ## Disabling Specific Protocols in Windows builds
181
182 The configure utility, unfortunately, is not available for the Windows
183 environment, therefore, you cannot use the various disable-protocol options of
184 the configure utility on this platform.
185
186 However, you can use the following defines to disable specific
187 protocols:
188
189 - `HTTP_ONLY` disables all protocols except HTTP
190 - `CURL_DISABLE_FTP` disables FTP
191 - `CURL_DISABLE_LDAP` disables LDAP
192 - `CURL_DISABLE_TELNET` disables TELNET
193 - `CURL_DISABLE_DICT` disables DICT
194 - `CURL_DISABLE_FILE` disables FILE
195 - `CURL_DISABLE_TFTP` disables TFTP
196 - `CURL_DISABLE_HTTP` disables HTTP
197 - `CURL_DISABLE_IMAP` disables IMAP
198 - `CURL_DISABLE_POP3` disables POP3
199 - `CURL_DISABLE_SMTP` disables SMTP
200
201 If you want to set any of these defines you have the following options:
202
203 - Modify `lib/config-win32.h`
204 - Modify `lib/curl_setup.h`
205 - Modify `winbuild/Makefile.vc`
206 - Modify the "Preprocessor Definitions" in the libcurl project
207
208 Note: The pre-processor settings can be found using the Visual Studio IDE
209 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
210 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
211 versions.
212
213 ## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds
214
215 In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
216 necessary to make definition of preprocessor symbol `USE_LWIPSOCK` visible to
217 libcurl and curl compilation processes. To set this definition you have the
218 following alternatives:
219
220 - Modify `lib/config-win32.h` and `src/config-win32.h`
221 - Modify `winbuild/Makefile.vc`
222 - Modify the "Preprocessor Definitions" in the libcurl project
223
224 Note: The pre-processor settings can be found using the Visual Studio IDE
225 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
226 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
227 versions.
228
229 Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, in
230 order to use it with your program it is mandatory that your program includes
231 lwIP header file `<lwip/opt.h>` (or another lwIP header that includes this)
232 before including any libcurl header. Your program does not need the
233 `USE_LWIPSOCK` preprocessor definition which is for libcurl internals only.
234
235 Compilation has been verified with [lwIP
236 1.4.0](https://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip) and
237 [contrib-1.4.0](https://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip).
238
239 This BSD-style lwIP TCP/IP stack support must be considered experimental given
240 that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl
241 might yet need some additional adjustment, caveat emptor.
242
243 ## Important static libcurl usage note
244
245 When building an application that uses the static libcurl library on Windows,
246 you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will
247 look for dynamic import symbols.
248
249 ## Legacy Windows and SSL
250
251 Schannel (from Windows SSPI), is the native SSL library in Windows. However,
252 Schannel in Windows <= XP is unable to connect to servers that
253 no longer support the legacy handshakes and algorithms used by those
254 versions. If you will be using curl in one of those earlier versions of
255 Windows you should choose another SSL backend such as OpenSSL.
256
257 # Apple iOS and macOS
258
259 On modern Apple operating systems, curl can be built to use Apple's SSL/TLS
260 implementation, Secure Transport, instead of OpenSSL. To build with Secure
261 Transport for SSL/TLS, use the configure option `--with-darwinssl`. (It is not
262 necessary to use the option `--without-ssl`.) This feature requires iOS 5.0 or
263 later, or OS X 10.5 ("Leopard") or later.
264
265 When Secure Transport is in use, the curl options `--cacert` and `--capath`
266 and their libcurl equivalents, will be ignored, because Secure Transport uses
267 the certificates stored in the Keychain to evaluate whether or not to trust
268 the server. This, of course, includes the root certificates that ship with the
269 OS. The `--cert` and `--engine` options, and their libcurl equivalents, are
270 currently unimplemented in curl with Secure Transport.
271
272 For macOS users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul
273 to the Secure Transport API that, among other things, added support for the
274 newer TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you
275 must build curl on Mountain Lion or later, or by using the equivalent SDK. If
276 you set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier
277 version of macOS prior to building curl, then curl will use the new Secure
278 Transport API on Mountain Lion and later, and fall back on the older API when
279 the same curl binary is executed on older cats. For example, running these
280 commands in curl's directory in the shell will build the code such that it
281 will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash):
282
283 export MACOSX_DEPLOYMENT_TARGET="10.6"
284 ./configure --with-darwinssl
285 make
286
287 # Cross compile
288
289 Download and unpack the curl package.
290
291 `cd` to the new directory. (e.g. `cd curl-7.12.3`)
292
293 Set environment variables to point to the cross-compile toolchain and call
294 configure with any options you need. Be sure and specify the `--host` and
295 `--build` parameters at configuration time. The following script is an
296 example of cross-compiling for the IBM 405GP PowerPC processor using the
297 toolchain from MonteVista for Hardhat Linux.
298
299 #! /bin/sh
300
301 export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
302 export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
303 export AR=ppc_405-ar
304 export AS=ppc_405-as
305 export LD=ppc_405-ld
306 export RANLIB=ppc_405-ranlib
307 export CC=ppc_405-gcc
308 export NM=ppc_405-nm
309
310 ./configure --target=powerpc-hardhat-linux
311 --host=powerpc-hardhat-linux
312 --build=i586-pc-linux-gnu
313 --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local
314 --exec-prefix=/usr/local
315
316 You may also need to provide a parameter like `--with-random=/dev/urandom` to
317 configure as it cannot detect the presence of a random number generating
318 device for a target system. The `--prefix` parameter specifies where curl
319 will be installed. If `configure` completes successfully, do `make` and `make
320 install` as usual.
321
322 In some cases, you may be able to simplify the above commands to as little as:
323
324 ./configure --host=ARCH-OS
325
326 # REDUCING SIZE
327
328 There are a number of configure options that can be used to reduce the size of
329 libcurl for embedded applications where binary size is an important factor.
330 First, be sure to set the `CFLAGS` variable when configuring with any relevant
331 compiler optimization flags to reduce the size of the binary. For gcc, this
332 would mean at minimum the -Os option, and potentially the `-march=X`,
333 `-mdynamic-no-pic` and `-flto` options as well, e.g.
334
335 ./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'...
336
337 Note that newer compilers often produce smaller code than older versions
338 due to improved optimization.
339
340 Be sure to specify as many `--disable-` and `--without-` flags on the
341 configure command-line as you can to disable all the libcurl features that you
342 know your application is not going to need. Besides specifying the
343 `--disable-PROTOCOL` flags for all the types of URLs your application will not
344 use, here are some other flags that can reduce the size of the library:
345
346 - `--disable-ares` (disables support for the C-ARES DNS library)
347 - `--disable-cookies` (disables support for HTTP cookies)
348 - `--disable-crypto-auth` (disables HTTP cryptographic authentication)
349 - `--disable-ipv6` (disables support for IPv6)
350 - `--disable-manual` (disables support for the built-in documentation)
351 - `--disable-proxy` (disables support for HTTP and SOCKS proxies)
352 - `--disable-unix-sockets` (disables support for UNIX sockets)
353 - `--disable-verbose` (eliminates debugging strings and error code strings)
354 - `--disable-versioned-symbols` (disables support for versioned symbols)
355 - `--enable-hidden-symbols` (eliminates unneeded symbols in the shared library)
356 - `--without-libidn` (disables support for the libidn DNS library)
357 - `--without-librtmp` (disables support for RTMP)
358 - `--without-ssl` (disables support for SSL/TLS)
359 - `--without-zlib` (disables support for on-the-fly decompression)
360
361 The GNU compiler and linker have a number of options that can reduce the
362 size of the libcurl dynamic libraries on some platforms even further.
363 Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on
364 the configure command-line, e.g.
365
366 CFLAGS="-Os -ffunction-sections -fdata-sections
367 -fno-unwind-tables -fno-asynchronous-unwind-tables -flto"
368 LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections"
369
370 Be sure also to strip debugging symbols from your binaries after compiling
371 using 'strip' (or the appropriate variant if cross-compiling). If space is
372 really tight, you may be able to remove some unneeded sections of the shared
373 library using the -R option to objcopy (e.g. the .comment section).
374
375 Using these techniques it is possible to create a basic HTTP-only shared
376 libcurl library for i386 Linux platforms that is only 113 KiB in size, and an
377 FTP-only library that is 113 KiB in size (as of libcurl version 7.50.3, using
378 gcc 5.4.0).
379
380 You may find that statically linking libcurl to your application will result
381 in a lower total size than dynamically linking.
382
383 Note that the curl test harness can detect the use of some, but not all, of
384 the `--disable` statements suggested above. Use will cause tests relying on
385 those features to fail. The test harness can be manually forced to skip the
386 relevant tests by specifying certain key words on the `runtests.pl` command
387 line. Following is a list of appropriate key words:
388
389 - `--disable-cookies` !cookies
390 - `--disable-manual` !--manual
391 - `--disable-proxy` !HTTP\ proxy !proxytunnel !SOCKS4 !SOCKS5
392
393 # PORTS
394
395 This is a probably incomplete list of known hardware and operating systems
396 that curl has been compiled for. If you know a system curl compiles and
397 runs on, that isn't listed, please let us know!
398
399 - Alpha DEC OSF 4
400 - Alpha Digital UNIX v3.2
401 - Alpha FreeBSD 4.1, 4.5
402 - Alpha Linux 2.2, 2.4
403 - Alpha NetBSD 1.5.2
404 - Alpha OpenBSD 3.0
405 - Alpha OpenVMS V7.1-1H2
406 - Alpha Tru64 v5.0 5.1
407 - AVR32 Linux
408 - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x
409 - ARM INTEGRITY
410 - ARM iOS
411 - Cell Linux
412 - Cell Cell OS
413 - HP-PA HP-UX 9.X 10.X 11.X
414 - HP-PA Linux
415 - HP3000 MPE/iX
416 - MicroBlaze uClinux
417 - MIPS IRIX 6.2, 6.5
418 - MIPS Linux
419 - OS/400
420 - Pocket PC/Win CE 3.0
421 - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2
422 - PowerPC Darwin 1.0
423 - PowerPC INTEGRITY
424 - PowerPC Linux
425 - PowerPC Mac OS 9
426 - PowerPC Mac OS X
427 - SH4 Linux 2.6.X
428 - SH4 OS21
429 - SINIX-Z v5
430 - Sparc Linux
431 - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10
432 - Sparc SunOS 4.1.X
433 - StrongARM (and other ARM) RISC OS 3.1, 4.02
434 - StrongARM/ARM7/ARM9 Linux 2.4, 2.6
435 - StrongARM NetBSD 1.4.1
436 - Symbian OS (P.I.P.S.) 9.x
437 - TPF
438 - Ultrix 4.3a
439 - UNICOS 9.0
440 - i386 BeOS
441 - i386 DOS
442 - i386 eCos 1.3.1
443 - i386 Esix 4.1
444 - i386 FreeBSD
445 - i386 HURD
446 - i386 Haiku OS
447 - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6
448 - i386 Mac OS X
449 - i386 MINIX 3.1
450 - i386 NetBSD
451 - i386 Novell NetWare
452 - i386 OS/2
453 - i386 OpenBSD
454 - i386 QNX 6
455 - i386 SCO unix
456 - i386 Solaris 2.7
457 - i386 Windows 95, 98, ME, NT, 2000, XP, 2003
458 - i486 ncr-sysv4.3.03 (NCR MP-RAS)
459 - ia64 Linux 2.3.99
460 - m68k AmigaOS 3
461 - m68k Linux
462 - m68k uClinux
463 - m68k OpenBSD
464 - m88k dg-dgux5.4R3.00
465 - s390 Linux
466 - x86_64 Linux
467 - XScale/PXA250 Linux 2.4
468 - Nios II uClinux