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