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.


CROSS-COMPILING
---------------

Cross compiling is building code on one machine to be run on another,
particularly when the two machines are different enough that it matters,
e.g. one executes x86 instructions and the other executes PowerPC
instructions.

The machine that will run the code is called the target machine.  The one
that will build the code is the build machine.

To cross-compile, you set up nearly all of the build environment for the
target machine (that includes such things as the default include file search
path for the compiler and library search path for the linker).  On your
'configure' command, you use a --host option to identify the kind of target
machine (rather than let it default to the kind of machine on which
'configure' is running).  It's a nontrivial task, and beyond the scope of
this document as it is not specific to Xmlrpc-c.

There is one area that requires special attention and is specific to Xmlrpc-c:
The Xmlrpc-c build does part of its job by compiling a program from C source
code and running that program as part of the build.  That compile, unlike all
the regular ones, must be done for the build machine, not the target
machine.

To facilitate that, there are the BUILDTOOL_CC and BUILDTOOL_CCLD make
variables.  BUILDTOOL_CC is the command name for the appropriate compiler
which which to build a build tool, i.e. a compiler that generates code to run
on the build system.  BUILDTOOL_CCLD is similarly for the linker, and should
be the kind of linker command that invokes a combined compiler/linker,
e.g. "gcc" instead of "ld".

You can set these make variables on the Make command line, or if you prefer,
by modifying the file 'config.mk' after 'configure' creates it.  The default
value of these variables (as set in 'config.mk') is the same compile and link
commands as for building target code.

(There is probably a way to do this with GNU Autoconf facilities and avoid the
BUILDTOOL_CC complication.  If you know how (without using Automake), tell the
Xmlrpc-c maintainer and he will change the build system to use it).


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 they do 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.