cygport is the standard method for building and maintaining packages for
the Cygwin distribution.
1. BACKGROUND
In the past, the sanctioned way of building a Cygwin package was by
using a build script, the template for which is commonly known as the
generic-build-script, or g-b-s[2].
However, the g-b-s has many drawbacks:
1) Even the simplest changes, such as adding an argument to configure,
requires wading through the entire 500+ line script; many beginners
have struggled with their first packages.
2) Having a history as a ash script, it is nearly impossible to read, with
run-on commands, && continuations, and backslash-escaped line breaks.
3) It is aimed primarily at autotooled packages, and adapting it to
other packaging systems (e.g. perl MakeMaker, python Distutils,
stand-alone Makefiles, etc.) requires having several "branches" of the
script for each purpose.
4) Updating to a newer script requires either merging package-specific
changes into a new template (and not forgetting anything), or
back-porting g-b-s changes into an existing package script.
5) There is no simple method of dealing with an original source package
whose name or top directory do not conform with the PKGNAME-VERSION
form, or where the Cygwin package name differs from the upstream name
(e.g. gtk2.0 from gtk+).
6) It is not designed to create more than one binary package per source
package -- e.g. whereby the foo source is separated into foo, libfoo1,
and libfoo-devel binary packages -- despite the fact that is often
desirable to do so.
Having used the g-b-s in various forms for a couple of years, during
which I've packaged hundreds of unique source packages (not counting
versions), I have found various ways of 'getting by'. I forked the
g-b-s a while back, and created a few templates for various purposes.
This solution, however, is still severely limiting, as mentioned above.
In the meantime, I also had exposure to a Linux distribution and its
packaging system, namely Gentoo Linux and Portage. Being a source-based
distribution, the entire packaging database consists of a collection of
scripts (ebuilds), which contain basic information about the package,
and the steps necessary to compile and install (into a DESTDIR) the
package. With the repository available through WebCVS, it is indeed an
invaluable resource to anyone building a non-trivial package from
scratch.
In fact, Portage answers many of the drawbacks of the g-b-s:
1) Ebuilds are small, containing only package-specific information,
making them easy to read, and even to create with little effort.
2) Ebuilds are written in a clean bash syntax.
3) The Eclass system allows ebuilds to be easily extended to any number
of different build systems (Perl, Python, Ruby, etc.) and/or categorical
templates (e.g. GNOME or KDE).
4) Updates to Portage take affect immediately, without updating all
ebuilds, and ebuilds can be created without even looking at the
internals of Portage itself.
5) Ebuilds anyway define the source package name, and can easily
override the assumed source top directory when necessary.
Despite it's advantages, implementing Portage on Cygwin is impractical,
because:
1) Portage is primarily a package management system, while Cygwin
already uses setup.exe, and is impractical to use just for building
packages.
2) Portage is mainly Linux/BSD specific in a number of ways which would
not work for Cygwin, based on its Win32 limitations (such as replacing
in-use files).
3) There is no way to create multiple binary packages from a single
source package, without building the source multiple times.
4) Most importantly, setup.exe provides a GUI which makes installation
easier for the uninitiated.
(It should be noted that there have been renewed attempts to run Portage
on Cygwin[3], and this was even recently ITP'd and rejected[4].)
2. CONCEPT
The conclusion, therefore, was that a compromise was required: take the
g-b-s, and separate the package-specific (Ebuild) and
package-independent (Portage) sections into two parts. The
package-independent sections would become the build system, into which
the package-specific information would be fed to create a package. The
package-independent system could then be cleaned up and expanded without
affecting package-specific information.
From this idea, cygport was created.
The cygport build system contains all the package-independent functions
of the g-b-s, rewritten in a modern, easy-to-read bash syntax. It
provides commonly-used build-time functions for the package .cygport
files, which contain only the compiling, testing, and installation
instructions.
In addition, cygport is modularized. Support for various build systems
is provided through separate cygclasses, which are 'inherit'ed by the
package .cygport as necessary.
The public functions and syntax (those used by a package .cygport) are
closer to those of Portage then of the g-b-s (it is extremely unlikely,
however, that a Gentoo ebuild will work as a .cygport with a simple
rename); internal syntax is still, to some degree, similar to the g-b-s.
3. USAGE
Similar to a g-b-s source package, a cygport-generated -src tarball will
contain the package .cygport, one or two patchfiles, and the original source
package, for example:
foo-2.3.7.tar.gz
foo2.cygport
foo2-2.3.7-1.cygwin.patch
foo2-2.3.7-1.src.patch (will be absent if package builds OOTB)
GPG .sig files for any of the above may be present as well. All these
files must remain in the same directory.
The general format of a cygport command is:
cygport CYGPORT_FILE COMMAND [COMMAND2]
The first argument is the (relative or absolute) path to the .cygport file
to be processed. All other arguments are interpreted as a COMMAND, which may be:
prep - create working directory, unpack the source and apply patches
compile - run all compilation steps
test - run the package's test suite, if one exists
install - install into a DESTDIR, and run post-installation steps
package - create binary and source packages
upload - upload finished packages to cygwin.com
finish - delete the working directory
all - run prep, compile, install and package
Other COMMANDs are meant primarily for maintainers:
fetch - download the original source from the Internet
check - run the testsuite
postinst - re-run post-installation steps
list - create a file listing suitable for the Cygwin README
deps - list direct dependencies of all executables
The standard arguments --help or --version may also be passed to cygport.
4. CREATING A CYGPORT PACKAGE
See the data/sample.cygport file, included in the Cygwin package in
${prefix}/share/cygport, for a simple example. Many more examples
are available in the Cygwin package git repositories[5].
Please see the Cygport Reference Manual, included with this package, for
documentation on the cygport API.
A Cygwin README file should be included in the CYGWIN-PATCHES directory,
named README. A standard template for this purpose is available from
the Cygwin distribution website[2]. The setup.hint files should also be
included in CYGWIN-PATCHES.
Custom postinstall and preremove commands may be included in the
CYGWIN-PATCHES directory as postinstall.sh and preremove.sh; these
scripts should be written as stubs, without the she-bang header.
5. REQUIREMENTS
The following packages are required to build packages with cygport, in
addition to the packages own dependencies:
cygwin
autoconf (wrapper) and autoconf2.*
automake (wrapper) and automake1.*
bash
binutils
bzip2
coreutils
diffstat
diffutils
dos2unix
file
gawk
grep
gzip
lftp
libtool
lndir
make
openssh
patch
rsync
sed
tar
unzip
util-linux
wget
which
xz
6. DOWNLOAD AND INSTALLATION
Cygwin binary and source packages of cygport are available as part of
the Cygwin distribution, under the 'Devel' category. Installing cygport
with setup.exe will automatically install all mandatory dependencies.
cygport is hosted on Git. Those interested in helping with cygport
development, or testing the newest features should use branch 'master'.
The sources and history can be browsed at either:
https://cygwin.com/git/gitweb.cgi?p=cygwin-apps/cygport.git
https://github.com/cygwin/cygport
Patches for cygport should be created through 'git format-patch' and
based on the 'master' branch. The source repository can be cloned from:
https://cygwin.com/git/cygwin-apps/cygport.git
https://github.com/cygwin/cygport.git
To build cygport from git, meson and ninja are required. The following
packages are required for the documentation: groff, help2man, and robodoc.
The testsuite will use a number of packages if they are present; at a
minimum, you should have git-archive-all for the bootstrap test.
7. SUPPORT
Discussion on cygport should occur on the Cygwin-apps list
<[email protected]>. Do NOT, for any reason, email the author directly.
[1] http://www.cygwin.com/
[2] http://cygwin.com/setup.html#package_contents
[3] http://gentoo-wiki.com/HOWTO_Gentoo_on_Cygwin
[4] http://www.cygwin.com/ml/cygwin-apps/2006-03/msg00000.html
[5] https://cygwin.com/git-cygwin-packages/