Cygwin package .hint files

Contents

• package-version-release.hint file
• external-source:
• package-version-release-src.hint file
• override.hint file

package-version-release.hint file

Lines in package-version-release.hint consist of one of the following:

# comment
sdesc: "some text"
ldesc: "some text"
category: name1[ name2...]
requires: version-relation[ version-relation...]
obsoletes: version-relation[ version-relation...]
provides: package[, package...]
conflicts: version-relation[, version-relation...]
external-source: package
message: id "some text"
test:
version: version-identifier
disable-check: check-name [check-name...]

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

• Use UTF-8 character encoding.

• Lines that begin with '#' are comments and are ignored.

• sdesc is a one line description of the package, enclosed in double-quotes. This is the information that will be displayed when installing packages via setup.

  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"
  

  sdesc is a mandatory line.

• ldesc is a more descriptive, multi-line description of the package, enclosed in double-quotes. 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."
  

  Note that there is currently no method for escaping double-quotes, so there is no way to represent a double-quote embedded in the ldesc.

• 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. At the time of writing, the current categories are:

  Accessibility

  Admin

  Archive

  Audio

  Base

  Database

  Debug

  Devel

  Doc

  Editors

  Fonts

  Games

  GNOME

  Graphics

  Interpreters

  KDE

  Libs

  Lua

  LXDE

  Mail

  MATE

  Math

  Net

  Ocaml

  Office

  Perl

  PHP

  Publishing

  Python

  Ruby

  Scheme

  Science

  Security

  Shells

  Sugar

  System

  Tcl

  Text

  Utils

  Video

  Virtual

  Web

  X11

  Xfce

  As you can see, currently, all categories consist of only a single word. We don't anticipate that this will change anytime soon.

  category is a mandatory line.

• 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 can rely on multiple other packages.

  Do not include transitive dependencies, unless they are also direct dependencies. i.e. don't drop 'bar' from your dependency list if your package requires it, even if you are including 'foo' which also relies on 'bar'.

  If you think that another package has an incorrect dependency list, send email to cygwin-apps noting that fact.

  • Multiple packages may be separated by spaces or commas.
  • Do not enclose multiple package names within quotation marks.
  • See relationship fields for details of the optional version-relation syntax.

• provides indicates additional package requires: and depends: that this package satisfies.

• conflicts indicates the packages that this package conflicts with. See relationship fields for details of the syntax.

• obsoletes indicates the packages that this package supersedes. See relationship fields for details of the syntax.

• external-source. See the section on external-source.

• The message line indicates text that will be displayed by the setup program when the package is installed.

  This should be used extremely sparingly, for example, if a 3rd party driver or service needs to be installed in Windows for the package to function.

  The id used should be derived from the package name. Currently, the text for a given id will be shown by setup exactly once, when the package is first installed, even if the text subsequently changes.

• test indicates this is a test package. When the use of test packages is enabled in setup, the highest version-release marked as a test package will be installed.

  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.

• version overrides the version-release, which is otherwise inferred from the version-release part of the filename.

• disable-check disables the named checks for this package.

Here's an example of a complete release/boffo/boffo-1.0-1.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."

external-source:

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: an installable package that contains all of the normal contents of boffo -- except for the shared library.
• libboffo7-2.4.1-2.tar.xz: an installable package that contains only the shared library from boffo
• boffo-2.4.1-2-src.tar.xz: the source package for boffo.

boffo-2.4.1-2.tar.xz, boffo-2.4.1-2-src.tar.xz, and boffo-2.4.1-2.hint would go into the release/boffo/ subdirectory. libboffo7-2.4.1-2.tar.xz, and libboffo7-2.4.1-2.hint would go into a separate subdirectory, such as release/boffo/libboffo7/. The two .hint files would look something like this:

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 .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 version-release matches (i.e. libboffo7-5.2-1 can't point to boffo-1.4-1-src). The same logic is used to "match up" other versions with their external sources.

package-version-release-src.hint file

# comment
build-depends: dependency-atom[ dependency-atom...]
category: name1[ name2...]
disable-check: check-name [check-name...]
homepage: url
ldesc: "some text"
license: license-expression
sdesc: "some text"
skip:
test:
version: version-identifier

As above, and:

• build-depends is a list of packages that are needed to build this source package.

• homepage records the URL of the upstream homepage.

• license is an SPDX license expression for the open source license(s) of the package source code.

• skip is obsolete.

  It was only useful for indicating directories which contain source-only packages, which are now automatically recognized, irrespective of skip.

override.hint file

An override.hint file may exist, for information not associated with a specific version-release.

# comment
keep: version-identifier[ version-identifier...]
keep-count: count
keep-count-test: count
keep-days: days
keep-superseded-test:
disable-check: check-name [check-name...]
replace-versions: version-identifier [version-identifier...]

• Lines that begin with '#' are comments and are ignored.

• The various keep* keys can be used to override the default package expiry settings, which control when old package versions are automatically removed.

  • All package version-releases listed in a keep line are always kept.

  • A keep-count line causes the highest count non-test versions to be kept.

  • keep-count-test, likewise, for test versions.

  • A keep-days line causes the first version which is less than days days old, and all higher versions to be kept.

  • By default, a version labelled test: is expired when a superseding non-test version exists. keep-superseded-test disables that behaviour.

• disable-check disables the named checks for all versions of this package.

• replace-versions lists version-releases which should always be replaced.

  This is intended for (temporarily) dealing with withdrawn versions, e.g. those which have been removed (or relabelled as test), without a superseding higher version existing, and indicates that the named versions(s), if installed, should be replaced with by the current version, even if lower.