openSUSE:OBS Light Manual
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:
- 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)
- Install your private full appliance (advanced users only) 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 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.
- 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
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.
|
|
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 Project filesystem.
The local directory tab
This tab shows the list of files contained in the selected package.
| |
| File-related buttons | Patch-related buttons |
|
|
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.
| ||
| Repository-related buttons | Filesystem-related buttons | Rpmbuild-related buttons |
|
|
|
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
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
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
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
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
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
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
- Project filesystem 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 Project filesystem->Open terminal
# 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:
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.
- Make a copy of a base virtual machine
- Copy test script and associated files in a shared folder
- Run virtual machine
- Run test script inside virtual machine with SSH
- Get results from shared folder
- 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:
- install OBS Light
- configure a server
- import a project
- create project filesystem
- import some packages (vim, tzdata, fastinit)
- execute preparation step of these packages
- build the RPMs of these packages
This scenario is implemented in a shell script, available here.