Cygwin

Get that Linux feeling - on Windows

How can I help out?

This document deals with contributions to the Cygwin DLL and Cygwin-specific utilities*. Although the space and internet connection for this site have been paid for by Red Hat, the vast majority of the time for this project is volunteer time, including the time spent by Red Hat employees. Volunteer time is always in short supply, so if you are thinking about contributing, rest assured that your efforts will be welcome.

Contributions to other packages in the Cygwin distribution are also welcome and some of the principles involved are the same. However, most of the specific instructions here will not be applicable to utilities like apache, bash, gawk, etc., which are generally found in linux releases. If you have a patch for any of those, send it along to the cygwin mailing list and the appropriate package maintainer will respond. If you want to contribute a package that is not currently part of the Cygwin distribution, look here.

If you are looking to donate money to cygwin developers then check out the donations page.

Two other important cygwin components are also not covered by the guidelines set forth on this page. The cygwin setup utility "setup.exe" and the newlib library (used by cygwin for some common "libc"-like functions) also have different contribution rules. See their project pages for more information.

Building the development version of Cygwin


The code corresponding to cygwin1.dll is mostly in the winsup directory with additional code coming from newlib/libc and newlib/libm. Any changes you make should be to the current development sources. This makes it much easier to integrate your changes once they're completed and tested. Note that the current CVS tree (and the development snapshots) should compile, but they should always be assumed to be unstable since they contain untested, experimental code.

Build instructions are included in the FAQ under "How do I build Cygwin on my own?". If your object directory is /c/obj, the Cygwin dll you will build should be /c/obj/i686-pc-cygwin/winsup/cygwin/new-cygwinxx.dll where xx represents the current API_MAJOR version number (currently it is 1).

Note that minimally, the top-level source tree needs to contain:

Makefile.in, config, config-ml.in, config.guess, config.sub, configure, configure.in, include, install-sh, ltconfig, ltmain.sh, missing, move-if-change, newlib, symlink-tree, winsup, ylwrap.

but you really should just check out the winsup module as mentioned on the Cygwin CVS page.

Before you get started


Once you've checked out the sources, you will be able to avail yourself of the "how*" files in the winsup/cygwin directory. These are developer-written files which summarize various techniques involved in cygwin design. You should familiarize yourself with their content before making changes to the subsystems that they describe.

If your change is going to be a significant one in terms of the size of your code changes, be aware that you will have to sign over the copyright ownership of your code changes to Red Hat or the FSF (depending on the source file) before we can include your changes in the main source tree. Your employer may also have to send us a disclaimer stating that they have no claims to your contribution. This is necessary for liability reasons. Here is our standard assignment form for changes to Cygwin that you can fill out, sign, and send back.

Finally, before you start modifying anything for real, you should probably join the cygwin-developers mailing list and send it mail describing what you want to do and how you want to do it so you don't waste time working on something we can't integrate. This also allows us to keep track of what's being worked on so efforts aren't duplicated.

It should go without saying but when you start coding your change, make sure that you adhere to the brace, indentation, and whitespace style of the surrounding code. For the most part, that means following the GNU coding standards but some parts of the code which have been imported from other sources use other styles. Just pay close attention to the formatting of the surrounding code and don't, e.g., add K&R style coding to a file which uses GNU formatting.

If you want to keep track of who's doing what to the sources, you can subscribe to the cygwin-cvs and newlib-cvs mailing lists using the standard subscription techniques employed for the other non-cvs mailing lists.

When you have finalized your changes


Once you've finished making and testing your changes, you should send a unified diff to the cygwin-patches list. As an example, if you have modified several files in /c/src/winsup, then do the following in bash:

      cd /c/src/winsup
      cvs diff -up > /tmp/mypatch

This will produce one file with all of your changes, making it easy for someone to review and apply. Send the contents of this file as plain text. Do not uuencode or otherwise encrypt it.

Then send it to the cygwin-patches list in an email along with an explanation of what the change does. Make sure that you include a ChangeLog entry. If you have never used a ChangeLog before 1) refer to the GNU ChangeLog Standards and 2) model your entry after other entries in the file winsup/ChangeLog.

Ideally, diffs should be sent as plain text with no encoding or other special formatting. ChangeLogs should not be sent as "diffs". Just send the complete ChangeLog entry.

Common patch submission problems include:

Note that you must be subscribed to cygwin-developers and cygwin-patches to send email to those lists.

Please feel free to ask questions about any of this. We would love it if more people made useful contributions -- this can be one of the big advantages of free software; we all benefit from everyone else's work as well as our own.

What needs doing


You can get a good idea of the current bugs and problem areas by browsing the cygwin mailing list archives. In addition, check out the API calls portion of the FAQ and look for references to unimplemented functions.

Remember that the cygwin-developers and cygwin-patches mailing lists are intended only for people who are serious about augmenting the cygwin DLL. These lists are not intended as a vehicle for getting general cygwin questions answered, for announcing ports of any utilities, or for providing patches for anything other than the files in the "winsup" directory. And, again, you will first have to join the lists before you are able to send email.

(If you just want to send email to the cygwin-patches mailing list without receiving email you can send email to cygwin-patches-allow-subscribe at cygwin dot com. This will allow you to send email to the list without receiving any of the email traffic. Be advised, however, that you may miss some messages about your patch if you do this.)


* Cygwin-specific utilities are any executable or shared libraries distributed in the cygwin distribution tar file, i.e., those files that are generated from the winsup/{cygwin,cygserver,utils} source directories.