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