** This file is adapted from libcurl and not yet fully rewritten for c-ares! ** ___ __ _ _ __ ___ ___ / __| ___ / _` | '__/ _ \/ __| | (_ |___| (_| | | | __/\__ \ \___| \__,_|_| \___||___/ How To Compile Installing Binary Packages ========================== 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. Building from git ================= If you get your code off a git repository, see the GIT-INFO file in the root directory for specific instructions on how to proceed. UNIX ==== A normal unix installation is made in three or four steps (after you've unpacked the source archive): ./configure make make test (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 MORE OPTIONS ------------ 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. SPECIAL CASES ------------- 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 Win32 ===== Building Windows DLLs and C run-time (CRT) linkage issues --------------------------------------------------------- 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 http://support.microsoft.com/kb/94248/en-us KB140584 - How to link with the correct C Run-Time (CRT) library http://support.microsoft.com/kb/140584/en-us KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries http://msdn.microsoft.com/en-us/library/ms235460 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. MingW32 ------- Make sure that MinGW32's bin dir is in the search path, for example: set PATH=c:\mingw32\bin;%PATH% then run 'mingw32-make' in the root dir. There is another make target available to build the demo files: 'mingw32-make demos' Cygwin ------ 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' Dev-Cpp ------- See the separate INSTALL.devcpp file for details. MSVC 6 caveats -------------- 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 MSVC from command line ---------------------- 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 MSVC IDES --------- Details in README.msvc Important static c-ares usage note ---------------------------------- When building an application that uses the static libc-ares library, you must add '-DCARES_STATICLIB' to your CFLAGS. Otherwise the linker will look for dynamic import symbols. IBM OS/2 ======== Building under OS/2 is not much different from building under unix. You need: - emx 0.9d - GNU make - GNU patch - ksh - GNU bison - GNU file utilities - GNU sed - autoconf 2.13 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. QNX === (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' RISC OS ======= 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 NetWare ======= To compile libcares.a / libcares.lib you need: - either any gcc / nlmconv, or CodeWarrior 7 PDK 4 or later. - gnu make and awk running on the platform you compile on; native Win32 versions can be downloaded from: http://www.gknw.net/development/prgtools/ - recent Novell LibC SDK available from: http://developer.novell.com/ndk/libc.htm - or recent Novell CLib SDK available from: http://developer.novell.com/ndk/clib.htm 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; Android ======= 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 CROSS COMPILE ============= (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-7.12.3) 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. (begin script) #! /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 (end script) 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 PORTS ===== 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 Useful URLs =========== c-ares http://c-ares.haxx.se/ MingW http://www.mingw.org/ MinGW-w64 http://mingw-w64.sourceforge.net/ OpenWatcom http://www.openwatcom.org/