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.
Contents
- Making a package with cygport
- Locally installing your package for testing
- Marking your package as a test version
- Submitting a package
- Adopting an orphaned package
- Uploading a package
- Updating a package
Making a package with cygport
While older, hand-made packages exist, the only accepted way to make a new
Cygwin package is using the cygport tool, which automatically handles most
packaging requirements and 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.
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-fix-whatever.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 # .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 a .hint generated by running cygport
, e.g.
$ cygport boffo.cygport fetch --2017-04-01 11:59:59-- http://boffo.org/downloads/boffo-1.0.tar.xz Resolving boffo.org... 209.197.75.87 Connecting to boffo.org|209.197.75.87|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 352 [application/x-tar] Saving to: ‘boffo-1.0.tar.xz.tmp’ boffo-1.0.tar.xz.tmp 100%[===================>] 352 --.-KB/s in 0s 2017-04-01 11:59:59 (8.06 MB/s) - ‘boffo-1.0.tar.xz.tmp’ saved [352/352] $ cygport boffo.cygport all >>> Preparing boffo-1.0-1.x86_64 >>> Unpacking source boffo-1.0.tar.xz *** Info: applying patch boffo-1.0-fix-whatever.patch: >>> Preparing working source directory >>> Compiling boffo-1.0-1.x86_64 [...] >>> Installing boffo-1.0-1.x86_64 [...] Fixing symlinks: Stripping executables: usr/bin/boffo.exe Preparing debuginfo source files: 1 files >>> Packaging boffo-1.0-1.x86_64 >>> Creating binary package(s) >>> boffo-1.0-1.tar.xz usr/ usr/bin/ usr/bin/boffo.exe usr/lib/ usr/share/ usr/share/doc/ usr/share/doc/boffo/ usr/share/doc/boffo/README >>> boffo-debuginfo-1.0-1.tar.xz usr/lib/debug/ usr/lib/debug/usr/ usr/lib/debug/usr/bin/ usr/lib/debug/usr/bin/boffo.exe.dbg usr/src/debug/ usr/src/debug/boffo-1.0-1/ usr/src/debug/boffo-1.0-1/boffo.c >>> Checking packages for missing or duplicate files >>> Creating source patches 0 files changed >>> Creating source package boffo-1.0-1.src/ boffo-1.0-1.src/boffo-1.0-fix-whatever.patch boffo-1.0-1.src/boffo-1.0.tar.xz boffo-1.0-1.src/boffo.cygport >>> boffo requires: cygwin libncursesw10
For more information on using cygport
consult the
man page,
README,
reference manual
and sample .cygport files.
Locally installing your package for testing
Unfortunately, there is no tool for directly installing package files, at the moment. Two common techniques to achieve this:
-
For simple packages you can fake installation by directly untarring the
package file and then running any
postinstall scripts
manually:
$ tar -C / -xvf boffo-1.0-1.x86_64/dist/boffo/boffo-1.0-1.tar.xz $ /etc/postinstall/boffo.sh
-
For multiple packages with complex dependencies, you can use
an overlay package server. Note
that
setup
can acceptfile://
URLs so an FTP or HTTP server is not necessary.
Marking your package as a test version
Packages can be marked as test versions, which are not offered for installation by setup unless the use of test packages has been opted-into, by usingcygport all-test
, rather than cygport all
.
Building the packages in that way adds a
test:
hint.
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.
-
Do you have the time to maintain the package?
Packages without an active maintainer may be pulled from the distribution. Generally speaking the time commitment is relatively low, simply subscribe to the
cygwin
mailing list. 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 upstream if you've determined that the bug is not a Cygwin-related bug. -
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:
- If the new package is a well-known program already included in a major Linux distribution (e.g. Debian, Fedora, SuSE) please mention that.
- 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.
- Mention which open source license applies to the source.
-
Write good package metadata
- In order to select an appropriate a correct
category
you can look in e.g. 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 thesetup
program.
- In order to select an appropriate a correct
-
If at all possible, build the package and place the package files on a publicly accessible HTTP/FTP site, and provide the URL in your mail.
- 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.
- 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.
Adopting an orphaned package
Unfortunately some packages are without a maintainer, and volunteers to take over are welcome.
- Find the appropriate source package in the source package list.
-
The package summary page should link to the packaging git repository,
containing the
.cygport
and patch files.git clone
that repository from the listed URL (for some older packages, this repository may not exist yet, in which case, install the source package usingsetup
instead). -
Edit the
.cygport
file to adjust the version appropriately. -
cygport package.cygport download all check
- Fix any problems! (Consider looking at e.g. upstream bug reports and fixes, and patches applied in Linux distributions to avoid duplicating effort).
-
email the
cygwin-apps
mailing list, as in submitting a new package, except use "[ITA]" rather than "[ITP]" in the subject.
Uploading a package
- Once you have your GTG, follow the instructions for submitting a ssh key and uploading your package files.
- Please remember to build and upload packages for all architectures (x86 and x86_64).
-
Announce via the
cygwin-announce
mailing list that the new package is available. See the announce message template later in this page. -
If you encounter any problems, email the
cygwin-apps
mailing list. - 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 should already have upload privileges, and should be able to do the entire process yourself.
- You must increase the version or release number. Reset the release number to 1 on a version increase.
- Follow the steps to upload, as above.
NOTE: On any major version upgrade, you may want to mark the release as test
.
Composing an announcement mail
cygport announce
can help you compose and send an announcement mail,
based on the following template.
The following packages have been uploaded to the Cygwin distribution:
* foo 0.30.2-1
(a couple of lines about what "foo" is)
(short changelog of important features or fixes; big emphasis for security fixes)
(paths or links to installed and online changelogs, with more details)
--
*** 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:
https://sourceware.org/lists.html#unsubscribe
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 [ANNOUNCEMENT]
prepended to the subject.