Revision as of 11:12, 6 December 2011

This is the user manual of the command-line and graphical interface of OBS Light.

• OBS Light project
• Frequently Asked Questions
• Installation

General principles

Operation modes

OBS Light is available via command line (obslight) and a graphical user interface GUI (obslightgui). Independently of that fact that you are using the command line or the GUI, you will get access to the same services.

Videos training

We have created a set of video which will provide you a quick overview of how to start with OBS Light.
They cover :

• Where to find the tool and information
• How to install OBS Light and get write access to an OBS
• Creation of you first project and package import
• Working in the Chroot
• Auto creation of patch and upload to OBS

http://www.dailymotion.com/playlist/x1t5ll_dominigarfoll_obs-light-training

Step by step

Get Login access to an OBS server

OBS Light is a simplified model to develop code via an OBS. It does not replace your OBS.
To use OBS Light you will need a login access to an OBS. You have two simple methods to get a login on an OBS:

• You can create a login on several "free" OBS :
  • MeeGo Community https://build.pub.meego.com/
  • OpenSUSE https://build.opensuse.org/
• Run your private OBS instance
  • Select a ready made MeeGo OBS appliance (highly recommended) http://susestudio.com/a/e0uuBG/meego-obs
  • Install your private full appliance (advanced users only) http://en.opensuse.org/openSUSE:Build_Service_private_instance

Once you have a login on an OBS instance, you will need to copy a project to play with. You can use the utilities obstag and obs2obscopy to achieve that in an easy way. See Obstag .

Configure your OBS servers

OBS Light needs to know on which server you will connect to. As OBS Light does more than the osc tool, more information will be needed. You will be asked the following  :

• OBS server web URL
• OBS server API URL
• OBS repository URL
• Login
• Password
• Alias (note that Alias will need to be different from any Alias already present in your osc configuration and OBS light will enforce that constrain). If you plan to use the import/export functions make sure that you use the same Alias on the sending and receiving hosts.

Even if these information are copied in .osrcrc, they must be maintain via the OBS light command.

Import the package(s) to work on

After the configuration of one or more OBS servers, you will be able to import a package to work on. You can also create an empty package would you like to.

OBS Light will create a local copy of that package on your workstation in a very similar way to what an osc checkout action would do. As osc, OBS Light transparently keeps track directly of the links between the packages and the associated OBS servers.

Create a Chroot

Once that you have loaded the packages, you can, by a simple selection of a given package, request the creation of a chroot. The created chroot is specific to the project and will not be recreated if it's already present. During the creation of the chroot, extra packages imposed by the build dependencies will be loaded automatically. If you are connected on a remote OBS that phase can take some time and may require a bit of patience.

OBS Light tries to load automatically the dependencies from the analysis of the .spec file in the RPM but that is not always possible. The user has the possibility to add manually extra file and/or packages to the chroot.

Packages can be imported either from a project already present in OBS Light or from any URL.

Importing the code in the chroot

Once that the chroot is created, the source from the package can be imported in the chroot. During that process, OBS Light will load the extra package needed to build that specific imported source and will create a special git tree which will monitor any changes done by the user.

The user can directly open a window on the chroot from OBS Light. The console program used by default can be defined in the OBS Light configuration file. From there direct modification of the code in the chroot is possible and local build can be run as often as desired.

Committing changes

When the user is happy of his change, he can request the change from the chroot to be committed directly in the package.
A patch will be created and added to the package and configured in the .spec file by OBS Light.

Saving changes on the OBS server

Once that changes on a given project (which can work on one or multiple packages) achieve a stage which is worth to push on the OBS server. The user can simply request to save the project and OBS Light will commit the changes automatically.

Example: patching MeeGo 1.2 kernel package

Step1: inform obslight about your OBS account

obslight addObsServer --serverApi <your OBS API URL> --serverRepo <your OBS package repository URL> --alias <alias> --user <login> --password <password>

serverApi

is the URL to the OBS control API. If you are using OBS appliance, it's probably on port 81.

serverRepo

is the URL to the OBS package repositories. If you are using OBS appliance, it's probably on port 82.

alias

is the alias you want to use to refer to this server.

Step2: create a local project related to your OBS project

• The project is created in ~/OBSLight/MeeGo_1.2_oss/

obslight addProject --projectLocalName MeeGo_1.2_oss --projectObsName MeeGo:1.2:oss --obsServer <alias> --projectArch i586 --projectTarget standard

projectLocalName

is the name you will use to refer to this project with the obslight command.

projectObsName

is the name of the project on the OBS.

obsServer

is the URL (or alias) of the OBS from which we get the project (which has been configured in first step).

projectTarget

is the target against which we will build (standard is the common name when there is only one).

projectArch

is the target architecture of the project.

Step3: add the kernel package to your local project

• The package is created in ~/OBSLight/MeeGo_1.2_oss/MeeGo:1.2:oss/kernel/
• In this directory, the package is manageable by osc.

obslight addPackage --projectLocalName MeeGo_1.2_oss --package kernel

Step4: create the chroot of the project

• The chroot directory is ~/OBSLight/MeeGo_1.2_oss/aChroot/.
• The chroot is created with zypper and your OBS project repository is automatically added.

obslight createChRoot --projectLocalName MeeGo_1.2_oss

Step5: add the source of the kernel package into your chroot

• The source package is extracted in directory /root/rpmbuild/BUILD/kernel-X.X.X/linux-X.X.X.
• After the installation, a git repository is initialized in package's directory.

obslight addPackageSourceInChRoot --projectLocalName MeeGo_1.2_oss --package kernel

Step6: work as you want into your chroot

• The directory ~/OBSLight/MeeGo_1.2_oss/chrootTransfert/ is mounted into the chroot in /chrootTransfert/.
• Every script executed in aChroot, is stored in /chrootTransfert/ as runMe_YYYY-MM-DD_HHhMMmSS.sh.

obslight goToChRoot --projectLocalName MeeGo_1.2_oss --package kernel

Now you are logged in the chroot. In this example we just modify the kernel configuration.

# cp configs/kernel-x86.config .config
# make menuconfig

Step7: save your modifications

There are two methods.

Method1: by making a patch

# cp .config config-x86
# exit
obslight makePatch --projectLocalName  MeeGo_1.2_oss --package kernel --patch myKernelPatch.patch

• The patch is automatically added to the local spec file.
• myKernelPatch.patch is automatically added to the local package directory.
• kernel package specific: you must move the patch application command %patchXXX -p1 after the command line cp $RPM_SOURCE_DIR/config-* . in the local spec file

vi ~/OBSLight/MeeGo_1.2_oss/MeeGo:1.2:oss/kernel/kernel.spec

Method2: by copying the new configuration file in OSC directory

# cp .config /chrootTransfert/config-x86
# exit
cp /chrootTransfert/config-x86 ~/OBSLight/MeeGo_1.2_oss/MeeGo:1.2:oss/kernel/

Upstream your modifications to the OBS server

• The command addAndCommitChanges checks the additions and deletions of files, before committing the package to the OBS server.

obslight addAndCommitChanges --projectLocalName MeeGo_1.2_oss --package kernel -m "Patch kernel"

Command-line

The help is integrated in the tool. obslight --help will give you an online help.
To get more detail on a specific command you can type obslight command --help.

#obslight --help
Usage: ObsLight [global command] <command> [--command-options]

Type obslight <command> --help to get help on a specific command.
Commands:

       getLocalProjectList:    Print the list of local projects.
       getPackageList:         Print the list of packages of a project.

       getObsServerList:       Print the list of OBS servers.
       addObsServer:           Add an OBS server.
       delObsServer:           Del an OBS server.

       addProject:             Create a local project based on an existing project on an OBS server.
       exportProject:          save a Project into a path
       importProject:          import a Project from a file
       getWebProjectPage:              return the web URL of a project.

       removeProject:          Remove local project
       removePackage:          Remove local package from a local project

       addPackage:             Create a local package in a local project, based on an existing package in a project on an OBS server.
       createChRoot:           Create a chroot, built from a local project.
       addPackageSourceInChRoot:Install the source RPM of a package into the chroot of the project.
       goToChRoot:             Open a bash in the chroot of a project.
       makePatch:              Generate a patch with modifications made in the chroot of a local project.
       addAndCommitChanges:    Add the new files (including patches) and commit them to the OBS
       addRepoInChRoot:        Add a repository to the chroot's zypper configuration file.

global commands
       --quiet:        Print all subprocess outputs.
       --debug:        Print all subprocess commands.
       --version       Print the current version.

ObsLight:
       Provides a tool to manage an OBS project on your local machine
       For additional informations, see
       * http://wiki.meego.com/OBS_Light

Graphical interface

The GUI is launched via the command obslightgui.

Only the parameter --version is supported.

The GUI is split in 3 main sections:

• OBS project
• Packages
• local files and chroot (on a tab)

The buttons in each section apply to the relative section. They display a tool-tip when the mouse is positioned on them. Button are grayed when there are not active or not yet implemented.

The graphical interface has two main tabs: OBS Projects and Imager Projects.

OBS projects tab

This tab allows you to manage an OBS project, its packages (and their files) and its chroot.

The project panel

The panel on the left displays the list of projects locally configured, and information about the selected project.

The package panel

The panel on the middle displays the list of packages of the selected project, and information about the selected package.

The file panel

The file panel has two tabs: local directory and chroot.

The local directory tab

This tab shows the list of files contained in the selected package.

The chroot tab

This tab shows the complete file tree of the chroot of the selected project. If a package is selected and it has previously been imported into the chroot, its path is expanded by default.

Imager projects tab

Currently not available.

Troubleshooting

"Source package 'xxx' not found" or "Problem: nothing provides X needed by Y"

These message may appear in two situations:

• The package you are trying to build is missing a dependency. OBS Light is not capable of searching dependencies outside the project from which your package comes. You will need to configure an additional repository in the chroot, using command addRepoInChRoot or the repository-related buttons in the GUI.
• In an ARM chroot, zypper or libzypp are broken, they do not see noarch packages. This problem was reported with zypper 1.5.3 and libzypp 8.12.1. We suggest you to update your zypper version to 1.6+. For convenience, we pre-built zypper 1.6.15 and libzypp 9.10.2 to Meego 1.2.0.

How to install zypper 1.6.15 from our repository in an ARM chroot

From commandline

First add our repository to your chroot's zypper configuration file:

obslight addRepoInChRoot --projectLocalName $ProjectName --url http://repo.pub.meego.com/Project:/OBS_Light:/Zypper/MeeGo_1.2_OSS/ --alias "Zypper_1.6.15_backport"

Then go to the chroot and update zypper:

obslight goToChRoot --projectLocalName $ProjectName
 # zypper update zypper
 # exit

From GUI

• chroot tab, Repository->New, URL http://repo.pub.meego.com/Project:/OBS_Light:/Zypper/MeeGo_1.2_OSS/ and alias "Zypper_1.6.15_backport"
• Then Chroot->Open terminal

# zypper update zypper
# exit

"error: Architecture is not included: armv8el"

The build package of your chroot does not support armv8el builds. Consider using another version, like the 2011.03.29 of MeeGo repositories.

How to install build version 2011.03.29 in a MeeGo 1.2.0 chroot

First add the MeeGo building tools repository to your chroot's zypper configuration file:

obslight addRepoInChRoot --projectLocalName $ProjectName --url http://download.meego.com/live/Tools:/Building/MeeGo_1.2.0/ --alias "Tools:Building_MeeGo_1.2.0"

Then go to the chroot and update build:

obslight goToChRoot --projectLocalName $ProjectName
  # zypper update build
  # exit

"chroot: failed to run command `sh': No such file or directory"

This appears when binfmt_misc is not or badly configured. Launch qemu's binfmt configuration script (as root):

qemu-binfmt-conf.sh

If you still get the same message, try this (as root):

echo -1 > /proc/sys/fs/binfmt_misc/arm
echo ":arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:`which qemu-arm`:" > /proc/sys/fs/binfmt_misc/register

gnomekeyring.IOError

This error appears on Ubuntu when running obslight from a console, without a graphical environment. At the moment, the only known solution is to run obslight only from a graphical environment (e.g. Gnome).