userapps/opensource/net-snmp/PORTING

   1 --- INTRODUCTION
   2
   3 Just a quick note on porting and sending me patches:
   4
   5 First off, you probably should subscribe to
   6 net-snmp-coders@lists.sourceforge.net by sending a message to
   7 net-snmp-coders-request@lists.sourceforge.net with a subject line of
   8 subscribe.  This is a mailing list to discuss all oft the coding
   9 aspects of the project.
  10
  11 Additionally, you should probably be developing against the latest
  12 snapshot of the source code, which can be obtained through the
  13 net-snmp cvs server.  Details can be found at
  14 http://www.net-snmp.org/cvs/.
  15
  16 If you send patches to us, it would greatly help us if you sent them
  17 to us based on the current checked out copy from CVS.  To do this,
  18 send us the output of "cvs diff -u" run in the top level net-snmp
  19 source tree after you have modified the files that will fix the
  20 problem or add the feature you're submitting the patch for.
  21
  22 Quite a while back I started using the GNU autoconf testing suite to
  23 greatly enhance portability.  Because of this porting to new
  24 architectures is much easier than before.  However, new people porting
  25 the package to new architectures rarely take advantage of this setup
  26 and send me patches with lots of '#ifdef ARCH' type C code in it.  Let
  27 me say up front, I *hate* this type of coding now (even though I used
  28 to use it a lot).  What is better is to check for the necissary
  29 functionality using the configure script and then use the results of
  30 those tests.
  31
  32 To do this, you need to install the GNU 'autoconf' package which also
  33 requires the GNU 'm4' (gm4) package as well.  This double installation
  34 is extremely easy and shouldn't take you more than 15 minutes max.
  35 After that, modify the configure.in and acconfig.h files as needed
  36 instead of modifying the config.h or configure files directly.  The
  37 Makefile will re-produce these files from the first two.
  38
  39 Worst case: Don't put in #ifdef architecture style statements.
  40 Rather, create a new define in the s/ and m/ system specific header
  41 files and use those defines to test against in the C code.  This
  42 should only be done for things that can't be checked using configure
  43 though.
  44
  45 Some autoconf examples:
  46
  47 --- HEADER FILES
  48
  49 In configure.in:
  50   AC_CHECK_HEADERS(headdir/header.h)
  51
  52 Then in your source code:
  53   #ifdef HAVE_HEADDIR_HEADER_H
  54     #include <headdir/header.h>
  55   #ENDIF
  56
  57 --- LIBRARY ROUTIENS
  58
  59 In configure.in:
  60   AC_CHECK_LIB(libexample, example_function)
  61
  62 Thats it.  The Makefiles will automatically link against -llibexample
  63 if example_function is found in the library.
  64
  65 --- FUNCTION CHECKS
  66
  67 In configure.in:
  68   AC_CHECK_FUNCS(example_function)
  69
  70 In source code:
  71   #ifdef HAVE_EXAMPLE_FUNCTION
  72     /* use it */
  73   #endif
  74
  75 --- STRUCTURE MEMBER CHECKS
  76
  77 In configure.in:
  78   AC_CHECK_STRUCT_FOR([
  79 #include lines
  80 ], STRUCTURE, MEMBER)
  81    ^^^^^^^^^  ^^^^^^  (change)
  82
  83 In acconfig.h:
  84   #undef STRUCT_STRUCTURE_HAS_MEMBER
  85                 ^^^^^^^^^     ^^^^^^  (change)
  86
  87 In source code:
  88   #ifdef STRUCT_STRUCTURE_HAS_MEMBER
  89     /* use it */
  90   #endif
  91
  92 --- READ THE MANUAL
  93
  94 The GNU autoconf info files are extremely well written and easy to
  95 follow.  Please check them out.
  96
  97 I'd be happy to help you through anything you don't understand or
  98 through more complex examples (eg, checking for structure parts or
  99 existance).  I'd be far less happy to get patches ignoring the above
 100 request.  If you simple can't abide by this, please send the patches
 101 anyway, but it'll just take me longer to get them applied.
 102
 103 Submit the patch to http://www.net-snmp.org/patches/.
 104 Please include what version of the net-snmp package it was applied to
 105 and state the arcitectures you have tested it on.
 106
 107 Thanks a lot for the consideration,
 108 Wes