Building against Mer in Community OBS

= Assumptions =


 * You've checked the Mer Community OBS article
 * Mer Platform SDK installed

= Overview = The Mer Project uses the OBS system to build packages.

OBS packages are built either locally or on a remote build server. Each package can be setup to build multiple times for combinations of different architectures and different repositories.

Footnote: This is useful because a repository is 'just' a collection of packages eg: Mer-armv7hl or Debian-i586 are different repositories. "Mer-current-armv7hlt" and "Mer-next-armvhl" are also repositories. "Audio Team project with latest audio code built against Mer-next for armv6l" could also be a repository. This allows complex workflows to be developed for 'real' work.

Each build is done in a fresh, clean chroot with packages taken from the target repositories.

If any package changes then the OBS ensures that packages which have a build-dependency against it are also rebuilt. If that results in a change to the pacakage binaries then the rebuild chain continues.

= Web UI = The OBS offers a webui at https://build.merproject.org/

See home project on OBS
On your first visit you'll be prompted to create a home project; after that there will be a link to your 'Home Project' in the top right.

A project is like a directory and contains packages.

As mentioned, in order to build packages a project must have build targets.

All the packages in a project will be built against the build targets for that project. (Footnote: this, like many things on this page is an over-simplification; the OBS is massively flexible - but sometimes it's better to keep it simple).

This means it makes sense to have different projects for different purposes; one for apps building against Nemo maybe another for code building against low-level Mer

Create subproject
Visit your home project and click the 'Subprojects' tab along the top of the page; then at the bottom click 'Create subproject'

In the new project page give it a name (you type this on the cli so keep it simple). Use 'mer' The title is descriptive so we'll use 'Mer packages'. The description is useful for more complex projects with multiple packages. For now 'A project for building against Mer core'.

Now 'Create Project'

The project overview page has several tabs
 * Overview: Provides a summary. The Build Status section will provide progress/success/fail info against targets/architectures
 * Packages: Lists the packages in a project
 * Repositories: Manages the build target repositories, architectures, and publish/build/debug settings
 * Requests: Requests are used inter-project working (like git merge requests)
 * Users: Control access rights
 * Subprojects: List and create subprojects
 * (Advanced) Project Config: Advanced projects need to define how to setup or adjust the build root
 * (Advanced) Attributes: Set OBS attributes (not used in Mer)
 * (Advanced) Meta: View/edit the raw XML metadata for the project
 * (Advanced) Status: General information about requests and builds

Create package
(If you want to create some package using just cli tools, see below in "Working locally). Go to the 'Packages' tab and 'Create package'

Use: Name: 'hello' Title: 'hello world' Description: 'Sample package'

Then 'Save changes'

The package screen then appears with a new set of tabs:


 * Overview: Provides a summary. The Build Status section will provide progress/success/fail info against targets/architectures
 * Sources : Lists and allows editing of the source files for the package
 * Repositories : Override repository/architecture/publish/build for the package
 * Revisions : See the history of changes
 * Requests : Manage requests related to the package
 * Users : Control access rights
 * (Advanced) Attributes : Set OBS attributes (not used in Mer)
 * (Advanced) Meta : View/edit the raw XML metadata for the project

Add source/packaging
First download all the files from: http://www.merproject.org/~lbt/hello/

For each of the files, click 'Sources' and then, 'add file' and 'upload from local file'. The 'remote URL' option *WILL NOT WORK*.

Note that this phase is usually done from the commandline - see later.

Setup build targets / repositories
In order to build you must add a repository. So on the 'Repositories' tab, select both the 'Mer i486 port' and the 'Mer armv7 hardfp port' and then click the 'Add selected repositories' button.

Now, for each of the repositories we select an appropriate scheduler.

Select 'Edit repository' for Mer_Core_armv7hl and ensure only 'armv8el' is ticked. Then click the Update button

Select 'Edit repository' for Mer_Core_i486 and ensure only 'i586' is ticked. Then click the Update button

Footnote: Yes OBS architecture naming is a little confusing; it will improve eventually.

= Working Locally = As a note, all the steps above can be carried out using osc too.

In the following steps we'll use the convention $OBSUSER to stand for your OBS username. If you set and export this you can cut'n'paste many commands.

osc
OBS uses a command called 'osc' to manage it remotely.

osc uses the https API to the OBS for all remote activities. It supports:
 * Uploading/downloading packages/projects

To get an idead of the things osc does, run: osc --help

Setup .oscrc
First you need to setup osc to run against your OBS API.

run: osc -A https://api.merproject.org/ ls mer-tools:testing

You will be asked for your username and password and then you should be given a list of the packages in the mer-tools:testing project. You should take this approach with any OBSes you have access to.

You should now edit the ~/.oscrc file which osc created and:

apiurl = https://api.merproject.org/  Some advanced settings that you can come back and review when you're more familiar with osc and local builds:
 * Set
 * Add "aliases=mobs" in the section
 * The 'packagecachedir' setting - it can be useful to share this amongst SDKs
 * Ideally the 'build-root' setting should be set to a fast build area such as an SSD.

Local checkout
In a suitable area (eg $HOME/src/obs/cobs) run: osc co home:$OBSUSER:mer

If you are under running the Mer VM under Windows, you won't be able to create paths with colons included.

The workaround is to checkout a single package at the time.

Note that in this context all following path references should be taken as aliases to .

osc co -c home:$OBSUSER: 

(If you have problems, ensure you set the correct default apiurl in your ~/.oscrc)

This will checkout your project and *all* packages in it.

If you already created hello package through the UI as above, it will be checked out, and if not and you want to create it through the local too, see below (Creating a package locally). When it's ready do: cd home:$OBSUSER:mer/hello and you can see files in the package.

Creating a package locally
When in your base location (eg $HOME/src/obs/cobs), go to your subproject and create a package hello (assuming you didn't create it through the UI above yet): cd home:$OBSUSER:mer osc mkpac hello

Now check-in the empty package first (not sure why it's needed, but you can't assign the metadata otherwise, before the first check-in): osc ci hello

Go to the package directory and edit the metadata:

cd hello osc meta pkg -e

It will open an editor where you can modify the metadata XML. Assign the title and description for the package. Then copy files from http://www.merproject.org/~lbt/hello/ to the package directory, add them to the package and then check-in again (for your own real package make your own files of course):

curl -O http://www.merproject.org/~lbt/hello/hello-0.1.tar.gz \ -O http://www.merproject.org/~lbt/hello/hello.changes \ -O http://www.merproject.org/~lbt/hello/hello.spec \ -O http://www.merproject.org/~lbt/hello/hello.yaml osc add hello-0.1.tar.gz hello.changes hello.spec hello.yaml osc ci

managing files
You can now modify the files or add new ones.

So add a patch:

cat < hello.patch diff -ur hello-0.1/src/hello.c hello-0.2/src/hello.c --- hello-0.1/src/hello.c      2012-10-23 00:09:37.603101455 +0100 +++ hello-0.2/src/hello.c      2012-10-23 10:03:18.689713430 +0100 @@ -3,5 +3,6 @@ int main(void) {     printf("hello, and welcome to Mer\n"); +   printf("Congratulations on patching using osc\n"); return 0; } EOF

or curl -O http://www.merproject.org/~lbt/hello2/hello.patch

Now add it to the yaml file echo 'Patches:' >> hello.yaml echo '  - "hello.patch"' >> hello.yaml

Update the Release value to "2" in the yaml file too (use sed or edit the file). sed -i '/^Release:/cRelease: 2' hello.yaml

And run: specify

Don't forget to make a note in the changelog too:

mv hello.changes hello.changes2 echo "* Tue Oct 23 2012 David Greaves  - 0.1-2" > hello.changes echo "- Modify message for release 2" >> hello.changes cat hello.changes2 >> hello.changes rm hello.changes2 (or just edit the file!)

Now you have a new set of packaging

check-in
To send this to the OBS we could just do: osc ci

But this would miss the added patch file.

Running: osc status shows modified files and a ? by the patch means it is unknown.

Usually 'osc ar' (which is short for 'addremove') will do the right thing - so run that now: osc ar

Now to checkin the files and push them up to the server: osc ci

This will launch an editor to add a commit message which may be seen in the OBS revision history.

Now check the 'Monitor' page for your home:$OBSUSER:mer project and you should see the package building.

build logs
If you click on the 'building' or 'succeeded' (or hopefully not : 'failed') you get to see an updating build log.

(you can even watch this locally : osc buildlog --help)

Set publish
If you go to the 'Repository' tab there is a 'Go to download repository' link which takes you to http://repo.pub.meego.com//home:/$OBSUSER:/mer/

This is a zypper repository and could be added to a VM or device using:

zypper ar http://repo.merproject.org/obs/home:/lbt:/mer/Mer_Core_armv7hl/home:$OBSUSER:mer.repo

download rpm, install and run
The rpms can be downloaded from the publish area or using osc getbinaries

This prompts you for the target/arch you want - so for the x86 version run osc getbinaries Mer_Core_i486 i586

The rpm will appear in a binaries/ subdir and you can install them onto a device, into an emulator or even into the SDK: sudo rpm -i binaries/hello-0.1-5.1.i486.rpm

and now hello

Hopefully you got a suitable message :)

local build
osc is also capable of building locally. This downloads the latest packages and creates a chroot so it takes a few minutes. It really is worth using an SSD if you do this a lot.

Run osc build Mer_Core_i486 i586

Watch and wait.

You should see the entire download, build and package process happen.

At the end you'll see something like: /maemo/obs/build/Mer_Core_i486-i586-hello/home/abuild/rpmbuild/SRPMS/hello-0.1-2.src.rpm /maemo/obs/build/Mer_Core_i486-i586-hello/home/abuild/rpmbuild/RPMS/i486/hello-0.1-2.i486.rpm /maemo/obs/build/Mer_Core_i486-i586-hello/home/abuild/rpmbuild/RPMS/i486/hello-debuginfo-0.1-2.i486.rpm /maemo/obs/build/Mer_Core_i486-i586-hello/home/abuild/rpmbuild/RPMS/i486/hello-debugsource-0.1-2.i486.rpm

So you can access the rpm directly.

More adventurous types may like osc chroot Mer_Core_i486 i586 and then cd rpmbuild/BUILD/hello-0.1/

where you can hack on the code and run make etc. Bear in mind this is a copy of the code so changes are lost. There are techniques for working in this area: search/ask for quickbuild

branch
todo

submit request
todo

BOSS
todo

= Next Steps = To work on Mer Core packages look at [Contribution in detail]

= Advanced =

Editing project metadata directly
To change the build target repositories of your OBS project (part of the project metadata) to build against Mer: osc -A https://api.pub.meego.com meta prj home:YOURNAME -e

The XML should look along these lines (make sure you use your own "YOURNAME" value) paying special attention to the  tags which you most likely need to add by yourself:

As mentioned, this can also be edited in the web interface, under your project -> Advanced -> Raw config -> Edit

You can also osc branch from these repositories but you need to add repositories manually.

Notice if osc build fails with Either wrong repo/arc it could be wrong path or repository

To fixit:

Go check directory structure at: repo.merproject.org

and change it to XML to point to correct path.

Lookup where the *.repo file exists. For example:

mer-core:/armv7hl:/release/Core_armv7hl/

"translated" to XML it should look like:



BOSS managed submit requests
Before trying to issue submit requests to projects that are under automated integration (ex. CE:* projects on community OBS), make sure you have created the correct set of repositories.

For each repository in the target project, there should be a repository in source project which builds only against the target repository and have at least the same architectures as the target repository they build against.

This can be done easily using the addrepos osc plugin, drop it in your ~/.osc-plugins and run the command :

osc -A https://api.pub.meego.com addrepos MYPROJECT TARGETPROJECT

It will open an editor with the repositories appended to the bottom of your prj meta.