summaryrefslogtreecommitdiff
path: root/docs/INSTALL.md
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2016-10-21 15:55:24 +0200
committerDaniel Stenberg <daniel@haxx.se>2016-10-21 15:57:29 +0200
commit8571d1c0b4ac9688961436603587cff4c09e4116 (patch)
tree41c5f435afff92da8e98f6105926ecd7a439c3e6 /docs/INSTALL.md
parentc9cb17fbd6bc224a739ba794e3569830d87a5f6a (diff)
downloadcurl-8571d1c0b4ac9688961436603587cff4c09e4116.tar.gz
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.
Diffstat (limited to 'docs/INSTALL.md')
-rw-r--r--docs/INSTALL.md513
1 files changed, 513 insertions, 0 deletions
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 `<lwip/opt.h>` (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