Cygwin package .hint files

Contents

• package-version-release.hint file
• package-version-release.hint file (Advanced Options)
• override.hint file
• setup.hint file

package-version-release.hint file

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

# comment
sdesc: "some text"
ldesc: "some text"
category: name1[ name2...]
requires: package[ package...]
depends: version-relation[, version-relation...]
obsoletes: version-relation[, version-relation...]
build-depends: dependency-atom[ dependency-atom...]
external-source: package
message: id "some text"
test:
skip:
version: version
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. It is intended for future use. 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

  Comm

  Database

  Devel

  Doc

  Editors

  Games

  GNOME

  Graphics

  Interpreters

  KDE

  Libs

  Lua

  LXDE

  Mail

  MATE

  Math

  Mingw

  Net

  Ocaml

  Office

  Perl

  PHP

  Publishing

  Python

  Ruby

  Scheme

  Science

  Shells

  Sugar

  System

  Tcl

  Text

  Utils

  Video

  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 are separated by spaces. Do not enclose multiple package names within quotation marks.

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

• depends indicates the packages that this package relies upon, in a more sophisticated way than requires:. See relationship fields for details of the syntax.

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

• build-depends indicates the binary packages that are needed to build this source package. This is a space-separated list of cygport(1) dependency atoms.

• test indicates this is a test package. The highest version marked as a test package will be installed by setup, when use of test packages is selected.

  With the current setup implementation, it will also mean that it will be overlooked by most people during installation.

  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.

• skip is obsolete.

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

• version overrides the version, 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."

package-version-release.hint file (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: 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:

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

override.hint file

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

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

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

• The curr line indicates which version of that package should be normally installed by setup. Use this setting only if you need to circumvent the normal version ordering.

  By default, the highest version-release number is used for the current version of a package.

  Use of curr is usually not required. e.g. if you had previously released boffo-0.9-1 and now have a new boffo-1.0-1, there is no need to use curr as 1.0-1 is greater than 0.9-1.

  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 an entry like this:

  curr: 0.9-1
  

  This usage should be rare, however.

• Any test line indicates which version of that package should be installed by setup, when use of test packages is selected.

  So, something like "test: 1.9-1" will cause setup to characterize the 1.9-1 version as a "test" package.

  This should be obsolescent to the use of test: lines in package-version-release.hint.

• prev is obsolete, as setup no longer supports explicitly installing prev versions, so it now just indicates that the package should also be retained, and thus is equivalent to keep.

• keep, keep-count and keep-days can be used to override the default package expiry settings, which control when old package versions are automatically removed.

  All package versions listed in any keep line are always kept.

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

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

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

• replace-versions lists versions 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.

setup.hint file

A setup.hint which acts as a package-version-release.hint for all version-release and as a override.hint is also supported, for backwards compatibility.