From Fedora Project Wiki

(Replace with link to Package Maintainer Docs at docs.fp.o)
Tag: Replaced
 
(47 intermediate revisions by 33 users not shown)
Line 1: Line 1:
<!-- page was renamed from PackageMaintainers/UsingKojiDraft
{{admon/warning |This page has been moved out of the wiki. The current version of this document is located at https://docs.fedoraproject.org/en-US/package-maintainers/Using_the_Koji_Build_SystemPlease update your bookmarks.}}
-->
= Using Koji in Fedora =
 
The [[Koji|  Koji Build System]]  is Fedora's buildsystem for Fedora 7 and beyond. Packagers use the koji client to request package builds and get information about the buildsystem.
 
There is also a [[Zh/使用Koji编译打包系统|simplified Chinese edition]].
 
== Installing Koji ==
 
==== Installing the Koji CLI ====
 
Everything you need to use Koji (and be a Fedora contributor) can be installed in a single step:
 
<pre>
yum install fedora-packager
</pre>
 
fedora-packager provides useful scripts to help maintain and setup your koji environment. Additionally, it includes dependencies on the Koji CLI, so it will be installed when you install <code>fedora-packager</code>.  The command is called <code>koji</code> and is included in the main koji package. By default the koji tool authenticates to the central server using Kerberos.  However SSL and username/password authentications are available. You will need to have a valid authentication token to use many features. However, many of the read-only commands will work without authentication.
 
==== Initial Fedora Setup ====
 
In order to interface with the koji server, maintainers will need to run
<pre>
/usr/bin/fedora-packager-setup
</pre>
 
Each user on a system will need to run fedora-packager-setup if they wish to use Koji to build Fedora packages. Each user has their own certificates that authenticate them.
 
{{admon/tip|Plague users rejoice!|For existing users of plague (the old build system that preceded Koji), <code>fedora-packager-setup</code> will use your existing certificates.  If you did not have plague before, it will get the server CA certs and tell you where to get your user cert.}}
 
===== Fedora Certificates =====
Koji uses three certificates:
; <code>~/.fedora.cert</code> (specific to the Fedora Maintainer) : This cert is generated from [https://admin.fedoraproject.org/accounts/user/gencert this form] in [[Infrastructure/AccountSystem | FAS]]. It should have been generated when you became maintainer. You may need to refresh it when it expires.
 
the following are downloaded automatically by fedora-packager-setup and dont need to be manually setup
 
; <code>~/.fedora-upload-ca.cert</code> (The certificate for the Certificate Authority used to sign the user keys.) : It can be manually downloaded from [https://admin.fedoraproject.org/accounts/fedora-upload-ca.cert here] or <code>fedora-packager-setup or fedora-cert -n</code> should fetch it. using the CLI is prefered.
; <code>~/.fedora-server-ca.cert</code> (The certificate for the Certificate Authority used to sign the build system's server keys.) : It can be downloaded manually from [https://admin.fedoraproject.org/accounts/fedora-server-ca.cert here] or <code>fedora-packager-setup</code> should fetch it.
 
{{admon/warning|RHEL6 cert bug|If you're using RHEL6, an incompatibility between RHEL6's openssl and nss causes certificates downloaded from fas to fail to work with some fedpkg tools.  [[https://bugzilla.redhat.com/show_bug.cgi?id=631000 Bug 631000 rhel6 openssl creates PKCS#8 encoded PEM RSA private key files, nss can't read them]].  The cert can be made compatible using this command: <code>(openssl x509 -in ~/.fedora.cert -text; echo; openssl rsa -in ~/.fedora.cert) > fedora.cert.new</code>}}
 
===== Koji Config =====
The global local client configuration file for koji is <code>/etc/koji.conf</code>. You should not need to change this from the defaults for building Fedora packages, as running <code>fedora-packager-setup</code> will create a set of configuration files in ~/.koji/ file for your user these will allow you to use the primary build system as well as secondary arch build systems.
 
== The web interface ==
 
The primary interface for viewing Koji data is a web application.
It is available at http://koji.fedoraproject.org/koji/ .
Most of the interface is read-only, but if you are logged in (see below) and have sufficient privileges there are some actions that can be performed though the web. For example:
 
* Cancel a build
* Resubmit a failed task
* Setup a notification
 
Those with admin privileges will find additional actions, such as:
 
* Create/Edit/Delete a tag
* Create/Edit/Delete a target
* Enable/Disable a build host
 
 
The web site utilizes SSL authentication. In order to log in you will need a valid SSL certificate and your web browser will need to be configured to trust the SSL cert.  Instructions on how to do this are printed when running <code>fedora-packager-setup</code>.
 
===== Notifications =====
With Koji you can setup a notification requests, to make sure you do not miss when a package you care about gets built. Login and scroll to the bottom of the page, there you should find a ''[https://koji.fedoraproject.org/koji/notificationcreate Add a notification]'' link and a list of your configured notifications.
 
== Building with make targets ==
Note that all build requests need to be done against tagged trees (run <code>make tag</code> first).
 
For simple build requests, there is an alias in Makefile.common to request koji builds. This enables Fedora packagers to simply cd into the appropriate branch of a package (from a cvs checkout), and run:
 
<pre>
make build
</pre>
 
This will trigger a build request for the branch. Easy!
 
It is also possible to target a specific koji tag as follows:
 
<pre>
make build TARGET='<target>'
</pre>
 
for example, if building on rawhide against a special tag created by rel-eng for updating API for many packages, e.g. <code>dist-f11-python</code> you would use the following:
 
<pre>
make build TARGET='dist-f11-python'
</pre>
 
==== Scratch Builds ====
 
You can do a scratch build with:
 
<pre>
make scratch-build
</pre>
 
if you want to do a scratch build for a specific architecture, you can type:
 
<pre>
make scratch-build-<archs>
</pre>
 
<archs> can be a comma separated list of severals architectures.
 
finally is possible to combine the scratch-build command with a specific koji tag in the form:
 
<pre>
make scratch-build TARGET='<target>'
</pre>
 
==== Chained builds ====
{{Admon/warning | chain-builds only work when building on the devel/ branch (aka rawhide).  To chain-build packages to update a released OS version, open a [https://fedorahosted.org/rel-eng/ ticket with the Release Engineering team] asking for earlier built packages to be included in the proper buildroot. For Fedora packages, select component 'koji'.  For EPEL packages, select component 'epel'.}}
Sometimes you want to make sure than one build succeeded before
launching the next one, for example when you want to rebuild
a package against a just rebuilt dependency. In that case
you can use a chain build with:
 
make chain-build CHAIN='libwidget libgizmo'
 
 
The current package is added to the end of the CHAIN list. Colons (:) can be used in the CHAIN parameter to define groups of packages. Packages in any single group will be built in parallel and all packages in a group must build successfully and populate the repository before the next group will begin building. For example:
                   
make chain-build CHAIN='libwidget libaselib : libgizmo :'
 
will cause libwidget and libaselib to be built in parallel, followed by libgizmo and then the currect directory package. If no groups are defined, packages will be built sequentially.
 
If a build fail, following builds are canceled but the builds that already succeeded are pushed to the repository.
 
==== Build Failures ====
 
If your package fails to build, you will see something like this:
 
<pre>
420066 buildArch kernel-2.6.18-1.2739.10.9.el5.jjf.215394.2.src.rpm,
ia64): open (build-1.example.com) -> FAILED: BuildrootError:
error building package (arch ia64), mock exited with status 10
</pre>
 
You can figure out why the build failed by looking at the log files. If there is a build.log, start there. Otherwise, look at init.log.
 
Logs can be found via the web interface in the Task pages for the failed task.  Alternatively the koji client can be used to view the logs via the <code>watch-logs</code> command.  See the help output for more details.
 
== Advanced use of Koji ==
 
We've tried to make Koji self-documenting wherever possible. The command line tool will print a list of valid commands and each command supports --help. For example:
 
<pre>
$ koji help
 
Koji commands are:
build                Build a package from source
cancel-task          Cancel a task
help                List available commands
latest-build        Print the latest rpms for a tag
latest-pkg          Print the latest builds for a tag
[...]
</pre>
 
<pre>
$ koji build --help
 
usage: koji build [options]  tag URL
(Specify the --help global option for a list of other help options)
 
options:
-h, --help            show this help message and exit
--skip-tag            Do not attempt to tag package
--scratch            Perform a scratch build
--nowait              Don't wait on build
[...]
</pre>
 
==== Using koji to generate a mock config to replicate a buildroot ====
 
koji can be used to replicate a build root for local debugging
<pre>
koji mock-config --help
Usage: koji mock-config [options] name
(Specify the --help global option for a list of other help options)
 
Options:
  -h, --help            show this help message and exit
  --arch=ARCH          Specify the arch
  --tag=TAG            Create a mock config for a tag
  --task=TASK          Duplicate the mock config of a previous task
  --buildroot=BUILDROOT
                        Duplicate the mock config for the specified buildroot
                        id
  --mockdir=DIR        Specify mockdir
  --topdir=DIR          Specify topdir
  --topurl=URL          url under which Koji files are accessible
  --distribution=DISTRIBUTION
                        Change the distribution macro
  -o FILE              Output to a file
</pre>
for example to get the latest buildroot for dist-f12-build run
<pre>
koji mock-config --tag dist-f12-build --arch=x86_64 --topurl=http://kojipkgs.fedoraproject.org/ dist-f12
</pre>
 
you will need to pass in --topurl=http://kojipkgs.fedoraproject.org/ to any mock-config command to get a working mock-config from fedoras koji.
 
==== Using Koji to control tasks ====
 
List tasks:
<pre>
koji list-tasks
</pre>
 
List only tasks requested by you:
<pre>
koji list-tasks --mine
</pre>
 
requeue an already-processed task: general syntax is: koji resubmit [options]  taskID
 
<pre>
koji resubmit 3
</pre>
 
==== Building a Package with the command-line tool ====
 
Instead of using the make target, you can also directly
use the command_line tool, koji.
To build a package, the syntax is:
 
<pre>
$ koji build <build target> <cvs URL>
</pre>
 
For example:
{{Admon/warning | Replace <code>dist-f8</code> with the tag you wish to build against, e.g., <code>dist-f9</code> or <code>dist-f10</code>}}
<pre>
$ koji build dist-f8 'cvs://cvs.example.com/cvs/dist?rpms/kernel/FC-7#kernel-2_6_20-1_2925_fc7'
</pre>
 
The koji build command creates a build task in Koji. By default the tool will wait and print status updates until the build completes. You can override this with the --nowait option. This can also be used with the make command by setting an ENV variable:
<pre>
KOJI_FLAGS="--nowait" make build
</pre>
 
===== Scratch builds =====
 
Sometime it is useful to be able to build a package against the buildroot but without actually including it in the release. This is called a scratch build. To create a scratch of latest CVS commit:
 
{{Admon/warning | Replace <code>dist-f8</code> with the tag you wish to build against, e.g., <code>dist-f9</code> or <code>dist-f10</code>.}}
 
<pre>
koji build --scratch dist-f8 'cvs://cvs.fedoraproject.org/cvs/pkgs?rpms/yum/devel#HEAD'
</pre>
 
You can also scratch build source rpms.
 
<pre>
koji build --scratch dist-f8 mycoolpackage-3.2-1.src.rpm
</pre>
 
Warning: Scratch builds will ''not'' work correctly if your .spec file does something different depending on the value of %fedora, %fc9, and so on.  Macro values like these are set by the ''builder'', not by koji, so the value of %fedora will be for whatever created the source RPM, and ''not'' what it's being built on.  Non-scratch builds get around this by first re-building the source RPM.
 
===== Build Options =====
 
There are a few options to the build command. Here are some more detailed explanations of them:
 
<pre>
--skip-tag
Normally the package is tagged after the build completes.
This option causes the tagging step to be skipped.
The package will be in the system, but untagged
(you can later tag it with the tag-pkg command)
--scratch
This makes the build into a scratch build.
The build will not be imported into the db, it will just be built.
The rpms will land under <topdir>/scratch.
Scratch builds are not tracked and can never be tagged, but can be convenient for testing.
Scratch builds are typically removed from the filesystem after one week.
--nowait
As stated above, this prevents the cli from waiting on the build task.
--arch-override
This option allows you to override the base set of arches to build for.
This option is really only for testing during the beta period, but it may be retained for scratch builds in the future.
</pre>
 
== Koji tags and packages organization ==
 
==== Terminology ====
In Koji, it is sometimes necessary to distinguish between a package in general, a specific build of a package, and the various rpm files created by a build. When precision is needed, these terms should be interpreted as follows:
 
* Package: The name of a source rpm. This refers to the package in general and not any particular build or subpackage. For example: kernel, glibc, etc.
* Build: A particular build of a package. This refers to the entire build: all arches and subpackages. For example: kernel-2.6.9-34.EL, glibc-2.3.4-2.19.
* RPM: A particular rpm. A specific arch and subpackage of a build. For example: kernel-2.6.9-34.EL.x86_64, kernel-devel-2.6.9-34.EL.s390, glibc-2.3.4-2.19.i686, glibc-common-2.3.4-2.19.ia64
 
==== Tags and targets ====
 
Koji organizes packages using tags. In Koji a tag is roughly a collection of packages:
 
* Tags support inheritance
* Each tag has its own list of valid packages (inheritable)
* Package ownership can be set per-tag (inheritable)
* When you build you specify a target rather than a tag
 
A build target specifies where a package should be built and how it should be tagged afterwards. This allows target names to remain fixed as tags change through releases.
 
==== Koji commands for tags ====
 
 
===== Targets =====
You can get a full list of build targets with the following command:
 
<pre>
$ koji list-targets
</pre>
 
You can see just a single target with the --name option:
 
<pre>
$ koji list-targets --name dist-fc7
 
Name                          Buildroot                      Destination
---------------------------------------------------------------------------------------------
dist-fc7                      dist-fc7-build                dist-fc7
</pre>
 
This tells you a build for target dist-fc7 will use a buildroot with packages from the tag dist-fc7-build and tag the resulting packages as dist-fc7.
 
Watch out: You probably don't want to build against dist-rawhide.  If Fedora N is the latest one out, to build to the next one, choose dist-f{N+1}.
 
===== Tags =====
 
You can get a list of tags with the following command:
<pre>
$ koji list-tags
</pre>
 
===== Packages =====
 
As mentioned above, each tag has its own list of packages that may be placed in the tag. To see that list for a tag, use the list-pkgs command:
 
<pre>
$ koji list-pkgs --tag dist-fc7
 
Package                Tag                    Extra Arches    Owner
----------------------- ----------------------- ---------------- ----------------
ElectricFence          dist-fc6                                pmachata
GConf2                  dist-fc6                                rstrode
lucene                  dist-fc6                                dbhole
lvm2                    dist-fc6                                lvm-team
ImageMagick            dist-fc6                                nmurray
m17n-db                dist-fc6                                majain
m17n-lib                dist-fc6                                majain
MAKEDEV                dist-fc6                                clumens
[...]
</pre>
 
The first column is the name of the package, the second tells you which tag the package entry has been inherited from, and the third tells you the owner of the package.
 
===== Latest Builds =====
 
To see the latest builds for a tag, use the latest-pkg command:
 
<pre>
$ koji latest-pkg --all dist-fc7
 
Build                                    Tag                  Built by
----------------------------------------  --------------------  ----------------
ConsoleKit-0.1.0-5.fc7                    dist-fc7              davidz
ElectricFence-2.2.2-20.2.2                dist-fc6              jkeating
GConf2-2.16.0-6.fc7                      dist-fc7              mclasen
ImageMagick-6.2.8.0-3.fc6.1              dist-fc6-updates      nmurray
MAKEDEV-3.23-1.2                          dist-fc6              nalin
MySQL-python-1.2.1_p2-2                  dist-fc7              katzj
NetworkManager-0.6.5-0.3.cvs20061025.fc7  dist-fc7              caillon
ORBit2-2.14.6-1.fc7                      dist-fc7              mclasen
</pre>
 
The output gives you not only the latest builds, but which tag they have been inherited from and who built them.
 
[[Category:Package Maintainers]]

Latest revision as of 05:45, 15 September 2021

This page has been moved out of the wiki. The current version of this document is located at https://docs.fedoraproject.org/en-US/package-maintainers/Using_the_Koji_Build_System/ Please update your bookmarks.