|
|
| Line 1: |
Line 1: |
| {{autolang|base=yes}} | | {{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_System/ Please update your bookmarks.}} |
| = Using Koji in Fedora =
| |
| | |
| The [[Koji| Koji Build System]] is Fedora's RPM buildsystem. Packagers use the koji client to request package builds and get information about the buildsystem. Koji runs on top of Mock to build RPM packages for specific architectures and ensure that they build correctly.
| |
| | |
| There is also a [[Zh/使用Koji编译打包系统|simplified Chinese edition]].
| |
| | |
| == Installing Koji ==
| |
| | |
| ==== Installing the Koji CLI ====
| |
| | |
| To use Koji (and be a Fedora contributor) install the fedora-packager package:
| |
| | |
| <pre>
| |
| dnf 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 is 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. You must have a valid authentication token to use many features. However, many of the read-only commands work without authentication.
| |
| | |
| If you need help setting up authentication or becoming a Fedora packager use this guide: [[Join_the_package_collection_maintainers]]<br>
| |
| | |
| ==== Koji Setup ====
| |
| | |
| Before using Koji to build packages, you must have the fedora-packager package installed:
| |
| | |
| <pre>
| |
| dnf install fedora-packager
| |
| </pre>
| |
| | |
| You must also have a valid kerberos ticket. Assuming you are using Koji to build for Fedora, use your [[Account System|FAS]] username and FEDORAPROJECT.ORG as the realm. Kerberos requires the 'realm'. which here also looks like a 'domain' name, to be in all capital letters.
| |
| | |
| <pre>
| |
| KRB5_TRACE=/dev/stdout kinit your_fas_username@FEDORAPROJECT.ORG
| |
| </pre>
| |
| | |
| Store your FAS username (all lower case) in <code>~/.fedora.upn</code> (This is not actually needed for Kerberos but for other tools that used the Fedora client certificate to determine the FAS username.)
| |
| | |
| For more information, see [[Infrastructure/Kerberos|Kerberos setup]].
| |
| | |
| ==== 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. These allow you to use the primary build system as well as secondary arch build systems.
| |
| | |
| You can use the koji command directly, or use fedpkg, a script that interacts with the RPM Packaging system and other subsystems, like git and koji itself.
| |
| | |
| == Building with fedpkg targets ==
| |
| | |
| When building with fedpkg within a git repository, every push is automatically tagged via git. All you have to do to build the package is to run:
| |
| | |
| <pre>
| |
| fedpkg build
| |
| </pre>
| |
| | |
| This triggers a build request for the branch. Easy! | |
| | |
| It is also possible to target a specific koji tag:
| |
| | |
| <pre>
| |
| fedpkg build --target TARGET
| |
| </pre>
| |
| | |
| For example, if building on rawhide against a special tag created by releng for updating API for many packages, such as <code>dist-f14-python</code>, use the following:
| |
| | |
| <pre>
| |
| fedpkg build --target 'dist-f14-python'
| |
| </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, [https://fedoraproject.org/wiki/Bodhi/BuildRootOverrides set up an override using bodhi] requesting packages to be included in the proper buildroot.}}
| |
| Sometimes you want to make sure that one build has succeeded before
| |
| launching the next one, for example when you want to rebuild
| |
| a package against a dependency that has just been rebuilt. In that case,
| |
| use a chain build with:
| |
| | |
| fedpkg chain-build 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:
| |
| | |
| fedpkg chain-build libwidget libaselib : libgizmo :
| |
| | |
| causes libwidget and libaselib to be built in parallel, followed by libgizmo, and then the package in your current directory. If no groups are defined, packages will be built sequentially.
| |
| | |
| If a build fails, following builds are canceled, but the builds that already succeeded are pushed to the repository.
| |
| | |
| == Scratch Builds ==
| |
| | |
| Sometimes it is useful to be able to build a package against the buildroot without actually including it in the release. This is called a scratch build.
| |
| | |
| The following section covers using koji directly, as well as the fedpkg tool, to do scratch builds. | |
| | |
| To create a scratch build from changes you haven't committed, do the following:
| |
| | |
| <pre>
| |
| rpmbuild -bs foo.spec
| |
| koji build --scratch rawhide foo.srpm
| |
| </pre>
| |
| | |
| From the latest git commit:
| |
| | |
| <pre>
| |
| koji build --scratch rawhide 'git url'
| |
| </pre>
| |
| | |
| If you have committed the changes to git and you are in the current branch, you can do a scratch build with fedpkg tool, which wraps the koji command line tool with the appropriate options:
| |
| | |
| <pre>
| |
| fedpkg scratch-build
| |
| </pre>
| |
| | |
| To run a scratch build for a specific architecture:
| |
| | |
| <pre>
| |
| fedpkg scratch-build --arches <archs>
| |
| </pre>
| |
| | |
| <archs> can be a comma separated list of several architectures.
| |
| | |
| Finally, it is possible to combine the scratch-build command with a specific koji tag in the form:
| |
| | |
| <pre>
| |
| fedpkg scratch-build --target TARGET
| |
| </pre>
| |
| | |
| fedpkg scratch-build --help or koji build --help for more information.
| |
| | |
| == Build Failures ==
| |
| | |
| If your package fails to build, you get an error, for example:
| |
| | |
| <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>
| |
| | |
| Investigate why the build failed by looking at the log files. If there is a build.log, start there. Otherwise, look at init.log.
| |
| | |
| Each job you successfully start gets a unique task ID, which is listed in its output.
| |
| | |
| Logs can be found in the web interface, in the Task pages for the failed task. Alternatively, use <code>koji watch-log</code>, along with the task ID, to view the logs. 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 prints 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 the 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 must pass --topurl=http://kojipkgs.fedoraproject.org/ to any mock-config command to get a working mock-config from Fedora's 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 fedpkg target, you can also directly
| |
| use the command_line tool, koji.
| |
| | |
| To build a package, the syntax is:
| |
| | |
| <pre>
| |
| $ koji build <build target> <git URL>
| |
| </pre>
| |
| | |
| For example:
| |
| {{Admon/warning | Replace <code>dist-f14</code> with the tag you wish to build against, e.g. <code>dist-rawhide</code>}}
| |
| | |
| <pre>
| |
| $ koji build dist-f14 'git url'
| |
| </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.
| |
| | |
| NOTE: For fedora koji, the git url MUST be based on pkgs.fedoraproject.org. Other arbitrary git repos cannot be used for builds.
| |
| | |
| == 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 afterward. 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 f30
| |
| Name Buildroot Destination
| |
| ---------------------------------------------------------------------------------------------
| |
| f30 f30-build f30-pending
| |
| </pre>
| |
| | |
| This tells you a build for target f30 will use a buildroot with packages from the f30-build tag and tag the resulting packages as f30-pending.
| |
| | |
| Watch out: You probably do not want to build against rawhide. If Fedora N is the latest one out, to build to the next one, choose 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-f14
| |
| | |
| </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-f14
| |
| | |
| </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]]
| |
