1 ** This file is adapted from libcurl and not yet fully rewritten for c-ares! **
4 / __| ___ / _` | '__/ _ \/ __|
5 | (_ |___| (_| | | | __/\__ \
6 \___| \__,_|_| \___||___/
10 Installing Binary Packages
11 ==========================
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
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.
26 A normal unix installation is made in three or four steps (after you've
27 unpacked the source archive):
31 make ahost adig acountry (optional)
34 You probably need to be root when doing the last command.
36 If you have checked out the sources from the git repository, read the
37 GIT-INFO on how to proceed.
39 Get a full listing of all available configure options by invoking it like:
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:
46 ./configure --prefix=/path/to/c-ares/tree
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:
52 ./configure --prefix=$HOME
59 To force configure to use the standard cc compiler if both cc and gcc are
60 present, run configure like
66 To force a static library compile, disable the shared library creation
67 by running configure like:
69 ./configure --disable-shared
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.
76 Some versions of uClibc require configuring with CPPFLAGS=-D_GNU_SOURCE=1
77 to get correct large file support.
79 The Open Watcom C compiler on Linux requires configuring with the variables:
81 ./configure CC=owcc AR="$WATCOM/binl/wlib" AR_FLAGS=-q \
82 RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra
88 Building Windows DLLs and C run-time (CRT) linkage issues
89 ---------------------------------------------------------
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
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
100 KB94248 - How To Use the C Run-Time
101 http://support.microsoft.com/kb/94248/en-us
103 KB140584 - How to link with the correct C Run-Time (CRT) library
104 http://support.microsoft.com/kb/140584/en-us
106 KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries
107 http://msdn.microsoft.com/en-us/library/ms235460
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.
117 Make sure that MinGW32's bin dir is in the search path, for example:
119 set PATH=c:\mingw32\bin;%PATH%
121 then run 'make -f Makefile.m32' in the root dir.
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.
135 See the separate INSTALL.devcpp file for details.
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
143 MSVC from command line
144 ----------------------
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.
151 Further details in README.msvc
156 Details in README.msvc
158 Important static c-ares usage note
159 ----------------------------------
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.
168 Building under OS/2 is not much different from building under unix.
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__
184 If you're getting huge binaries, probably your makefiles have the -g in
190 (This section was graciously brought to us by David Bentham)
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.
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'
205 The library can be cross-compiled using gccsdk as follows:
207 CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \
208 --host=arm-riscos-aof --without-random --disable-shared
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
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
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;
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]
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
260 (This section was graciously brought to us by Jim Duey, with additions by
263 Download and unpack the c-ares package.
265 'cd' to the new directory. (e.g. cd c-ares-1.7.6)
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.
277 export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
278 export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
282 export RANLIB=ppc_405-ranlib
283 export CC=ppc_405-gcc
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
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.
300 In some cases, you may be able to simplify the above commands to as
303 ./configure --host=ARCH-OS
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!
312 - Alpha Tru64 v5.0 5.1
313 - ARM Android 1.5, 2.1, 2.3
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
324 c-ares http://c-ares.haxx.se/
326 MingW http://www.mingw.org/
327 MinGW-w64 http://mingw-w64.sourceforge.net/
328 OpenWatcom http://www.openwatcom.org/