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:

You have an account on an Open Build Service instance. To create an account, use the Web UI.
You have installed osc as described in Section 3.1, “Installing and Configuring”.
You have configured osc as described in Section 3.3.2, “Using osc for the First Time”.

Procedure 5.1: Setting Up Your Home Project #

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.

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>

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>
```
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>
```
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 #

Open a shell. Choose or create a directory on your system in a partition that has enough space to hold the package sources.
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
```
Download the source of the upstream project and save it in home:obsgeeko/YOUR_PROJECT.
Create a spec file which contains metadata and build instructions. For more information about spec files, see https://rpm-packaging-guide.github.io.
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).
Add all the files to your working directory:
```
geeko > osc add *.spec *.changes *.tar.gz
```
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”.
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 #

```
geeko > cp ORIGINAL_FILE NEW_FILE
```
```
geeko > osc delete ORIGINAL_FILE
```
```
geeko > osc add NEW_FILE
```
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:

Section 5.4.1, “Adding Dependencies to Your Build Recipes”
Section 5.4.2, “Associating Other Repositories with Your Repository” (layering)
Section 5.4.3, “Reusing Packages in Your Project” (linking and aggregating)

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:

Open a terminal.

Edit the project metadata:

geeko > osc meta prj --edit home:obsgeeko

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: 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.
Add more path elements under the same repository element.
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>"