262 lines
12 KiB
ReStructuredText
262 lines
12 KiB
ReStructuredText
====================
|
|
Building for Windows
|
|
====================
|
|
|
|
Koji provides a fairly basic mechanism to perform builds for Windows.
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
win_spec_example
|
|
|
|
Introduction
|
|
============
|
|
|
|
Koji supports building components in a Windows-based environment. This is
|
|
accomplished by cloning and starting a Windows VM, checking out sources and
|
|
building from within it. The VM would have compile tools and utility already
|
|
installed, and the results are then passed back up the hub. Windows builds are
|
|
treated similarly to RPM builds in that they have a unique name, version, and
|
|
release field. The resulting builds are built using targets and tagged into tags
|
|
just as normal builds are. When you build a Windows component, you can
|
|
reference other components and they will be downloaded into the build
|
|
environment to satisfy build-time dependencies.
|
|
|
|
|
|
Initiating a build
|
|
==================
|
|
|
|
Note: access to performing Windows builds is governed by the ``vm`` policy on the hub.
|
|
The default policy requires the user to have the ``win-admin`` permission.
|
|
Different Koji instances may have different policies.
|
|
If the policy denies you access, you will see an ``ActionNotAllowed`` error.
|
|
In that case, you will need file a request with your Koji administators.
|
|
|
|
|
|
Windows builds are initiated with the ``win-build`` subcommand.
|
|
|
|
..
|
|
|
|
$ koji win-build <target> <scm-url> <vm-name>
|
|
|
|
Where ``target`` is the build target to use for the build,
|
|
``scm-url`` is the SCM URL for the sources to build,
|
|
and ``vm-name`` is the name of the vm image to use for the build.
|
|
|
|
The ``target`` works like targets for other types of builds.
|
|
The build tag for the target determines where Koji will pull build dependencies from,
|
|
and the destination tag for the target determines where the resulting build is tagged
|
|
after building is completed.
|
|
|
|
The ``scm-url`` follows the same syntax used for other Koji builds
|
|
|
|
..
|
|
|
|
scheme://[user@]host/path/to/repo?path/to/module#revision_or_tag_identifier
|
|
|
|
In order for Koji to perform the build, a "Windows spec file" is required (see below).
|
|
This spec file can either be included in the top directory of the sources or specified
|
|
separately with the ``--specfile`` option.
|
|
|
|
The ``vm-name`` argument is the name of the vm image that will be used for the build.
|
|
This name must be one of the know images available on the builders.
|
|
|
|
An option you may be interested in is ``--specfile``, which allows you to specify a second
|
|
remote repository that contains the windows spec file using the same SCM URL syntax as
|
|
described below. That way you are not forced to keep the spec in with the rest of your
|
|
sources if you don't want to. There is also a ``--patches`` option which is just
|
|
like ``--specfile``, except meant for a repository of separate patches, which will
|
|
be applied to the sources before the build is launched. ``--specfile`` and
|
|
--patches may reference the same repo.
|
|
|
|
|
|
The Windows "Spec-File"
|
|
=======================
|
|
|
|
This is the file that controls the build process, and is modeled very loosely
|
|
on RPM's spec files. The Windows spec file is in .ini format.
|
|
|
|
It's probably easiest to start by looking at this
|
|
:doc:`example <win_spec_example>`
|
|
spec file.
|
|
|
|
All values in the [naming] section must be defined.
|
|
The name, version, and release are used to determine the NVR of the build.
|
|
As with all NVRs in Koji, this must be a unique value.
|
|
|
|
The [building] section defines preconditions that must be satisfied before the
|
|
build will be launched, and the commands used to perform the build. platform
|
|
indicates to VM type the build is running in, and should be in the format of
|
|
osname-arch.
|
|
|
|
|
|
The ``preinstalled`` value under [building] lists the files and directories
|
|
that must be present for the build
|
|
to run. Any tools that were installed in the VM when it was setup should be
|
|
listed here. If any of the files or directories listed here are missing when
|
|
the build runs, it will fail immediately. Files and directories may be listed
|
|
in Windows format (C:\Program Files\...), full Cygwin paths (/bin/...), or as
|
|
command names (tar, unzip, etc). If they are listed as command names, the
|
|
Cygwin PATH will be checked for the command.
|
|
|
|
|
|
The ``buildrequires`` value under [building] lists other packages that
|
|
the build depends on. As with rpm
|
|
BuildRequires, the buildrequires entries should be package names only (no
|
|
version information). The latest build of that package will be looked up in
|
|
the -build tag associated with the build target that was used when launching
|
|
the build, and files from that build will be downloaded into the VM. Each
|
|
package listed in buildrequires can have a colon-delimited list of options
|
|
associated with it, which determine which files from the build will be
|
|
downloaded. By default, all Windows files associated with the dependent build
|
|
will be downloaded (this is the same as specifying type=win). In this case,
|
|
comma-separated lists of platforms= and flags can also be specified, in which
|
|
case the files downloaded into the VM will be limited to those associated with
|
|
one or more of the platform and flag values (more about this in the [files]
|
|
section below. If type=rpm is specified, then all rpms associated with the
|
|
dependent build will be installed. In this case a comma-separated list of
|
|
arches= may be specified, and only rpms matching one of those arches will be
|
|
downloaded. If type=maven is specified, then comma-separated lists of
|
|
group_ids=, artifact_ids=, and/or versions= may be specified, and only Maven
|
|
artifacts matching at least one value in each list will be downloaded. In all
|
|
cases, a patterns= option may be specified, which is a comma-separated list of
|
|
globs to match against the filenames. Only files matching at least one of the
|
|
patterns will be downloaded.
|
|
|
|
|
|
The files downloaded to satisfy the buildrequires are placed in a directory
|
|
based on their type, and variables are set which point to their location. The
|
|
variable names are constructed by converting the dependency name to variable
|
|
format (a leading number is converted to and underscore, and any character that
|
|
is not a letter, number, or underscore is converted to an underscore). If
|
|
type= is specified, then <type>_dir is appended to complete the variable name.
|
|
Otherwise, just _dir is appended. In the example above, the directory
|
|
containing the boost-win files would be indicated by $boost_win_dir. The
|
|
directory containing the .src.rpm from the qpid-cpp-mrg build would be
|
|
$qpid_cpp_mrg_rpm_dir. Note the extra _rpm there, because it specified
|
|
type=rpm. There is also a corresponding _files variable which is a
|
|
newline-delimited list of all files downloaded for each dependency. In the
|
|
example, both $boost_win_files and $qpid_cpp_mrg_rpm_files would be defined.
|
|
|
|
|
|
The files are downloaded to the VM unmodified. It is up to the build process
|
|
to extract them if necessary, and move/copy them to whatever location is
|
|
required by the current build.
|
|
|
|
|
|
The ``provides`` value under [building] is optional, and can be used to indicate what the build is
|
|
producing. It is freeform, but a structure like <name>-<version> is
|
|
encouraged.
|
|
|
|
|
|
The ``shell`` value under [building] indicates how the build script should be run.
|
|
Valid values are
|
|
bash, which will cause the script to be run in bash, and cmd.exe, which will
|
|
cause the script to be run in Windows cmd.exe. cmd is also an alias for
|
|
cmd.exe. bash is the default if no shell value is present.
|
|
|
|
|
|
The ``execute`` value under [building] is required, and this is what drives the build process.
|
|
This value is multiline, and each line is treated as a separate command to be execute in the
|
|
shell specified above. In addition to the variables defined for the buildrequires, the
|
|
following variables will be available when the script is executed:
|
|
|
|
* name: name from the [naming] section
|
|
* version: version from the [naming] section
|
|
* release: release from the [naming] section
|
|
* source_dir: the directory the sources were checked out into
|
|
* spec_dir: the directory the .ini was checked out into. If there was no separate --winspec
|
|
option passed on the command-line, this will be the same as source_dir
|
|
* patches_dir: the directory the patches were checked out into. If there was no --patches
|
|
option passed on the command-line, this will be undefined.
|
|
|
|
|
|
If using bash, the build script will be executed with -x and -e, which will
|
|
cause all commands to be echoed, and will cause the script to fail if any
|
|
commands have a non-zero exit status. There is no equivalent fail-fast option
|
|
for Windows cmd.exe. If executing the script using cmd.exe, it is recommend
|
|
that you frequently check the return value of commands with this:
|
|
|
|
..
|
|
|
|
if %ERRORLEVEL% neq 0 exit %ERRORLEVEL%
|
|
|
|
|
|
The script will start in the root directory of the sources that were checked
|
|
out ($source_dir). Extra scripts or supplementary files required by the build
|
|
may be checked in along with the .ini file, and will be available under
|
|
$spec_dir (assuming a separate --specfile option was used).
|
|
|
|
|
|
The postbuild value is optional, and specifies a list of files and directories
|
|
(relative to $source_dir) that must be present for the build to be considered
|
|
successful. If any of them are missing, the build will fail. This is useful
|
|
for verifying that all expected output was generated correctly, in the case
|
|
that some commands may have failed silently.
|
|
|
|
|
|
The [files] section describes what output should be collected after the build
|
|
completes. The logfiles value is optional, but it should be set to whatever
|
|
build logs are produced from the build. The syntax for the output variable is
|
|
as follows:
|
|
|
|
..
|
|
|
|
output = qpid-cpp-x86-$version.zip:i386:chk,fre
|
|
|
|
Note the colon-separated nature. The first token is the path to the file you
|
|
want collected as part of your build output. This path is rooted at the
|
|
checkout from the SCM ($source_dir). The file path relative to $source_dir is
|
|
retained when output is uploaded to Koji and when it is downloaded as a
|
|
buildrequires by future builds. If you don't want a long, confusing file path,
|
|
it may be desirable to copy the build output to $source_dir at the end of your
|
|
build script. File globs are not allowed, but the $name, $version, and
|
|
$release variables will be expanded in the file paths and names, using the
|
|
values from the [naming] section. The second token is a comma-separated list of
|
|
platforms (which we haven't really standardized on yet, but i386 and/or x86_64
|
|
are logical choices). The last is a comma-separated list of build flags. These
|
|
fields are purely informational, they do not influence future builds at this
|
|
time, but they do make for good housekeeping in the future. Common flags are
|
|
chk (indicating a debug build) and fre (indicating an optimized build). If an
|
|
output file contains both kinds of builds, both may be specified.
|
|
|
|
|
|
The logs value indicates extra log files generated during the build that should
|
|
be tracked. The contents of these log files will be streamed to the hub during
|
|
the build and may be watched in realtime using the "Watch logs"
|
|
feature of the web interface, or the "koji watch-logs" cli command.
|
|
They will also be included in the build logs stored on in Koji.
|
|
|
|
|
|
Source Repository
|
|
=================
|
|
|
|
As noted earlier, the sources are checked out from within a Windows VM that
|
|
Koji clones and starts when you submit your task with the client. Koji supports
|
|
checking out sources from CVS, SVN, and git.
|
|
As with other types of builds, the ``allowed_scms`` setting limits which sources
|
|
can be built from.
|
|
|
|
|
|
Administration
|
|
==============
|
|
|
|
Windows Build Hosts
|
|
-------------------
|
|
|
|
By default, all ``winbuild`` tasks go to the ``vm`` channel.
|
|
The hosts in this channel require special setup.
|
|
|
|
* They run the ``kojivmd`` daemon instead of the regular ``kojid`` daemon
|
|
* VM images for builds must be stored in the local image directory
|
|
|
|
|
|
Managing VM Images
|
|
------------------
|
|
|
|
The directory where ``kojivmd`` looks for vm images can be controlled by setting ``imagedir``
|
|
in ``/etc/kojivmd/kojivmd.conf``. The default value is ``/var/lib/libvirt/images``.
|
|
|
|
These images must be qcow2 images named with a ``.qcow2`` extension. The basename of the
|
|
image file is the same name that users refer to in the ``vm-name`` parameter to the
|
|
``win-build`` command.
|