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

   1 Here are some notes to help you develop code for Xmlrpc-c.  I include
   2 as "developing" debugging to figure out why Xmlrpc-c doesn't work for
   3 you.
   4
   5 CODE LIBRARY
   6 ------------
   7
   8 The master Xmlrpc-c source code tree is the CVS repository on
   9 Sourceforge.  Anybody can read it; only the maintainer can commit to
  10 it.  If you're not the maintainer, simply use a 'cvs diff' command in
  11 your CVS working directory to create a patch file that embodies your
  12 changes and email that to the maintainer.  He can easily apply that
  13 patch to his own CVS working directory and then commit the changes.
  14
  15
  16 MAKE VARIABLES
  17 --------------
  18
  19 You can pass make variable values to GNU Make to change the build.
  20 There are two common ways to do this:
  21
  22   1) Like this:
  23
  24      $ make MYVAR=myvalue
  25
  26   2) Via an environment variable, like this:
  27
  28      $ MYVAR=myvalue make
  29
  30      or
  31
  32      $ export MYVAR=myvalue
  33      $ make
  34
  35 See GNU Make and shell documentation for details.
  36
  37 In Xmlrpc-c make files, there are two make variables that add
  38 arbitrary options to every compile command: CADD and CFLAGS_PERSONAL.
  39
  40 They both do the same thing.  CADD is meant to be set on an individual
  41 make command, whereas CFLAGS_PERSONAL is meant to be a long-lived
  42 environment variable.  CFLAGS_PERSONAL is for flags you like on all
  43 your compiles, but maybe others don't.
  44
  45 One of my favorite CADD settings is CADD=--save-temps.  To the GNU
  46 Compiler, --save-temps means to create, in addition to the object
  47 code, a file containing the intermediate preprocessed C code and a
  48 file containing the intermediate assembler source code.  I can use
  49 that to debug certain things.
  50
  51 The Xmlrpc-c build uses -g by default with Gcc, so you don't need to
  52 use CADD to get debugging symbols in your object code.
  53
  54
  55 There's also LADD for linker options.
  56
  57
  58 CODE STYLE
  59 ----------
  60
  61 The maintainer is pretty particular about coding style, but doesn't
  62 require anyone to submit code in any particular style.  He changes
  63 what he thinks isn't maintainable enough as submitted.  You could do
  64 him a big favor, though, and reduce the chance of him introducing bugs
  65 into your code, but trying to copy the style you see in existing code.
  66 The major theme is high level programming -- closer to English prose
  67 and further from machine instructions.
  68
  69 Probably the most important thing is not to use tabs.  Tabs are
  70 actually quite common in Unix C programming, but apart from tradition,
  71 they are a bad idea.  They don't look the same to everyone.  A person
  72 must suffer an additional configuration step -- setting up tab stops
  73 in order to see the code the right way.  Spaces, on the other hand,
  74 look the same to everyone.  Very old editors made it easier to compose
  75 with tabs than with spaces, but with modern ones, there is no
  76 difference.
  77
  78 The maintainer tries to catch all tabs in code submitted to him and
  79 convert them to spaces, but this often leaves the code incorrectly
  80 indented.  Better to give him code that already has the right number
  81 of spaces explicitly.
  82