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

And on Linux systems, you'll usually also need:

  $ ldconfig

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.


LDCONFIG
--------

On systems that use the GNU C Library (usually Linux), you often have to run
the program 'ldconfig' after installing the shared libraries of Xmlrpc-c.  If
you don't, when you try to run a program that uses an Xmlrpc-c library, you
get an error message telling you it can't find the library.

This is because the usual way that the dynamic (shared) library loader finds
libraries is through the file /etc/ld.so.cache, which is a directory of most
of the shared libraries on the system.  'ldconfig' is what updates that
directory.  It searches various places that shared libraries might be,
including the place you probably installed the Xmlrpc-c shared libraries, and
records all their locations, indexed by the library's soname.

If you suspect a problem with your shared library lookup, you can use the
command

  $ ldconfig -p

to list out the directory (i.e. the information in /etc/ld.so.cache).

But this directory is not the only way the OS can find a shared library, so
'ldconfig' may not be required or helpful in your circumstance.  Another way
to tell the OS how to find shared libraries is through the environment
variable LD_LIBRARY_PATH.  If that value includes the directory in which you
installed the Xmlrpc-c libraries, the OS should be able to find them
regardless of what is in the directory.


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, to determine what value
to use for --host.

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 make variables CC_FOR_BUILD,
CFLAGS_FOR_BUILD, and LDFLAGS_FOR_BUILD.

CC_FOR_BUILD is the command name for the appropriate compiler with which to
build a build tool, i.e. a compiler that generates code to run on the build
system.  It is also the command name for the linker, which obviously has to be
the the kind of linker command that invokes a combined compiler/linker,
e.g. "gcc" instead of "ld".

CFLAGS_FOR_BUILD and LD_FLAGS_FOR_BUILD are options for the compile and 
link commands, respectively, used to build build tools.

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') are the same as for building
target code.

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


SKIPPING SHARED LIBRARY BUILD/INSTALL
-------------------------------------

To build just the static libraries, not the shared (dynamically linked)
libraries, set make variable MUST_BUILD_SHLIB to "N":

  $ make MUST_BUILD_SHLIB=N

You can add this setting to the bottom of the 'config.mk' file that
'configure' generates if that is more convenient.

Alternatively, you could just build and install normally and delete the shared
libraries afterward.  That normally works.


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.

