** This file is adapted from libcurl and not yet fully rewritten for c-ares! **
___ __ _ _ __ ___ ___
/ __| ___ / _` | '__/ _ \/ __|
| (_ |___| (_| | | | __/\__ \
\___| \__,_|_| \___||___/
How To Compile
Lots of people download binary distributions of c-ares. This document does not describe how to install c-ares using such a binary package. This document describes how to compile, build and install c-ares from source code.
If you get your code off a Git repository rather than an official release tarball, see the GIT-INFO file in the root directory for specific instructions on how to proceed.
In particular, you will need to run ./buildconf (Unix) or buildconf.bat (Windows) to generate build files, and for the former you will need a local installation of Autotools.
A normal Unix installation is made in three or four steps (after you've unpacked the source archive):
./configure make make ahost adig acountry (optional) make install
You probably need to be root when doing the last command.
If you have checked out the sources from the git repository, read the GIT-INFO on how to proceed.
Get a full listing of all available configure options by invoking it like:
./configure --help
If you want to install c-ares in a different file hierarchy than /usr/local, you need to specify that already when running configure:
./configure --prefix=/path/to/c-ares/tree
If you happen to have write permission in that directory, you can do make install without being root. An example of this would be to make a local install in your own home directory:
./configure --prefix=$HOME make make install
To force configure to use the standard cc compiler if both cc and gcc are present, run configure like
CC=cc ./configure # or env CC=cc ./configure
To force a static library compile, disable the shared library creation by running configure like:
./configure --disable-shared
If you're a c-ares developer and use gcc, you might want to enable more debug options with the --enable-debug option.
Some versions of uClibc require configuring with CPPFLAGS=-D_GNU_SOURCE=1 to get correct large file support.
The Open Watcom C compiler on Linux requires configuring with the variables:
./configure CC=owcc AR="$WATCOM/binl/wlib" AR_FLAGS=-q \
RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra
As a general rule, building a DLL with static CRT linkage is highly discouraged, and intermixing CRTs in the same app is something to avoid at any cost.
Reading and comprehension of Microsoft Knowledge Base articles KB94248 and KB140584 is a must for any Windows developer. Especially important is full understanding if you are not going to follow the advice given above.
KB94248 - How To Use the C Run-Time
KB140584 - How to link with the correct C Run-Time (CRT) library
KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries
If your app is misbehaving in some strange way, or it is suffering from memory corruption, before asking for further help, please try first to rebuild every single library your app uses as well as your app using the debug multithreaded dynamic C runtime.
Make sure that MinGW32's bin dir is in the search path, for example:
set PATH=c:\mingw32\bin;%PATH%
then run ‘make -f Makefile.m32’ in the root dir.
Almost identical to the unix installation. Run the configure script in the c-ares root with sh configure. Make sure you have the sh executable in /bin/ or you'll see the configure fail toward the end.
Run make
If you use MSVC 6 it is required that you use the February 2003 edition PSDK: http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm
Run the vcvars32.bat file to get a proper environment. The vcvars32.bat file is part of the Microsoft development environment and you may find it in C:\Program Files\Microsoft Visual Studio\vc98\bin provided that you installed Visual C/C++ 6 in the default directory.
Further details in README.msvc
Details in README.msvc
When building an application that uses the static c-ares library, you must add -DCARES_STATICLIB to your CFLAGS. Otherwise the linker will look for dynamic import symbols.
Building under OS/2 is not much different from building under unix. You need:
If during the linking you get an error about _errno being an undefined symbol referenced from the text segment, you need to add -D__ST_MT_ERRNO__ in your definitions.
If you're getting huge binaries, probably your makefiles have the -g in CFLAGS.
(This section was graciously brought to us by David Bentham)
As QNX is targeted for resource constrained environments, the QNX headers set conservative limits. This includes the FD_SETSIZE macro, set by default to 32. Socket descriptors returned within the c-ares library may exceed this, resulting in memory faults/SIGSEGV crashes when passed into select(..) calls using fd_set macros.
A good all-round solution to this is to override the default when building c-ares, by overriding CFLAGS during configure, example:
# configure CFLAGS='-DFD_SETSIZE=64 -g -O2'
The library can be cross-compiled using gccsdk as follows:
CC=riscos-gcc AR=riscos-ar RANLIB='riscos-ar -s' ./configure \
--host=arm-riscos-aof --without-random --disable-shared
make
where riscos-gcc and riscos-ar are links to the gccsdk tools. You can then link your program with c-ares/lib/.libs/libcares.a.
To compile libcares.a / libcares.lib you need:
Set a search path to your compiler, linker and tools; on Linux make sure that the var OSTYPE contains the string ‘linux’; set the var NDKBASE to point to the base of your Novell NDK; and then type make -f Makefile.netware from the top source directory;
Method using a configure cross-compile (tested with Android NDK r7b):
prepare the toolchain of the Android NDK for standalone use; this can be done by invoking the script:
./tools/make-standalone-toolchain.sh
which creates a usual cross-compile toolchain. Lets assume that you put this toolchain below /opt then invoke configure with something like:
export PATH=/opt/arm-linux-androideabi-4.4.3/bin:$PATH
./configure --host=arm-linux-androideabi [more configure options]
make
if you want to compile directly from our GIT repo you might run into this issue with older automake stuff:
checking host system type...
Invalid configuration `arm-linux-androideabi':
system `androideabi' not recognized
configure: error: /bin/sh ./config.sub arm-linux-androideabi failed
this issue can be fixed with using more recent versions of config.sub and config.guess which can be obtained here: http://git.savannah.gnu.org/gitweb/?p=config.git;a=tree you need to replace your system-own versions which usually can be found in your automake folder: find /usr -name config.sub
(This section was graciously brought to us by Jim Duey, with additions by Dan Fandrich)
Download and unpack the c-ares package.
cd to the new directory. (e.g. cd c-ares-1.7.6)
Set environment variables to point to the cross-compile toolchain and call configure with any options you need. Be sure and specify the --host and --build parameters at configuration time. The following script is an example of cross-compiling for the IBM 405GP PowerPC processor using the toolchain from MonteVista for Hardhat Linux.
#! /bin/sh export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include" export AR=ppc_405-ar export AS=ppc_405-as export LD=ppc_405-ld export RANLIB=ppc_405-ranlib export CC=ppc_405-gcc export NM=ppc_405-nm ./configure --target=powerpc-hardhat-linux \ --host=powerpc-hardhat-linux \ --build=i586-pc-linux-gnu \ --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \ --exec-prefix=/usr/local
You may also need to provide a parameter like --with-random=/dev/urandom to configure as it cannot detect the presence of a random number generating device for a target system. The --prefix parameter specifies where c-ares will be installed. If configure completes successfully, do make and make install as usual.
In some cases, you may be able to simplify the above commands to as little as:
./configure --host=ARCH-OS
This is a probably incomplete list of known hardware and operating systems that c-ares has been compiled for. If you know a system c-ares compiles and runs on, that isn't listed, please let us know!
- Alpha Tru64 v5.0 5.1 - ARM Android 1.5, 2.1, 2.3 - MIPS IRIX 6.2, 6.5 - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2 - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6 - i386 Novell NetWare - i386 Windows 95, 98, ME, NT, 2000, XP, 2003 - x86_64 Linux