Cygwin Package Contributors GuideThis document is intended for people who post packages to sources.redhat.com, and thus need to make them available through the standard Cygwin setup program. This documents the syntax of the setup.ini 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 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. 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. ContentsPackage file namingPackage 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:
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. See the making packages section below for more details on the contents of a -src tar file.. The setup.hint file is discussed below. Automatic setup.ini generation on sources.redhat.comA script runs on sources.redhat.com 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.hintEach 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...] (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. 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-1This 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-1then 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 and ldesc are both mandatory fields for setup.hint. Your package must contain these fields. In particular, 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 no 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:
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.iniNote that setup.ini is automatically generated. This section is for completeness, not instruction. Setup reads a file called setup.ini that resides on all cygwin FTP mirrors. There are a two global parameters in this file, followed by a list of packages. Any line beginning with # is ignored by setup and can be used to add commentary to the file at any point. setup-timestamp: number This line is at the beginning of all setup.ini files. It indicates the time that the setup.ini file was created. Its only purpose is to warn the user when the timestamp is less than the last setup.ini used; i.e. it prevents accidental regression. Use "perl -e 'print time'" to get a timestamp.setup-version: number This line follows the setup-timestamp in all setupl.ini files. It indicates the version number of the setup.exe for which this setup.ini was generated.@ package Lines beginning with the "at" symbol indicate the start of a package section. Each package consists of a name, one or more descriptive texts, package categories, package requirements, and up to three version definitions.sdesc: "some text" This is the "short description" of the package. This text, if available, accompanies the package name in package listings.ldesc: "some text" This is the "long description" of the package. This text, if available, is used as a supplimental description of the package.category: name1[ name2...] The category line indicates the categories that this package belongs to. One package can belong to multiple categories. Multiple categories are separated by spaces. See the description of categories in setup.hint above for more information on categories.requires: package[ package...] The requires line indicates the packages that this package belongs to. A package can rely on multiple packages. Multiple packages are separated by spaces.[curr] version: version Indicates the version of the package. This is currently derived from the name of the package.install: filename size-in-bytes Indicates the file to install for that version, and its size in bytes. The file name must include the full path (relative to setup.ini's directory), and the file size must match the actual file size (setup uses this to verify it got the whole file).source: filename size-in-bytes Like the file to install, this is the corresponding sources.Examplesetup-timestamp: 967844652 @ cygwin sdesc: Cygwin Runtime ldesc: A Posix runtime emulator for Windows platforms version: 1.1.4 install: release/cygwin/cygwin-1.1.4.tar.bz2 1234567 source: release/cygwin/cygwin-1.1.4.tar.bz2 1341245 [prev] version: 1.1.3 install: release/cygwin/cygwin-1.1.3.tar.bz2 1234580 source: release/cygwin/cygwin-1.1.3.tar.bz2 1341123 @ bash [test] version: 20000901 install: release/bash/bash-20000901.tar.bz2 276403 source: release/bash/bash-20000901-src.tar.bz2 1892899 [curr] version: 2.04 install: release/bash/bash-2.04.tar.bz2 277375 source: release/bash/bash-2.04-src.tar.bz2 1815177 Making PackagesThe 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.
Package SourceThere are two accepted ways to package the source code for cygwin packages. Method One
Method Two
Creating a package postinstall scriptIf 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 packageSo 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.
NOTE: On any major version upgrade, you may want to mark the release as Test. |