openSUSE:OBS Light Manual

Jump to: navigation, search


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

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 project filesystem
  • Auto creation of patch and upload to OBS

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

Practical labs

You can getting start with OBS Light consulting the practical labs. These labs give you relevant use cases regarding the use of OBS Light.

Introduction Slides

Presentation done during the Tizen's Developers conference in San Francisco, CA, USA on May 7th, 2012 [1]


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:

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 constraint). 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 maintained 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 the project filesystem

Once that you have loaded the packages, you can request the creation of a "chroot jail" (thereafter referred to as "filesystem" or "project filesystem"), where the packages can be built without interfering with the host's filesystem. The created filesystem is specific to the project and will not be recreated if it's already present. During the creation of the filesystem, 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 filesystem.

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

Importing the code in the project filesystem

Once that the filesystem is created, the source from the package can be imported in the filesystem. 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 filesystem 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 filesystem 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 filesystem 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

## synthax: obslight server add server_alias <server_alias> login <login> password <password> api_url <api_url> repository_url <repository_url> web_url <web_url>
server_alias
is the alias you want to use to refer to this server.
api_url
is the URL to the OBS control API. If you are using an OBS appliance, it's probably on port 444.
repository_url
is the URL to the OBS package repositories. If you are using an OBS appliance, it's probably on port 82.
web_url
is the URL to the OBS web interface.

Step2: create a local project related to your OBS project

  • The project is created in ~/OBSLight/ObsProjects/MeeGo_1.2_oss/
## synthax: obslight obsproject add <project_alias> <name_on_obs> <target> <arch> <server_alias>
obslight obsproject add MeeGo_1.2_oss MeeGo:1.2:oss standard i586 <server_alias>
project_alias
is the name you will use to refer to this project with the obslight command (e.g. MeeGo_1.2_oss).
name_on_obs
is the name of the project on the OBS (e.g. MeeGo:1.2:oss).
target
is the target against which we will build (standard is the common name when there is only one).
arch
is the target architecture of the project.
server_alias
is the alias of the OBS server from which we get the project (which has been configured in first step).

Step3: add the kernel package to your local project

  • The package is created in ~/OBSLight/ObsProjects/MeeGo_1.2_oss/MeeGo:1.2:oss/kernel/
  • In this directory, the package is manageable by osc.
## synthax: obslight package add package <package> project_alias <project_alias>
obslight package add package kernel project_alias MeeGo_1.2_oss
package
is the name of the package you want to work on (e.g. kernel).
project_alias
is the name of the project you created in step2.

Step4: create the filesystem of the project

  • The filesystem root directory is ~/OBSLight/ObsProjects/MeeGo_1.2_oss/aChroot/.
  • zypper is included in the filesystem and your OBS project's repository is automatically added.
## synthax: obslight filesystem create <project_alias>
obslight filesystem create MeeGo_1.2_oss

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

  • The source package is extracted in directory /root/rpmbuild/BUILD/kernel-X.X.X/linux-X.X.X.
## synthax: obslight rpmbuild prepare package <package> project_alias <project_alias>
obslight rpmbuild prepare package kernel project_alias MeeGo_1.2_oss

Step6: work as you want in your filesystem

  • The directory ~/OBSLight/ObsProjects/MeeGo_1.2_oss/chrootTransfert/ is mounted in the chroot jail at /chrootTransfert/.
  • Every script executed in aChroot, is stored in /chrootTransfert/ as runMe_YYYY-MM-DD_HHhMMmSS.sh.
## synthax: obslight filesystem enter package <package> project_alias <project_alias>
obslight filesystem enter package kernel project_alias MeeGo_1.2_oss

Now you are logged in the chroot jail. 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
## synthax: obslight rpmbuild createpatch <patch> package <package> project_alias <project_alias>
obslight rpmbuild createpatch myKernelPatch.patch package kernel project_alias MeeGo_1.2_oss
  • 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 ~/OBSLight/ObsProjects/MeeGo_1.2_oss/chrootTransfert/config-x86 ~/OBSLight/ObsProjects/MeeGo_1.2_oss/MeeGo:1.2:oss/kernel/

Step8: Upstream your modifications to the OBS server

  • The command package commit checks the additions and deletions of files, before committing the package to the OBS server.
## synthax: obslight package commit <message> package <package> project_alias <project_alias>
obslight package commit "Patch kernel" package kernel project_alias MeeGo_1.2_oss

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 
OBSlight:
   Provides a tool to manage an OBS project on your local machine in command line
   For informations, see the Help section
       obslight --Help
   The gui for OBSlight is obslightgui
   A FAQ is available at:
       *http://wiki.meego.com/OBS_Light_FAQ
   For additional informations, see:
       *http://wiki.meego.com/OBS_Light
Usage: OBSlight [global command] <command> [--command-options]

Type OBSlight <command> --Help to get Help on a specific command.
Commands:

   server:                   Manage the OBS server
   obsproject:               Manage the OBSlight project
   package:                  Manage the packages of OBSlight project
   projectfilesystem (projectfs,filesystem,pfs) :
                             Manage the project filesystem of OBSlight project
   rpmbuild (rb) :           Manage the rpmbuild of the package into the project filesystem
   man:                      print the man help document

global Options:

   quiet (-quiet,--quiet) :  run obslight in quiet mode
   debug (-debug,--debug) :  run obslight in debugger mode
   version (--version) :     show program's version number and exit
   help (-h,-help,--help) :  show this help message and exit
   noaction:                 Execute command but do nothing

Graphical interface

The GUI is launched via the command obslightgui. Only the parameter --version is supported.

It has two main tabs: one for OBS projects, one for MIC projects

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.

OBS projects tab

OBS Light GUI main window

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

It has 3 main areas:

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

The project panel

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

New
Create a new project. Currently you cannot create a new project from scratch using OBS Light, only import one.
Import
Import a project from an OBS server.
Delete
Delete the selected project. The project will be removed locally but will remain on the OBS server.
Modify
Modify the selected project configuration.
Save
Save the selected project to a file.
Load
Load a project from a file.

The package panel

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

New
Create a new package.
Import
Import a package from an OBS project.
Delete
Delete the selected package(s). The packages will be removed locally but will remain on the OBS server.
Modify
Modify the package title and description. Currently not available.
Update files
Checkout/update files from the OBS (osc update equivalent).
Commit changes
Commit changes to the OBS (osc commit equivalent).
Repair OSC directory
Repair the OSC working copy of a package.
Refresh status
Refresh OBS and Local statuses.

The file panel

The file panel has two tabs: Local directory and Project filesystem.

The local directory tab

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

Open terminal
Open a terminal in the package directory
Package path
Location of the package's OSC working copy
File-related buttons Patch-related buttons
New
Create a new empty file. Currently not available.
Import
Add a file from your local filesystem to the package.
Delete
Delete the selected file from the package.
Modify
Launch an editor on the selected file.
New
Generate a patch from the changes made into the project filesystem, and add this patch to the package and in the yaml and/or spec files. This patch becomes the current patch of the package, until the next '%prep'.
Import
Import an external patch. Currently not available.
Delete
Delete a patch. Currently not available.
Update
Update the current patch with new modifications.

The project filesystem tab

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

Open terminal
Open a terminal in the filesystem, using chroot, in the source directory of the current package if it is installed.
Chroot path
Location of the project filesystem.
Repository-related buttons Filesystem-related buttons Rpmbuild-related buttons
New
Make a package repository accessible from zypper inside the filesystem, by URL.
Import
Make the package repository of another OBS Light project accessible from zypper inside the filesystem.
Delete
Delete a repository from the filesystem.
Modify
Modify the URL or alias of a repository.
New
Create the filesystem of the project.
Import
Not yet implemented.
Delete
Delete the filesystem
Modify
Not yet implemented.
%prep
Install the sources of a package into the filesystem, execute the %prep section of the spec file and do the first build.
%build
Execute the %build section of the spec file of the selected package, in an alternative rpmbuild directory.
%install
Execute the %install section of the spec file of the selected package, in an alternative rpmbuild directory.
%files
Build the source and binary RPMs of the selected package, in an alternative rpmbuild directory.

MIC projects tab

This tab allows you to manage a MIC (MeeGo Image Creator) project. You can change its architecture and image type, and edit its Kickstart file.

On the left panel you can see a list of MIC projects. Click New to add one, you will be asked for a name, and an empty Kickstart file will be created.

Project options

OBS Light GUI main window - MIC project - Project options

In this tab you can:

  • change the generated image type
    • fs: a directory hierarchy containing the whole filesystem
    • livecd: a bootable image suitable for a CD
    • liveusb: a bootable image suitable for a USB key
    • loop: a filesystem image to be mounted with a loop device (with mount -o loop)
    • raw
  • change the architecture of the project (only i686 has been tested)
  • open the directory of the project (with you default file browser)
  • import a Kickstart file (that will overwrite the current file)
  • export the current Kickstart file
  • launch the creation of the image

Kickstart options

OBS Light GUI main window - MIC project - Kickstart options

In this tab you can add, delete or modify the different options of the project's Kickstart file. These options are documented here.

  • To add an option press the add button, and enter the full option line in the bottom text field, then press save.
  • To modify an option, select it, modify the bottom text field and press save.
  • To delete an option, select it, press delete, and then save.

Notice that some options may have aliases, which will appear on the same line in the option list. The repo option will not be listed here, but in the Repositories tab.

Repositories

OBS Light GUI main window - MIC project - Kickstart repositories

In this tab, you can add, delete, or modify Kickstart repositories.

  • To add a repository, there are two possibilities:
    • The repository is from an OBS project you worked on with OBS Light: press Import from OBS project and select the project.
    • The repository is from an external project: press Add by URL, and you will be asked for an URL and a name.
  • To delete a repository, select it and press Delete.
  • To edit a repository, double-click on the cell of the property you want to edit (or simple click if it is a checkbox).

The changes are automatically saved.

Packages

OBS Light GUI main window - MIC project - Kickstart packages

Here you can edit the package list of the project's Kickstart file. Notice that multiple %package sections of original Kickstart file have been merged into one.

Each package has an Included parameter which tells if it should be included in the generated image. If Included is not checked, the package will be explicitly excluded in the Kickstart file (its name will be prefixed with '-').

Package groups

Here you can edit the list of package groups of the project's Kickstart file. At the moment, no verification is done on package groups.

Scripts

OBS Light GUI main window - MIC project - Kickstart scripts

Here you can add, delete or modify Kickstart scripts.

  • To add a script, press Add, write your script in the bottom text field, choose script options in the right panel, and press Save.
  • To delete a script, select it and press Delete.
  • To modify a script, select it, modify the script in the bottom text field or the script options in the right panel, and press Save.

Overlay files

OBS Light GUI main window - MIC project - Overlay files

Here you can add files that will be included in the project image.

  • To add an overlay file, press Add and a file browser will appear. Browse to your file and validate. Then a text dialog will appear, enter the path were you want your file to be copied in the image. tar archives will be extracted at the location you selected, instead of simply being copied.
  • To delete an overlay file, select it and press Delete.

Implementation details:

  • source files are first copied in MIC project's directory
  • each overlay file will appear as a %post --nochoot script in the Kickstart file (but will be hidden in the Scripts tab).

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 project filesystem, using command filesystem repositories add or the repository-related buttons in the GUI.
  • In an ARM project filesystem, 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 project filesystem

From commandline

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

obslight filesystem repositories add http://repo.pub.meego.com/Project:/OBS_Light:/Zypper/MeeGo_1.2_OSS/ "Zypper_1.6.15_backport" $ProjectName

Then chroot in the filesystem and update zypper:

obslight filesystem enter $ProjectName
 $ zypper update zypper
 $ exit

From GUI

# zypper update zypper
# exit

"error: Architecture is not included: armv8el"

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

How to install build version 2011.03.29 in a MeeGo 1.2.0 project filesystem

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

obslight filesystem repositories add http://download.meego.com/live/Tools:/Building/MeeGo_1.2.0/ "Tools:Building_MeeGo_1.2.0" $ProjectName

Then chroot in the filesystem and update build:

obslight filesystem enter $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): Disable binfmt arm target:

echo -1 > /proc/sys/fs/binfmt_misc/arm

Select your qemu binary:

ARM_BINFMT=`which qemu-arm`

Test:

echo $ARM_BINFMT
/usr/bin/qemu-arm-binfmt

Enable your binfmt arm target:

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:$ARM_BINFMT:P" > /proc/sys/fs/binfmt_misc/register

More informartion:

git.kernel Doc

wiki Binfmt_misc

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).

"sudo: sorry, you must have a tty to run sudo"

This message may appear in logs if the requiretty option is set in sudo configuration file. Edit /etc/sudoers and comment out the following line:

Defaults    requiretty

Testing

Infrastructure

You can find in OBS Light Git repository some configuration files for Vagrant and Veewee. Using them, you can build reference virtual machines (Fedora 16, openSUSE 12.1, Ubuntu 11.10 and 12.04) and run test suites on them.

  1. Make a copy of a base virtual machine
  2. Copy test script and associated files in a shared folder
  3. Run virtual machine
  4. Run test script inside virtual machine with SSH
  5. Get results from shared folder
  6. Destroy (or just stop in case of failure) virtual machine

The complete procedure is explained in a README.

Test scenarios

Currently we provide only one test scenario:

  1. install OBS Light
  2. configure a server
  3. import a project
  4. create project filesystem
  5. import some packages (vim, tzdata, fastinit)
  6. execute preparation step of these packages
  7. build the RPMs of these packages

This scenario is implemented in a shell script, available here.