neo/curl/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 your SSL library was compiled with rsaref (usually for use in the United
  83    States), you may also need to set:
  84
  85      LIBS=-lRSAglue -lrsaref
  86      (as suggested by Doug Kaufman)
  87
  88    MORE OPTIONS
  89
  90      To force configure to use the standard cc compiler if both cc and gcc are
  91      present, run configure like
  92
  93        CC=cc ./configure
  94          or
  95        env Cc=cc ./configure
  96
  97      To force a static library compile, disable the shared library creation
  98      by running configure like:
  99
 100        ./configure --disable-shared
 101
 102      To tell the configure script to skip searching for thread-safe functions,
 103      add an option like:
 104
 105        ./configure --disable-thread
 106
 107      To build curl with kerberos4 support enabled, curl requires the krb4 libs
 108      and headers installed. You can then use a set of options to tell
 109      configure where those are:
 110
 111           --with-krb4-includes[=DIR]   Specify location of kerberos4 headers
 112           --with-krb4-libs[=DIR]       Specify location of kerberos4 libs
 113           --with-krb4[=DIR]            where to look for Kerberos4
 114
 115      In most cases, /usr/athena is the install prefix and then it works with
 116
 117        ./configure --with-krb4=/usr/athena
 118
 119      If you're a curl developer and use gcc, you might want to enable more
 120      debug options with the --enable-debug option.
 121
 122 Win32
 123 =====
 124
 125    Without SSL:
 126
 127       MingW32 (GCC-2.95) style
 128       ------------------------
 129         Run the 'mingw32.bat' file to get the proper environment variables
 130         set, then run 'make mingw32' in the root dir.
 131
 132         If you have any problems linking libraries or finding header files, be
 133         sure to verify that the provided "Makefile.m32" files use the proper
 134         paths, and adjust as necessary.
 135
 136       Cygwin style
 137       ------------
 138         Almost identical to the unix installation. Run the configure script in
 139         the curl root with 'sh configure'. Make sure you have the sh
 140         executable in /bin/ or you'll see the configure fail towards the end.
 141
 142         Run 'make'
 143
 144       Microsoft command line style
 145       ----------------------------
 146         Run the 'vcvars32.bat' file to get the proper environment variables
 147         set, then run 'nmake vc' in the root dir.
 148
 149         The vcvars32.bat file is part of the Microsoft development
 150         environment.
 151
 152       IDE-style
 153       -------------------------
 154         If you use VC++, Borland or similar compilers. Include all lib source
 155         files in a static lib "project" (all .c and .h files that is).
 156         (you should name it libcurl or similar)
 157
 158         Make the sources in the src/ drawer be a "win32 console application"
 159         project. Name it curl.
 160
 161         With VC++, add 'ws2_32.lib' to the link libs when you build curl!
 162         Borland seems to do that itself magically. Of course you have to make
 163         sure it links with the libcurl too!
 164
 165         For VC++ 6, there's an included Makefile.vc6 that should be possible
 166         to use out-of-the-box.
 167
 168         Microsoft note: add /Zm200 to the compiler options to increase the
 169         compiler's memory allocation limit, as the hugehelp.c won't compile
 170         due to "too long puts string".
 171
 172
 173    With SSL:
 174
 175       MingW32 (GCC-2.95) style
 176       ------------------------
 177         Run the 'mingw32.bat' file to get the proper environment variables
 178         set, then run 'make mingw32-ssl' in the root dir.
 179
 180         If you have any problems linking libraries or finding header files, be
 181         sure to look at the provided "Makefile.m32" files for the proper
 182         paths, and adjust as necessary.
 183
 184       Cygwin style
 185       ------------
 186         Haven't done, nor got any reports on how to do. It should although be
 187         identical to the unix setup for the same purpose. See above.
 188
 189       Microsoft command line style
 190       ----------------------------
 191
 192         Please read the OpenSSL documentation on how to compile and install
 193         the OpenSSL libraries.  The build process of OpenSSL generates the
 194         libeay32.dll and ssleay32.dll files in the out32dll subdirectory in
 195         the OpenSSL home directory.  OpenSSL static libraries (libeay32.lib,
 196         ssleay32.lib, RSAglue.lib) are created in the out32 subdirectory.
 197
 198         Run the 'vcvars32.bat' file to get a proper environment. The
 199         vcvars32.bat file is part of the Microsoft development environment and
 200         you may find it in 'C:\Program Files\Microsoft Visual Studio\vc98\bin'
 201         provided that you installed Visual C/C++ 6 in the default directory.
 202
 203         Before running nmake define the OPENSSL_PATH environment variable with
 204         the root/base directory of OpenSSL, for example:
 205
 206           set OPENSSL_PATH=c:\openssl-0.9.7a
 207
 208         lib/Makefile.vc6 depends on zlib (http://www.gzip.org/zlib/) as well.
 209         Please read the zlib documentation on how to compile zlib.  Define the
 210         ZLIB_PATH environment variable to the location of zlib.h and zlib.lib,
 211         for example:
 212
 213           set ZLIB_PATH=c:\zlib-1.1.4
 214
 215         Then run 'nmake vc-ssl' or 'nmake vc-ssl-dll' in curl's root
 216         directory.  'nmake vc-ssl' will create a libcurl static and dynamic
 217         libraries in the lib subdirectory, as well as a statically linked
 218         version of curl.exe in the src subdirectory.  This statically linked
 219         version is a standalone executable not requiring any DLL at
 220         runtime. This make method requires that you have the static OpenSSL
 221         libraries available in OpenSSL's out32 subdirectory.
 222         'nmake vc-ssl-dll' creates the libcurl dynamic library and
 223         links curl.exe against libcurl and OpenSSL dynamically.
 224         This executable requires libcurl.dll and the OpenSSL DLLs
 225         at runtime.
 226
 227       Microsoft / Borland style
 228       -------------------------
 229         If you have OpenSSL, and want curl to take advantage of it, edit your
 230         project properties to use the SSL include path, link with the SSL libs
 231         and define the USE_SSLEAY symbol.
 232
 233       Using Borland C++ compiler version 5.5.1 (available as free download
 234       from Borland's site)
 235       ---------------------------------------------------------------------
 236
 237         compile openssl
 238
 239         Make sure you include the paths to curl/include and openssl/inc32 in
 240         your bcc32.cnf file
 241
 242
 243         eg : -I"c:\Bcc55\include;c:\path_curl\include;c:\path_openssl\inc32"
 244
 245         Check to make sure that all of the sources listed in lib/Makefile.b32
 246         are present in the /path_to_curl/lib directory. (Check the src
 247         directory for missing ones.)
 248
 249         Make sure the environment variable "BCCDIR" is set to the install
 250         location for the compiler eg : c:\Borland\BCC55
 251
 252         command line:
 253         make -f /path_to_curl/lib/Makefile-ssl.b32
 254
 255         compile simplessl.c with appropriate links
 256
 257         c:\curl\docs\examples\> bcc32 -L c:\path_to_curl\lib\libcurl.lib
 258                                       -L c:\borland\bcc55\lib\psdk\ws2_32.lib
 259                                       -L c:\openssl\out32\libeay32.lib
 260                                       -L c:\openssl\out32\ssleay32.lib
 261                                       simplessl.c
 262
 263    Disabling Specific Protocols:
 264
 265       The configure utility, unfortunately, is not available for the Windows
 266       environment, therefore, you cannot use the various disable-protocol
 267       options of the configure utility on this platform.
 268
 269       However, you can use the following defines to disable specific
 270       protocols:
 271
 272       HTTP_ONLY             disables all protocols except HTTP
 273       CURL_DISABLE_FTP      disables FTP
 274       CURL_DISABLE_LDAP     disables LDAP
 275       CURL_DISABLE_TELNET   disables TELNET
 276       CURL_DISABLE_DICT     disables DICT
 277       CURL_DISABLE_FILE     disables FILE
 278       CURL_DISABLE_GOPHER   disables GOPHER
 279
 280       If you want to set any of these defines you have the following
 281       possibilities:
 282
 283       - Modify lib/setup.h
 284       - Modify lib/Makefile.vc6
 285       - Add defines to Project/Settings/C/C++/General/Preprocessor Definitions
 286         in the curllib.dsw/curllib.dsp Visual C++ 6 IDE project.
 287
 288 IBM OS/2
 289 ========
 290
 291    Building under OS/2 is not much different from building under unix.
 292    You need:
 293
 294       - emx 0.9d
 295       - GNU make
 296       - GNU patch
 297       - ksh
 298       - GNU bison
 299       - GNU file utilities
 300       - GNU sed
 301       - autoconf 2.13
 302
 303    If you want to build with OpenSSL or OpenLDAP support, you'll need to
 304    download those libraries, too. Dirk Ohme has done some work to port SSL
 305    libraries under OS/2, but it looks like he doesn't care about emx.  You'll
 306    find his patches on: http://come.to/Dirk_Ohme
 307
 308    If during the linking you get an error about _errno being an undefined
 309    symbol referenced from the text segment, you need to add -D__ST_MT_ERRNO__
 310    in your definitions.
 311
 312    If everything seems to work fine but there's no curl.exe, you need to add
 313    -Zexe to your linker flags.
 314
 315    If you're getting huge binaries, probably your makefiles have the -g in
 316    CFLAGS.
 317
 318 VMS
 319 ===
 320    (The VMS section is in whole contributed by the friendly Nico Baggus)
 321
 322    Curl seems to work with FTP & HTTP other protocols are not tested.  (the
 323    perl http/ftp testing server supplied as testing too cannot work on VMS
 324    because vms has no concept of fork(). [ I tried to give it a whack, but
 325    thats of no use.
 326
 327    SSL stuff has not been ported.
 328
 329    Telnet has about the same issues as for Win32. When the changes for Win32
 330    are clear maybe they'll work for VMS too. The basic problem is that select
 331    ONLY works for sockets.
 332
 333    Marked instances of fopen/[f]stat that might become a problem, especially
 334    for non stream files. In this regard, the files opened for writing will be
 335    created stream/lf and will thus be safe. Just keep in mind that non-binary
 336    read/wring from/to files will have a records size limit of 32767 bytes
 337    imposed.
 338
 339    Stat to get the size of the files is again only safe for stream files &
 340    fixed record files without implied CC.
 341
 342    -- My guess is that only allowing access to stream files is the quickest
 343    way to get around the most issues. Therefore all files need to to be
 344    checked to be sure they will be stream/lf before processing them.  This is
 345    the easiest way out, I know. The reason for this is that code that needs to
 346    report the filesize will become a pain in the ass otherwise.
 347
 348    Exit status.... Well we needed something done here,
 349
 350    VMS has a structured exist status:
 351    | 3  |       2    |     1       |  0|
 352    |1098|765432109876|5432109876543|210|
 353    +----+------------+-------------+---+
 354    |Ctrl|  Facility  | Error code  |sev|
 355    +----+------------+-------------+---+
 356
 357    With the Ctrl-bits an application can tell if part or the whole message has
 358    allready been printed from the program, DCL doesn't need to print it again.
 359
 360    Facility - basicaly the program ID. A code assigned to the program
 361    the name can be fetched from external or internal message libraries
 362    Errorcode - the errodes assigned by the application
 363    Sev. - severity: Even = error, off = non error
 364                 0 = Warning
 365                 1 = Success
 366                 2 = Error
 367                 3 = Information
 368                 4 = Fatal
 369                 <5-7> reserved.
 370
 371    This all presents itself with:
 372    %<FACILITY>-<SeV>-<Errorname>, <Error message>
 373
 374    See also the src/curlmsg.msg file, it has the source for the messages In
 375    src/main.c a section is devoted to message status values, the globalvalues
 376    create symbols with certain values, referenced from a compiled message
 377    file. Have all exit function use a exit status derived from a translation
 378    table with the compiled message codes.
 379
 380    This was all compiled with:
 381
 382         Compaq C V6.2-003 on OpenVMS Alpha V7.1-1H2
 383
 384    So far for porting notes as of:
 385    13-jul-2001
 386    N. Baggus
 387
 388 QNX
 389 ===
 390    (This section was graciously brought to us by David Bentham)
 391
 392    As QNX is targetted for resource constrained environments, the QNX headers
 393    set conservative limits. This includes the FD_SETSIZE macro, set by default
 394    to 32. Socket descriptors returned within the CURL library may exceed this,
 395    resulting in memory faults/SIGSEGV crashes when passed into select(..)
 396    calls using fd_set macros.
 397
 398    A good all-round solution to this is to override the default when building
 399    libcurl, by overriding CFLAGS during configure, example
 400    #  configure CFLAGS='-DFD_SETSIZE=64 -g -O2'
 401
 402 CROSS COMPILE
 403 =============
 404
 405    (This section was graciously brought to us by Jim Duey, 23-oct-2001)
 406
 407    Download and unpack the cURL package.  Version should be 7.9.1 or later.
 408
 409    'cd' to the new directory. (ie. curl-7.9.1-pre4)
 410
 411    Set environment variables to point to the cross-compile toolchain and call
 412    configure with any options you need.  Be sure and specify the '--host' and
 413    '--build' parameters at configuration time.  The following script is an
 414    example of cross-compiling for the IBM 405GP PowerPC processor using the
 415    toolchain from MonteVista for Hardhat Linux.
 416
 417    (begin script)
 418
 419    #! /bin/sh
 420
 421    export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
 422    export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
 423    export AR=ppc_405-ar
 424    export AS=ppc_405-as
 425    export LD=ppc_405-ld
 426    export RANLIB=ppc_405-ranlib
 427    export CC=ppc_405-gcc
 428    export NM=ppc_405-nm
 429
 430    configure --target=powerpc-hardhat-linux \
 431         --host=powerpc-hardhat-linux \
 432         --build=i586-pc-linux-gnu \
 433         --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
 434         --exec-prefix=/usr/local
 435
 436    (end script)
 437
 438    The '--prefix' parameter specifies where cURL will be installed.  If
 439    'configure' completes successfully, do 'make' and 'make install' as usual.
 440
 441 RISC OS
 442 =======
 443    The library can be cross-compiled using gccsdk as follows:
 444
 445         CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \
 446              --host=arm-riscos-aof --without-random --disable-shared
 447         make
 448
 449    where riscos-gcc and riscos-ar are links to the gccsdk tools.
 450    You can then link your program with curl/lib/.libs/libcurl.a
 451
 452
 453 AmigaOS
 454 =======
 455    (This section was graciously brought to us by Diego Casorran)
 456
 457    To build cURL/libcurl on AmigaOS just type 'make amiga' ...
 458
 459    What you need is:    (not tested with others versions)
 460
 461         GeekGadgets / gcc 2.95.3 (http://www.geekgadgets.org/)
 462
 463         AmiTCP SDK v4.3 (http://www.aminet.net/comm/tcp/AmiTCP-SDK-4.3.lha)
 464
 465         Native Developer Kit (http://www.amiga.com/3.9/download/NDK3.9.lha)
 466
 467    As no ixemul.library is required you will be able to build it for
 468    WarpOS/PowerPC (not tested by me), as well a MorphOS version should be
 469    possible with no problems.
 470
 471    To enable SSL support, you need a OpenSSL native version (without ixemul),
 472    you can find a precompiled package at http://amiga.sourceforge.net/OpenSSL/
 473
 474
 475 PORTS
 476 =====
 477    This is a probably incomplete list of known hardware and operating systems
 478    that curl has been compiled for. If you know a system curl compiles and
 479    runs on, that isn't listed, please let us know!
 480
 481         - Alpha DEC OSF 4
 482         - Alpha Digital UNIX v3.2
 483         - Alpha FreeBSD 4.1, 4.5
 484         - Alpha Linux 2.2, 2.4
 485         - Alpha NetBSD 1.5.2
 486         - Alpha OpenBSD 3.0
 487         - Alpha OpenVMS V7.1-1H2
 488         - Alpha Tru64 v5.0 5.1
 489         - HP-PA HP-UX 9.X 10.X 11.X
 490         - HP-PA Linux
 491         - HP3000 MPE/iX
 492         - MIPS IRIX 6.2, 6.5
 493         - MIPS Linux
 494         - Pocket PC/Win CE 3.0
 495         - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1
 496         - PowerPC Darwin 1.0
 497         - PowerPC Linux
 498         - PowerPC Mac OS 9
 499         - PowerPC Mac OS X
 500         - SINIX-Z v5
 501         - Sparc Linux
 502         - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8
 503         - Sparc SunOS 4.1.X
 504         - StrongARM (and other ARM) RISC OS 3.1, 4.02
 505         - StrongARM Linux 2.4
 506         - StrongARM NetBSD 1.4.1
 507         - Ultrix 4.3a
 508         - i386 BeOS
 509         - i386 DOS
 510         - i386 FreeBSD
 511         - i386 HURD
 512         - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4
 513         - i386 NetBSD
 514         - i386 Novell NetWare
 515         - i386 OS/2
 516         - i386 OpenBSD
 517         - i386 SCO unix
 518         - i386 Solaris 2.7
 519         - i386 Windows 95, 98, ME, NT, 2000
 520         - i386 QNX 6
 521         - i486 ncr-sysv4.3.03 (NCR MP-RAS)
 522         - ia64 Linux 2.3.99
 523         - m68k AmigaOS 3
 524         - m68k Linux
 525         - m68k OpenBSD
 526         - m88k dg-dgux5.4R3.00
 527         - s390 Linux
 528         - XScale/PXA250 Linux 2.4
 529
 530 OpenSSL
 531 =======
 532
 533    You'll find OpenSSL information at:
 534
 535       http://www.openssl.org
 536
 537
 538 MingW32/Cygwin
 539 ==============
 540
 541    You'll find MingW32 and Cygwin information at:
 542
 543       http://www.mingw.org
 544
 545 OpenLDAP
 546 ========
 547
 548    You'll find OpenLDAP information at:
 549
 550       http://www.openldap.org
 551