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.