Get thatLinux feeling - on Windows
This document deals with contributions to the Cygwin DLL andCygwin-specific utilities*.
Note: Thenewlib library(used by Cygwin for some common "libc"-like functions) has differentcontribution rules. See their project page for more information.
The code corresponding to cygwin1.dll is mostly in the winsupdirectory with additional code coming from newlib/libc and newlib/libm.Any changes you make should be to thecurrentdevelopment sources. This makes it much easier to integrate yourchanges once they're completed and tested. Note that the current Gittree should compile, but it should always be assumed to be unstablesince it contains potentially untested, experimental code.
Build instructions are included intheFAQunder "How do I build Cygwin on my own?".
Basically, just clone the newlib-cygwin Git repository as mentioned on theCygwinGit page.
Once you've checked out the sources, you will be able to availyourself of the "how*" files in thewinsup/cygwin/DevDocs directory.These are developer-written files which summarize various implementationdetails in cygwin. You should familiarize yourself withtheir content before making changes to the subsystems that they describe.
If your change is going to be a significant one in terms of thesize of your code changes, be aware that for changes to all sourcefiles under the "winsup" directory you will have to license your codechanges under the 2-clause BSD license before we can include yourchanges in the main source tree. (This is necessary for the next fewyears so that Red Hat can meet its continuing obligations to Cygwinbuyout license customers while Cygwin transitions away from thislicensing model.).
To do this, just make a public statement that you provide yourpatches to the Cygwin sources under the 2-clause BSD license.
You can do that with your first patch submission. After your firstpatch has been approved and applied, your name and email address will beadded to the new winsup/CONTRIBUTORS file.
For the wording of the 2-clause BSD license, see thewinsup/CONTRIBUTORS file in theCygwin gitrepository.
If you already have a Cygwin Copyright Assignment signed andsubmitted, you can ignore this procedure. If you're not sure if youalready signed the Copyright Assignment, see the list of signees in thewinsup/CONTRIBUTORS file.
Finally, before you start modifying anything for real, you shouldprobably join the cygwin-developers mailing list and send it maildescribing what you want to do and how you want to do it so youdon't waste time working on something we can't integrate. This alsoallows us to keep track of what's being worked on so efforts aren'tduplicated.
It should go without saying but when you start coding your change,make sure that you adhere to the brace, indentation, and whitespacestyle of the surrounding code. For the most part, that means followingtheGNU coding standards but some parts of the code which have been importedfrom other sources use other styles. Just pay close attention to theformatting of the surrounding code and don't, e.g., add K&R style codingto a file which uses GNU formatting.
If you want to keep track of who's doing what to the sources, you cansubscribe to the cygwin-cvs and newlib-cvs mailing lists using the standardsubscription techniques employed for theothermailing lists.
Once you've finished making and testing your changes, send your patches tothecygwin-patches mailing listin git format-patch format.
As an example, if you have modified several files in/oss/newlib-cygwin/winsup, then do the following in bash:
[hack, hack, hack] git add git commit [hack, hack, hack] git add git commit git format-patch [--cover-letter]
This will produce files with all of your changes newer than origin,making it easy for someone to review and, if you don't have writeaccess, push. Give them a final once-over. Ideally you include a gooddescription of your change with details what it does, how it works, whatbug it fixes (if any) and generally lend a hand to readers of the gitlogs. Adding URLs to mailing list postings referencing the problem yourpatch solves might be a good idea, too.
Patchsets with smaller, self-contained patches are preferred over asingle, huge patch. Add a cover letter (--cover-letter option) if you'resending a patch series to simplify discussing it on the mailing list.
If you're satisfied with the patch and the log message, send thepatches as they got created by git format-patch. The git send-emailcommand will usually do the right thing:
git send-email --to="cygwin-patches@cygwin.com" <format-patch-files>
Note that you must be subscribed to cygwin-developers andcygwin-patches to send email to those lists.
Please feel free to ask questions about any of this. Wewould love it if more people made useful contributions -- this can beone of the big advantages of free software; we all benefit fromeveryone else's work as well as our own.
You can get a good idea of the current bugs and problem areas bybrowsing the cygwin mailing list archives. In addition, you can look atthe list of unimplemented functions in the API reference portion of thedocumentation.
Remember that the cygwin-developers and cygwin-patches mailing lists areintended only for people who are serious about augmenting the cygwinDLL. These lists are not intended as a vehicle for getting generalcygwin questions answered, for announcing ports of any utilities, or forproviding patches for anything other than the files in the "winsup"directory. And, again, you will first have to join the lists before youare able to send email.
(If you just want to send email to the cygwin-patches mailing listwithout receiving email you can send email to cygwin-patches-allow-subscribeat cygwindot com. This will allow you to send email tothe list without receiving any of the email traffic. Be advised,however, that you may miss some messages about your patch if you dothis.)
*Here by "Cygwin-specificutilities" we mean any executable or shared libraries generated from thewinsup/{cygwin,cygserver,utils} source directories.