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: Not every spiffy utility belongs in cygutils. We don't want cygutils to become a huge grab bag of hundreds of small programs...in many cases, your spiffy new program should become a standalone package and a full-fledged member of the cygwin distribution. (Don't worry -- that's not hard. It's probably easier than integrating your spiffy program into cygutils). So, your first step is to post a message to the cygwin-apps mailing list, present your program, and ASK if it should be included in cygutils, or turned into a standalong package. If you believe it should become part of cygutils, explain why. I will not add any program to cygutils without a consensus from the cygwin-apps list. 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. Second, once you're obtained agreement that yourfile.c should be added to cygutils: 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. Again, are you SURE you want it to become part of cygutils? Making a standalone program is a lot easier... 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) You should also add it to the licenses variable in the toplevel Makefile.am: e.g. licenses = ... licenses/COPYING.MPL ... 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 /foo.c /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. Naturally, the header files should also be copied into src/foo/. 5) Modify cygutils/Makefile.am a) Add your program to the list of progs to be built. If your program will build on non-windows platforms in addition to cygwin, then you can add your program to the "bin_PROGRAMS" variable: bin_PROGRAMS = ... src/foo/foo ... If your contribution is windows-specific, then you should add it to BOTH the "windows_progs" and the EXTRA_PROGRAMS variables: windows_progs = ... src/foo/foo ... EXTRA_PROGRAMS = ... src/foo/foo ... b) 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: src_foo_foo_LDADD = -lwinlib Where "src_foo_foo" is the path to your program, where the '/' characters are replaced with '_' characters. Yes, it looks a little funny -- but because our subdirectory has the same name as our program, we get double foo's... Also, 'winlib' is the library that you need. See the src_lpr_lpr_LDADD variable in Makefile.am for an example. 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 create an LDADD variable in Makefile.am with -lreadline (or whatever). We'll figure out how to handle it better further down the road. However, make sure to let me know about your special link requirements. src_foo_foo_LDADD = -lreadline One special case is the gettext internationalization libraries. If your program must link with -lintl, then all you need to do is create an LDADD variable as follows: src_foo_foo_LDADD = @LIBINTL@ The configuration process will replace @LIBINTL@ with the appropriate -lintl -liconv invocation. Note that you do NOT need to include the following libraries in a 'src_foo_foo_LDADD' line; these will be added automatically... -lcygipc -lpopt (that is, cygipc or popt) c) man pages and other documentation If you got 'em, copy 'em to your src/foo directory, and add the manpage to the man_MANS variable in Makefile.am like this: man_MANS = ... src/foo/foo.1 ... If there are non-man-page documentation files, you should those files to the extra_docs variable (which gets automatically included in EXTRA_DIST) extra_docs = ... src/foo/foo.README ... However, there is no provisiion for actually INSTALLING these additional documentation files. At least not yet. d) Extra files If your contribution consists of more source files than a single .c, then you need to add a variable to Makefile.am that lists all of them: src_foo_foo_SOURCES = foo.c otherfoo.c foo.h Note that this variable should NOT be specified if your program consists merely of a single .c file whose name is the same as your program + '.c'. If there are .h files in your SOURCES list, then you need to add those .h files to the noinst_HEADERS variable, or the headers would get installed into /usr/include/src/foo/ -- and we don't want that! noinst_HEADERS = ... src/foo/foo.h ... If you have other questions about the Makefile.am file, try to follow the "patterns" established in it by the other programs, or (gasp) 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 /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 /PROGLIST Add your app to the list at the end of the README file Add your name to the AUTHORS file. 8) 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 ./bootstrap If you haven't made any mistakes, you should (a) see no errors, and (b) see some new rules in Makefile.in that correspond to your program. 9) 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... 10) Create a patch and ChangeLog entry a) PATCH cd 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 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 * src/foo: new directory * src/foo/foo.c: new file * Makefile.am: add program 'foo' * Makefile.in: regenerate * 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) 11) Send a notice email to cygwin-apps@cygwin.com, that says "Hey, I finished the integration work neceesary to include 'foo' in the 'cygutils' package, as previously agreed on this list." Paste the ChangeLog into that notice. But do NOT send the patch or tarball to the mailing list. Instead, send that to ME, cwilson@ece.gatech.edu. The patch and tarball should be attachments, but paste the ChangeLog entry into the body of the message. Do NOT paste your patch into the body of the email; most mail programs will horrendously distort it if you do). Also, be sure and warn of any special link requirements (cf. section 5a and 5b above). 12) Bask in the glow of a job well done. -- Chuck Wilson cygutils maintainer Note to self: how to commit contributions: apply the patch untar the contribution Add the Changelog entry ./bootstrap cvs add src/directory cvs add src/directory/srcfiles cvs commit -m "Add foo contribution" ./bootstrap cvs diff | grep Index > foo >>> use 'foo' to add another Changelog entry cvs commit -m "Add foo contribution" cvs tag something