README

   1 cygport is the standard method for building and maintaining packages for
   2 the Cygwin distribution.
   3
   4
   5 1. BACKGROUND
   6
   7 In the past, the sanctioned way of building a Cygwin package was by
   8 using a build script, the template for which is commonly known as the
   9 generic-build-script, or g-b-s[2].
  10
  11 However, the g-b-s has many drawbacks:
  12
  13 1) Even the simplest changes, such as adding an argument to configure,
  14    requires wading through the entire 500+ line script; many beginners
  15    have struggled with their first packages.
  16
  17 2) Having a history as a ash script, it is nearly impossible to read, with
  18    run-on commands, && continuations, and backslash-escaped line breaks.
  19
  20 3) It is aimed primarily at autotooled packages, and adapting it to
  21    other packaging systems (e.g. perl MakeMaker, python Distutils,
  22    stand-alone Makefiles, etc.) requires having several "branches" of the
  23    script for each purpose.
  24
  25 4) Updating to a newer script requires either merging package-specific
  26    changes into a new template (and not forgetting anything), or
  27    back-porting g-b-s changes into an existing package script.
  28
  29 5) There is no simple method of dealing with an original source package
  30    whose name or top directory do not conform with the PKGNAME-VERSION
  31    form, or where the Cygwin package name differs from the upstream name
  32    (e.g. gtk2.0 from gtk+).
  33
  34 6) It is not designed to create more than one binary package per source
  35    package -- e.g.  whereby the foo source is separated into foo, libfoo1,
  36    and libfoo-devel binary packages -- despite the fact that is often
  37    desirable to do so.
  38
  39 Having used the g-b-s in various forms for a couple of years, during
  40 which I've packaged hundreds of unique source packages (not counting
  41 versions), I have found various ways of 'getting by'.  I forked the
  42 g-b-s a while back, and created a few templates for various purposes.
  43 This solution, however, is still severely limiting, as mentioned above.
  44
  45 In the meantime, I also had exposure to a Linux distribution and its
  46 packaging system, namely Gentoo Linux and Portage.  Being a source-based
  47 distribution, the entire packaging database consists of a collection of
  48 scripts (ebuilds), which contain basic information about the package,
  49 and the steps necessary to compile and install (into a DESTDIR) the
  50 package.  With the repository available through WebCVS, it is indeed an
  51 invaluable resource to anyone building a non-trivial package from
  52 scratch.
  53
  54 In fact, Portage answers many of the drawbacks of the g-b-s:
  55
  56 1) Ebuilds are small, containing only package-specific information,
  57    making them easy to read, and even to create with little effort.
  58
  59 2) Ebuilds are written in a clean bash syntax.
  60
  61 3) The Eclass system allows ebuilds to be easily extended to any number
  62    of different build systems (Perl, Python, Ruby, etc.) and/or categorical
  63    templates (e.g. GNOME or KDE).
  64
  65 4) Updates to Portage take affect immediately, without updating all
  66    ebuilds, and ebuilds can be created without even looking at the
  67    internals of Portage itself.
  68
  69 5) Ebuilds anyway define the source package name, and can easily
  70    override the assumed source top directory when necessary.
  71
  72 Despite it's advantages, implementing Portage on Cygwin is impractical,
  73 because:
  74
  75 1) Portage is primarily a package management system, while Cygwin
  76    already uses setup.exe, and is impractical to use just for building
  77    packages.
  78
  79 2) Portage is mainly Linux/BSD specific in a number of ways which would
  80    not work for Cygwin, based on its Win32 limitations (such as replacing
  81    in-use files).
  82
  83 3) There is no way to create multiple binary packages from a single
  84    source package, without building the source multiple times.
  85
  86 4) Most importantly, setup.exe provides a GUI which makes installation
  87    easier for the uninitiated.
  88
  89 (It should be noted that, there were renewed attempts to run Portage
  90 on Cygwin, and this was ITP'd and rejected[3] in 2006.  And, the project
  91 "Gentoo on Cygwin", which contains Portage, is unmaintained as of 2008.
  92 But, there is another project "Gentoo Prefix on Cygwin", as of 2020.
  93 It's a try to run well-maintained "Gentoo Prefix" sources on Cygwin[4].)
  94
  95
  96 2. CONCEPT
  97
  98 The conclusion, therefore, was that a compromise was required: take the
  99 g-b-s, and separate the package-specific (Ebuild) and
 100 package-independent (Portage) sections into two parts.  The
 101 package-independent sections would become the build system, into which
 102 the package-specific information would be fed to create a package.  The
 103 package-independent system could then be cleaned up and expanded without
 104 affecting package-specific information.
 105
 106 From this idea, cygport was created.
 107
 108 The cygport build system contains all the package-independent functions
 109 of the g-b-s, rewritten in a modern, easy-to-read bash syntax.  It
 110 provides commonly-used build-time functions for the package .cygport
 111 files, which contain only the compiling, testing, and installation
 112 instructions.
 113
 114 In addition, cygport is modularized.  Support for various build systems
 115 is provided through separate cygclasses, which are 'inherit'ed by the
 116 package .cygport as necessary.
 117
 118 The public functions and syntax (those used by a package .cygport) are
 119 closer to those of Portage then of the g-b-s (it is extremely unlikely,
 120 however, that a Gentoo ebuild will work as a .cygport with a simple
 121 rename); internal syntax is still, to some degree, similar to the g-b-s.
 122
 123
 124 3. USAGE
 125
 126 Similar to a g-b-s source package, a cygport-generated -src tarball will
 127 contain the package .cygport, one or two patchfiles, and the original source
 128 package, for example:
 129
 130     foo-2.3.7.tar.gz
 131     foo2.cygport
 132     foo2-2.3.7-1.cygwin.patch
 133     foo2-2.3.7-1.src.patch     (will be absent if package builds OOTB)
 134
 135 GPG .sig files for any of the above may be present as well.  All these
 136 files must remain in the same directory.
 137
 138 The general format of a cygport command is:
 139
 140     cygport CYGPORT_FILE COMMAND [COMMAND2]
 141
 142 The first argument is the (relative or absolute) path to the .cygport file
 143 to be processed.  All other arguments are interpreted as a COMMAND, which may be:
 144
 145     prep      - create working directory, unpack the source and apply patches
 146     compile   - run all compilation steps
 147     test      - run the package's test suite, if one exists
 148     install   - install into a DESTDIR, and run post-installation steps
 149     package   - create binary and source packages
 150     upload    - upload finished packages to cygwin.com
 151     finish    - delete the working directory
 152     all       - run prep, compile, install and package
 153
 154 Other COMMANDs are meant primarily for maintainers:
 155
 156     fetch    - download any missing upstream sources
 157     fetchall - download any all upstream sources
 158     check    - run the testsuite
 159     postinst - re-run post-installation steps
 160     list     - create a file listing suitable for the Cygwin README
 161     deps     - list direct dependencies of all executables
 162     info     - show a summary of package information
 163     diff     - write a patch file capturing changes to source in the working directory
 164     stage    - as upload, but don't request processing of uploaded packages
 165     announce - compose and send a package announcement
 166     repro-build  - rebuild from created source package to temp directory
 167     repro-diff   - check whether packages from original and rebuild differ
 168     repro-check  - run repro-build and repro-diff
 169     repro-finish - delete the temp directory used for rebuild
 170
 171 The standard arguments --help or --version may also be passed to cygport.
 172
 173
 174 4. CREATING A CYGPORT PACKAGE
 175
 176 See the data/sample.cygport file, included in the Cygwin package in
 177 ${prefix}/share/cygport, for a simple example.  Many more examples
 178 are available in the Cygwin package git repositories[5].
 179
 180 Please see the Cygport Reference Manual, included with this package, for
 181 documentation on the cygport API.
 182
 183 A Cygwin README file may be included in the CYGWIN-PATCHES directory,
 184 named README.  A standard template for this purpose is available from
 185 the Cygwin distribution website[2].
 186
 187 If .hint file auto-generation isn't being used, setup.hint files may also be
 188 included in CYGWIN-PATCHES.
 189
 190 Custom postinstall and preremove commands may be included in the
 191 CYGWIN-PATCHES directory as postinstall.sh and preremove.sh; these
 192 scripts should be written as stubs, without the shebang header.
 193
 194
 195 5. REQUIREMENTS
 196
 197 The following packages are required to build packages with cygport, in
 198 addition to the packages own dependencies:
 199
 200     cygwin
 201     autoconf (wrapper) and autoconf2.*
 202     automake (wrapper) and automake1.*
 203     bash
 204     binutils
 205     bzip2
 206     coreutils
 207     diffstat
 208     diffutils
 209     dos2unix
 210     file
 211     gawk
 212     grep
 213     gzip
 214     lftp
 215     libtool
 216     lndir
 217     make
 218     openssh
 219     patch
 220     rsync
 221     sed
 222     tar
 223     unzip
 224     util-linux
 225     wget
 226     which
 227     xz
 228
 229 6. DOWNLOAD AND INSTALLATION
 230
 231 Cygwin binary and source packages of cygport are available as part of
 232 the Cygwin distribution, under the 'Devel' category.  Installing cygport
 233 with setup.exe will automatically install all mandatory dependencies.
 234
 235 cygport is hosted on Git.  Those interested in helping with cygport
 236 development, or testing the newest features should use branch 'master'.
 237 The sources and history can be browsed at either:
 238
 239   https://cygwin.com/git/gitweb.cgi?p=cygwin-apps/cygport.git
 240   https://github.com/cygwin/cygport
 241
 242 Patches for cygport should be created through 'git format-patch' and
 243 based on the 'master' branch.  The source repository can be cloned from:
 244
 245   https://cygwin.com/git/cygwin-apps/cygport.git
 246   https://github.com/cygwin/cygport.git
 247
 248 To build cygport from git, meson and ninja are required. The following
 249 packages are required for the documentation: groff, help2man, and robodoc.
 250 The testsuite will use a number of packages if they are present; at a
 251 minimum, you should have git-archive-all for the bootstrap test.
 252
 253
 254 7. SUPPORT
 255
 256 Discussion on cygport should occur on the Cygwin-apps list
 257 <cygwin-apps@cygwin.com>.  Do NOT, for any reason, email the author directly.
 258
 259
 260 [1] https://www.cygwin.com/
 261 [2] https://cygwin.com/setup-packaging-historical.html  Method Two
 262 [3] https://sourceware.org/legacy-ml/cygwin-apps/2006-03/msg00000.html
 263 [4] https://wiki.gentoo.org/wiki/Prefix/Cygwin
 264 [5] https://cygwin.com/git-cygwin-packages/