Red Hat GNU Red Hat Microsoft Cygwin
Cygwin Home
Cygwin/X Home
Red Hat Cygwin Product
Community
Documentation
Contributing
Software
sourceware.org

Cygwin Package Contributor's Guide

This document is intended for people who post packages to sourceware.org, and thus need to make them available through the standard Cygwin setup program. This documents the syntax of the setup.hint file, the program that automatically generates it on a regular basis, the layout required for packages, and the related policies to ensure good behaviour from the setup.exe program.

Setup.exe depends on certain conventions being followed. If they are not followed, bad things may happen to the users of setup.exe. Where a convention can be ignored, should circumstances warrent, this document will specify that. Setup.exe has it's own homepage http://sourceware.org/cygwin-apps/setup.html. If you are interested in adding features to setup.exe, or in manually creating a setup.ini file, you should consult the setup.exe homepage.

The mailing list cygwin-apps@cygwin.com is the correct place to discuss any package creation or maintenance issues. It is not a place for end user bug reports - direct those to cygwin at cygwin dot com instead.

Contents

Package file naming

Package naming scheme: use the vendor's version plus a release suffix for ports of existing packages (i.e. bash 2.04 becomes 2.04-1, 2.04-2, etc, until bash 2.05 is ported, which would be 2.05-1, etc). Some packages also use a YYMMDD format for their versions, e.g. binutils-20010901-1.tar.bz2. The first release of a package should have a -1 release suffix.

A complete package currently consists of three files:

  • a binary tar file
  • a source tar file
  • a setup.hint file

Binary tar files are named "package-version-release.tar.bz2". They generally contain the executable files that will be installed on a user's system plus any auxilliary files needed by the package. See the making packages section below for more details on how to generate a binary tar file.

Source tar files are named "package-version-release-src.tar.bz2". Source tar files should contain the source files needed to rebuild the package. While installing these files is optional under setup.exe, the inclusion of a source tar file is part of the totality that makes up a cygwin package and so, these files are not optional. In some cases, there may be multiple packages generated from the same source; for instance, one might have a "boffo" package and its associate shared library in "libboffo7", where both are generated from the same -src tarball. See the making packages section below for more details on the contents of a -src tar file, and the setup.hint section for information on the "external-source:" option.

The setup.hint file is discussed below.

Automatic setup.ini generation on sourceware.org

A script runs on sourceware.org which collects information from (currently) the release directory in the ftp download area. Information from subdirectories of these directories is parsed to automatically generate the default setup.ini file which is used by the cygwin setup.exe program for installation control. If you are responsible for maintaining a cygwin package, it is important that you understand how this process works.

Packages are grouped by directory under release. The directory name is the same as the package name. For example, the boffo package will live in the boffo subdirectory. Exceptions to this rule are historical. All new packages will follow the rule of package name == directory name. However, for closely related groups of packages, it is acceptable to use a heirarchical tree under release/:

release/
release/boffo/
release/boffo/<boffo files>
release/boffo/boffo-devel/
release/boffo/boffo-devel/<boffo-devel file>

Each directory contains source and binary tar files which have been been compressed using bzip2. The required format of these filenames is: package-version-release[-src].tar.bz2 . The contents of these files is discussed below.

The "package" part of the filename is the name mentioned above.

The version number must start with a digit and must adhere to the rules in package file naming above. Higher version (and release) numbers are used for the current version of a package; the previous stable version (if any) is used for the previous version (however see setup.hint for exceptions to this rule). Lexically, when two packages have identical vendor version numbers, the one with the higher release number is considered newer. Also, given two packages, the one with the higher vendor version number is always considered newer, regardless of the release number.

The -src component of the filename is added to files which contain source code.

A complete "package" is made up of three files: the "binary" package tar file, the "source" tar file, and the "setup.hint" file, e.g.:

bash$ ls release/boffo
boffo-1.0-1.tar.bz2  boffo-1.0-1-src.tar.bz2  setup.hint

Setup is currently unable to list more than three versions of each package. Therefore you should not keep more than three versions of each package around: The current version, the previous stable version, and, optionally, one test version. By keeping a previous stable version around, you isolate yourself (somewhat) from problems with partial mirrors. When you add a new "current" version, you can either keep the old "previous" version, or make the old current version the new previous version, depending on how stable they each were.

Test versions are specified via the setup.hint file as described below. It is not required that your package have a test version. Use of a test version of a package is at the discretion of the package maintainer.

Note that currently some files in the distribution are gzipped. Use of gzip for file compression is deprecated, however. New package submissions must be bzip2'ed.

setup.hint

Each package must be submitted with a file called setup.hint. This file is used for information that cannot be inferred just from the context of the file name or package name. Lines in setup.hint will consist of one of the following:

# comment
@ package
sdesc: "some text"
ldesc: "some text"
skip:
curr: version
prev: version
test: version
category: name1[ name2...]
requires: package[ package...]
external-source: package

Note: Not all of the above setup.hint lines are required. Please read the description below for further details on how to construct a setup.hint file.

(You may see some older setup.hint files which lack the colons after the introducing field. This usage is allowed but deprecated. Please use colons in your setup.hint for everything but '#' and "@'.)

Lines that begin with '#' are considered to be comments and are ignored by the setup.ini generator.

A line that begins with a "@" behaves similarly to the setup.ini field (see below). It overrides the package name for the enclosing directory. This is an optional entry. It is intended only for historical packages where the package name is different from the name of the directory in which the package resides. This should not be necessary for "modern" setup.hint files. Do not use this unless you've been instructed to do so.

The curr, prev, and test lines indicate which versions should be used for which sections of that package. Use these settings only if you need to circumvent the normal intuitive version numbering scheme.

Use of curr and prev is usually not required since the setup.ini generator does a good job of figuring out version number ordering. So, e.g. if you had previously released boffo-0.9-1 and now have a new boffo-1.0-1, the version numbering is obvious and there is no need to use curr or prev. It is obvious that boffo-1.0-1 is newer than boffo-0.9-1 and the setup.ini generator will do the right thing in this case.

However, if you had discovered a serious error in the boffo-1.0 release, and then decided that you want to drop back to boffo-0.9-1, you could include entries like this:

prev: 1.0-1
curr: 0.9-1
This usage should be rare, however.

In general, you should trust the automatic setup.ini generator to "do the right thing" -- with one exception. If you decide that you need to release a test version of your package, there is no way for the setup.ini generator to know that.

So, you will have to put something like "test: 1.9-1" in your setup.hint file. This will cause setup.exe to characterize the 1.9-1 version as a "test" package. With the current setup.exe implementation, it will also mean that it will be overlooked by most people during installation. So, unless you have made arrangements to advertise your test release, this option should be used sparingly.

Note that if any of the curr, prev, or test options are used, they will short circuit all of the automatic version detection used for generating setup.ini. So, if you include a test option, and you have valid current and/or previous tar files, you must specify curr and/or prev. Otherwise, the only version that setup.exe will display will be the test version.

For example, if your setup.hint looks like this:

test: 1.9-1
then setup.ini will not contain the 0.9-1 or 1.0-1 versions.

If you want all of the versions included, you must do this:

prev: 0.9-1
curr: 1.0-1
test: 1.9-1

The skip line indicates that that package should not appear in setup.ini. It is intended for directories that exist in the hierarchy that should not be considered for inclusion in setup.ini.

sdesc is a mandatory field for setup.hint. Your package must contain this field. The sdesc field is required for correct operation of setup.exe.

sdesc is a one line description of the package. This is the information that will be displayed when installing packages via setup.exe.

ldesc is a more descriptive, multi-line description of the package, intended for future use in setup.exe.

Please note that the package name should not be part of the description, e.g. this is incorrect:
sdesc:      "boffo: A whackamole simulation in ASCII art"
This is correct:
sdesc:      "A whackamole simulation in ASCII art"

Quote text that takes up several lines e.g.:

ldesc: "A whackamole simulation in ASCII art.
Intended for use on VT100 terminals at BAUD rates 1200 and
above.  Uses arrow keys for positioning over moles.  Space
bar whacks the mole.
No actual moles will be harmed during execution of this game."

The category line indicates the categories that this package belongs to. One package can belong to multiple categories. Multiple categories are separated by spaces.

Do not enclose multiple category names within quotation marks.

Please do not invent a new category without checking with the cygwin-apps mailing list first. As of this writing, the current categories are:

Admin Archive Audio Base Comm Database
Devel Doc Editors Games Gnome Graphics
Interpreters Libs Mail Math Mingw Net
Perl Python Publishing Science Shells System
Text Utils Web X11

As you can see, currently, all categories consist of only a single word. We don't anticipate that this will change anytime soon. However, with the use of quotes, setup.exe will understand category names which contain spaces, for example:

category: "ASCII Games"

The above would place a package in a single category called "ASCII Games" rather than two categories "ASCII" and "Games".

The requires line indicates the packages that this package relies on. If your package is dependent on a file provided by another package that other package should be included here. The requires field may be missing or empty if your package truly does not require any other package.

A package will probably require the cygwin package if it contain any DLLs or executable files since the cygwin package contains cygwin1.dll, which is required for most programs. However, the cygwin package would not be a required dependency for a package which contained only text files, as is the case with, for example, packages that consist entirely of man pages.

A package can rely on multiple other packages. Hierarchical dependencies should work correctly, however, it is best to always include specific dependencies, i.e. don't drop 'bar' from your dependency list if your package requires it, even if you are including 'foo' which relies on 'bar'.

Conversely, do not include package dependencies of dependent packages in your dependency list. If you think that another package has an incorrect dependency list, send email to cygwin-apps noting that fact.

Multiple packages are separated by spaces. Do not enclose multiple package names within quotation marks.

Here's an example of a complete release/boffo/setup.hint:

category: Games Text
requires: libncurses6 cygwin
sdesc:    "A whackamole simulation in ASCII art"
ldesc:    "A whackamole simulation in ASCII art.
Intended for use on VT100 terminals at BAUD rates 1200 and
above.  Uses arrow keys for positioning over moles.  Space
bar whacks the mole.
No actual moles will be harmed during execution of this game."

Notice that we didn't use the prev, curr, test, or @ options. Instead, we relied on the automatic setup.ini generator to do as much as possible for us.

setup.hint (Advanced Options)

The external-source line is used when multiple installation packages are generated from a single -src package. For example, suppose the boffo package contains the executables and documentation for boffo, but there is also a shared library cygboffo-7.dll that might be used by other packages; say, the fobbo program. It would be nice to separate that cygboffo-7.dll shared library into a second installation package, so that users of the fobbo program can install just the library, and not the entire boffo package. However, all of the boffo executables and the DLL are generated from the same source. To support this usage, the boffo maintainer would create three packages:

  • boffo-2.4.1-2.tar.bz2: an installable package that contains all of the normal contents of boffo -- except for the shared library.
  • libboffo7-2.4.1-2.tar.bz2: an installable package that contains only the shared library from boffo
  • boffo-2.4.1-2-src.tar.bz2: the -src tarball for boffo.

boffo-2.4.1-2.tar.bz2, boffo-2.4.1-2-src.tar.bz2, and the boffo setup.hint would go into the release/boffo/ subdirectory on the cygwin server. libboffo7-2.4.1-2.tar.bz2 would go into a separate subdirectory, such as release/boffo/libboffo7/, along with a separate libboffo7 setup.hint. The two setup.hint files would look something like this:

boffo setup.hint
libboffo7 setup.hint
category: Games Text
requires: libboffo7 libncurses6 cygwin
sdesc: "A whackamole simulation in ASCII art"
ldesc: "A whackamole simulation in ASCII art. Intended for use on VT100 terminals at BAUD rates 1200 and above. Uses arrow keys for positioning over moles. Space bar whacks the mole.

No actual moles will be harmed during execution of this game."
category: Games Text
requires: cygwin
external-source: boffo
sdesc: "Runtime library for a whackamole simulation in ASCII art"
ldesc: "A whackamole simulation in ASCII art. Intended for use on VT100 terminals at BAUD rates 1200 and above. Uses arrow keys for positioning over moles. Space bar whacks the mole.

No actual moles will be harmed during execution of this game."

The setup.ini generated from these setup.hint files will include these lines (only relevant lines shown):

@ boffo
requires: libboffo7 libncurses6 cygwin
version: 2.4.1-2
install: release/boffo/boffo-2.4.1-2.tar.bz2
source: release/boffo/boffo-2.4.1-2-src.tar.bz2
@ libboffo7
requires: cygwin
version: 2.4.1-2
install: release/boffo/libboffo7/libboffo7-2.4.1-2.tar.bz2
source: release/boffo/boffo-2.4.1-2-src.tar.bz2

Note that both packages point to the same -src tarball. Also, it is required that the version strings match (libboffo7-5.2 won't point to boffo-1.4-src). The same logic is used to "match up" prev: and test: versions.

Making Packages

The files paths within both the -src and the binary package files are quite important. Since setup.exe extracts into a predetermined directory, you must structure your package contents accordingly.

The following requirements avoid problems that have occured in the past with packages. Thus only skip them if you *know* your package will not recreate that prior problem.

  • Binary packages are extracted in /, include all file paths from the root in your archive, e.g.:
    usr/bin/boffo.exe
    usr/share/boffo/boffo.dat
    etc...
    
  • The package is configured using (at a minimum) the following paths:
    --prefix=/usr
    --sysconfdir=/etc
    --libexecdir=/usr/sbin
    --localstatedir=/var
    --datadir=/usr/share
    --mandir=/usr/share/man
    --infodir=/usr/share/info
    
  • All executables in your binary package are stripped (run 'strip' on them). Some makefiles have a install-strip command you can use to do this automatically when you setup your 'installed' tree.
  • Source packages are extracted in /usr/src. See the Package Source section for more information.
  • In your binary package, include a file /usr/share/doc/Cygwin/foo-vendor-suffix.README containing (at a minimum) the information needed for an end user to recreate the package. This includes CFLAGS settings, configure parameters, etc.
  • In your binary package include a directory /usr/share/doc/foo-vendor/ that includes any binary-relevant vendor documentation, such as ChangeLog's, copyright licence's, README's etc.
  • If you are not creating your package from an installed virtual root, be sure to check that the file permissions are appropriate.
  • If you have any 'info' documention in your package, run install-info as part of your post-install script
  • If the package has any global settings (ie in files in /etc) that are not overrideable on a per user basis (sshd, as a daemon, is an example of this) do not include the relevant config files in your package. Instead include in your post-install script to install the settings files. Be sure that if you would overwrite an already present file that the user is offered the choice of keeping their own or overwriting with your defaults.
  • Ensure that your package handles binary only systems, textmode only systems, and hybrid systems correctly.

Package Source

There are two accepted ways to package the source code for cygwin packages.

Method One

  • Source packages are extracted underneath /usr/src (so your -src tarball should not include /usr/src). On extraction, the tar file should put the sources in a directory with the same name as the package tar ball minus the -src.tar.bz2 part:
    boffo-1.0-1/Makefile.in
    boffo-1.0-1/README
    boffo-1.0-1/configure
    boffo-1.0-1/configure.in
    etc...
    
  • In your source package include the same foo-vendor-suffix.README as used in the binary package.
  • Your source package already be patched with any necessary cygwin specific changes. The user should be able to just ./configure; make; and go.
  • Include a single file foo-vendor-release.patch in your source package, that when applied (in reverse: 'patch -R') will remove all the patches you've applied to the package, leaving it as the vendor distributes it. This file should extract as : /usr/src/foo-vendor-release.patch (that is, since setup.exe extracts everything into /usr/src, the patch should be a "top level" member of the -src tarball.)

    Optionally, this patch could also unpack inside the source tree:
    boffo-1.0-1/README
    boffo-1.0-1/configure
    boffo-1.0-1/CYGWIN-PATCHES/boffo-1.0-1.patch
    etc...
    
    However, that tends to complicate actually creating the patch itself. Unless one enjoys recursion, one must move the .patch file OUT of the source tree, regenerate the patch to incorporate any new changes, and then copy the new patch back into .../CYGWIN-PATCHES/. This option is documented because some existing packages do it this way, but it is not recommended for new packages. Make boffo-1.0-1.patch a top-level member of the -src tarball instead:
    boffo-1.0-1.patch
    boffo-1.0-1/README
    boffo-1.0-1/configure
    etc...
    
    To create the patch file described above, you might run
    diff -Nrup vendor-src-dir patched-src-dir > foo-vendor-release.patch
    
    To apply the generated patch (in reverse; that is, to remove the cygwin specific changes from the unpacked -src tarball) the user would run (from within the source tree)
    patch -R -p1 < ../foo-vendor-release.patch
    
  • In general, any cygwin-specific "packaging" files -- such as cygwin-specific READMEs, a copy of the setup.hint file for your package, etc. -- should unpack within a /CYGWIN-PATCHES/ subdirectory in your sources. Naturally, applying the patch (in reverse, as described above) would remove these files from the source tree.
  • So, returning to the boffo example, boffo-1.0-1-src.tar.bz2 would contain:
    boffo-1.0-1.patch
    boffo-1.0-1/README
    boffo-1.0-1/configure
    boffo-1.0-1/configure.in
    boffo-1.0-1/Makefile.am
    boffo-1.0-1/Makefile.in
    boffo-1.0-1/boffo.c
    ...
    boffo-1.0-1/CYGWIN-PATCHES/boffo.README (cygwin-specific)
    boffo-1.0-1/CYGWIN-PATCHES/setup.hint
    ...
    

Method Two

  • In a packaging technique inspired by rpms and debs, you may create a -src tarball which simply contains:
    1. foo-vendor.tar.[gz|bz2]: The original source tarball, exactly as downloaded from the original vendor.
    2. foo-vendor-release.patch: the patch file as described in Method One, above.
    3. foo-vendor-release.sh: A build script that drives the entire unpacking, configuration, build, and packaging (binary and -src) process.
  • You can adapt this generic readme file for script-driven -src packages.
  • Here is an example build script which can be adapted for your package. By carefully modifying the details of this script, it can create the binary and -src packages for you, once you've finished porting your package. How? See the Initial packaging procedure below. But first, a few facts:
    • The buildscript will autodetect the package name, vendor version, and release number from its own filename.
    • When the buildscript is used to compile the package, all building occurs within a hidden subdirectory inside the source tree: boffo-1.0/.build/
    • To create the binary package, the script redirects 'make install' into a hidden subdirectory boffo-1.0/.inst/, creating a faux tree boffo-1.0/.inst/usr/bin, etc. This faux tree is tar'ed up into the new binary package.
    • To create the -src package, the script generates a patch file, and copies the original tarball, the patch, and the script into yet another hidden subdirectory boffo-1.0/.sinst/. The contents of this subdirectory are tar'ed up into the new -src package.
    • Sometimes, you will find that a package cannot build outside of its source directory. In this case, the script must recreate the source tree within the .build subdirectory. The jbigkit -src package uses GNU shtool's mkshadow to do this.
    • generic-build-script is not a one-size-fits-all solution. It must be customized for your package.
  • Initial packaging procedure, script-based
    • Suppose you've got your boffo package ported to cygwin. It took some work, but it now builds and runs. Further, suppose that the boffo-1.0.tar.bz2 file that you downloaded from the boffo homepage unpacks into boffo-1.0/, so you've been doing all of your work in ~/sources/boffo-1.0/. That's good.
    • Place a copy of boffo-1.0.tar.bz2 in ~/sources
    • copy generic-build-script into ~/sources/ and rename it boffo-1.0-1.sh. Carefully adapt this script for your purposes. However, it should auto detect most of what it needs to know: the package name, vendor version, release number, etc.

    • Clean up inside your ~/sources/boffo-1.0/ directory -- make sure that no files which are generated during the build process are lying around. Usually, a 'make distclean' will do the trick, but not always.
    • Ensure that you've put any cygwin-specific readme files, setup.hint files, etc, into ~/sources/boffo-1.0/CYGWIN-PATCHES/. You can adapt this generic readme file for this purpose. The build script expects that the cygwin-specific README file will be named .../CYGWIN-PATCHES/<package>.README. In this example, it would be stored as ~/sources/boffo-1.0/CYGWIN-PATCHES/boffo.README. The build script will ensure that it gets installed as /usr/share/doc/Cygwin/boffo-1.0.README
    • Prepare the staging location for the -src package (yes, do the -src package first): From the directory above your boffo-1.0 tree (e.g. ~/sources/ in our example) execute './boffo-1.0-1.sh mkdirs'
    • Create the -src package: './boffo-1.0-1.sh spkg'
    • Now, let's go somewhere else and unpack this new -src package:
      cd /tmp
      tar xvjf ~/sources/boffo-1.0-1-src.tar.bz2
      
    • Finally, rebuild the whole thing (you're still in /tmp):
      ./boffo-1.0-1.sh all
      
      (Or, you may want to do each step in 'all' manually: prep, conf, build, (check), install, strip, pkg, spkg, finish.

Creating a package postinstall script

If your package requires certain commands to be executed after the files in the package are installed, include them in a file in the package called /etc/postinstall/package.sh or /etc/postinstall/package.bat.

If the file's name ends in ".sh", it is executed with the Cygwin shell; if it ends in ".bat", it is executed with the DOS command interpreter. If it doesn't end with either of these suffixes, it is ignored.

After the script has been run it is renamed by appending the suffix ".done" to its previous name, to prevent it from being run again the next time the user runs the setup program.

Note that the setup program runs all the postinstall scripts after all desired packages have been installed, that is, it does not run each package's postinstall script immediately after installing that package. Note, furthermore, that the order in which the scripts are run is not guaranteed. Therefore, if your package depends on others which have their own postinstall scripts, you cannot assume in your script that the other packages' scripts have already been run.

Submitting a new package

So you've got a package you want to submit. Follow the following checklist before emailing cygwin-apps@cygwin.com and you'll almost certainly save time.

  1. Do you have the time to maintain the package?
    Packages without active maintainers are pulled from the distribution. Generally speaking the time commitment is relatively low, simply subscribe to cygwin@cygwin.com. We'd prefer if you read the non-digest mode since prompt response to packaging issues is a plus. When a bug in your package is reported in the cygwin mailing list, address the bug (if it's a cygwin-only bug) or pass back to the vendor. When a solution exists, create an updated package with the fix in it, and send a notification that you need the package uploaded to cygwin-apps. Note that you are not expected to be a helpdesk for the package - the users should be pointed to the vendors lists if you've determined that the bug is not a cygwin-related bug.
  2. Propose on cygwin-apps@cygwin.com that you are interested in becoming a package maintainer for package "foo" using a subject like "[ITP] foo 0.10". Some packages cannot be distributed via cygwin's setup due to vendor licence limitations. Other packages may not be appropriate for cygwin. This step will save time if, for some reason, we cannot accept the package.
    Submission rules:
    • Include a complete setup.hint file as part of your proposal. Include this file in the text of your message so that it can be commented on. Do not submit it as an attachment.
    • If the new package is a well-known program already included in a major Linux distribution (e.g. Debian, Fedora, SuSE) please include the URL of the package page. Note that "development", "test", and "unstable" packages are not eligible for this rule.
    • If the package is not included in any major Linux distro it must receive five positive votes from other package mantainers in order to be accepted.
  3. In order to create a good setup.hint file do read and follow the documentation in the specific section of this very web page.
    A few things to take extra care to:
    • Avoid the "@ foo" line at the beginning of the file: it is added automatically.
    • In order to select an appropriate a correct Category you can look in the Debian package list and identify the section that your package is present in there - if it's available via Debian. If it's not, have a look and take a sensible guess. Use existing categories if at all possible.
    • Do not use the package name in sdesc, as it is added automatically by setup.exe.
    • Opinion on whether to mark your initial version as a Test version is currently mixed. If you have doubts about the stability of your initial offering you may decide to mark it as Test. Then, once the package has no major bug reports from users, a current package may be introduced. Otherwise, it is perfectly acceptable to forgo the Test designation in your first release.
  4. Place the package files in a web accessible http/ftp site somewhere. If at all possible the files should have a directory structure in order to get them all with a single command. For example, if I am proposing "foo" and "libfoo", an upload site should look like:
    • myserver.com/whatever/foo/foo-0.20.3-1.tar.bz2
    • myserver.com/whatever/foo/foo-0.20.3-1-src.tar.bz2
    • myserver.com/whatever/foo/setup.hint
    • myserver.com/whatever/foo/libfoo/libfoo-0.20.3-1.tar.bz2
    • myserver.com/whatever/foo/libfoo/setup.hint
  5. Announce on cygwin-apps@cygwin.com that you have the package ready for uploading. Provide the URLs of all package files to your mail.
  6. Each new package must in any case receive one GTG vote from a package mantainer, meaning that an existing mantainer has downloaded the package, inspected the tarball contents, tested the applications, and rebuilt the package from the source tarball without incident. Once a successful package is produced, you become a mantainer yourself and can provide GTG reviews for others as well.
  7. Feel free to delete your temporary copy once the files have been uploaded to sourceware.org.
  8. Announce via cygwin-announce@cygwin.com that the new package is available. Use the announce message example listed later in this page as a template for your announcement.
    Be sure the unsubscribe instructions are included at the end of the email, since cygwin-announce does not add any.
    Once sent, your message will be reviewed by one of the cygwin-announce moderators and, once approved, will be automatically forwarded to the cygwin mailing list with an [ANNOUNCEMENT] prepended to the subject.

Package acceptation

  1. Build the package and make sure that you have time to maintain it.
  2. Send an ITP to the cygwin mailing list. If the package is part of a distribution, include the URL which demonstrates this. Include a setup.hint.
  3. If you have received the correct number of votes or if the package is part of a distribution, include URL(s) for the package binary and source so that someone can download them to check the package for any obvious problems.
  4. Once you get a GTG from a package maintainer, send a "Please upload" to the cygwin-apps mailing list.
  5. When you get the "uploaded" confirmation, send an immediate note to cygwin-announce@cygwin.com.

Updating a package

So you've got an updated package you want to submit. Follow the following checklist before emailing cygwin-apps@cygwin.com and you'll almost certainly save time.

  1. Place the package files in a web accessible http/ftp site somewhere. If at all possible the files should have a directory structure in order to get them all with a single command. For example, if I am updating "foo" and "libfoo", an upload site should look like:
    • myserver.com/whatever/foo/foo-0.21.1-1.tar.bz2
    • myserver.com/whatever/foo/foo-0.21.1-1-src.tar.bz2
    • myserver.com/whatever/foo/libfoo/libfoo-0.21.1-1.tar.bz2
  2. Do increase the version number no matter what (if upstream version didn't change, bump the cygwin release number): even if the package was bad, even if it was removed from the server for a security issue, even if has only been discussed in mailing list and never uploaded: it costs nothing and avoids confusion in both setup.exe and people mind.
  3. Announce on cygwin-apps@cygwin.com that you have the package ready for uploading. Include in the mail the URLs of all the new package files.
    Be concise in your message: as package mantainer you're trusted to know when and how your packages should be updated, no reason to explain it.
    Just provide URLs for files that have actually changed, i.e. it is not necessary to provide a new link to a setup.hint file every time you update your packages unless the actual content changed (e.g. because version numbers are not parsable or ordered and have to be specified manually).
    Please do specify which version must be kept as "old", all the others will be deleted from the server.
  4. Feel free to delete your temporary copy once the files have been uploaded to sourceware.org. This fact will be made clear by an "Uploaded." reply to your announcement by someone with upload privileges.
  5. Announce via cygwin-announce@cygwin.com that the new package is available. Use the announce message example listed later in this page as a template for your announcement..
    Once sent, your message will be reviewed by one of the cygwin-announce moderators and, once approved, will be automatically forwarded to the cygwin mailing list with an [ANNOUNCEMENT] prepended to the subject.

NOTE: On any major version upgrade, you may want to mark the release as Test.

Example announcement

To: cygwin-announce@cygwin.com
Subject: New package: foo-0.30.2-1
or
Updated: foo-0.30.2-1
Version 0.30.2-1 of "foo" has been uploaded.

(a couple of lines about what "foo" is)
(short changelog of important features or fixes; big emphasis for security fixes)

If you have questions or comments, please send them to the Cygwin mailing list at: cygwin@cygwin.com .

              *** CYGWIN-ANNOUNCE UNSUBSCRIBE INFO ***

If you want to unsubscribe from the cygwin-announce mailing list, look at the "List-Unsubscribe: " tag in the email header of this message. Send email to the address specified there. It will be in the format:

cygwin-announce-unsubscribe-you=yourdomain.com@cygwin.com

If you need more information on unsubscribing, start reading here:

http://sources.redhat.com/lists.html#unsubscribe-simple

Please read *all* of the information on unsubscribing that is available starting at this URL.