git.maemo.org Git - xmlrpc-c/blob - doc/INSTALL

   1 These are instructions for building Xmlrpc-c from source and installing
   2 it on a system.
   3
   4 See the README file for information on prerequisites (things you need to
   5 have installed before you can build).
   6
   7
   8 Essentially, it's just the conventional
   9
  10   $ ./configure
  11   $ make
  12   $ make install
  13
  14 You can also do
  15
  16   $ make check
  17
  18 to run a battery of tests before you install.  But note that it's as common
  19 for the tests to fail because the tests are broken as because the product
  20 is broken, so consider the results carefully.
  21
  22 To see it work, run a simple server like this:
  23
  24   $ examples/xmlrpc_sample_add_server 8080
  25
  26 Then run a client that does an RPC to this server:
  27
  28   $ examples/xmlrpc_sample_add_client
  29
  30 (I don't mean to imply that the above are consecutive shell commands;
  31 They can't be, because the server program runs indefinitely).
  32
  33 Also try other sample servers and clients, described in examples/README.
  34
  35
  36 You may want to pass a '--prefix' argument to 'configure'.  See
  37 './configure --help' for details.
  38
  39 You may also want to disable client XML transports that you won't be
  40 using.  In particular, the Libwww transport can be inconvenient, because
  41 it typically uses about 20 shared libraries.  Any XML-RPC client
  42 program that uses Xmlrpc-c, whether or not the program uses any of the
  43 libwww facilities, must attach all those libraries, and that can take
  44 a significant amount of time.
  45
  46 See './configure --help' for the options that disable certain transports.
  47
  48
  49 COMMON PROBLEMS
  50 ---------------
  51
  52 Improper -config files
  53 ----------------------
  54
  55 The most common problem building Xmlrpc-c is one of improperly installed
  56 prerequisite libraries, namely Libwww and Curl.  These libraries are
  57 designed to be installed along with a -config program (libwww-config
  58 and curl-config) that tells builders of dependent packages (such as
  59 Xmlrpc-c) how to use them.  When the -config program is wrong, you get
  60 Xmlrpc-c build failures with messages about undefined references.
  61
  62 The exact nature of the problems with -config programs can be quite
  63 involved, especially since there is no guarantee that a -config
  64 program can do what's required of it in every situation.  But I'll
  65 explain the basic problem.  For simplicity, I'll talk specifically
  66 about Curl, but the principles apply to any library that has a -config
  67 program.
  68
  69 The point of curl-config is to describe how Curl is installed on your
  70 particular system.  You have choices of where to install the various parts
  71 and what prerequisites to build into them, and curl-config is how you
  72 communicate those choices to the Xmlrpc-c make files.
  73
  74 Curl's builder automatically creates a curl-config program for you,
  75 but you should not think of it as part of Curl.  It's really a
  76 configuration file -- something that tells how your particular system
  77 is put together.  The Curl builder is not smart enough to know exactly
  78 what to put in curl-config; it just builds one that works for most
  79 people.  The local system administrator is actually responsible for
  80 the contents of curl-config.
  81
  82 One rather complex way in which the curl-config that the Curl builder
  83 builds can be wrong is that it often indicates that to link to the
  84 Curl library, you need a "-L /usr/lib" option (or something like that
  85 -- an option that adds to the linker's search path a directory that is
  86 already in it).  This is usually unnecessary because the directory is
  87 already in the search path, and often breaks things because it puts
  88 the directory too early in the search path.  If your curl-config says to
  89 link with -L /usr/lib, you should normally edit it to remove that.
  90
  91 As an example of how -L /usr/lib breaks things, here is a problem that
  92 is often reported: The user has Xmlrpc-c installed on his system, but
  93 wants to build a new one to replace it, or to use for a particular
  94 project instead of the system version.  But the build of the new
  95 version fails with undefined references to symbol "xmlrpc_foo".
  96 xmlrpc_foo is a new symbol - it was added to Xmlrpc-c in a recent
  97 release.  The version of Xmlrpc-c installed on the system is too old
  98 to have it.  The make file obviously specifies the path to the current
  99 libraries that the user just built in the link library search order,
 100 but the link is picking up the old system version instead.  Why?
 101 Because the link options say to search /usr/lib _before_ the local
 102 build directory.  And it does that because curl-config erroneously
 103 says that you need a -L /usr/lib link option to find the Curl library.
 104
 105 64 Bit Linux -fPIC
 106 ------------------
 107
 108 The GNU link-editor produces this error message when building the C++
 109 libraries for certain 64 bit machines:
 110
 111   relocation R_X86_64_32 against `a local symbol' can not be used when
 112   making a shared object; recompile with -fPIC
 113
 114 Xmlrpc-c 1.06 C++ libraries are not designed for these platforms.
 115 (Releases starting with 1.07 are).
 116
 117 You can work around this by adding a setting of the CADD make variable
 118 to your make command:
 119
 120   make CADD=-fPIC
 121
 122
 123 WINDOWS
 124 -------
 125
 126 All of the above is essentially for Unix-type operating systems.  To
 127 build and use Xmlrpc-c on Windows, see the file
 128 Windows/ReadMeWin32.txt.
 129