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       You should also add it to the licenses variable in
  83       the toplevel Makefile.am: e.g.
  84
  85       licenses = ... licenses/COPYING.MPL ...
  86
  87 3) Make a home
  88
  89    create a new directory for your contribution underneath 'src'
  90    In our case, we will do this:
  91      cd cygutils/src
  92      mkdir foo
  93
  94    copy your source into the new directory
  95      cp <location>/foo.c <cygutils>/src/foo/
  96
  97 4) Modify your source code
  98
  99    Add the following snippet to the beginning of your .c and .h(*)
 100    files, just after the license information:
 101
 102      #if HAVE_CONFIG_H
 103      #include "config.h"
 104      #endif
 105      #include "common.h"
 106
 107    a) If your contribution has its own .h file(s), the entire .h file
 108       should be "guarded" as follows:
 109
 110         /* license information */
 111         #ifndef _FOO_H
 112         #define _FOO_H
 113         /* the config.h/common.h stuff */
 114         /* your header stuff */
 115         #endif /* !_FOO_H */
 116
 117       the "_FOO_H" identifier should be changed to match the filename
 118       of your header file.  Thus, "bob.h" would be guarded with _BOB_H.
 119
 120       Naturally, the header files should also be copied into src/foo/.
 121
 122 5) Modify cygutils/Makefile.am
 123
 124   a) Add your program to the list of progs to be built.  If your
 125      program will build on non-windows platforms in addition to cygwin,
 126      then you can add your program to the "bin_PROGRAMS" variable:
 127
 128      bin_PROGRAMS = ... src/foo/foo ...
 129
 130      If your contribution is windows-specific, then you should add it
 131      to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables:
 132
 133      windows_progs = ... src/foo/foo ...
 134      EXTRA_PROGRAMS = ... src/foo/foo ...
 135
 136   b) Special link libraries
 137
 138      If you need to link to special *WINDOWS* libraries, then obviously
 139      your program is windows-specific, but also you should add a line
 140      in your Makefile.am like this:
 141
 142      src_foo_foo_LDADD = -lwinlib
 143
 144      Where "src_foo_foo" is the path to your program, where the '/'
 145      characters are replaced with '_' characters.  Yes, it looks a little
 146      funny -- but because our subdirectory has the same name as our
 147      program, we get double foo's...  Also, 'winlib' is the library
 148      that you need.  See the src_lpr_lpr_LDADD variable in Makefile.am
 149      for an example.
 150
 151      If, on the other hand, you need to link to some other (cygwin)
 152      library that is also more generally available -- like libreadline
 153      or libncurses -- then you'll need to do a little more work.
 154      For your initial submission, just create an LDADD variable in
 155      Makefile.am with -lreadline (or whatever).  We'll figure out how
 156      to handle it better further down the road.  However, make sure
 157      to let me know about your special link requirements.
 158
 159      src_foo_foo_LDADD = -lreadline
 160
 161      One special case is the gettext internationalization libraries.
 162      If your program must link with -lintl, then all you need to
 163      do is create an LDADD variable as follows:
 164
 165      src_foo_foo_LDADD = @LIBINTL@
 166
 167      The configuration process will replace @LIBINTL@ with the
 168      appropriate -lintl -liconv invocation.
 169
 170      Note that you do NOT need to include the popt library in
 171      a 'src_foo_foo_LDADD' line; -lpopt will be added automatically...
 172
 173      If your app depends on IPC functions, then add @IPCLIBS@
 174      to the 'src_foo_foo_LDADD' line.
 175
 176   c) man pages and other documentation
 177
 178      If you got 'em, copy 'em to your src/foo directory, and add the
 179      manpage to the man_MANS variable in Makefile.am like this:
 180
 181      man_MANS = ... src/foo/foo.1 ...
 182
 183      If there are non-man-page documentation files, you should do
 184      one of the following:
 185        i) if your app is windows-specific, then create a new
 186           variable inside the 'if WITH_WINDOWS_PROGRAMS' section
 187           suffixed with '_docs', and list the documentation files
 188              foo_docs = src/foo/README src/foo/TODO
 189           Also, add those files to the extra_docs variable (which
 190           gets automatically included in EXTRA_DIST)
 191              extra_docs = src/foo/README src/foo/TODO
 192       ii) otherwise, simply create the 'foo_docs' variable
 193           outside of the 'if WITH_WINDOWS_PROGRAMS' section
 194      These files will be installed into $(docdir)/foo/ so there
 195      is no worry that your README will conflict with any other
 196      component's README.
 197
 198   d) Extra files
 199
 200      If your contribution consists of more source files than a single
 201      .c, then you need to add a variable to Makefile.am that lists all
 202      of them:
 203
 204      src_foo_foo_SOURCES = foo.c otherfoo.c foo.h
 205
 206      Note that this variable should NOT be specified if your program
 207      consists merely of a single .c file whose name is the same as
 208      your program + '.c'.
 209
 210      If there are .h files in your SOURCES list, then you need to
 211      add those .h files to the noinst_HEADERS variable, or the headers
 212      would get installed into /usr/include/src/foo/ -- and we don't
 213      want that!
 214
 215      noinst_HEADERS = ... src/foo/foo.h ...
 216
 217   If you have other questions about the Makefile.am file, try to
 218   follow the "patterns" established in it by the other programs,
 219   or (gasp) read the automake documentation.
 220
 221   Libraries are quite complicated to deal with in the cygutils
 222   build framework. Fortunately I doubt there will be many of
 223   these to worry about, other than cygicons.
 224
 225 6) Simplify your #includes.
 226
 227    Take a good look at the #include statements in your .c and .h
 228    files.  If the dependencies are listed in <cygutils>/common.h,
 229    then you shouldn't re-include them.  If a dependency is NOT
 230    listed in common.h, then leave it in your .h/.c file -- for
 231    now.  We may choose to add them to common.h and add new tests
 232    to configure.ac, or we may choose to let your .c file
 233    include it directly.  However, anything that's already in
 234    common.h, remove from your .c/.h file.  It's okay to just
 235    comment them out, rather than deleting them entirely, if
 236    you prefer.
 237
 238 7) Add information to cygutils documentation files:
 239
 240    Add a short blurb about your app to <cygutils>/PROGLIST
 241    Add your app to the list at the end of the README file
 242    Add your name to the AUTHORS file.  Don't worry about NEWS;
 243    I do that before each release.
 244
 245 8) Bootstrap
 246
 247    (You need to have autoconf, autoconf-devel, automake, and
 248    automake-devel installed for this to work).  Change dir
 249    to the top of your checked-out source, and run bootstrap:
 250
 251    cd <cygutils>
 252    ./bootstrap
 253
 254    If you haven't made any mistakes, you should (a) see no
 255    errors, and (b) see some new rules in Makefile.in that
 256    correspond to your program.
 257
 258 9) Build and test
 259
 260    Now, just run './configure ; make' as usual.  Somewhere
 261    amongst the flurry of messages, you should see your application
 262    being built.  If so, you're almost done.  If not, then you
 263    need to figure out why.  Time to read the auto* documentation...
 264
 265 10) Create a patch and ChangeLog entry
 266
 267    a) PATCH
 268
 269       cd <cygutils>
 270       cvs diff -u > foo.patch
 271
 272       If you've already edited the ChangeLog file, make sure to
 273       *remove* that chunk from foo.patch.  I don't want a PATCH
 274       for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
 275       patches rarely apply cleanly; it's easier to cut-n-paste.  More
 276       below).
 277
 278    b) NEW FILES
 279
 280       However, you'll notice that none of the files in your src/foo
 281       directory are represented in the patch.  That's normal.  Remove
 282       any .o and .exe files from src/foo, and then just make a tarball
 283
 284       cd <cygutils>
 285       tar cvjf foo.tar.bz2 src/foo
 286
 287    c) CHANGELOG
 288
 289       You should also create a ChangeLog entry.  Don't actually edit
 290       the ChangeLog itself; create a new file (foo.changelog?) and
 291       put your stuff there.  It should look like this:
 292
 293       2002-03-02  Your Name  <your_email_address@domain.com>
 294
 295          * src/foo: new directory
 296          * src/foo/foo.c: new file
 297          * Makefile.am: add program 'foo'
 298          * Makefile.in: regenerate
 299          * AUTHORS: add yourname for foo
 300          * PROGLIST: add foo
 301          * README: add foo
 302
 303       Don't list src/foo/Makefile.  Do list every original
 304       file in src/foo/ (like your man pages, or extra documentation
 305       files, or headers)
 306
 307 11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I
 308    finished the integration work neceesary to include 'foo' in the
 309    'cygutils' package, as previously agreed on this list."  Paste
 310    the ChangeLog into that notice.  But do NOT send the patch or
 311    tarball to the mailing list.
 312
 313    Instead, send that to ME, cygwin@cwilson.fastmail.fm.  The patch
 314    and tarball should be attachments, but paste the ChangeLog entry
 315         into the body of the message.  Do NOT paste your patch into the
 316         body of the email; most mail programs will horrendously distort
 317    it if you do).  Also, be sure and warn of any special link
 318    requirements (cf. section 5a and 5b above).
 319
 320 12) Bask in the glow of a job well done.
 321
 322 --
 323 Chuck Wilson
 324 cygutils maintainer
 325
 326 Note to self: how to commit contributions:
 327   apply the patch
 328   untar the contribution
 329   Add the Changelog entry
 330   ./bootstrap
 331   cvs add src/directory
 332   cvs add src/directory/srcfiles
 333   cvs commit -m "Add foo contribution"
 334   ./bootstrap
 335   cvs diff | grep Index > foo
 336   >>> use 'foo' to add another Changelog entry
 337   cvs commit -m "Add foo contribution"
 338   cvs tag something
 339