INSTALL

   1 ** This file is adapted from libcurl and not yet fully rewritten for c-ares! **
   2
   3                           ___       __ _ _ __ ___  ___
   4                          / __| ___ / _` | '__/ _ \/ __|
   5                         | (_  |___| (_| | | |  __/\__ \
   6                          \___|     \__,_|_|  \___||___/
   7
   8                                 How To Compile
   9
  10 Installing Binary Packages
  11 ==========================
  12
  13    Lots of people download binary distributions of c-ares. This document
  14    does not describe how to install c-ares using such a binary package.
  15    This document describes how to compile, build and install c-ares from
  16    source code.
  17
  18 Building from git
  19 =================
  20
  21    If you get your code off a git repository, see the GIT-INFO file in the
  22    root directory for specific instructions on how to proceed.
  23
  24 UNIX
  25 ====
  26    A normal unix installation is made in three or four steps (after you've
  27    unpacked the source archive):
  28
  29         ./configure
  30         make
  31         make ahost adig acountry (optional)
  32         make install
  33
  34    You probably need to be root when doing the last command.
  35
  36    If you have checked out the sources from the git repository, read the
  37    GIT-INFO on how to proceed.
  38
  39    Get a full listing of all available configure options by invoking it like:
  40
  41         ./configure --help
  42
  43    If you want to install c-ares in a different file hierarchy than /usr/local,
  44    you need to specify that already when running configure:
  45
  46         ./configure --prefix=/path/to/c-ares/tree
  47
  48    If you happen to have write permission in that directory, you can do 'make
  49    install' without being root. An example of this would be to make a local
  50    install in your own home directory:
  51
  52         ./configure --prefix=$HOME
  53         make
  54         make install
  55
  56    MORE OPTIONS
  57    ------------
  58
  59      To force configure to use the standard cc compiler if both cc and gcc are
  60      present, run configure like
  61
  62        CC=cc ./configure
  63          or
  64        env CC=cc ./configure
  65
  66      To force a static library compile, disable the shared library creation
  67      by running configure like:
  68
  69        ./configure --disable-shared
  70
  71      If you're a c-ares developer and use gcc, you might want to enable more
  72      debug options with the --enable-debug option.
  73
  74    SPECIAL CASES
  75    -------------
  76    Some versions of uClibc require configuring with CPPFLAGS=-D_GNU_SOURCE=1
  77    to get correct large file support.
  78
  79    The Open Watcom C compiler on Linux requires configuring with the variables:
  80
  81        ./configure CC=owcc AR="$WATCOM/binl/wlib" AR_FLAGS=-q \
  82            RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra
  83
  84
  85 Win32
  86 =====
  87
  88    Building Windows DLLs and C run-time (CRT) linkage issues
  89    ---------------------------------------------------------
  90
  91    As a general rule, building a DLL with static CRT linkage is highly
  92    discouraged, and intermixing CRTs in the same app is something to
  93    avoid at any cost.
  94
  95    Reading and comprehension of Microsoft Knowledge Base articles
  96    KB94248 and KB140584 is a must for any Windows developer. Especially
  97    important is full understanding if you are not going to follow the
  98    advice given above.
  99
 100    KB94248  - How To Use the C Run-Time
 101               http://support.microsoft.com/kb/94248/en-us
 102
 103    KB140584 - How to link with the correct C Run-Time (CRT) library
 104               http://support.microsoft.com/kb/140584/en-us
 105
 106    KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries
 107               http://msdn.microsoft.com/en-us/library/ms235460
 108
 109    If your app is misbehaving in some strange way, or it is suffering
 110    from memory corruption, before asking for further help, please try
 111    first to rebuild every single library your app uses as well as your
 112    app using the debug multithreaded dynamic C runtime.
 113
 114    MingW32
 115    -------
 116
 117    Make sure that MinGW32's bin dir is in the search path, for example:
 118
 119      set PATH=c:\mingw32\bin;%PATH%
 120
 121    then run 'make -f Makefile.m32' in the root dir.
 122
 123    Cygwin
 124    ------
 125
 126    Almost identical to the unix installation. Run the configure script in the
 127    c-ares root with 'sh configure'. Make sure you have the sh executable in
 128    /bin/ or you'll see the configure fail toward the end.
 129
 130    Run 'make'
 131
 132    Dev-Cpp
 133    -------
 134
 135    See the separate INSTALL.devcpp file for details.
 136
 137    MSVC 6 caveats
 138    --------------
 139
 140    If you use MSVC 6 it is required that you use the February 2003 edition PSDK:
 141    http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm
 142
 143    MSVC from command line
 144    ----------------------
 145
 146    Run the 'vcvars32.bat' file to get a proper environment. The
 147    vcvars32.bat file is part of the Microsoft development environment and
 148    you may find it in 'C:\Program Files\Microsoft Visual Studio\vc98\bin'
 149    provided that you installed Visual C/C++ 6 in the default directory.
 150
 151    Further details in README.msvc
 152
 153    MSVC IDES
 154    ---------
 155
 156    Details in README.msvc
 157
 158    Important static c-ares usage note
 159    ----------------------------------
 160
 161    When building an application that uses the static c-ares library, you must
 162    add '-DCARES_STATICLIB' to your CFLAGS.  Otherwise the linker will look for
 163    dynamic import symbols.
 164
 165
 166 IBM OS/2
 167 ========
 168    Building under OS/2 is not much different from building under unix.
 169    You need:
 170
 171       - emx 0.9d
 172       - GNU make
 173       - GNU patch
 174       - ksh
 175       - GNU bison
 176       - GNU file utilities
 177       - GNU sed
 178       - autoconf 2.13
 179
 180    If during the linking you get an error about _errno being an undefined
 181    symbol referenced from the text segment, you need to add -D__ST_MT_ERRNO__
 182    in your definitions.
 183
 184    If you're getting huge binaries, probably your makefiles have the -g in
 185    CFLAGS.
 186
 187
 188 QNX
 189 ===
 190    (This section was graciously brought to us by David Bentham)
 191
 192    As QNX is targeted for resource constrained environments, the QNX headers
 193    set conservative limits. This includes the FD_SETSIZE macro, set by default
 194    to 32. Socket descriptors returned within the c-ares library may exceed this,
 195    resulting in memory faults/SIGSEGV crashes when passed into select(..)
 196    calls using fd_set macros.
 197
 198    A good all-round solution to this is to override the default when building
 199    c-ares, by overriding CFLAGS during configure, example
 200    #  configure CFLAGS='-DFD_SETSIZE=64 -g -O2'
 201
 202
 203 RISC OS
 204 =======
 205    The library can be cross-compiled using gccsdk as follows:
 206
 207         CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \
 208              --host=arm-riscos-aof --without-random --disable-shared
 209         make
 210
 211    where riscos-gcc and riscos-ar are links to the gccsdk tools.
 212    You can then link your program with c-ares/lib/.libs/libcares.a
 213
 214
 215 NetWare
 216 =======
 217    To compile libcares.a / libcares.lib you need:
 218    - either any gcc / nlmconv, or CodeWarrior 7 PDK 4 or later.
 219    - gnu make and awk running on the platform you compile on;
 220      native Win32 versions can be downloaded from:
 221      http://www.gknw.net/development/prgtools/
 222    - recent Novell LibC SDK available from:
 223      http://developer.novell.com/ndk/libc.htm
 224    - or recent Novell CLib SDK available from:
 225      http://developer.novell.com/ndk/clib.htm
 226
 227    Set a search path to your compiler, linker and tools; on Linux make
 228    sure that the var OSTYPE contains the string 'linux'; set the var
 229    NDKBASE to point to the base of your Novell NDK; and then type
 230    'make -f Makefile.netware' from the top source directory;
 231
 232
 233 Android
 234 =======
 235    Method using a configure cross-compile (tested with Android NDK r7b):
 236       - prepare the toolchain of the Android NDK for standalone use; this can
 237         be done by invoking the script:
 238         ./tools/make-standalone-toolchain.sh
 239         which creates a usual cross-compile toolchain. Lets assume that you put
 240         this toolchain below /opt then invoke configure with something like:
 241         export PATH=/opt/arm-linux-androideabi-4.4.3/bin:$PATH
 242         ./configure --host=arm-linux-androideabi [more configure options]
 243         make
 244       - if you want to compile directly from our GIT repo you might run into
 245         this issue with older automake stuff:
 246         checking host system type...
 247         Invalid configuration `arm-linux-androideabi':
 248         system `androideabi' not recognized
 249         configure: error: /bin/sh ./config.sub arm-linux-androideabi failed
 250         this issue can be fixed with using more recent versions of config.sub
 251         and config.guess which can be obtained here:
 252         http://git.savannah.gnu.org/gitweb/?p=config.git;a=tree
 253         you need to replace your system-own versions which usually can be
 254         found in your automake folder:
 255         find /usr -name config.sub
 256
 257
 258 CROSS COMPILE
 259 =============
 260    (This section was graciously brought to us by Jim Duey, with additions by
 261    Dan Fandrich)
 262
 263    Download and unpack the c-ares package.
 264
 265    'cd' to the new directory. (e.g. cd c-ares-1.7.6)
 266
 267    Set environment variables to point to the cross-compile toolchain and call
 268    configure with any options you need.  Be sure and specify the '--host' and
 269    '--build' parameters at configuration time.  The following script is an
 270    example of cross-compiling for the IBM 405GP PowerPC processor using the
 271    toolchain from MonteVista for Hardhat Linux.
 272
 273    (begin script)
 274
 275    #! /bin/sh
 276
 277    export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
 278    export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
 279    export AR=ppc_405-ar
 280    export AS=ppc_405-as
 281    export LD=ppc_405-ld
 282    export RANLIB=ppc_405-ranlib
 283    export CC=ppc_405-gcc
 284    export NM=ppc_405-nm
 285
 286    ./configure --target=powerpc-hardhat-linux \
 287         --host=powerpc-hardhat-linux \
 288         --build=i586-pc-linux-gnu \
 289         --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
 290         --exec-prefix=/usr/local
 291
 292    (end script)
 293
 294    You may also need to provide a parameter like '--with-random=/dev/urandom'
 295    to configure as it cannot detect the presence of a random number
 296    generating device for a target system.  The '--prefix' parameter
 297    specifies where c-ares will be installed.  If 'configure' completes
 298    successfully, do 'make' and 'make install' as usual.
 299
 300    In some cases, you may be able to simplify the above commands to as
 301    little as:
 302
 303        ./configure --host=ARCH-OS
 304
 305
 306 PORTS
 307 =====
 308    This is a probably incomplete list of known hardware and operating systems
 309    that c-ares has been compiled for. If you know a system c-ares compiles and
 310    runs on, that isn't listed, please let us know!
 311
 312         - Alpha Tru64 v5.0 5.1
 313         - ARM Android 1.5, 2.1, 2.3
 314         - MIPS IRIX 6.2, 6.5
 315         - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2
 316         - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6
 317         - i386 Novell NetWare
 318         - i386 Windows 95, 98, ME, NT, 2000, XP, 2003
 319         - x86_64 Linux
 320
 321 Useful URLs
 322 ===========
 323
 324 c-ares       http://c-ares.haxx.se/
 325
 326 MingW        http://www.mingw.org/
 327 MinGW-w64    http://mingw-w64.sourceforge.net/
 328 OpenWatcom   http://www.openwatcom.org/