So, you have a utility that you believe would 
be a good addition to cygutils, do you?  You 
probably want to know how you could contribute it,
don't you?  Well, first:

  Don't just send me yourfile.c and expect me to
  do all the integration work.

You need to do more than merely insure that it builds
on your machine with a simple

  gcc -o yourfile.exe yourfile.c -lthislibrary -lthatlibrary

In addition to that, you need to check out the cygutils 
source and integrate yourfile into the whole system.  Instructions
follow below.  However, you'll notice that it's quite a bit
of work.  You may want to send an exploratory email to
cygwin@cygwin.com and explain your programs behavior, what
need it fills, and get pre-clearance for eventual inclusion
into cygutils before embarking on the journey outlined below.
Also, note that I will not fix your bugs.  If, at some time
after your program is accepted into cygutils, I (as cygutils
maintainer) get a bug report on your program, I will forward
it to you.  If you don't fix it or respond within a reasonable
time, I will remove it from the distribution.

------------------------------------------------------

Okay, now that we're past that unpleasantness, here's how to
integrate your spiffy new utility.  First, let's assume that 
your spiffy utility is called 'foo', and its source is in 'foo.c'.

The simple 12 step program:
---------------------------

1) Get the cygutils source

   cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps login
      use 'anoncvs' as the password
   cvs -z3 -d:pserver:anoncvs@sources.redhat.com:/cvs/cygwin-apps co cygutils

   you now have a 'cygutils' directory with the existing source.

2) License information

   make sure that all .c and .h files in your contribution
   have license information: preferably GPL, but other
   open licenses are acceptable, too.  See the top of
   src/lpr/lpr.c for an example.
	
   a) if your license is not GPL or BSD-no-advert, then
      you must also include a copy of the ENTIRE license
      in the licenses subdirectory.  (Most of the time,
      the blurb in the .c or .h file is just that: a short
      blurb, with a reference to the full text elsewhere)

3) Make a home 

   create a new directory for your contribution underneath 'src'
   In our case, we will do this:
     cd cygutils/src
     mkdir foo

   copy your source into the new directory
     cp <location>/foo.c <cygutils>/src/foo/

4) Modify your source code

   Add the following snippet to the beginning of your .c and .h(*) 
   files, just after the license information:

     #if HAVE_CONFIG_H
     #include "config.h"
     #endif
     #include "common.h"
	
   a) If your contribution has its own .h file(s), the entire .h file
      should be "guarded" as follows:
		
        /* license information */
        #ifndef _FOO_H
        #define _FOO_H
        /* the config.h/common.h stuff */
        /* your header stuff */
        #endif /* !_FOO_H */

      the "_FOO_H" identifier should be changed to match the filename
      of your header file.  Thus, "bob.h" would be guarded with _BOB_H.

5) Makefile.am

   Create a Makefile.am file in your 'foo' directory. If your 
   contribution will build on non-windows platforms in addition to
   cygwin, then Makefile.am should look like this:

   ## Makefile.am -- Process this file with automake to produce Makefile.in
   INCLUDES = -I$(top_builddir) -I$(top_srcdir)
   bin_PROGRAMS = foo
   ## end

   (Yes, really.  That's it).  If your contribution is windows-specific,
   like lpr or mkshortcut or the [put|get]clip programs, then your
   Makefile.am should look like:

   ## Makefile.am -- Process this file with automake to produce Makefile.in
   INCLUDES = -I$(top_builddir) -I$(top_srcdir)
   if WITH_WINDOWS_PROGRAMS
   windows_progs = foo
   endif
   bin_PROGRAMS = $(windows_progs)
   EXTRA_PROGRAMS = foo
   ## end

   a) Special link libraries
	
      If you need to link to special *WINDOWS* libraries, then obviously
      your program is windows-specific, but also you should add a line 
      in your Makefile.am like this:

      foo_LDADD = -lwinlib

      Where foo is your program name, and winlib is the library you need.
      See src/lpr/Makefile.am or src/mkshortcut/Makefile.am for 
      more examples.

      If, on the other hand, you need to link to some other (cygwin)
      library that is also more generally available -- like libreadline
      or libncurses -- then you'll need to do a little more work. 
      For your initial submission, just add the -lreadline (or whatever)
      command to your Makefile.am foo_LDADD line.  However, make sure
      to let me know about your special link requirements.

      Note that you do NOT need to include the following libraries in
      a 'foo_LDADD' line; these will be added automatically...

      -lintl -lcygipc -lpopt  (that is, gettext, cygipc, or popt)

   b) man pages and other documentation

      If you got 'em, copy 'em to your foo directory, and add a line
      to your Makefile.am like this:

      man_MANS = foo.1

      If there are non-man-page documentation files, you should add
      a line like this:

      EXTRA_DIST = foo.README

      However, there is no provisiion for actually INSTALLING these
      additional documentation files.  At least not yet.

   c) Extra files

      If your contribution consists of more source files than a single
      .c, then you need to add a line that lists all of them in your
      Makefile.am:

      foo_SOURCES = foo.c otherfoo.c foo.h

      If there are .h files in that list, you should also add a line
      like this:

      noinst_HEADERS = foo.h

   If you have other questions about the Makefile.am file, consult
   the other ones already in cygutils as examples, or read the
   automake documentation.

6) Simplify your #includes.

   Take a good look at the #include statements in your .c and .h
   files.  If the dependencies are listed in <cygutils>/common.h,
   then you shouldn't re-include them.  If a dependency is NOT
   listed in common.h, then leave it in your .h/.c file -- for 
   now.  We may choose to add them to common.h and add new tests
   to configure.ac, or we may choose to let your .c file 
   include it directly.  However, anything that's already in 
   common.h, remove from your .c/.h file.  It's okay to just
   comment them out, rather than deleting them entirely, if 
   you prefer.

7) Add information to cygutils documentation files:

   Add a short blurb about your app to <cygutils>/PROGLIST
	Add your app to the list at the end of the README file
   Add your name to the AUTHORS file.

8) Hook your directory into the package build structure

   Add the name of your directory in src to the list in 
   src/Makefile.am.

   Add your Makefile to the list at the end of configure.ac

9) Bootstrap

   (You need to have autoconf, autoconf-devel, automake, and
   automake-devel installed for this to work).  Change dir
   to the top of your checked-out source, and run bootstrap:

   cd <cygutils>
   ./bootstrap

   If you haven't made any mistakes, you should (a) see no
   errors, and (b) see a Makefile.in file added to your foo
	directory.

10) Build and test

   Now, just run './configure ; make' as usual.  Somewhere 
   amongst the flurry of messages, you should see your application
   being built.  If so, you're almost done.  If not, then you
   need to figure out why.  Time to read the auto* documentation...

11) Create a patch and ChangeLog entry

   a) PATCH
	
      cd <cygutils>
      cvs diff -u > foo.patch

      If you've already edited the ChangeLog file, make sure to
      *remove* that chunk from foo.patch.  I don't want a PATCH
      for the ChangeLog, I want the ChangeLog entry itself (ChangeLog
      patches rarely apply cleanly; it's easier to cut-n-paste.  More
      below).
  
   b) NEW FILES

      However, you'll notice that none of the files in your src/foo
      directory are represented in the patch.  That's normal.  Remove 
      any .o and .exe files from src/foo, and then just make a tarball

      cd <cygutils>
      tar cvjf foo.tar.bz2 src/foo

   c) CHANGELOG

      You should also create a ChangeLog entry.  Don't actually edit
      the ChangeLog itself; create a new file (foo.changelog?) and
      put your stuff there.  It should look like this:

      2002-03-02  Your Name  <your_email_address@domain.com>

         * src/foo: new directory
         * src/foo/Makefile.am: new file
         * src/foo/Makefile.in: new file
         * src/foo/foo.c: new file
         * src/Makefile.am: add subdirectory foo
         * src/Makefile.in: regenerate
         * configure.ac: add src/foo/Makefile to output list
         * AUTHORS: add yourname for foo
         * PROGLIST: add foo
         * README: add foo

      Don't list src/foo/Makefile.  Do list every original
      file in src/foo/ (like your man pages, or extra documentation
      files, or headers)

12) Send an email to cygwin@cygwin.com with the patch and the 
   tarball as attachements.  Paste your changelog into the body 
   of the message -- or you can send it as an attachment.  (Do NOT
   put your patch into the body of the email; most mail programs
   will horrendously distort it if you do). 
	
   In the body of your email, Describe what your program does, why
   it's needed, and why you think it should be added to the 
   cygutils package.  Also explain why (or state that) existing
   tools will not meet the need your program does.  Also, be
   sure and warn of any special link requirements (cf. section
   5a and 5b above).

--
Chuck Wilson
cygutils maintainer