Revision as of 02:43, 9 December 2013

Assumptions

• Account registered on merproject.org
• Mer Platform SDK installed
• Knowledge of underlying rpm packaging technologies

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:

• Set

apiurl = https://api.merproject.org/

• Add "aliases=mobs" in the section

[https://api.merproject.org]

Some advanced settings that you can come back and review when you're more familiar with osc and local builds:

• 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 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:

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 <<EOF > 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 <david@dgreaves.com> - 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 <repository> tags which you most likely need to add by yourself:

<project name="home:YOURNAME">
 <title>YOURNAME's Home Project</title>
 <description>Mer is cool</description>
 <person userid="YOURNAME" role="maintainer"/>
 <person userid="YOURNAME" role="bugowner"/>
 <repository name="Mer_Core_armv7hl">
   <path project="Mer:MDS:Core:armv7hl" repository="Core_armv7hl"/>
   <arch>armv8el</arch>
 </repository>
 <repository name="Mer_Core_armv7l">
   <path project="Mer:MDS:Core:armv7l" repository="Core_armv7l"/>
   <arch>armv7el</arch>
 </repository>
 <repository name="Mer_Core_i586">
   <path project="Mer:MDS:Core:i586" repository="Core_i586"/>
   <arch>i586</arch>
 </repository>
 <repository name="Mer_Core_i486">
   <path project="Mer:MDS:Core:i486" repository="Core_i486"/>
   <arch>i586</arch>
 </repository>
</project>

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.

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.