You should be familiar with the source code environment your project is using for your package. The Build Service can work around some common mistakes and will try to guide you in case of failures. We have a buildservice-mailinglist which can be a source of help and advice. However, decisions on which patches to apply, what compiler flags to use, etc. are ultimately up to you.

Терминология

The Build Service contains projects (you can view a list of them). Each project contains the resources needed to build one or more packages (i.e. RPMs/DEBs/etc.). These resources include source archives, patch files, spec files, etc. The output of a project is one or more repositories. A repository is an old familiar concept: simply a bunch of RPMs organized in a directory hierarchy along with some index/meta-data files that make it easy for tools like zypper to search and resolve dependencies. The repositories a project outputs correspond to the different operating system versions such as openSUSE 11.2, etc.

As far as the projects that exist, there are "official" openSUSE projects that build the RPMs provided in the standard openSUSE distributions. The "factory" project is the work-in-progress project that will become the next version of openSUSE. There are also lots of area-specific projects such as Apache and network:telephony. Finally, each user has his own "playground" project named home:username.

RPMs tend to have lots of dependencies on other RPMs, and often these RPMs come from different projects within the Build Service. This has two important implications.

First, if your package depends on some other package at runtime ("Requires"), it will often also depend on it at build time (i.e., "BuildRequires"). The Build Service does not automatically go search and find build dependencies for you (other than what is included in the standard distribution you are building for). So somehow you have to tell the Build Service where to get the required package.

Secondly, a nice goal is for a repository to be transitively closed, i.e. any dependency of any package in the repository is also in the repository (packages in the standard distribution excepted). This makes life easier for people installing the RPMs your project provides. But this is not required: users can always find these dependencies manually using the search interface.

The Build Service provides a few different ways to facilitate handling of these dependencies.

First, you can directly add the required package(s) to your repository. This is certainly the approach you must take if no other project builds the required
packages. Typically though, those packages are already being built by some other project. Consider re-using their work.

The second option is to link the other project's repository to your repository. This is called layering. It is done by editing the meta-data of your
project. Add the other project/repository as an additional path. This simply adds to the list of repositories in which the Build Service will search for
"BuildRequires" dependencies at build time. This will allow your package's build to succeed, addressing the first problem, but it does not address the
"transitively closed" goal at all: users will have to go fetch the required package themselves. However, this is a good choice when there are several
dependencies from your project into another project and/or users are likely to be pulling from both repositories anyway.

The third option is called linking and is a way to allow your project to re-use a package that already exists in another project. When you link a
package into your project, dependent packages will be able to build, and the package will also appear your project's repository, therefore solving both
problems without duplicating any work.

There are two types of linking: link and aggregate. When you link, you can optionally modify the way the package is built. You can add patches, and enable the build for additional repositories. Your build of the package's RPM will have a different build number from the original
project's build of it. Note, this could cause confusion for users. Really, you are building a different version of a package with the same name.

Unless you need to modify the required package, you should aggregate instead of link. When you aggregate, you are performing a
"read-only" link. The package is not built within your project; instead, the already-built package is copied into your project from the original project. So
the same RPM (with the same build number) will appear in both projects. For the user, there is less confusion because the RPMs are identical.

The Build Service automatically detects changes in linked packages and triggers rebuilds of any packages depending on them.

Correct Errors in the Local Build Process

The main reason why you would need to compile a new package for openSUSE or any other distro is to assert compatibility if your package has not yet been compiled for your operating system version and release.
However, that way you may encounter new errors in the build process which need to be fixed.
The easiest way to fix errors is to chroot to the build environment and create a fix there. You may want to use openroot instead of chroot in order to get X11 access and all the other necessary directories mounted.

Install extra packages to build root

For debugging purposes, you might need to install extra packages to your local build root to debug and fix build related problems. This can be done through the ~/.oscrc file and variable extra-pkgs. For example:

extra-pkgs = vim gdb strace valgrind

install privileges

If you get an error message like this:

error: Bad exit status from /var/tmp/rpm-tmp.qrRAn2 (%install)

this means that your %install step has failed (and all others before went well). This can be because of missing write privileges if you try to install to the wrong place. In this case add the following make install command to your spec file:

make install DESTDIR=%buildroot

submit your work back to OBS

Once you have your <package> directory the way you want it, use the below commands to submit your work back to OBS.

add a new file to the package

osc add

remove a file from the package

osc rm

update the change log (ie. *.changes)

osc vc

submit your updated files back to OBS

osc commit

Patches

If you plan to patch a file copy it before editing to .orig, retry the desired step in the build process until it succeeds and then create a patch for it.
To make the build more verbose you may want to insert a "set -x" in your specfile making bash recite all executed commands (set +x disables reciting afterwards).

Now add the patch to the .spec-file by listing "Patch67: my.patch" in the header and then let it be applied at the appropriate position (usually %setup) in the build process by "%patch67 -p7" (-p7 strips seven directory levels if you have not manually edited the file directories in the header of the patch file.).

You may find it easier to use a special program for automatic patch generation like quilt:

foo-fixbuild.patch will automatically be created in the parent dir. If you work on a package which doesnt have a patch yet. You have to remember to copy the patch from the patch directory to your package directory. Rerun quilt setup to get an initial patch. You can remove patches from your working copy with quilt pop.

Шаг 5 — проверка журнальных файлов

The buildservice produces one big logfile for each build of a package.

Web client: Just click on the status of the Build result tab in the package view.

Command line: You have a few choices depending on your needs (packagedir is optional if you are in the package directory):

osc prjresults [packagedir]

Shows the aggregated build results of an entire project. Or you can do:

osc results [packagedir]

Shows the build results of a single package.

osc buildlog <platform> <arch>

Shows the log file from a package (you need to be inside a package directory).

Create Patterns

Patterns are files which contain a list of packages together with a description of what they are useful for. Additionally the Build Service creates .ymp files for each generated repository pattern. These .ymp files can be used for a One Click Install by the user.

In short, patterns are useful for installing a set of software for a typical need without creating dependencies between packages.

Submitting patterns is possible using the api directly, or using osc:

to open a pattern in $EDITOR (creating it if it doesn't exist yet)

osc meta pattern -e <project> <pattern>

to list existing patterns

osc meta pattern <project>

get an existing pattern

osc meta pattern <project> <pattern>

You can also submit an existing file as below:

osc meta pattern --file <local_file> <project> <pattern>

To test: clicking on the .ymp in konqueror should launch the installer, if you do not have konqueror installed, you can try launching from shell as normal user:

Requires RPM example: this package must be installed - otherwise the pattern is not fulfilled.

<rpm:recommends>
<rpm:entry name="example" />
</rpm:recommends>

Recommends RPM example: if available and all dependencies of this package are fulfilled, the package would be installed. If the package is not available, there are not error messages. If the package dependencies are not met, the package would be visible but not installed.

<rpm:suggests>
<rpm:entry name="example" />
</rpm:suggests>

Suggests RPM example: would be shown in the pattern but not installed per default

A start to end example of a simple change

Note: There are at least two other wiki pages that document the branch/fix/submit patch workflow:

The goal here is to have a specific example that can be used as a tutorial.

Внимание:Всё нижеописанное не закончено или не испытывалось

A common activity is to branch an existing package in an existing project, make a change and submit that change back to the original package.

The basic steps are:

Branch the original package: "osc branch <original_project> <original_package>" This creates a new branch project that is specific for you named home:<your_user_name>:branches:<original_project_name> and therein it creates a new package with the same name as original package that is basically a copy of the original package.

Checkout the branched package: "osc checkout home:<your_user_name>:branches:<original_project_name>/<original_package_name>" This downloads the source files of the branched package from the server into a local sub-directory named home:<your_user_name>:branches:<original_project_name>/<original_package_name>

Go to the local sub-directory: "cd home:<your_user_name>:branches:<original_project_name>/<original_package_name>" and set the usual default umask "umask 0022"

Work on your local copy of the package until it works for you:

Change the local source files (e.g. edit the specfile or create a patch)

Perform a local build

Do a local package installation

Test the local installed package

Update the changes file: "osc vc" This opens an editor (usually 'vi') and creates an appropriate header for a RPM changes entry. If there was a bug report it must be referenced as bnc#123456

If you added new files (e.g. new patches) or removed files (e.g. obsolete patches), update the version control status of the local source files: "osc addremove" and verify with "osc status" that there are no files with problematic version control status like '?' or '!'

Commit the local source files into the branched package: "osc commit" This uploads the local source files into the branched package on the server and that triggers an automated re-build of the branched package.

Review the build results of the branched package for all build repositories that are enabled for the original package: "osc results --verbose home:<your_user_name>:branches:<original_project_name> <original_package_name>" To list the build repositories that are enabled for the original package get its build results: "osc results <original_project> <original_package>"

If the re-build of the branched package "succeeded" for all build repositories that are enabled for the original package, create a request to submit the branched package back to the original package: "osc submitrequest --message='<a short message that describes what you changed plus bnc#123456 if there exists a matching bug report>' home:<your_user_name>:branches:<original_project_name> <original_package_name> <original_project> <original_package>" and remenber the request ID number.

From time to time check what happened with your request: "osc request show <request_ID_number>" If you need to get in direct contact with the maintainers of the original package: "osc maintainer <original_project> <original_package>" shows their user names and "osc whois <user_name>" shows fullname and email of a buildservice user.

It's a few steps, but once you get a hang on it, it becomes second nature.

This assumes you already have an account on OBS. If not, go ahead and set that up at http://build.opensuse.org/ and use the login link on the upper right to login. OBS uses the same authentication system as the rest of the openSUSE infrastructure like bugzilla, so you likely all ready have a account, you just need to login for the first time and the OBS account home project will be automatically created.

# this untars the tarball and does some magic
quilt setup sleuthkit.spec
# chdir to sources
cd sleuthkit-3.2.3
# apply all patches
quilt push -a
# add new patch
quilt new testing.patch
# add a file to the patch
quilt add some-file
vi <some-file>
# or alternatively:
quilt edit <some-file>
# and finally
quilt refresh -p1
# copy the patch up to the project dir
cp patches/testing.patch ..
# and now handle the spec file
cd ..
vi sleuthkit.spec
# Add patch to it by creating a Patch0 entry in the header area and a %patch0 -p1 line to the %prep section
# tell OBS that the package now includes a new file
osc add testing.patch
# update the changes file
osc vc -m "Fix some typos."
# and build, install and test your work
osc build
# perform a local install. At the end of the osc build output the full path of the RPM file should be shown
zypper in -f <full_path_to_rpm>
# repeat until happy. Go back to quilt edit if not happy.
# send your edits back to OBS
osc commit
# wait a period of time for new packages to build on OBS
# check the build status via the WebUI for your branched package
# Once published, install the RPM from OBS and test again
# submit your changes back to the original package. If there is a bugzilla entry, be sure to reference it