freeswitch/libs/xmlrpc-c/doc/INSTALL

These are instructions for building Xmlrpc-c from source and installing
it on a system.

See the README file for information on prerequisites (things you need to 
have installed before you can build).


Essentially, it's just the conventional

  $ ./configure
  $ make
  $ make install

To build handy tools such as the 'xmlrpc' command line XML-RPC client:

  $ cd tools
  $ make
  $ make install

You can also do

  $ make check

to run a battery of tests before you install.  But note that it's as common
for the tests to fail because the tests are broken as because the product
is broken, so consider the results carefully.

To see it work, build and run a simple server like this:

  $ cd examples
  $ make
  $ ./xmlrpc_sample_add_server 8080

That runs forever, serving clients as they arrive.  Now, from another
shell, run a client that does an RPC to this server:

  $ ./xmlrpc_sample_add_client

Also try other example servers and clients, described in examples/README.


You may want to pass a '--prefix' argument to 'configure'.  See
'./configure --help' for details.

You may also want to disable client XML transports that you won't be
using.  In particular, the Libwww transport can be inconvenient, because
it typically uses about 20 shared libraries.  Any XML-RPC client
program that uses Xmlrpc-c, whether or not the program uses any of the
libwww facilities, must attach all those libraries, and that can take
a significant amount of time.

See './configure --help' for the options that disable certain transports.


SEPARATE BUILD TREE
-------------------

While it's traditional to build a Unix package by adding object files
to the same tree with the source files, it's actually much cleaner to
keep your source tree exactly as you got it and put the built files in
a separate directory, called the build tree.

To do this, just create an empty directory and run 'configure' in it,
then 'make':

  mkdir xmlrpcbuild
  cd xmlrpcbuild
  /usr/src/xmlrpc-c/configure
  ...
  make

But if you plan to work on Xmlrpc-c source code, you'll probably find
it more convenient to build the traditional way, with a single tree
for source and build.

In the source tree, you can type 'make' in any directory to do the
default make for that directory, or make FILENAME to make the file of
that name there.  In the separate build tree, there are special
facilities to allow you to do a simple make from the _top level
directory_, but if you want to make a subcomponent or individual part,
you have to have a -f option and set SRCDIR and BLDDIR on your 'make'
command.


COMMON PROBLEMS
---------------

Improper -config files
----------------------

The most common problem building Xmlrpc-c is one of improperly installed
prerequisite libraries, namely Libwww and Curl.  These libraries are
designed to be installed along with a -config program (libwww-config
and curl-config) that tells builders of dependent packages (such as
Xmlrpc-c) how to use them.  When the -config program is wrong, you get
Xmlrpc-c build failures with messages about undefined references.

The exact nature of the problems with -config programs can be quite
involved, especially since there is no guarantee that a -config
program can do what's required of it in every situation.  But I'll
explain the basic problem.  For simplicity, I'll talk specifically
about Curl, but the principles apply to any library that has a -config
program.

The point of curl-config is to describe how Curl is installed on your
particular system.  You have choices of where to install the various parts
and what prerequisites to build into them, and curl-config is how you
communicate those choices to the Xmlrpc-c make files.

Curl's builder automatically creates a curl-config program for you,
but you should not think of it as part of Curl.  It's really a
configuration file -- something that tells how your particular system
is put together.  The Curl builder is not smart enough to know exactly
what to put in curl-config; it just builds one that works for most
people.  The local system administrator is actually responsible for
the contents of curl-config.

One rather complex way in which the curl-config that the Curl builder
builds can be wrong is that it often indicates that to link to the
Curl library, you need a "-L /usr/lib" option (or something like that
-- an option that adds to the linker's search path a directory that is
already in it).  This is usually unnecessary because the directory is
already in the search path, and often breaks things because it puts
the directory too early in the search path.  If your curl-config says to
link with -L /usr/lib, you should normally edit it to remove that.

As an example of how -L /usr/lib breaks things, here is a problem that
is often reported: The user has Xmlrpc-c installed on his system, but
wants to build a new one to replace it, or to use for a particular
project instead of the system version.  But the build of the new
version fails with undefined references to symbol "xmlrpc_foo".
xmlrpc_foo is a new symbol - it was added to Xmlrpc-c in a recent
release.  The version of Xmlrpc-c installed on the system is too old
to have it.  The make file obviously specifies the path to the current
libraries that the user just built in the link library search order,
but the link is picking up the old system version instead.  Why?
Because the link options say to search /usr/lib _before_ the local
build directory.  And it does that because curl-config erroneously
says that you need a -L /usr/lib link option to find the Curl library.


WINDOWS
-------

All of the above is essentially for Unix-type operating systems.  To
build and use Xmlrpc-c on Windows, see the file
Windows/ReadMeWin32.txt.