INTERNALS: cat lib/README* >> INTERNALS

###########################################################################

AUTOMAKE_OPTIONS = foreign nostdinc

DOCS = README.encoding README.memoryleak README.ares README.curlx	\

 README.hostip README.multi_socket README.httpauth README.curl_off_t

CMAKE_DIST = CMakeLists.txt curl_config.h.cmake

EXTRA_DIST = Makefile.b32 Makefile.m32 Makefile.vc6 config-win32.h	\

 makefile.dj config-dos.h libcurl.plist libcurl.rc config-amigaos.h	\

 makefile.amiga Makefile.netware nwlib.c nwos.c config-win32ce.h	\

 config-os400.h setup-os400.h config-symbian.h Makefile.Watcom		\

 config-tpf.h $(DOCS) mk-ca-bundle.pl mk-ca-bundle.vbs $(CMAKE_DIST)	\

 config-tpf.h mk-ca-bundle.pl mk-ca-bundle.vbs $(CMAKE_DIST)	\

 firefox-db2pem.sh config-vxworks.h Makefile.vxworks checksrc.pl	\

 objnames-test08.sh objnames-test10.sh objnames.inc checksrc.whitelist

                                  _   _ ____  _

                              ___| | | |  _ \| |

                             / __| | | | |_) | |

                            | (__| |_| |  _ <| |___

                             \___|\___/|_| \_\_____|

          How To Build libcurl to Use c-ares For Asynch Name Resolves

          ===========================================================

c-ares:

  http://c-ares.haxx.se/

NOTE

  The latest libcurl version requires c-ares 1.6.0 or later.

  Once upon the time libcurl built fine with the "original" ares. That is no

  longer true. You need to use c-ares.

Build c-ares

============

1. unpack the c-ares archive

2. cd c-ares-dir

3. ./configure

4. make

5. make install

Build libcurl to use c-ares in the curl source tree

===================================================

1. name or symlink the c-ares source directory 'ares' in the curl source

   directory

2. ./configure --enable-ares

  Optionally, you can point out the c-ares install tree root with the the

  --enable-ares option.

3. make

Build libcurl to use an installed c-ares

========================================

1. ./configure --enable-ares=/path/to/ares/install

2. make

c-ares on win32

===============

(description brought by Dominick Meglio)

First I compiled c-ares. I changed the default C runtime library to be the

single-threaded rather than the multi-threaded (this seems to be required to

prevent linking errors later on). Then I simply build the areslib project (the

other projects adig/ahost seem to fail under MSVC).

Next was libcurl. I opened lib/config-win32.h and I added a:

 #define USE_ARES 1

Next thing I did was I added the path for the ares includes to the include

path, and the libares.lib to the libraries.

Lastly, I also changed libcurl to be single-threaded rather than

multi-threaded, again this was to prevent some duplicate symbol errors. I'm

not sure why I needed to change everything to single-threaded, but when I

didn't I got redefinition errors for several CRT functions (malloc, stricmp,

etc.)

I would have modified the MSVC++ project files, but I only have VC.NET and it

uses a different format than VC6.0 so I didn't want to go and change

everything and remove VC6.0 support from libcurl.

   curl_off_t explained

   ====================

curl_off_t is a data type provided by the external libcurl include headers. It

is the type meant to be used for the curl_easy_setopt() options that end with

LARGE. The type is 64bit large on most modern platforms.

Transition from < 7.19.0 to >= 7.19.0

-------------------------------------

Applications that used libcurl before 7.19.0 that are rebuilt with a libcurl

that is 7.19.0 or later may or may not have to worry about anything of

this. We have made a significant effort to make the transition really seamless

and transparent.

You have have to take notice if you are in one of the following situations:

o Your app is using or will after the transition use a libcurl that is built

  with LFS (large file support) disabled even though your system otherwise

  supports it.

o Your app is using or will after the transition use a libcurl that doesn't

  support LFS at all, but your system and compiler support 64bit data types.

In both these cases, the curl_off_t type will now (after the transition) be

64bit where it previously was 32bit. This will cause a binary incompatibility

that you MAY need to deal with.

Benefits

--------

This new way has several benefits:

o Platforms without LFS support can still use libcurl to do >32 bit file

  transfers and range operations etc as long as they have >32 bit data-types

  supported.

o Applications will no longer easily build with the curl_off_t size

  mismatched, which has been a very frequent (and annoying) problem with

  libcurl <= 7.18.2

Historically

------------

Previously, before 7.19.0, the curl_off_t type would be rather strongly

connected to the size of the system off_t type, where currently curl_off_t is

independent of that.

The strong connection to off_t made it troublesome for application authors

since when they did mistakes, they could get curl_off_t type of different

sizes in the app vs libcurl, and that caused strange effects that were hard to

track and detect by users of libcurl.

SONAME

------

We opted to not bump the soname for the library unconditionally, simply

because soname bumping is causing a lot of grief and moaning all over the

community so we try to keep that at minimum. Also, our selected design path

should be 100% backwards compatible for the vast majority of all libcurl

users.

Enforce SONAME bump

-------------------

If configure doesn't detect your case where a bump is necessary, re-run it

with the --enable-soname-bump command line option!

                                  _   _ ____  _

                              ___| | | |  _ \| |

                             / __| | | | |_) | |

                            | (__| |_| |  _ <| |___

                             \___|\___/|_| \_\_____|

                     Source Code Functions Apps Might Use

                     ====================================

The libcurl source code offers a few functions by source only. They are not

part of the official libcurl API, but the source files might be useful for

others so apps can optionally compile/build with these sources to gain

additional functions.

We provide them through a single header file for easy access for apps:

"curlx.h"

 curlx_strtoofft()

   A macro that converts a string containing a number to a curl_off_t number.

   This might use the curlx_strtoll() function which is provided as source

   code in strtoofft.c. Note that the function is only provided if no

   strtoll() (or equivalent) function exist on your platform. If curl_off_t

   is only a 32 bit number on your platform, this macro uses strtol().

 curlx_tvnow()

   returns a struct timeval for the current time.

 curlx_tvdiff()

   returns the difference between two timeval structs, in number of

   milliseconds.

 curlx_tvdiff_secs()

   returns the same as curlx_tvdiff but with full usec resolution (as a

   double)

FUTURE

======

 Several functions will be removed from the public curl_ name space in a

 future libcurl release. They will then only become available as curlx_

 functions instead. To make the transition easier, we already today provide

 these functions with the curlx_ prefix to allow sources to get built properly

 with the new function names. The functions this concerns are:

      curlx_getenv

      curlx_strequal

      curlx_strnequal

      curlx_mvsnprintf

      curlx_msnprintf

      curlx_maprintf

      curlx_mvaprintf

      curlx_msprintf

      curlx_mprintf

      curlx_mfprintf

      curlx_mvsprintf

      curlx_mvprintf

      curlx_mvfprintf