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