INSTALL.md

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