Cygwin

Get that Linux feeling - on Windows

Cygwin Package Contributor's Guide

This document is intended for people who upload packages to sourceware.org, to be made available through the standard Cygwin setup program. This documents the syntax of the setup.hint file, the layout required for packages, and the related policies to ensure good behaviour from the setup program.

Setup depends on certain conventions being followed. If they are not followed, bad things may happen to the users of the setup program. Where a convention can be ignored, should circumstances warrant, this document will specify that. Setup has it's own homepage. If you are interested in adding features to setup, you should consult the setup homepage. If you are interested in creating a local mirror with or without custom Cygwin packages, see the package server page.

The cygwin-apps mailing list 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 the cygwin mailing list instead.

Contents

Package file naming scheme

Use the upstream's version plus a release suffix (i.e. findutils 4.5.12 becomes 4.5.12-1, 4.5.12-2, etc., until findutils 4.5.13 is packaged, which would be 4.5.13-1, etc). Some packages also use a YYYYMMDD format for their versions, e.g. terminfo-5.9-20140524-1.tar.xz. The first release of a package should have a -1 release suffix.

A complete package currently consists of three files:

e.g.:

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

Binary tar files generally contain the executable files that will be installed on a user's system plus any auxiliary files needed by the package. See the package contents section below for more details on the contents of a binary tar file.

Source tar files should contain the source files, patches and scripts needed to rebuild the package. While installing these files is optional, 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 associated shared library in "libboffo7", where both are generated from the same source tar file. See the package contents section below for more details on the contents of a source tar file, and the setup.hint section for information on the "external-source:" option.

Note that package files may be .bz2, .gzip or .xz compressed. .gzip is deprecated and .xz is preferred for new package submissions.

The version and release must start with a digit. The release must not contain a hyphen.

Version and release sort according to the following rules:

A package with a higher version is greater, regardless of the release. When two packages have an identical version, the one with the higher release is greater.

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
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.

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 or test options. Instead, we relied on setup 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 source 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 package files:

boffo-2.4.1-2.tar.xz, boffo-2.4.1-2-src.tar.xz, and the boffo setup.hint would go into the release/boffo/ subdirectory. libboffo7-2.4.1-2.tar.xz 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.xz
source: release/boffo/boffo-2.4.1-2-src.tar.xz
@ libboffo7
requires: cygwin
version: 2.4.1-2
install: release/boffo/libboffo7/libboffo7-2.4.1-2.tar.xz
source: release/boffo/boffo-2.4.1-2-src.tar.xz

Note that both packages point to the same source tar file. Also, it is required that the versions match (libboffo7-5.2 can't point to boffo-1.4-src). The same logic is used to "match up" prev: and test: versions with their external sources.

Package contents

The files paths within both the source and the binary package files are quite important. Since setup 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.

While older packages exist which satisfy these requirements by hand, the only accepted way to make a new Cygwin package is using the cygport tool, which automatically handles most of the above issues for you. It is also strongly recommended to convert existing packages to cygport when updating them; ask on the cygwin-apps list if you need help converting an existing package to use cygport.

Making a package with cygport

The cygport framework improves on previous Cygwin build scripts, and borrows concepts from the Gentoo portage system.

Suppose that the upstream's boffo-1.0.tar.xz source tar file, that you downloaded from the boffo homepage, unpacks into boffo-1.0/.

Further, suppose you've got "boffo" ported to Cygwin. It took some work, but you've got a patch file, which we will name boffo-1.0-1.src.patch, and with that applied 'boffo' builds and runs.

All that remains is to write a 'boffo.cygport' file which will describe how to unpack, configure, build and package:

# package name
NAME="boffo"
VERSION=1.0
RELEASE=1

# setup.hint generation
CATEGORY="Games"
SUMMARY="A whackamole simulation in ASCII art"
DESCRIPTION="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."

# source and patch files
SRC_URI="http://boffo.org/downloads/boffo-${VERSION}.tar.xz"
PATCH_URI="boffo-1.0-fix-whatever.patch"

# use the standard src_compile, src_install and src_test

The source and binary packages can then be built and setup.hint generated by running 'cygport boffo.cygport all'.

For more information on using cygport consult the man page, README, reference manual and sample .cygport files.

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 successfully 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 the cygwin-apps mailing list 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 the cygwin mailing list. 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 upstream. When a solution exists, create and upload an updated package with the fix in it. Note that you are not expected to be a helpdesk for the package - the users should be pointed to the upstream's lists if you've determined that the bug is not a Cygwin-related bug.
  2. Propose on the cygwin-apps mailing list 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 upstream 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 maintainers in order to be accepted.
    • It's helpful to mention which open source license applies to the source.
  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:
    • 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 the setup program.
    • 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/x86/foo/foo-0.20.3-1.tar.xz
    • myserver.com/whatever/x86/foo/foo-0.20.3-1-src.tar.xz
    • myserver.com/whatever/x86/foo/setup.hint
    • myserver.com/whatever/x86/foo/libfoo/libfoo-0.20.3-1.tar.xz
    • myserver.com/whatever/x86/foo/libfoo/setup.hint
  5. Announce on the cygwin-apps mailing list 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 maintainer, meaning that an existing maintainer has downloaded the package, inspected the tar file contents, tested the applications, and rebuilt the package from the source tar file without incident. Once a successful package is produced, you become a maintainer yourself and can provide GTG reviews for others as well.

Uploading an accepted package

  1. Once you have your GTG, follow these instructions for submitting a ssh key and uploading your package files.
  2. Announce via the cygwin-announce mailing list 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.
  3. Feel free to delete your local copy once the files have been uploaded to sourceware.org.

Updating a package

So you've got an updated package you want to submit. You should already have upload privileges, and should be able to do the entire process yourself, by following these instructions. If you encounter any problems, email the cygwin-apps mailing list.

  1. There is no need to increase the release number if the package has not been officially released. So, if you are releasing a -1 release of a package keep using -1 for any refinements until the package has been uploaded.
  2. Thereafter, you must increase the version or release number when uploading an updated version of the package.
  3. After doing a upload, announce via the cygwin-announce mailing list 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


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)

              *** 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 <at> cygwin.com

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

http://sourceware.org/lists.html#unsubscribe-simple

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