1 Beginnerʼs Guide #

To allow all users in the osc group to build packages without entering the root password, do as follows.

1. Log in as root and create a new group osc. This group will contain all users which are allowed to build packages:

   root # groupadd osc

2. Add users to your newly created group osc which are allowed to build packages:

   root # usermod -a -G osc geeko

   Repeat this step to add other users, if necessary.

3. Run visudo to create the sudoers file /etc/sudoers.d/osc:

   root # visudo -f /etc/sudoers.d/osc

4. Add the following lines to create a command alias that can be executed only by the osc group:

   # sudoers file "/etc/sudoers.d/osc" for the osc group
   Cmnd_Alias  OSC_CMD = /usr/bin/osc, /usr/bin/build
   %osc  ALL = (ALL) NOPASSWD:OSC_CMD

5. Log out of your system and log in again to apply the changes.

6. Create a new OBS configuration file:

   geeko > osc ls home:obsgeeko

   If you run the command for the first time, you will be prompted to enter your OBS user name and OBS password.

1. Log in to the Open Build Service instance.

2. Click the Your Home Project link in the Places menu on the left.

3. Click the Repositories tab, then the Add from a Distribution link.

4. Select the distributions you want to build for.

   OBS shows several Linux distributions. For SUSE distributions, it is recommended to activate at least openSUSE Tumbleweed and the latest openSUSE Leap release. To enable package builds for SUSE Linux Enterprise, mark one of the openSUSE Backports for SLE 12.

   When you select a distribution, OBS shows a message that the distribution has been successfully added it to your home project.

5. Click the Overview tab to see the available build targets on the right side.

1. Set up your home project as shown in Section 1.6, “Setting Up Your Home Project for the First Time”.

2. In the terminal, choose or create a directory on a local partition that has enough space to hold the package sources.

3. Check out your home project:

   geeko > osc checkout home:obsgeeko

   This creates an empty home:obsgeeko directory in the current directory.

4. Create a new package in your local working directory:

   geeko > cd home:obsgeeko
   geeko > osc mkpac my-first-obs-package

5. Get the source code from the upstream repository and save it in home:obsgeeko/my-first-obs-package.

   Download a TAR archive of the sources. You do not have to unpack it yet.

   In our example, the upstream repository is hosted on GitHub and you can use the following URL: https://github.com/obs-example/my-first-obs-package/releases. If there is no published release, click the Clone or download button and download the latest sources using the Download ZIP link.

6. Create the build recipe. This file contains metadata and build instructions.

   In this example, we are building an RPM for openSUSE. For RPM-based distributions, we create a spec file. The skeleton of such a spec file looks like this:

   Example 1.1: Skeleton of a Spec File #

    

   #
   # spec file for package my-first-obs-package
   #
   # -- Copyright omitted --
   
   Name:           my-first-obs-package 1
   Version:        0.1.0 1
   Release:        0 1
   License:        GPL-3.0 1
   Group:          Documentation 1
   Summary:        Frobnication Tool 1
   Url:            https://github.com/obs-example/my-first-obs-package 1
   Source:         my-first-obs-package-%{version}.tar.gz 1
   BuildRequires:  gcc 2
   BuildRequires:  cmake 2
   BuildRoot:      %{_tmppath}/%{name}-%{version}-build
   
   %description 3
   This tool frobnicates the bar with the foo when choosing the baz.
   
   %prep 4
   %setup -q -n %{name}-%{version}
   
   %build 5
   
   %install 6
   
   %files 7
   %defattr(-,root,root,-)
   %doc README LICENSE *.txt
   %{_bindir}/*
   
   %changelog 8

   1	The Header. Metadata like package name, version, release, license, the RPM group, a brief summary, the upstream URL, and the name of the source file.
   2	Build Requirements. Lists package dependencies that are required for building. The listed packages are downloaded and installed before building the package.
   3	The Description Section. Describes the purpose of the package and gives a comprehensive explanation.
   4	The Preparation Section.  Prepares the sources for building. This usually includes unpacking them with the %setup macro and patching them using the %patch macro. (For more information about patching, see Section 1.8, “Patching Source Code”.)
   5	The Build Section.  Contains commands or RPM macros for building the package.
   6	The Install Section. Contains commands or RPM macros which create directories or copy files to the installation location.
   7	The Files Section. Lists all files and directories which belong to the package. Documentation-related files are marked with %doc, and they are automatically installed in the default documentation directory.
   8	The Changelog Section. This section is usually empty. Instead, OBS searches for a file with the extension .changes. If such a file exists in the project directory, it will be automatically included as a changelog. The changelog file itself contains a high level overview of the history of the package.

   For the complete spec file, see https://build.opensuse.org/package/view_file/home:obsgeeko/my-first-obs-package/my-first-obs-package.spec.

7. Create a changelog file:

   geeko > osc vc

   This command opens a text file with the following content in the default editor:

   -------------------------------------------------------------------
   Fri Aug 23 12:31:41 UTC 2017 - geeko@example.com

   Add a short summary of your changes. Usually, a changelog entry contains a high-level overview such as the version of the software in the package, which patches you applied, and other changes in your project.

   Save the file and leave the editor. osc then creates the file my-first-obs-package.changes.

   Your project directory should now look something like this:

   project directory
        ├── my-first-obs-package-0.1.0.tar.gz
        ├── my-first-obs-package.changes
        └── my-first-obs-package.spec

8. Add all the files to your working directory:

   geeko > osc add *.spec *.changes *.tar.gz

9. Build the package for the default build target:

   geeko > osc build --local-package

   The option --local-package is used here, because the package is not yet submitted to OBS.

   The default build target is set in the osc configuration file ~/.oscrc using the variable build_repository. On openSUSE Build Service this is usually openSUSE Tumbleweed.

   To build the package for another build target, use the following command:

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

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

    geeko > osc commit

    If you encounter build errors, use the osc buildlog command to review them, as described below.

1. In the terminal, switch to your working directory.

2. Prepare a patch file:

   1. Unpack the source code:

      geeko > tar xvf my-first-obs-package-*.tar.gz

      If you have downloaded the archive from GitHub, the archive contains a directory in the form NAME-VERSION. In our case, unpacking the downloaded archive results in the my-first-obs-package-0.1.0/ directory.

   2. Switch to the directory my-first-obs-package-0.1.0/ and make a copy of the original C++ source file:

      geeko > cd my-first-obs-package-0.1.0/
      geeko > cp src/main.cpp src/main.cpp.orig

   3. Make your changes in src/main.cpp.

   4. Create a diff and carefully inspect your changes:

      geeko > diff -u src/main.cpp.orig src/main.cpp

      The output should look like this:

      --- src/main.cpp.orig   2017-08-09 16:28:31.407449707 +0200
      +++ src/main.cpp        2017-08-09 16:28:49.131541230 +0200
      @@ -2,7 +2,7 @@
      
       int main()
       {
      -    std::cout<<"Hello OBS!\n";
      +    std::cout<<"Hello Alice!\n";
      
           return 0;
       }

   5. Redirect the diff into a file:

      geeko > diff -u src/main.cpp.orig src/main.cpp \
        > ../my-first-obs-package_main.diff

      You can use an arbitrary name for the patch file. However, we recommend giving the file a descriptive name and adding the name of the upstream project. If there is a bug or issue number associated with the patch, add it to the file name as well. You can either use .diff or .patch as the file extension.

   6. You can now remove the directory my-first-obs-package-0.1.0/, as it is not needed anymore.

3. Open your spec file and add the following line in the header under the Source line like this:

   Source:         my-first-obs-package-%{version}.tar.gz
   Patch0:         my-first-obs-package_main.diff

4. In the %prep section, add the %patch macro:

   %prep
   %setup -q -n %{name}-%{version}
   %patch0

5. Add your patch file to the local repository:

   geeko > osc add my-first-obs-package_main.diff

6. Rebuild your package:

   geeko > osc build

7. If everything was successful, commit your changes:

   geeko > osc commit

   When prompted, specify and save a commit message.

1. In the terminal, choose or create a directory on a local partition with enough free space.

2. Create a branch from geeko's home project:

   tux > osc branchco home:obsgeeko my-first-obs-package

   This creates a branched package in OBS at home:obstux:branches/my-first-obs-package and checks out a directory home:obstux:branches:home:obsgeeko:my-first-obs-package.

3. Change the working directory to your checked-out branch:

   tux > cd home:obstux/branches/home/obsgeeko/my-first-obs-package

4. Make changes as shown in Section 1.8, “Patching Source Code”.

5. Build the package for the default build target:

   geeko > osc build

6. Review the build log:

   geeko > osc buildlog openSUSE_Tumbleweed x86_64

7. Make sure all included and removed files are added to the OBS repository:

   tux > osc addremove

8. If everything was successful, commit your changes:

   geeko > osc commit

   When prompted, specify and save a commit message.

9. Create a submit request and finish it by adding a comment:

   tux > osc submitreq

   Used without any options, the submitreq command submits back to the package where you branched from. Note that with the submit request, you submit a specific version of the source. Later changes do not get automatically fetched by default.

   If there are multiple packages in a branch, all packages will be submitted together. To avoid that, specify the names of the source and destination projects and the package name:

   tux > osc submitreq home:obstux:branches:home:obsgeeko my-first-obs-package home:obsgeeko

1. Show all submit requests that belong to your home project

   geeko > osc request list -s new -P home:obsgeeko

2. Find the correct submit request. If you know the correct number you can use:

   geeko > osc request show 246

3. Review the request and decide:

   • Accept the submit request:

     geeko > osc request accept 246 --message="Reviewed OK."

   • Decline the request and give a reason:

     geeko > osc request decline 256 --message="Declined, because of missing semicolon."

1. Inside your working directory, determine the download repository URLs:

   geeko > osc repourls
   https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_Tumbleweed/home:obsgeeko.repo
   https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_42.2/home:obsgeeko.repo

2. Copy the desired URL of your preferred distribution. In our case, that is the line containing openSUSE_Tumbleweed.

3. Use zypper and add the copied URL:

   root # zypper addrepo https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_Tumbleweed/home:obsgeeko.repo

   When prompted, accept the GPG key of the download repository.

4. Install the package:

   root # zypper install my-first-obs-package