Tips for writing a .cygport file

• A cygport file is a bash shell script fragment, which defines some variables, and (maybe) the src_compile(), src_install() and src_test() functions.

• By default, cygport assumes an autotools build system (./configure ${CYGCONF_ARGS}; make; make install DESTDIR=${D}) using the autotools cygclass. See the examples there.

  Those examples can also serve as a starting point for packaging small source packages which have a very simple build system, e.g. only a Makefile.

  If the upstream sources uses a different build systems, inherit the appropriate cygclass (e.g. cmake, meson, waf) to get appropriate src_compile(), src_install() and src_test() functions.

• Various cygclasses exist to simplify working with several large meta-projects, language-specific package repositories, or languages. Refer to the full list of cygclasses in the reference manual.
• When the upstream source is delivered directly from a VCS, rather than as an archive, cygclasses exist to assist in retrieving that source (e.g. bzr, cvs, fossil, git, hg, mtn, svn).
• If the files in the upstream source archive are not under a $NAME-$VERSION top-level directory, define SRC_DIR appropriately.
• If the package is arch-independent, define ARCH=noarch.

• If the package is just an executable, the default of generating one install package called NAME is probably all you need.

  If it's a library, you'll probably want to set PKG_NAMES to a value listing the install packages: libboffoN (where N is the soversion) (containing the shared library runtime), libboffo-devel (containing headers, link libraries, pkgconfig files and tools for developing with the library), maybe libboffo-doc (if there's a large amount of non-manpage documentation), maybe boffo (if there's user tool(s) provided with the library), and maybe more.

• When packaging a versioned shared library like libboffoN (where N is the soversion), it's best practice to describe it's contents using glob(s) which explicitly match against the soversion. At it's simplest, this means something like:

  libboffo0_CONTENTS="
    usr/bin/*-0.dll
    usr/share
  "
  

  So that if and when the soversion changes, packaging fails, rather than silently ploughing on to create a libboffo0 containing cygboffo-1.dll (which would, when installed, break any packages depending on libboffo0 to provide cygboffo-0.dll ).

• If a library supports building as a shared or static library, usually only a shared library should be built and packaged.

  Common exceptions are:

  • MinGW cross-packages should probably contain both, so that users can choose to build monolithic, statically-linked executables, which can be easily distributed without an installer.
  • soversion-less libraries where upstream recommends a static library, e.g. because the API isn't stable.

• When removing a package name from PKG_NAMES you should consider what you want to happen in Cygwin installations where that package is already present. Just remaining installed indefinitely is not usually what's wanted, so a superseding or replacement package in the same or a different cygport should OBSOLETES it. Versioned shared libraries are an obvious exception to this rule.

• Use make_etc_defaults on files installed into /etc which are expected to be customized locally, so those customizations aren't lost when the package is upgraded.
• If the upstream source only builds in the source directory, use lndirs, e.g.:

  src_compile() {
    cd ${S}
    cygautoreconf
    lndirs
    cd ${B}
    cygconf
    cygmake
  }
  

• If your package(s) install a python module into /usr/lib/python3.N/site-packages/, along with a python script with a #! line containing /usr/bin/python3 into /usr/bin/, you might need to use python3_fix_shebang to ensure that line is rewritten to ensure that the python version used is the same one for which the module is installed.

  Similar considerations may apply with other interpreted languages which support parallel installation of multiple versions, e.g. see lua_fix_shebang, php_fix_shebang, etc.

• If you need to programmatically generate a package name, you can use declare to set it's contents etc., e.g.:

  inherit python3 meson
  ...
  PKG_NAMES="foo libfoo1 libfoo-devel python3-foo python${PYTHON3_PKGVERSION}-foo"
  ...
  python3_foo_SUMMARY="Python bindings for libfoo"
  python3_foo_REQUIRES="python${PYTHON3_PKGVERSION}-foo"
  python3_foo_CATEGORY="Virtual Python"
  
  declare python${PYTHON3_PKGVERSION}_foo_SUMMARY="Python ${PYTHON3_VERSION} bindings for libfoo"
  declare python${PYTHON3_PKGVERSION}_foo_CONTENTS="usr/lib/python*/"
  declare python${PYTHON3_PKGVERSION}_foo_CATEGORY="Python"
  

• If your package installs shared libraries into a private directory (e.g to be used as plugins by an executable in that or a different package), you'll want to list that directory in DEPS_PATH so that they are checked for dependencies.

• If the build generates (or even modifies!) files in the source directory, those files should probably be listed in DIFF_EXCLUDES to indicate to cygport that those changes don't need to be packaged.
• A data only package probably wants a src_compile function which does nothing, e.g.:

  src_compile() {
    true
  }
  

• Where you need to deviate from cygport's default behaviour, a comment in the cygport file explaining why that's necessary is always helpful.
• Shell code which does something other than determine the value of a variable is probably suspect: It will execute every time the cygport is sourced, irrespective of what subcommand is used. If you're checking something about the execution environment, or modifying files in some way, that probably belongs in a src_* function, or in some (perhaps yet to be implemented) hook.
• Cygports (and the underlying build and install mechanisms) are allowed to assume the filesystem is case-sensitive. If you happen to be building one of the rare ones which requires that, and your filesystem is not case-sensitive (perhaps because a Windows update has reset obcaseinsensitive), you lose, probably with a confusing error message.
• The lines within the .cygport file defining NAME, VERSION and RELEASE are expected to be eval-able on their own (so we can determine the working directory name and create it, before source-ing the cygport file itself) - so no defining these in terms of other variables or by complex logic.
• If you think you've found a cygport bug, use cygport --debug to produce very, very verbose debug output.
• If you don't understand something, or need help, ask on the cygwin-apps list or #cygwin IRC channel.