Chiebot-Mirror
/
c-ares
mirror of https://github.com/c-ares/c-ares.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Re-organize sections in INSTALL.md and add CMake section

Browse Source
pull/182/head
Brad House 7 years ago
parent a600f58a94
commit f80caf4be2
1 changed files with 214 additions and 143 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 357
      INSTALL.md

357
INSTALL.md
Unescape View File

@ -24,12 +24,15 @@ 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 release tarball, see the [GIT-INFO](GIT-INFO) file in the root directory
for specific instructions on how to proceed. for specific instructions on how to proceed.
In particular, you will need to run `./buildconf` (Unix) or In particular, if not using CMake you will need to run `./buildconf` (Unix) or
`buildconf.bat` (Windows) to generate build files, and for the former `buildconf.bat` (Windows) to generate build files, and for the former
you will need a local installation of Autotools. you will need a local installation of Autotools. If using CMake the steps are
the same for both Git and official release tarballs.
Unix AutoTools Build
==== ===============
### General Information, works on most Unix Platforms (Linux, FreeBSD, etc)
A normal Unix installation is made in three or four steps (after you've A normal Unix installation is made in three or four steps (after you've
unpacked the source archive): unpacked the source archive):
@ -61,8 +64,7 @@ install in your own home directory:
make make
make install make install
More Options ### More Options
------------
To force configure to use the standard cc compiler if both cc and gcc are To force configure to use the standard cc compiler if both cc and gcc are
present, run configure like present, run configure like
@ -79,8 +81,8 @@ by running configure like:
If you're a c-ares developer and use gcc, you might want to enable more If you're a c-ares developer and use gcc, you might want to enable more
debug options with the `--enable-debug` option. debug options with the `--enable-debug` option.
Special Cases ### Special Cases
-------------
Some versions of uClibc require configuring with `CPPFLAGS=-D_GNU_SOURCE=1` Some versions of uClibc require configuring with `CPPFLAGS=-D_GNU_SOURCE=1`
to get correct large file support. to get correct large file support.
@ -90,44 +92,53 @@ The Open Watcom C compiler on Linux requires configuring with the variables:
RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra RANLIB=/bin/true STRIP="$WATCOM/binl/wstrip" CFLAGS=-Wextra
Win32 ### CROSS COMPILE
=====
Building Windows DLLs and C run-time (CRT) linkage issues (This section was graciously brought to us by Jim Duey, with additions by
--------------------------------------------------------- Dan Fandrich)
As a general rule, building a DLL with static CRT linkage is highly Download and unpack the c-ares package.
discouraged, and intermixing CRTs in the same app is something to
avoid at any cost.
Reading and comprehension of Microsoft Knowledge Base articles `cd` to the new directory. (e.g. `cd c-ares-1.7.6`)
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 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.
- [KB140584](http://support.microsoft.com/kb/140584/en-us) - How to link with the correct C Run-Time (CRT) library ```sh
#! /bin/sh
- [KB190799](http://msdn.microsoft.com/en-us/library/ms235460) - Potential Errors Passing CRT Objects Across DLL Boundaries 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
If your app is misbehaving in some strange way, or it is suffering ./configure --target=powerpc-hardhat-linux \
from memory corruption, before asking for further help, please try --host=powerpc-hardhat-linux \
first to rebuild every single library your app uses as well as your --build=i586-pc-linux-gnu \
app using the debug multithreaded dynamic C runtime. --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \
--exec-prefix=/usr/local
```
MingW32 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.
Make sure that MinGW32's bin dir is in the search path, for example: In some cases, you may be able to simplify the above commands to as
little as:
set PATH=c:\mingw32\bin;%PATH% ./configure --host=ARCH-OS
then run 'make -f Makefile.m32' in the root dir.
Cygwin ### Cygwin (Windows)
------
Almost identical to the unix installation. Run the configure script in the 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 c-ares root with `sh configure`. Make sure you have the sh executable in
@ -135,60 +146,8 @@ c-ares root with `sh configure`. Make sure you have the sh executable in
Run `make` 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 ### QNX
----------------------
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) (This section was graciously brought to us by David Bentham)
@ -204,8 +163,7 @@ c-ares, by overriding `CFLAGS` during configure, example:
# configure CFLAGS='-DFD_SETSIZE=64 -g -O2' # configure CFLAGS='-DFD_SETSIZE=64 -g -O2'
RISC OS ### RISC OS
=======
The library can be cross-compiled using gccsdk as follows: The library can be cross-compiled using gccsdk as follows:
@ -217,27 +175,7 @@ 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`. You can then link your program with `c-ares/lib/.libs/libcares.a`.
NetWare ### Android
=======
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): Method using a configure cross-compile (tested with Android NDK r7b):
@ -272,51 +210,183 @@ Method using a configure cross-compile (tested with Android NDK r7b):
`find /usr -name config.sub` `find /usr -name config.sub`
CROSS COMPILE CMake builds
============= ============
(This section was graciously brought to us by Jim Duey, with additions by Current releases of c-ares introduce a CMake v3+ build system that has been
Dan Fandrich) tested on most platforms including Windows, Linux, FreeBSD, MacOS, AIX and
Solaris.
Download and unpack the c-ares package. In the most basic form, building with CMake might look like:
`cd` to the new directory. (e.g. `cd c-ares-1.7.6`) ```sh
cd /path/to/cmake/source
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/cares ..
make
sudo make install
```
Set environment variables to point to the cross-compile toolchain and call Options
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 Options to CMake are passed on the command line using "-D${OPTION}=${VALUE}".
toolchain from MonteVista for Hardhat Linux. The values defined are all boolean and take values like On, Off, True, False.
* CARES_STATIC - Build the static library (off by default)
* CARES_SHARED - Build the shared library (on by default)
* CARES_INSTALL - Hook in installation, useful to disable if chain building
* CARES_STATIC_PIC - Build the static library as position-independent (off by
default)
Ninja
-----
Ninja is the next-generation build system meant for generators like CMake that
heavily parallize builds. Its use is very similar to the normal build:
```sh ```sh
#! /bin/sh cd /path/to/cmake/source
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/cares -G "Ninja" ..
ninja
sudo ninja install
```
export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin Windows MSVC Command Line
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 \ cd \path\to\cmake\source
--build=i586-pc-linux-gnu \ mkdir build
--prefix=/opt/hardhat/devkit/ppc/405/target/usr/local \ cd build
--exec-prefix=/usr/local cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=C:\cares -G "NMake Makefiles" ..
nmake
nmake install
``` ```
You may also need to provide a parameter like `--with-random=/dev/urandom` Windows MinGW-w64 Command Line via MSYS
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 cd \path\to\cmake\source
successfully, do `make` and `make install` as usual. mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=C:\cares -G "MSYS Makefiles" ..
make
make install
```
In some cases, you may be able to simplify the above commands to as
little as:
./configure --host=ARCH-OS Platform-specific build systems
===============================
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.
### 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`.
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;
PORTS PORTS
@ -335,6 +405,7 @@ runs on, that isn't listed, please let us know!
- i386 Windows 95, 98, ME, NT, 2000, XP, 2003 - i386 Windows 95, 98, ME, NT, 2000, XP, 2003
- x86_64 Linux - x86_64 Linux
Useful URLs Useful URLs
=========== ===========

Write Preview
Loading…
Cancel
Save