Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
User Guide / Usage / Basic OBS Workflow

5 Basic OBS Workflow

5.1 Setting Up Your Home Project

This section shows how to set up your home project with the command line tool osc. For more information about setting up your home project with the Web UI, see Section 1.6, “Setting Up Your Home Project for the First Time”.

This chapter is based on the following assumptions:

Procedure 5.1: Setting Up Your Home Project
  1. Get a list of all available build targets of your OBS instance:

    geeko > osc ls /

    For example, on the openSUSE Build Service, build targets will include distributions such as openSUSE:Tumbleweed, openSUSE:Leap:VERSION, openSUSE:Tools, openSUSE:Templates.

  2. Configure your build targets with:

    geeko > osc meta prj --edit home:obsgeeko

    The previous command shows a XML structure like this:

    Example 5.1: XML Structure of Build Service Metadata
    <project name="home:obsgeeko">
      <title>obsgeeko's Home Project</title>
      <description>A description of the project.</description>
      <person userid="obsgeeko" role="bugowner"/>
      <!-- contains other OBS users -->
      <debuginfo>
        <enable repository="openSUSE_Factory"/>
      </debuginfo>
      <!-- add <repository> elements here -->
    </project>
  3. To add build targets, use the repository element. For example, on openSUSE Build Service, you can add the build targets openSUSE Tumbleweed for x86 and x86-64 with:

    <repository name="openSUSE_Tumbleweed">
        <path project="openSUSE:Tumbleweed" repository="standard"/>
        <arch>i586</arch>
        <arch>x86_64</arch>
    </repository>
  4. Add more repository elements as needed. Insert the information from Step 1 into the project attribute.

    On openSUSE Build Service, you can normally use the attribute repository with the value standard. For example, to add openSUSE Leap as a build target, create an entry like:

    <repository name="openSUSE_Leap_42.3">
        <path project="openSUSE:Leap:42.3" repository="standard"/>
        <arch>i586</arch>
        <arch>x86_64</arch>
    </repository>
  5. Save the file (or leave it untouched).

    osc will check if the new configuration is valid XML. If the file is valid, osc will save it. Otherwise, it will show an error and prompt you whether to Try again?. In this case, press n. Your changes will be lost and you will need to start from Step 2 again.

After a while, the defined build targets show up in your home project.

5.2 Creating a New Package

This section covers how to create packages for an arbitrary software project, which we will refer to here as the upstream project. We assume that this project contains source code which you want to package for one or more SUSE (openSUSE) distributions. We assume the setup of your home project in your OBS instance is already done. If not, refer to Section 5.1, “Setting Up Your Home Project”.

To create a package from the upstream project, do the following:

Procedure 5.2: General Procedure to Build a RPM Package
  1. Open a shell. Choose or create a directory on your system in a partition that has enough space to hold the package sources.

  2. Prepare your working directory. These steps only have to be performed once:

    1. Check out your home project:

      geeko > osc checkout home:obsgeeko

      This will create home:obsgeeko in the current directory.

    2. Create a new package inside your local working directory:

      geeko > cd home:obsgeeko
      geeko > osc mkpac YOUR_PROJECT
  3. Download the source of the upstream project and save it in home:obsgeeko/YOUR_PROJECT.

  4. Create a spec file which contains metadata and build instructions. For more information about spec files, see https://rpm-packaging-guide.github.io.

  5. Create a new changelog and add your changes:

    1. To create a new changelog file or to update an existing changelog file with osc, use:

      geeko > osc vc

      The command will open an editor with the following content:

      -------------------------------------------------------------------
      Fri Aug 23 08:42:42 UTC 2017 - geeko@example.com
    2. Enter your changes in the editor.

      Usually, changelog entries contain a high-level overview like:

      • Version Updates.  Provide a general overview of new features or changes in behavior of the package.

      • Bug and Security Fixes.  If a bug was fixed, mention the bug number. Most projects have policies or conventions for abbreviating bug numbers, so there is no need to add a long URL.

        For example, in openSUSE Build Service, boo# is used for bugs on https://bugzilla.opensuse.org and fate# is used for features on https://fate.opensuse.org.

      • Incompatible Changes.  Mention incompatible changes, such as API changes, that affect users or other developers creating extensions of your package.

      • Distribution-Related Changes.  Mention any changes in the package structure, package names, and additions or removals of patch files or hacks.

      For more information about changelogs, see https://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM).

  6. Add all the files to your working directory:

    geeko > osc add *.spec *.changes *.tar.gz
  7. Build the package for a specific distribution and architecture, for example, openSUSE Tumbleweed for x86-64:

    geeko > osc build --local-package openSUSE_Tumbleweed x86_64 *.spec

    If you encounter problems, see Section 5.3, “Investigating the Local Build Process”.

  8. Check if your build was successful. If everything was fine, commit the files to your package to your home project on OBS:

    geeko > osc commit

To delete a file in your working directory, merely deleting it from the local filesystem (rm FILE) is not sufficient, since osc, like any other Source Code Control System, will just complain that the file is missing. If you really want to delete a file, use the command:

geeko > osc delete FILE

While there is no dedicated osc to "move" (rename) a file, the desired end result can be obtained using the following procedure:

Procedure 5.3: Procedure for Moving a File within a Locally Checked-out OBS Package
  1. geeko > cp ORIGINAL_FILE NEW_FILE
  2. geeko > osc delete ORIGINAL_FILE
  3. geeko > osc add NEW_FILE
  4. And, finally:

    geeko > osc status

    to verify that the end result is as intended.

5.3 Investigating the Local Build Process

It is hard to describe a general procedure when you encounter a build error. Most build errors are very specific to the package being built. However, there are generic tools that often help:

5.3.1 Build Log

Each build produces a log file on OBS. This log file can be viewed by the buildlog (or bl) subcommand. It needs a build target which is the distribution and the architecture.

For example, to view the build log of your current project for openSUSE Tumbleweed on a x86-64 architecture, use: use:

geeko > osc buildlog openSUSE_Tumbleweed x86_64

However, this command will print the complete build log which could be difficult to spot the errors. Use the buildlogtail subcommand to show only the end of the log file:

geeko > osc buildlogtail openSUSE_Tumbleweed x86_64

Additionally, the osc creates some build log files in the build directory /var/tmp/build-root/:

.build.log

Contains the log.

.build.command

Contains the command which is used to build the package. For RPM-like systems it is rpmbuild -ba PACKAGE.spec.

.build.packages

Contains the path to all object files.

5.3.2 Local Build Root Directory

If you build a package locally and you get a build error, investigate the problems in the build root directory directly. This is sometimes easier and more effective than only looking at the build log.

By default, the directory /var/tmp/build-root/ is used as the build root. This is defined in the configuration file ~/.oscrc using the key build-root.

Each combination of distribution and architecture has its own build root. To change into the build root for openSUSE Tumbleweed on the x86-64 architecture, use the following command:

geeko > osc chroot openSUSE_Tumbleweed x86_64

When prompted, enter the root password.

Your shell will then change to the directory /home/abuild belonging to the user abuild in group abuild.

The build root contains the following structure:

Example 5.2: Directory Structure of a Build Root (/var/tmp/build-root/)
/home/abuild/
└── rpmbuild
    ├── BUILD 1
    ├── BUILDROOT  2
    ├── OTHER  3
    ├── RPMS  4
    │   ├── i386
    │   ├── noarch
    │   └── x86_64
    ├── SOURCES  5
    ├── SPECS  6
    └── SRPMS  7

1

Contains directory named after the package name. In spec files, the name of the package directory is referenced using the %buildroot macro.

2

If the build process was unable to create a package, this directory contains all files and directories which are installed in the target system through the %install section of the spec file.

If the package has been successfully built, this directory will be emptied.

3

Usually contains the file rpmlint.log.

4

If the build was successful, stores binary RPMs into subdirectories of architecture (for example, noarch or x86_64).

5

All source files from the working copy will be copied here.

6

7

Stores source RPMs into this directory.

5.4 Adding Dependencies to Your Project

Software usually depends on other software: To run an application, you may, for example, need additional libraries. Such dependencies are called installation requirements.

Additionally, there are also dependencies that are only necessary for building a package but not when the software it contains is run. Such dependencies are called build requirements.

The Open Build Service provides the following methods to handle both dependencies in your projects:

5.4.1 Adding Dependencies to Your Build Recipes

In a spec file, dependencies are expressed with the keywords Requires (installation requirements) and BuildRequires (installation requirements). Both belong to the header of the spec file.

Example 5.3: Excerpt of Build and Installation Requirements
Name:             foo-example
Version:          1.0.0
BuildRequires:    bar
Requires:         zool >= 1.5.6

5.4.2 Associating Other Repositories with Your Repository

There is no need to duplicate the work of others. If you need a specific package which is available in another repository, you can reference this repository in your project metadata. This is called layering.

When a package is needed, it can be installed from another other repository (see the note below).

To add another repository that can be used as build or installation requirements, do the following:

  1. Open a terminal.

  2. Edit the project metadata:

    geeko > osc meta prj --edit home:obsgeeko
  3. Search for repository elements. For example, to allow usage packages from devel:languages:python in a openSUSE Tumbleweed project, extend the repository element with:

    <repository name="openSUSE_Tumbleweed">
        <path project="devel:languages:python" repository="openSUSE_Factory"/>
        <path project="openSUSE:Factory" repository="standard"/>
        <arch>x86_64</arch>
    </repository>
    Note
    Note: Order Is Important

    The order of the path elements is important: path elements are searched from top to bottom.

    If a package cannot be found in the first repository, the second repository is considered. When the first suitable package is found, it is installed and the build preparation can continue.

    For practical reasons, additional repositories should be added before the standard repositories of the specified distribution.

  4. Add more path elements under the same repository element.

  5. If necessary, repeat Step 3 and Step 4 to add path elements to repository elements of other distributions or releases.

5.4.3 Reusing Packages in Your Project

To reuse existing packages in your package repository, OBS offers two methods: aggregating and linking.

5.4.3.1 Aggregating a Package

An aggregate package is a pointer to an OBS package. Such package and the result of it are referenced int another project. Aggregating is used in the following situations:

  • No changes in the source code are needed.

  • Packages that are needed for building are only available in a different project.

  • Build results (binaries) of the aggregated package are copied into the target's package repository.

  • To avoid package rebuilds.

The general syntax of the aggregatepac command is:

geeko > osc aggregatepac SOURCEPRJ SOURCEPAC DESTPRJ

For example, to aggregate the package python-lxml from devel:language:python into your home project, use the following command:

geeko > osc aggregatepac devel:language:python python-lxml home:obsgeeko

The next time you update your working directory, the python-lxml contains the _aggregate file.

5.4.3.2 Linking a Package

A linked package is a clone of another package with additional modifications. Linking is used in the following situations:

  • The source code needs changes, but the source either cannot be changed in the original package or doing so is impractical or inconvenient to change the source.

  • To separate the original source from own patches.

The general syntax of the linkpac command is:

geeko > osc linkpac SOURCEPRJ SOURCEPAC DESTPRJ

For example, to link the package python-lxml from devel:language:python into your home project, use the following command:

geeko > osc linkpac devel:language:python python-lxml home:obsgeeko

In contrast to aggregating, the checkout contains all the files from the linked repository. To reduce it to a single file (like with aggregating), unexpand it in the working directory like this:

geeko > osc up --unexpand-link
Unexpanding to rev 1
A    _link
D    pytest-3.2.1.tar.gz
D    python-pytest-doc.changes
D    python-pytest-doc.spec
D    python-pytest.changes
D    python-pytest.spec
At revision 1.

This gives you a _link file similar to the _aggregate file. You can use the --expand-link option in the up subcommand to revert to the previous state.

5.5 Manage Group

Users with Maintainer rights can add users to their group and remove users from it. They can also give other users Maintainer rights.

osc api -d "<group><title><group-title></title><email><group-email></email><maintainer userid="<user-name>"/><person><person userid="<user_name>"/></person></group>' -X PUT "/group/<group-title>"