From 8571d1c0b4ac9688961436603587cff4c09e4116 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 21 Oct 2016 15:55:24 +0200 Subject: INSTALL: converted to markdown => INSTALL.md Also heavily edited for content. Removed lots of old cruft that we added like 10+ years ago that is likely incorrect by now. Also removed INSTALL.devcpp for same reason. --- docs/INSTALL.md | 513 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 513 insertions(+) create mode 100644 docs/INSTALL.md (limited to 'docs/INSTALL.md') diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 000000000..a737993ed --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,513 @@ +# how to install curl and libcurl + +## Installing Binary Packages + +Lots of people download binary distributions of curl and libcurl. This +document does not describe how to install curl or libcurl using such a binary +package. This document describes how to compile, build and install curl and +libcurl from source code. + +## Building from git + +If you get your code off a git repository instead of a release tarball, see +the `GIT-INFO` file in the root directory for specific instructions on how to +proceed. + +# Unix + +A normal Unix installation is made in three or four steps (after you've +unpacked the source archive): + + ./configure + make + make test (optional) + make install + +You probably need to be root when doing the last command. + +Get a full listing of all available configure options by invoking it like: + + ./configure --help + +If you want to install curl in a different file hierarchy than `/usr/local`, +specify that when running configure: + + ./configure --prefix=/path/to/curl/tree + +If you have write permission in that directory, you can do 'make install' +without being root. An example of this would be to make a local install in +your own home directory: + + ./configure --prefix=$HOME + make + make install + +The configure script always tries to find a working SSL library unless +explicitly told not to. If you have OpenSSL installed in the default search +path for your compiler/linker, you don't need to do anything special. If you +have OpenSSL installed in /usr/local/ssl, you can run configure like: + + ./configure --with-ssl + +If you have OpenSSL installed somewhere else (for example, /opt/OpenSSL) and +you have pkg-config installed, set the pkg-config path first, like this: + + env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-ssl + +Without pkg-config installed, use this: + + ./configure --with-ssl=/opt/OpenSSL + +If you insist on forcing a build without SSL support, even though you may +have OpenSSL installed in your system, you can run configure like this: + + ./configure --without-ssl + +If you have OpenSSL installed, but with the libraries in one place and the +header files somewhere else, you have to set the LDFLAGS and CPPFLAGS +environment variables prior to running configure. Something like this should +work: + + CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure + +If you have shared SSL libs installed in a directory where your run-time +linker doesn't find them (which usually causes configure failures), you can +provide the -R option to ld on some operating systems to set a hard-coded +path to the run-time linker: + + LDFLAGS=-R/usr/local/ssl/lib ./configure --with-ssl + +## More Options + +To force a static library compile, disable the shared library creation by +running configure like: + + ./configure --disable-shared + +To tell the configure script to skip searching for thread-safe functions, add +an option like: + + ./configure --disable-thread + +If you're a curl developer and use gcc, you might want to enable more debug +options with the `--enable-debug` option. + +curl can be built to use a whole range of libraries to provide various useful +services, and configure will try to auto-detect a decent default. But if you +want to alter it, you can select how to deal with each individual library. + +## Select TLS backend + +The default OpenSSL configure check will also detect and use BoringSSL or +libressl. + + - GnuTLS: `--without-ssl --with-gnutls`. + - Cyassl: `--without-ssl --with-cyassl` + - NSS: `--without-ssl --with-nss` + - PolarSSL: `--without-ssl --with-polarssl` + - mbedTLS: `--without-ssl --with-mbedtls` + - axTLS: `--without-ssl --with-axtls` + - schannel: `--without-ssl --with-winssl` + - secure transport: `--with-winssl --with-darwinssl` + +# Windows + +## Building Windows DLLs and C run-time (CRT) linkage issues + + As a general rule, building a DLL with static CRT linkage is highly + discouraged, and intermixing CRTs in the same app is something to avoid at + any cost. + + Reading and comprehending Microsoft Knowledge Base articles KB94248 and + KB140584 is a must for any Windows developer. Especially important is full + understanding if you are not going to follow the advice given above. + + - [How To Use the C Run-Time](https://support.microsoft.com/kb/94248/en-us) + - [How to link with the correct C Run-Time CRT library](https://support.microsoft.com/kb/140584/en-us) + - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://msdn.microsoft.com/en-us/library/ms235460) + +If your app is misbehaving in some strange way, or it is suffering from +memory corruption, before asking for further help, please try first to +rebuild every single library your app uses as well as your app using the +debug multithreaded dynamic C runtime. + + If you get linkage errors read section 5.7 of the FAQ document. + +## MingW32 + +Make sure that MinGW32's bin dir is in the search path, for example: + + set PATH=c:\mingw32\bin;%PATH% + +then run `mingw32-make mingw32` in the root dir. There are other +make targets available to build libcurl with more features, use: + + - `mingw32-make mingw32-zlib` to build with Zlib support; + - `mingw32-make mingw32-ssl-zlib` to build with SSL and Zlib enabled; + - `mingw32-make mingw32-ssh2-ssl-zlib` to build with SSH2, SSL, Zlib; + - `mingw32-make mingw32-ssh2-ssl-sspi-zlib` to build with SSH2, SSL, Zlib + and SSPI support. + +If you have any problems linking libraries or finding header files, be sure +to verify that the provided "Makefile.m32" files use the proper paths, and +adjust as necessary. It is also possible to override these paths with +environment variables, for example: + + set ZLIB_PATH=c:\zlib-1.2.8 + set OPENSSL_PATH=c:\openssl-1.0.2c + set LIBSSH2_PATH=c:\libssh2-1.6.0 + +It is also possible to build with other LDAP SDKs than MS LDAP; currently +it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP +SDK. If you want to use these you need to set these vars: + + set LDAP_SDK=c:\openldap + set USE_LDAP_OPENLDAP=1 + +or for using the Novell SDK: + + set USE_LDAP_NOVELL=1 + +If you want to enable LDAPS support then set LDAPS=1. + +## Cygwin + +Almost identical to the unix installation. Run the configure script in the +curl source tree root with `sh configure`. Make sure you have the sh +executable in /bin/ or you'll see the configure fail toward the end. + +Run `make` + +## Borland C++ compiler + +Ensure that your build environment is properly set up to use the compiler and +associated tools. PATH environment variable must include the path to bin +subdirectory of your compiler installation, eg: `c:\Borland\BCC55\bin` + +It is advisable to set environment variable BCCDIR to the base path of the +compiler installation. + + set BCCDIR=c:\Borland\BCC55 + +In order to build a plain vanilla version of curl and libcurl run the +following command from curl's root directory: + + make borland + +To build curl and libcurl with zlib and OpenSSL support set environment +variables `ZLIB_PATH` and `OPENSSL_PATH` to the base subdirectories of the +already built zlib and OpenSSL libraries and from curl's root directory run +command: + + make borland-ssl-zlib + +libcurl library will be built in 'lib' subdirectory while curl tool is built +in 'src' subdirectory. In order to use libcurl library it is advisable to +modify compiler's configuration file bcc32.cfg located in +`c:\Borland\BCC55\bin` to reflect the location of libraries include paths for +example the '-I' line could result in something like: + + -I"c:\Borland\BCC55\include;c:\curl\include;c:\openssl\inc32" + +bcc3.cfg `-L` line could also be modified to reflect the location of of +libcurl library resulting for example: + + -L"c:\Borland\BCC55\lib;c:\curl\lib;c:\openssl\out32" + +In order to build sample program `simple.c` from the docs\examples +subdirectory run following command from mentioned subdirectory: + + bcc32 simple.c libcurl.lib cw32mt.lib + +In order to build sample program simplessl.c an SSL enabled libcurl is +required, as well as the OpenSSL libeay32.lib and ssleay32.lib libraries. + +## Disabling Specific Protocols in Windows builds + +The configure utility, unfortunately, is not available for the Windows +environment, therefore, you cannot use the various disable-protocol options of +the configure utility on this platform. + +However, you can use the following defines to disable specific +protocols: + + - `HTTP_ONLY` disables all protocols except HTTP + - `CURL_DISABLE_FTP` disables FTP + - `CURL_DISABLE_LDAP` disables LDAP + - `CURL_DISABLE_TELNET` disables TELNET + - `CURL_DISABLE_DICT` disables DICT + - `CURL_DISABLE_FILE` disables FILE + - `CURL_DISABLE_TFTP` disables TFTP + - `CURL_DISABLE_HTTP` disables HTTP + - `CURL_DISABLE_IMAP` disables IMAP + - `CURL_DISABLE_POP3` disables POP3 + - `CURL_DISABLE_SMTP` disables SMTP + +If you want to set any of these defines you have the following options: + + - Modify lib/config-win32.h + - Modify lib/curl_setup.h + - Modify lib/Makefile.vc6 + - Modify the "Preprocessor Definitions" in the libcurl project + +Note: The pre-processor settings can be found using the Visual Studio IDE +under "Project -> Settings -> C/C++ -> General" in VC6 and "Project -> +Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later +versions. + +## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds + +In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is +necessary to make definition of preprocessor symbol USE_LWIPSOCK visible to +libcurl and curl compilation processes. To set this definition you have the +following alternatives: + + - Modify lib/config-win32.h and src/config-win32.h + - Modify lib/Makefile.vc6 + - Modify the "Preprocessor Definitions" in the libcurl project + +Note: The pre-processor settings can be found using the Visual Studio IDE +under "Project -> Settings -> C/C++ -> General" in VC6 and "Project -> +Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later +versions. + +Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, in +order to use it with your program it is mandatory that your program includes +lwIP header file `` (or another lwIP header that includes this) +before including any libcurl header. Your program does not need the +`USE_LWIPSOCK` preprocessor definition which is for libcurl internals only. + +Compilation has been verified with [lwIP +1.4.0](http://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip) and +[contrib-1.4.0](http://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip). + +This BSD-style lwIP TCP/IP stack support must be considered experimental given +that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl +might yet need some additional adjustment, caveat emptor. + +## Important static libcurl usage note + +When building an application that uses the static libcurl library on Windows, +you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will +look for dynamic import symbols. + +## Legacy Windows and SSL + +WinSSL (specifically SChannel from Windows SSPI), is the native SSL library in +Windows. However, WinSSL in Windows <= XP is unable to connect to servers that +no longer support the legacy handshakes and algorithms used by those +versions. If you will be using curl in one of those earlier versions of +Windows you should choose another SSL backend such as OpenSSL. + +# Apple iOS and Mac OS X + +On modern Apple operating systems, curl can be built to use Apple's SSL/TLS +implementation, Secure Transport, instead of OpenSSL. To build with Secure +Transport for SSL/TLS, use the configure option `--with-darwinssl`. (It is not +necessary to use the option `--without-ssl`.) This feature requires iOS 5.0 or +later, or OS X 10.5 ("Leopard") or later. + +When Secure Transport is in use, the curl options `--cacert` and `--capath` +and their libcurl equivalents, will be ignored, because Secure Transport uses +the certificates stored in the Keychain to evaluate whether or not to trust +the server. This, of course, includes the root certificates that ship with the +OS. The `--cert` and `--engine` options, and their libcurl equivalents, are +currently unimplemented in curl with Secure Transport. + +For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul to +the Secure Transport API that, among other things, added support for the newer +TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you must +build curl on Mountain Lion or later, or by using the equivalent SDK. If you +set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier +version of OS X prior to building curl, then curl will use the new Secure +Transport API on Mountain Lion and later, and fall back on the older API when +the same curl binary is executed on older cats. For example, running these +commands in curl's directory in the shell will build the code such that it +will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash): + + export MACOSX_DEPLOYMENT_TARGET="10.6" + ./configure --with-darwinssl + make + +# Cross compile + +Download and unpack the curl package. + +'cd' to the new directory. (e.g. `cd curl-7.12.3`) + +Set environment variables to point to the cross-compile toolchain and call +configure with any options you need. Be sure and specify the `--host` and +`--build` parameters at configuration time. The following script is an +example of cross-compiling for the IBM 405GP PowerPC processor using the +toolchain from MonteVista for Hardhat Linux. + + #! /bin/sh + + export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin + export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include" + export AR=ppc_405-ar + export AS=ppc_405-as + export LD=ppc_405-ld + export RANLIB=ppc_405-ranlib + export CC=ppc_405-gcc + export NM=ppc_405-nm + + ./configure --target=powerpc-hardhat-linux + --host=powerpc-hardhat-linux + --build=i586-pc-linux-gnu + --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local + --exec-prefix=/usr/local + +You may also need to provide a parameter like `--with-random=/dev/urandom` to +configure as it cannot detect the presence of a random number generating +device for a target system. The `--prefix` parameter specifies where curl +will be installed. If `configure` completes successfully, do `make` and `make +install` as usual. + +In some cases, you may be able to simplify the above commands to as little as: + + ./configure --host=ARCH-OS + +# REDUCING SIZE + +There are a number of configure options that can be used to reduce the size of +libcurl for embedded applications where binary size is an important factor. +First, be sure to set the CFLAGS variable when configuring with any relevant +compiler optimization flags to reduce the size of the binary. For gcc, this +would mean at minimum the -Os option, and potentially the `-march=X`, +`-mdynamic-no-pic` and `-flto` options as well, e.g. + + ./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'... + +Note that newer compilers often produce smaller code than older versions +due to improved optimization. + +Be sure to specify as many `--disable-` and `--without-` flags on the +configure command-line as you can to disable all the libcurl features that you +know your application is not going to need. Besides specifying the +`--disable-PROTOCOL` flags for all the types of URLs your application will not +use, here are some other flags that can reduce the size of the library: + + - `--disable-ares` (disables support for the C-ARES DNS library) + - `--disable-cookies` (disables support for HTTP cookies) + - `--disable-crypto-auth` (disables HTTP cryptographic authentication) + - `--disable-ipv6` (disables support for IPv6) + - `--disable-manual` (disables support for the built-in documentation) + - `--disable-proxy` (disables support for HTTP and SOCKS proxies) + - `--disable-unix-sockets` (disables support for UNIX sockets) + - `--disable-verbose` (eliminates debugging strings and error code strings) + - `--disable-versioned-symbols` (disables support for versioned symbols) + - `--enable-hidden-symbols` (eliminates unneeded symbols in the shared library) + - `--without-libidn` (disables support for the libidn DNS library) + - `--without-librtmp` (disables support for RTMP) + - `--without-ssl` (disables support for SSL/TLS) + - `--without-zlib` (disables support for on-the-fly decompression) + +The GNU compiler and linker have a number of options that can reduce the +size of the libcurl dynamic libraries on some platforms even further. +Specify them by providing appropriate CFLAGS and LDFLAGS variables on the +configure command-line, e.g. + + CFLAGS="-Os -ffunction-sections -fdata-sections + -fno-unwind-tables -fno-asynchronous-unwind-tables -flto" + LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections" + +Be sure also to strip debugging symbols from your binaries after compiling +using 'strip' (or the appropriate variant if cross-compiling). If space is +really tight, you may be able to remove some unneeded sections of the shared +library using the -R option to objcopy (e.g. the .comment section). + +Using these techniques it is possible to create a basic HTTP-only shared +libcurl library for i386 Linux platforms that is only 109 KiB in size, and an +FTP-only library that is 109 KiB in size (as of libcurl version 7.45.0, using +gcc 4.9.2). + +You may find that statically linking libcurl to your application will result +in a lower total size than dynamically linking. + +Note that the curl test harness can detect the use of some, but not all, of +the `--disable` statements suggested above. Use will cause tests relying on +those features to fail. The test harness can be manually forced to skip the +relevant tests by specifying certain key words on the runtests.pl command +line. Following is a list of appropriate key words: + + - `--disable-cookies` !cookies + - `--disable-manual` !--manual + - `--disable-proxy` !HTTP\ proxy !proxytunnel !SOCKS4 !SOCKS5 + +# PORTS + +This is a probably incomplete list of known hardware and operating systems +that curl has been compiled for. If you know a system curl compiles and +runs on, that isn't listed, please let us know! + + - Alpha DEC OSF 4 + - Alpha Digital UNIX v3.2 + - Alpha FreeBSD 4.1, 4.5 + - Alpha Linux 2.2, 2.4 + - Alpha NetBSD 1.5.2 + - Alpha OpenBSD 3.0 + - Alpha OpenVMS V7.1-1H2 + - Alpha Tru64 v5.0 5.1 + - AVR32 Linux + - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x + - ARM INTEGRITY + - ARM iOS + - Cell Linux + - Cell Cell OS + - HP-PA HP-UX 9.X 10.X 11.X + - HP-PA Linux + - HP3000 MPE/iX + - MicroBlaze uClinux + - MIPS IRIX 6.2, 6.5 + - MIPS Linux + - OS/400 + - Pocket PC/Win CE 3.0 + - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2 + - PowerPC Darwin 1.0 + - PowerPC INTEGRITY + - PowerPC Linux + - PowerPC Mac OS 9 + - PowerPC Mac OS X + - SH4 Linux 2.6.X + - SH4 OS21 + - SINIX-Z v5 + - Sparc Linux + - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10 + - Sparc SunOS 4.1.X + - StrongARM (and other ARM) RISC OS 3.1, 4.02 + - StrongARM/ARM7/ARM9 Linux 2.4, 2.6 + - StrongARM NetBSD 1.4.1 + - Symbian OS (P.I.P.S.) 9.x + - TPF + - Ultrix 4.3a + - UNICOS 9.0 + - i386 BeOS + - i386 DOS + - i386 eCos 1.3.1 + - i386 Esix 4.1 + - i386 FreeBSD + - i386 HURD + - i386 Haiku OS + - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6 + - i386 Mac OS X + - i386 MINIX 3.1 + - i386 NetBSD + - i386 Novell NetWare + - i386 OS/2 + - i386 OpenBSD + - i386 QNX 6 + - i386 SCO unix + - i386 Solaris 2.7 + - i386 Windows 95, 98, ME, NT, 2000, XP, 2003 + - i486 ncr-sysv4.3.03 (NCR MP-RAS) + - ia64 Linux 2.3.99 + - m68k AmigaOS 3 + - m68k Linux + - m68k uClinux + - m68k OpenBSD + - m88k dg-dgux5.4R3.00 + - s390 Linux + - x86_64 Linux + - XScale/PXA250 Linux 2.4 + - Nios II uClinux -- cgit v1.2.3