HOW-TO-CONTRIBUTE

   1 So, you have a utility that you believe would
   2 be a good addition to cygutils, do you?  You
   3 probably want to know how you could contribute it,
   4 don't you?  Well, first:
   5
   6   Not every spiffy utility belongs in cygutils. We
   7   don't want cygutils to become a huge grab bag of
   8   hundreds of small programs...in many cases, your
   9   spiffy new program should become a standalone package
  10   and a full-fledged member of the cygwin distribution.
  11   (Don't worry -- that's not hard.  It's probably
  12   easier than integrating your spiffy program into
  13   cygutils).
  14
  15   So, your first step is to post a message to the
  16   cygwin-apps mailing list, present your program, and
  17   ASK if it should be included in cygutils, or turned
  18   into a standalong package.  If you believe it should
  19   become part of cygutils, explain why.  I will not
  20   add any program to cygutils without a consensus
  21   from the cygwin-apps list.
  22
  23   In the body of your email, describe what your program
  24   does, why it's needed, and why you think it should be
  25   added to the cygutils package.  Also explain why (or
  26   state that) existing tools will not meet the need your
  27   program does.
  28
  29 Second, once you're obtained agreement that yourfile.c
  30 should be added to cygutils:
  31
  32   Don't just send me yourfile.c and expect me to
  33   do all the integration work.
  34
  35 You need to do more than merely insure that it builds
  36 on your machine with a simple
  37
  38   gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary
  39
  40 In addition to that, you need to check out the cygutils
  41 source and integrate yourfile into the whole system.  Instructions
  42 follow below.  However, you'll notice that it's quite a bit
  43 of work.  Again, are you SURE you want it to become part
  44 of cygutils?  Making a standalone program is a lot easier...
  45
  46 Also, note that I will not fix your bugs.  If, at some time
  47 after your program is accepted into cygutils, I (as cygutils
  48 maintainer) get a bug report on your program, I will forward
  49 it to you.  If you don't fix it or respond within a reasonable
  50 time, I will remove it from the distribution.
  51
  52 ------------------------------------------------------
  53
  54 Okay, now that we're past that unpleasantness, here's how to
  55 integrate your spiffy new utility.  First, let's assume that
  56 your spiffy utility is called 'foo', and its source is in 'foo.c'.
  57
  58 The simple 12 step program:
  59 ---------------------------
  60
  61 1) Get the cygutils source
  62
  63    cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps login
  64       use 'anoncvs' as the password
  65    cvs -z3 -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps co cygutils
  66
  67    you now have a 'cygutils' directory with the existing source.
  68
  69 2) License information
  70
  71    make sure that all .c and .h files in your contribution
  72    have license information: preferably GPL, but other
  73    open licenses are acceptable, too.  See the top of
  74    src/lpr/lpr.c for an example.
  75
  76    a) if your license is not GPL or BSD-no-advert, then
  77       you must also include a copy of the ENTIRE license
  78       in the licenses subdirectory.  (Most of the time,
  79       the blurb in the .c or .h file is just that: a short
  80       blurb, with a reference to the full text elsewhere)
  81
  82 3) Make a home
  83
  84    create a new directory for your contribution underneath 'src'
  85    In our case, we will do this:
  86      cd cygutils/src
  87      mkdir foo
  88
  89    copy your source into the new directory
  90      cp <location>/foo.c <cygutils>/src/foo/
  91
  92 4) Modify your source code
  93
  94    Add the following snippet to the beginning of your .c and .h(*)
  95    files, just after the license information:
  96
  97      #if HAVE_CONFIG_H
  98      #include "config.h"
  99      #endif
 100      #include "common.h"
 101
 102    a) If your contribution has its own .h file(s), the entire .h file
 103       should be "guarded" as follows:
 104
 105         /* license information */
 106         #ifndef _FOO_H
 107         #define _FOO_H
 108         /* the config.h/common.h stuff */
 109         /* your header stuff */
 110         #endif /* !_FOO_H */
 111
 112       the "_FOO_H" identifier should be changed to match the filename
 113       of your header file.  Thus, "bob.h" would be guarded with _BOB_H.
 114
 115       Naturally, the header files should also be copied into src/foo/.
 116
 117 5) Modify cygutils/Makefile.am
 118
 119   a) Add your program to the list of progs to be built.  If your
 120      program will build on non-windows platforms in addition to cygwin,
 121      then you can add your program to the "bin_PROGRAMS" variable:
 122
 123      bin_PROGRAMS = ... src/foo/foo ...
 124
 125      If your contribution is windows-specific, then you should add it
 126      to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables:
 127
 128      windows_progs = ... src/foo/foo ...
 129      EXTRA_PROGRAMS = ... src/foo/foo ...
 130
 131   b) Special link libraries
 132
 133      If you need to link to special *WINDOWS* libraries, then obviously
 134      your program is windows-specific, but also you should add a line
 135      in your Makefile.am like this:
 136
 137      src_foo_foo_LDADD = -lwinlib
 138
 139      Where "src_foo_foo" is the path to your program, where the '/'
 140      characters are replaced with '_' characters.  Yes, it looks a little
 141      funny -- but because our subdirectory has the same name as our
 142      program, we get double foo's...  Also, 'winlib' is the library
 143      that you need.  See the src_lpr_lpr_LDADD variable in Makefile.am
 144      for an example.
 145
 146      If, on the other hand, you need to link to some other (cygwin)
 147      library that is also more generally available -- like libreadline
 148      or libncurses -- then you'll need to do a little more work.
 149      For your initial submission, just create an LDADD variable in
 150      Makefile.am with -lreadline (or whatever).  We'll figure out how
 151      to handle it better further down the road.  However, make sure
 152      to let me know about your special link requirements.
 153
 154      src_foo_foo_LDADD = -lreadline
 155
 156      One special case is the gettext internationalization libraries.
 157      If your program must link with -lintl, then all you need to
 158      do is create an LDADD variable as follows:
 159
 160      src_foo_foo_LDADD = @LIBINTL@
 161
 162      The configuration process will replace @LIBINTL@ with the
 163      appropriate -lintl -liconv invocation.
 164
 165      Note that you do NOT need to include the following libraries in
 166      a 'src_foo_foo_LDADD' line; these will be added automatically...
 167
 168      -lcygipc -lpopt  (that is, cygipc or popt)
 169
 170   c) man pages and other documentation
 171
 172      If you got 'em, copy 'em to your src/foo directory, and add the
 173      manpage to the man_MANS variable in Makefile.am like this:
 174
 175      man_MANS = ... src/foo/foo.1 ...
 176
 177      If there are non-man-page documentation files, you should those
 178      files to the EXTRA_DIST variable:
 179
 180      EXTRA_DIST = ... src/foo/foo.README ...
 181
 182      However, there is no provisiion for actually INSTALLING these
 183      additional documentation files.  At least not yet.
 184
 185   d) Extra files
 186
 187      If your contribution consists of more source files than a single
 188      .c, then you need to add a variable to Makefile.am that lists all
 189      of them:
 190
 191      src_foo_foo_SOURCES = foo.c otherfoo.c foo.h
 192
 193      Note that this variable should NOT be specified if your program
 194      consists merely of a single .c file whose name is the same as
 195      your program + '.c'.
 196
 197      If there are .h files in your SOURCES list, then you need to
 198      add those .h files to the noinst_HEADERS variable, or the headers
 199      would get installed into /usr/include/src/foo/ -- and we don't
 200      want that!
 201
 202      noinst_HEADERS = ... src/foo/foo.h ...
 203
 204   If you have other questions about the Makefile.am file, try to
 205   follow the "patterns" established in it by the other programs,
 206   or (gasp) read the automake documentation.
 207
 208 6) Simplify your #includes.
 209
 210    Take a good look at the #include statements in your .c and .h
 211    files.  If the dependencies are listed in <cygutils>/common.h,
 212    then you shouldn't re-include them.  If a dependency is NOT
 213    listed in common.h, then leave it in your .h/.c file -- for
 214    now.  We may choose to add them to common.h and add new tests
 215    to configure.ac, or we may choose to let your .c file
 216    include it directly.  However, anything that's already in
 217    common.h, remove from your .c/.h file.  It's okay to just
 218    comment them out, rather than deleting them entirely, if
 219    you prefer.
 220
 221 7) Add information to cygutils documentation files:
 222
 223    Add a short blurb about your app to <cygutils>/PROGLIST
 224    Add your app to the list at the end of the README file
 225    Add your name to the AUTHORS file.
 226
 227 8) Bootstrap
 228
 229    (You need to have autoconf, autoconf-devel, automake, and
 230    automake-devel installed for this to work).  Change dir
 231    to the top of your checked-out source, and run bootstrap:
 232
 233    cd <cygutils>
 234    ./bootstrap
 235
 236    If you haven't made any mistakes, you should (a) see no
 237    errors, and (b) see some new rules in Makefile.in that
 238    correspond to your program.
 239
 240 9) Build and test
 241
 242    Now, just run './configure ; make' as usual.  Somewhere
 243    amongst the flurry of messages, you should see your application
 244    being built.  If so, you're almost done.  If not, then you
 245    need to figure out why.  Time to read the auto* documentation...
 246
 247 10) Create a patch and ChangeLog entry
 248
 249    a) PATCH
 250
 251       cd <cygutils>
 252       cvs diff -u > foo.patch
 253
 254       If you've already edited the ChangeLog file, make sure to
 255       *remove* that chunk from foo.patch.  I don't want a PATCH
 256       for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
 257       patches rarely apply cleanly; it's easier to cut-n-paste.  More
 258       below).
 259
 260    b) NEW FILES
 261
 262       However, you'll notice that none of the files in your src/foo
 263       directory are represented in the patch.  That's normal.  Remove
 264       any .o and .exe files from src/foo, and then just make a tarball
 265
 266       cd <cygutils>
 267       tar cvjf foo.tar.bz2 src/foo
 268
 269    c) CHANGELOG
 270
 271       You should also create a ChangeLog entry.  Don't actually edit
 272       the ChangeLog itself; create a new file (foo.changelog?) and
 273       put your stuff there.  It should look like this:
 274
 275       2002-03-02  Your Name  <your_email_address@domain.com>
 276
 277          * src/foo: new directory
 278          * src/foo/foo.c: new file
 279          * Makefile.am: add program 'foo'
 280          * Makefile.in: regenerate
 281          * AUTHORS: add yourname for foo
 282          * PROGLIST: add foo
 283          * README: add foo
 284
 285       Don't list src/foo/Makefile.  Do list every original
 286       file in src/foo/ (like your man pages, or extra documentation
 287       files, or headers)
 288
 289 11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I
 290    finished the integration work neceesary to include 'foo' in the
 291    'cygutils' package, as previously agreed on this list."  Paste
 292    the ChangeLog into that notice.  But do NOT send the patch or
 293    tarball to the mailing list.
 294
 295    Instead, send that to ME, cwilson@ece.gatech.edu.  The patch
 296    and tarball should be attachments, but paste the ChangeLog entry
 297         into the body of the message.  Do NOT paste your patch into the
 298         body of the email; most mail programs will horrendously distort
 299    it if you do).  Also, be sure and warn of any special link
 300    requirements (cf. section 5a and 5b above).
 301
 302 12) Bask in the glow of a job well done.
 303
 304 --
 305 Chuck Wilson
 306 cygutils maintainer
 307
 308 Note to self: how to commit contributions:
 309   apply the patch
 310   untar the contribution
 311   Add the Changelog entry
 312   ./bootstrap
 313   cvs add src/directory
 314   cvs add src/directory/srcfiles
 315   cvs commit -m "Add foo contribution"
 316   ./bootstrap
 317   cvs diff | grep Index > foo
 318   >>> use 'foo' to add another Changelog entry
 319   cvs commit -m "Add foo contribution"
 320   cvs tag something
 321