docs/INSTALL

   1                                   _   _ ____  _
   2                               ___| | | |  _ \| |
   3                              / __| | | | |_) | |
   4                             | (__| |_| |  _ <| |___
   5                              \___|\___/|_| \_\_____|
   6
   7                                 How To Compile
   8
   9 Installing Binary Packages
  10 ==========================
  11
  12    Lots of people download binary distributions of curl and libcurl. This
  13    document does not describe how to install curl or libcurl using such a
  14    binary package. This document describes how to compile, build and install
  15    curl and libcurl from source code.
  16
  17 UNIX
  18 ====
  19
  20    A normal unix installation is made in three or four steps (after you've
  21    unpacked the source archive):
  22
  23         ./configure
  24         make
  25         make test (optional)
  26         make install
  27
  28    You probably need to be root when doing the last command.
  29
  30    If you have checked out the sources from the CVS repository, read the
  31    CVS-INFO on how to proceed.
  32
  33    Get a full listing of all available configure options by invoking it like:
  34
  35         ./configure --help
  36
  37    If you want to install curl in a different file hierarchy than /usr/local,
  38    you need to specify that already when running configure:
  39
  40         ./configure --prefix=/path/to/curl/tree
  41
  42    If you happen to have write permission in that directory, you can do 'make
  43    install' without being root. An example of this would be to make a local
  44    install in your own home directory:
  45
  46         ./configure --prefix=$HOME
  47         make
  48         make install
  49
  50    The configure script always tries to find a working SSL library unless
  51    explicitly told not to. If you have OpenSSL installed in the default search
  52    path for your compiler/linker, you don't need to do anything special. If
  53    you have OpenSSL installed in /usr/local/ssl, you can run configure like:
  54
  55         ./configure --with-ssl
  56
  57    If you have OpenSSL installed somewhere else (for example, /opt/OpenSSL,)
  58    you can run configure like this:
  59
  60         ./configure --with-ssl=/opt/OpenSSL
  61
  62    If you insist on forcing a build without SSL support, even though you may
  63    have OpenSSL installed in your system, you can run configure like this:
  64
  65         ./configure --without-ssl
  66
  67    If you have OpenSSL installed, but with the libraries in one place and the
  68    header files somewhere else, you have to set the LDFLAGS and CPPFLAGS
  69    environment variables prior to running configure.  Something like this
  70    should work:
  71
  72      (with the Bourne shell and its clones):
  73
  74        CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" \
  75            ./configure
  76
  77      (with csh, tcsh and their clones):
  78
  79        env CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" \
  80        ./configure
  81
  82    If you have shared SSL libs installed in a directory where your run-time
  83    linker doesn't find them (which usually causes configure failures), you can
  84    provide the -R option to ld on some operating systems to set a hard-coded
  85    path to the run-time linker:
  86
  87         LDFLAGS=-R/usr/local/ssl/lib ./configure --with-ssl
  88
  89    Another option to the previous trick, is to set LD_LIBRARY_PATH or edit the
  90    /etc/ld.so.conf file.
  91
  92    If your SSL library was compiled with rsaref (this was common in the past
  93    when used in the United States), you may also need to set:
  94
  95      LIBS=-lRSAglue -lrsaref
  96      (as suggested by Doug Kaufman)
  97
  98    MORE OPTIONS
  99
 100      To force configure to use the standard cc compiler if both cc and gcc are
 101      present, run configure like
 102
 103        CC=cc ./configure
 104          or
 105        env CC=cc ./configure
 106
 107      To force a static library compile, disable the shared library creation
 108      by running configure like:
 109
 110        ./configure --disable-shared
 111
 112      To tell the configure script to skip searching for thread-safe functions,
 113      add an option like:
 114
 115        ./configure --disable-thread
 116
 117      To build curl with kerberos4 support enabled, curl requires the krb4 libs
 118      and headers installed. You can then use a set of options to tell
 119      configure where those are:
 120
 121           --with-krb4-includes[=DIR]   Specify location of kerberos4 headers
 122           --with-krb4-libs[=DIR]       Specify location of kerberos4 libs
 123           --with-krb4[=DIR]            where to look for Kerberos4
 124
 125      In most cases, /usr/athena is the install prefix and then it works with
 126
 127        ./configure --with-krb4=/usr/athena
 128
 129      If you're a curl developer and use gcc, you might want to enable more
 130      debug options with the --enable-debug option.
 131
 132 Win32
 133 =====
 134
 135    MingW32
 136    -------
 137
 138    Run the 'mingw32.bat' file to get the proper environment variables set,
 139    then run 'make mingw32' in the root dir. Use  'make mingw32-ssl' to build
 140    curl SSL enabled.
 141
 142    If you have any problems linking libraries or finding header files, be sure
 143    to verify that the provided "Makefile.m32" files use the proper paths, and
 144    adjust as necessary.
 145
 146    Cygwin
 147    ------
 148
 149    Almost identical to the unix installation. Run the configure script in the
 150    curl root with 'sh configure'. Make sure you have the sh executable in
 151    /bin/ or you'll see the configure fail towards the end.
 152
 153    Run 'make'
 154
 155    Dev-Cpp
 156    -------
 157
 158    See the separate INSTALL.devcpp file for details.
 159
 160    MSVC from command line
 161    ----------------------
 162
 163    Run the 'vcvars32.bat' file to get a proper environment. The
 164    vcvars32.bat file is part of the Microsoft development environment and
 165    you may find it in 'C:\Program Files\Microsoft Visual Studio\vc98\bin'
 166    provided that you installed Visual C/C++ 6 in the default directory.
 167
 168    Then run 'nmake vc' in curl's root directory.
 169
 170    If you want to compile with zlib support, you will need to build
 171    zlib (http://www.gzip.org/zlib/) as well. Please read the zlib
 172    documentation on how to compile zlib. Define the ZLIB_PATH environment
 173    variable to the location of zlib.h and zlib.lib, for example:
 174
 175      set ZLIB_PATH=c:\zlib-1.2.1
 176
 177    Then run 'nmake vc-zlib' in curl's root directory.
 178
 179    If you want to compile with SSL support you need the OpenSSL package.
 180    Please read the OpenSSL documentation on how to compile and install
 181    the OpenSSL libraries.  The build process of OpenSSL generates the
 182    libeay32.dll and ssleay32.dll files in the out32dll subdirectory in
 183    the OpenSSL home directory.  OpenSSL static libraries (libeay32.lib,
 184    ssleay32.lib, RSAglue.lib) are created in the out32 subdirectory.
 185
 186    Before running nmake define the OPENSSL_PATH environment variable with
 187    the root/base directory of OpenSSL, for example:
 188
 189      set OPENSSL_PATH=c:\openssl-0.9.7d
 190
 191    Then run 'nmake vc-ssl' or 'nmake vc-ssl-dll' in curl's root
 192    directory.  'nmake vc-ssl' will create a libcurl static and dynamic
 193    libraries in the lib subdirectory, as well as a statically linked
 194    version of curl.exe in the src subdirectory.  This statically linked
 195    version is a standalone executable not requiring any DLL at
 196    runtime. This make method requires that you have the static OpenSSL
 197    libraries available in OpenSSL's out32 subdirectory.
 198    'nmake vc-ssl-dll' creates the libcurl dynamic library and
 199    links curl.exe against libcurl and OpenSSL dynamically.
 200    This executable requires libcurl.dll and the OpenSSL DLLs
 201    at runtime.
 202    Run 'nmake vc-ssl-zlib' to build with both ssl and zlib support.
 203
 204    Borland C++ compiler
 205    ---------------------
 206
 207    compile openssl
 208
 209    Make sure you include the paths to curl/include and openssl/inc32 in
 210    your bcc32.cnf file
 211
 212    eg : -I"c:\Bcc55\include;c:\path_curl\include;c:\path_openssl\inc32"
 213
 214    Check to make sure that all of the sources listed in lib/Makefile.b32
 215    are present in the /path_to_curl/lib directory. (Check the src
 216    directory for missing ones.)
 217
 218    Make sure the environment variable "BCCDIR" is set to the install
 219    location for the compiler eg : c:\Borland\BCC55
 220
 221    command line:
 222    make -f /path_to_curl/lib/Makefile-ssl.b32
 223
 224    compile simplessl.c with appropriate links
 225
 226    c:\curl\docs\examples\> bcc32 -L c:\path_to_curl\lib\libcurl.lib
 227                                  -L c:\borland\bcc55\lib\psdk\ws2_32.lib
 228                                  -L c:\openssl\out32\libeay32.lib
 229                                  -L c:\openssl\out32\ssleay32.lib
 230                                  simplessl.c
 231
 232
 233    MSVC IDE
 234    --------
 235
 236    If you use VC++, Borland or similar compilers. Include all lib source
 237    files in a static lib "project" (all .c and .h files that is).
 238    (you should name it libcurl or similar)
 239
 240    Make the sources in the src/ drawer be a "win32 console application"
 241    project. Name it curl.
 242
 243    For VC++ 6, there's an included Makefile.vc6 that should be possible
 244    to use out-of-the-box.
 245
 246
 247    Disabling Specific Protocols in Win32 builds
 248    --------------------------------------------
 249
 250    The configure utility, unfortunately, is not available for the Windows
 251    environment, therefore, you cannot use the various disable-protocol
 252    options of the configure utility on this platform.
 253
 254    However, you can use the following defines to disable specific
 255    protocols:
 256
 257    HTTP_ONLY             disables all protocols except HTTP
 258    CURL_DISABLE_FTP      disables FTP
 259    CURL_DISABLE_LDAP     disables LDAP
 260    CURL_DISABLE_TELNET   disables TELNET
 261    CURL_DISABLE_DICT     disables DICT
 262    CURL_DISABLE_FILE     disables FILE
 263
 264    If you want to set any of these defines you have the following
 265    possibilities:
 266
 267    - Modify lib/setup.h
 268    - Modify lib/Makefile.vc6
 269    - Add defines to Project/Settings/C/C++/General/Preprocessor Definitions
 270      in the curllib.dsw/curllib.dsp Visual C++ 6 IDE project.
 271
 272
 273    Important static libcurl usage note
 274    -----------------------------------
 275
 276    When building an application that uses the static libcurl library, you must
 277    add '-DCURL_STATICLIB' to your CFLAGS.  Otherwise the linker will look for
 278    dynamic import symbols.
 279
 280
 281 IBM OS/2
 282 ========
 283
 284    Building under OS/2 is not much different from building under unix.
 285    You need:
 286
 287       - emx 0.9d
 288       - GNU make
 289       - GNU patch
 290       - ksh
 291       - GNU bison
 292       - GNU file utilities
 293       - GNU sed
 294       - autoconf 2.13
 295
 296    If you want to build with OpenSSL or OpenLDAP support, you'll need to
 297    download those libraries, too. Dirk Ohme has done some work to port SSL
 298    libraries under OS/2, but it looks like he doesn't care about emx.  You'll
 299    find his patches on: http://come.to/Dirk_Ohme
 300
 301    If during the linking you get an error about _errno being an undefined
 302    symbol referenced from the text segment, you need to add -D__ST_MT_ERRNO__
 303    in your definitions.
 304
 305    If everything seems to work fine but there's no curl.exe, you need to add
 306    -Zexe to your linker flags.
 307
 308    If you're getting huge binaries, probably your makefiles have the -g in
 309    CFLAGS.
 310
 311 VMS
 312 ===
 313    (The VMS section is in whole contributed by the friendly Nico Baggus)
 314
 315    Curl seems to work with FTP & HTTP other protocols are not tested.  (the
 316    perl http/ftp testing server supplied as testing too cannot work on VMS
 317    because vms has no concept of fork(). [ I tried to give it a whack, but
 318    thats of no use.
 319
 320    SSL stuff has not been ported.
 321
 322    Telnet has about the same issues as for Win32. When the changes for Win32
 323    are clear maybe they'll work for VMS too. The basic problem is that select
 324    ONLY works for sockets.
 325
 326    Marked instances of fopen/[f]stat that might become a problem, especially
 327    for non stream files. In this regard, the files opened for writing will be
 328    created stream/lf and will thus be safe. Just keep in mind that non-binary
 329    read/wring from/to files will have a records size limit of 32767 bytes
 330    imposed.
 331
 332    Stat to get the size of the files is again only safe for stream files &
 333    fixed record files without implied CC.
 334
 335    -- My guess is that only allowing access to stream files is the quickest
 336    way to get around the most issues. Therefore all files need to to be
 337    checked to be sure they will be stream/lf before processing them.  This is
 338    the easiest way out, I know. The reason for this is that code that needs to
 339    report the filesize will become a pain in the ass otherwise.
 340
 341    Exit status.... Well we needed something done here,
 342
 343    VMS has a structured exist status:
 344    | 3  |       2    |     1       |  0|
 345    |1098|765432109876|5432109876543|210|
 346    +----+------------+-------------+---+
 347    |Ctrl|  Facility  | Error code  |sev|
 348    +----+------------+-------------+---+
 349
 350    With the Ctrl-bits an application can tell if part or the whole message has
 351    already been printed from the program, DCL doesn't need to print it again.
 352
 353    Facility - basically the program ID. A code assigned to the program
 354    the name can be fetched from external or internal message libraries
 355    Errorcode - the errodes assigned by the application
 356    Sev. - severity: Even = error, off = non error
 357       0 = Warning
 358       1 = Success
 359       2 = Error
 360       3 = Information
 361       4 = Fatal
 362       <5-7> reserved.
 363
 364    This all presents itself with:
 365    %<FACILITY>-<SeV>-<Errorname>, <Error message>
 366
 367    See also the src/curlmsg.msg file, it has the source for the messages In
 368    src/main.c a section is devoted to message status values, the globalvalues
 369    create symbols with certain values, referenced from a compiled message
 370    file. Have all exit function use a exit status derived from a translation
 371    table with the compiled message codes.
 372
 373    This was all compiled with:
 374
 375       Compaq C V6.2-003 on OpenVMS Alpha V7.1-1H2
 376
 377    So far for porting notes as of:
 378    13-jul-2001
 379    N. Baggus
 380
 381 QNX
 382 ===
 383    (This section was graciously brought to us by David Bentham)
 384
 385    As QNX is targeted for resource constrained environments, the QNX headers
 386    set conservative limits. This includes the FD_SETSIZE macro, set by default
 387    to 32. Socket descriptors returned within the CURL library may exceed this,
 388    resulting in memory faults/SIGSEGV crashes when passed into select(..)
 389    calls using fd_set macros.
 390
 391    A good all-round solution to this is to override the default when building
 392    libcurl, by overriding CFLAGS during configure, example
 393    #  configure CFLAGS='-DFD_SETSIZE=64 -g -O2'
 394
 395
 396 RISC OS
 397 =======
 398    The library can be cross-compiled using gccsdk as follows:
 399
 400         CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \
 401              --host=arm-riscos-aof --without-random --disable-shared
 402         make
 403
 404    where riscos-gcc and riscos-ar are links to the gccsdk tools.
 405    You can then link your program with curl/lib/.libs/libcurl.a
 406
 407
 408 AmigaOS
 409 =======
 410    (This section was graciously brought to us by Diego Casorran)
 411
 412    To build cURL/libcurl on AmigaOS just type 'make amiga' ...
 413
 414    What you need is:    (not tested with others versions)
 415
 416         GeekGadgets / gcc 2.95.3 (http://www.geekgadgets.org/)
 417
 418         AmiTCP SDK v4.3 (http://www.aminet.net/comm/tcp/AmiTCP-SDK-4.3.lha)
 419
 420         Native Developer Kit (http://www.amiga.com/3.9/download/NDK3.9.lha)
 421
 422    As no ixemul.library is required you will be able to build it for
 423    WarpOS/PowerPC (not tested by me), as well a MorphOS version should be
 424    possible with no problems.
 425
 426    To enable SSL support, you need a OpenSSL native version (without ixemul),
 427    you can find a precompiled package at http://amiga.sourceforge.net/OpenSSL/
 428
 429
 430 NetWare
 431 =======
 432
 433    To compile curl.nlm / libcurl.nlm you need:
 434    - either any gcc / nlmconv, or CodeWarrior 7 PDK 4 or later.
 435    - gnu make and awk running on the platform you compile on;
 436      native Win32 versions can be downloaded from:
 437      http://www.gknw.com/development/prgtools/
 438    - recent Novell LibC SDK available from:
 439      http://developer.novell.com/ndk/libc.htm
 440    - optional zlib sources (at the moment only dynamic linking with zlib.imp);
 441      sources with NetWare Makefile can be obtained from:
 442      http://www.gknw.com/mirror/zlib/
 443    - optional OpenSSL sources (version 0.9.8 or later which builds with BSD);
 444
 445    Set a search path to your compiler, linker and tools; on Linux make
 446    sure that the var OSTYPE contains the string 'linux'; and then type
 447    'make netware' from the top source directory; other tagets available
 448    are 'netware-ssl', 'netware-ssl-zlib', 'netware-zlib' and 'netware-ares';
 449    if you need other combinations you can control the build with the
 450    environment variables WITH_SSL, WITH_ZLIB, WITH_ARES and ENABLE_IPV6.
 451    I found on some Linux systems (RH9) that OS detection didnt work although
 452    a 'set | grep OSTYPE' shows the var present and set; I simply overwrote it
 453    with 'OSTYPE=linux-rh9-gnu' and the detection in the Makefile worked...
 454    Any help in testing appreciated!
 455    Builds automatically created 8 times a day from current CVS are here:
 456    http://www.gknw.com/mirror/curl/autobuilds/
 457    the status of these builds can be viewed at the autobuild table:
 458    http://curl.haxx.se/auto/
 459
 460
 461 CROSS COMPILE
 462 =============
 463
 464    (This section was graciously brought to us by Jim Duey, with additions by
 465    Dan Fandrich)
 466
 467    Download and unpack the cURL package.  Version should be 7.9.1 or later.
 468
 469    'cd' to the new directory. (e.g. cd curl-7.12.3)
 470
 471    Set environment variables to point to the cross-compile toolchain and call
 472    configure with any options you need.  Be sure and specify the '--host' and
 473    '--build' parameters at configuration time.  The following script is an
 474    example of cross-compiling for the IBM 405GP PowerPC processor using the
 475    toolchain from MonteVista for Hardhat Linux.
 476
 477    (begin script)
 478
 479    #! /bin/sh
 480
 481    export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
 482    export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
 483    export AR=ppc_405-ar
 484    export AS=ppc_405-as
 485    export LD=ppc_405-ld
 486    export RANLIB=ppc_405-ranlib
 487    export CC=ppc_405-gcc
 488    export NM=ppc_405-nm
 489
 490    ./configure --target=powerpc-hardhat-linux \
 491         --host=powerpc-hardhat-linux \
 492         --build=i586-pc-linux-gnu \
 493         --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
 494         --exec-prefix=/usr/local
 495
 496    (end script)
 497
 498    You may also need to provide a parameter like '--with-random=/dev/urandom'
 499    to configure as it cannot detect the presence of a random number
 500    generating device for a target system.  The '--prefix' parameter
 501    specifies where cURL will be installed.  If 'configure' completes
 502    successfully, do 'make' and 'make install' as usual.
 503
 504    In some cases, you may be able to simplify the above commands to as
 505    little as:
 506
 507        ./configure --host=ARCH-OS
 508
 509    There are a number of configure options that can be used to reduce the
 510    size of libcurl for embedded applications where binary size is an
 511    important factor.  First, be sure to set the CFLAGS environment variable
 512    when configuring with any compiler optimization flags to reduce the
 513    size of the binary.  For gcc, this would mean at minimum:
 514
 515       env CFLAGS='-Os' ./configure ...
 516
 517    Be sure to specify as many --disable- and --without- flags on the configure
 518    command-line as you can to disable all the libcurl features that you
 519    know your application is not going to need.  Besides specifying the
 520    --disable-PROTOCOL flags for all the types of URLs your application
 521    will not use, here are some other flags that can reduce the size of the
 522    library:
 523
 524      --disable-ares (disables support for the ARES DNS library)
 525      --disable-cookies (disables support for HTTP cookies)
 526      --disable-crypto-auth (disables HTTP cryptographic authentication)
 527      --disable-ipv6 (disables support for IPv6)
 528      --disable-verbose (eliminates debugging strings and error code strings)
 529      --without-libidn (disables support for the libidn DNS library)
 530      --without-ssl (disables support for SSL/TLS)
 531      --without-zlib (disables support for on-the-fly decompression)
 532
 533    You may find that statically linking libcurl to your application will
 534    result in a lower total size.
 535
 536
 537 PORTS
 538 =====
 539    This is a probably incomplete list of known hardware and operating systems
 540    that curl has been compiled for. If you know a system curl compiles and
 541    runs on, that isn't listed, please let us know!
 542
 543         - Alpha DEC OSF 4
 544         - Alpha Digital UNIX v3.2
 545         - Alpha FreeBSD 4.1, 4.5
 546         - Alpha Linux 2.2, 2.4
 547         - Alpha NetBSD 1.5.2
 548         - Alpha OpenBSD 3.0
 549         - Alpha OpenVMS V7.1-1H2
 550         - Alpha Tru64 v5.0 5.1
 551         - HP-PA HP-UX 9.X 10.X 11.X
 552         - HP-PA Linux
 553         - HP3000 MPE/iX
 554         - MIPS IRIX 6.2, 6.5
 555         - MIPS Linux
 556         - Pocket PC/Win CE 3.0
 557         - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2
 558         - PowerPC Darwin 1.0
 559         - PowerPC Linux
 560         - PowerPC Mac OS 9
 561         - PowerPC Mac OS X
 562         - SINIX-Z v5
 563         - Sparc Linux
 564         - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10
 565         - Sparc SunOS 4.1.X
 566         - StrongARM (and other ARM) RISC OS 3.1, 4.02
 567         - StrongARM/ARM7/ARM9 Linux 2.4, 2.6
 568         - StrongARM NetBSD 1.4.1
 569         - Ultrix 4.3a
 570         - i386 BeOS
 571         - i386 DOS
 572         - i386 Esix 4.1
 573         - i386 FreeBSD
 574         - i386 HURD
 575         - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6
 576         - i386 NetBSD
 577         - i386 Novell NetWare
 578         - i386 OS/2
 579         - i386 OpenBSD
 580         - i386 SCO unix
 581         - i386 Solaris 2.7
 582         - i386 Windows 95, 98, ME, NT, 2000, XP, 2003
 583         - i386 QNX 6
 584         - i486 ncr-sysv4.3.03 (NCR MP-RAS)
 585         - ia64 Linux 2.3.99
 586         - m68k AmigaOS 3
 587         - m68k Linux
 588         - m68k OpenBSD
 589         - m88k dg-dgux5.4R3.00
 590         - s390 Linux
 591         - XScale/PXA250 Linux 2.4
 592
 593 Useful URLs
 594 ===========
 595
 596 OpenSSL   http://www.openssl.org
 597 MingW     http://www.mingw.org
 598 OpenLDAP  http://www.openldap.org
 599 Zlib      http://www.gzip.org/zlib/