diff options
Diffstat (limited to 'src/c-ares/INSTALL.md')
| -rw-r--r-- | src/c-ares/INSTALL.md | 344 |
1 files changed, 344 insertions, 0 deletions
diff --git a/src/c-ares/INSTALL.md b/src/c-ares/INSTALL.md new file mode 100644 index 000000000..9595472d6 --- /dev/null +++ b/src/c-ares/INSTALL.md @@ -0,0 +1,344 @@ +** 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 rather than an official +release tarball, see the [GIT-INFO](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. + +Unix +==== + +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](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](http://support.microsoft.com/kb/94248/en-us) - How To Use the C Run-Time + + - [KB140584](http://support.microsoft.com/kb/140584/en-us) - How to link with the correct C Run-Time (CRT) library + + - [KB190799](http://msdn.microsoft.com/en-us/library/ms235460) - 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. + +MingW32 +------- + +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. + +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` + +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](README.msvc) + +MSVC IDEs +--------- + +Details in [README.msvc](README.msvc) + +Important static c-ares usage note +---------------------------------- + +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. + + +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-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. + +```sh +#! /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 + + +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: https://c-ares.haxx.se/ + - MingW: http://www.mingw.org/ + - MinGW-w64: http://mingw-w64.sourceforge.net/ + - OpenWatcom: http://www.openwatcom.org/ |