Revision as of 10:59, 23 May 2014

Tools

Getting started with Mer development requires some basic tools. Mer provides a Platform SDK with all these tools included as they are not always present (or are modified) in other distros.

This page describes the Mer:Tools project which is where the tools are developed and managed.

Most tools have their own page or are covered in other guides.

Packaged Versions

Generally packaged from Mer:Tools and Mer:Tools:Testing

 http://projects.merproject.org/releases/

Releases

The Tools project does not make regular scheduled releases; instead it releases when required - this can be when just one version of a package has changed.

Tools releases are made by building against the current Mer release; a release number represents a collection of tool versions. This is then combined with a Mer Core release to produce an SDK release.

This approach allows the tools to be rebuilt against 'in house' forks of Mer that may have been frozen.

Release numbers

<version>.<stable/pre>.<incr>

1.0.1   Tools version 1  this is a pre-release, first try
1.0.2   Tools version 1  this is a pre-release, second try
1.1.0   Tools version 1  this is a release
...
2.1.0   Tools version 2  this is a release
...
1.1.1   Tools version 1  this is an update to release 1.1.0 (most tools, same version as 1.1.0, some incremented but some < 2.1.0)

Tools release numbers could/should be reduced to a mapping to a sha1 of the contents of the release source.

Release Steps

A Tools release requires reliable version control of both the code and associated packaging. This is not yet implemented and the interim solution is to publish the OBS src rpm in the SDK repo.

SDK

An SDK binary release is done directly from the OBS Tools project using the Mer release script. (see lbt branch as of 27/May/2012)

tools/createrelease.sh --conf release.tools --next --all 5.0.1

# Configuration

# List of project repo arch schedulers(: sep) to release
PROJECTS="Mer:Tools       Mer_Core_i486  i486 i586"

# Set this to 1 if there are x86 cross- binaries in the arm/mips repos
CROSS=

PUBLISH_SRC=1

# This should point to a public api
API=https://api.pub.meego.com/public

# This should permit rsync of /srv/obs/repos on the OBS be or a
# suitable publishing slave
RSYNC=rsync://cdownload.in.meego.com/repos

RELEASEDIR=~/releases
OBSDIR=~/obs-repos

# The target for the OBS MDS (rsync destination)
RSYNC_OBS_PUBLISH=

# The target for the repository (rsync destination)
RSYNC_REPO_PUBLISH=rsync://cdownload.in.meego.com/repo/releases/Mer-Tools/

# If rsync needs a password
export RSYNC_PASSWORD=xxxxxxxxxxxxxxx

This is then built into an image using the SDK. Currently this is a bit convoluted; in an SDK

osc co Mer:Tools/sdk-kickstarter-configs
osc build Mer_Core_i486  i586

Determine the build directory and obtain the correct .ks

 .../build/Mer_Core_i486-i586-sdk-kickstarter-configs/mer-sdk-i486-chroot.ks

Upload this to IMG, wait for the build and move the image to the distribution dir.

Tools for developing

osc

Use a version > 0.132

osc is used to interact with the OBS. It does:

• command line functions provided by the OBS webui
• check in / out of packages
• submits requests
• runs local builds

You may find latest builds for various distributions at http://download.opensuse.org/repositories/openSUSE:/Tools/

osc build

build is the actual script used by the OBS workers to build packages. It installs a clean chroot for you and runs a suitable compile command from the package.

You may find latest builds for various distributions at http://download.opensuse.org/repositories/openSUSE:/Tools/

mb2 build

Notice, there is a tool named mb this is deprecated in favour of mb2.

mb2 Executes a subset of build commands in the context of an rpmbuild.

Typically it is called from QtCreator to perform qmake/make phases of a project.

Note that any other build steps in the .spec file will also be run.

mb2 can be invoked via shell using mb2 build command similar to deprecated mb build.

Example:

 mb2 build -t TARGET specfile
 mb2 make -t TARGET

where TARGET is sysroots for example nemo-armv7hl, sailfishos-armvhl etc...

For more info mb2 --help

spectacle

Spectacle creates .spec files from .yaml files. This makes is a *lot* easier to package your code.

https://github.com/mer-tools/spectacle

cd /mer/tools
mkdir spectacle
git clone https://github.com/mer-tools/spectacle

more info about spectacle here

qemu (specific snapshot)

qemu is needed for building non-native (ARM/MIPS) packages that need to execute ARM binaries.

qemu is found in the Mer:Tools project (currently on the MeeGo community OBS)

19 Nov2011 : Using 0.14.1

The OBS and IMG systems use qemu-usermode-static.

You need to install qemu-usermode-static package when you do 'osc build' for non-intel architecture and have "chroot: failed to run command `some-command': Exec format error" or "Warning: could not register binfmt handlers". As the package is statically linked, you may install OpenSUSE rpm on Fedora and it should work fine.

Tools for Image Building

kickstarter

https://meego.gitorious.org/~sage/meego-developer-tools/sages-kickstarter

cd /mer/tools
mkdir kickstarter
cd kickstarter
git clone git://gitorious.org/~sage/meego-developer-tools/sages-kickstarter.git kickstarter

mic2 / image-creator

http://meego.gitorious.org/meego-developer-tools/image-creator

cd /mer/tools
mkdir image-creator
cd image-creator
git clone git://gitorious.org/meego-developer-tools/image-creator.git image-creator

Development Tools for on Device usage

Device Memory Profiling via 'sp-smaps'

First you have to add the Mer_Extras repository to your device zypper configuration, available
<repositories> are 'Mer_Extras_armv6l', 'Mer_Extras_armv7hl', 'Mer_Extras_armv7l' and 'Mer_Extras_i568'

root@device# zypper addrepo http://repo.pub.meego.com/Project:/KDE:/Mer_Extras/<repository> Mer-Extras

Now feel free to install the 'sp-smaps' toolset

root@device# zypper refresh
root@device# zypper in sp-smaps

Usage:

Create a memory profiling snapshot:

root@device# sp_smaps_snapshot > my-memory-sp-smaps-snapshot.cap

Create a HTML report from the smaps capture:

root@device# sp_smaps_analyze my-memory-sp-smaps-snapshot.cap

Feel free to compress and copy the generates files for further analysis to a host system:

root@device# tar -cvf my-memory-sp-smaps-snapshot.tar \
  my-memory-sp-smaps-snapshot.cap \
  my-memory-sp-smaps-snapshot.html \
  my-memory-sp-smaps-snapshot.dir

root@device# bzip2 my-memory-sp-smaps-snapshot.tar
root@device# scp my-memory-sp-smaps-snapshot.tar.bz2 <your_user>@<your_host>:~/

Development of tools

In OBS the Mer tools are in two projects:

• SDK and device side tools in Mer:Tools
• Host (Linux distribution) side tools in Project:MINT

SDK and device side tools are compiled only against the Mer repositories. By this we try to keep the tools stable and avoid conflicts with the host distribution's packages (eg. Ubuntu/OpenSuse/Fedora).

The host side tools are provided for the most common Linux distributions.

• "Unstable" SDK and device side tools are in Mer:Tools:Testing
• "Unstable" host side tools are in Project:MINT:Testing

Mer:Tools

All Mer:Tools should be mastered in https://github.com/mer-tools

Modify a Package

The process to modify them is:

1. branch the package from Mer:Tools:Testing
2. clone the corresponding mer-tools repository on github
3. osc checkout the package from your branch of M:T:T
4. git clone the fork into the same osc branch checkout
5. use gp_mkpkg to recreate the tarball and packaging
6. checkout the git code, modify it (either adding a patch or pulling from upstream) and commit
7. checkout the packaging branch, modify it and build
8. when happy, issue a merge request on github and SR the package on OBS

As a developer:

1. Search the tool's version control location from About
2. Pull the tool's source code and make changes
3. Copy the original package to your home project in OBS
4. Update your changes to the home project package
5. Test your changes
6. Push your changes to the version control
7. Inform tools team about the changes with changes diff (URL to gitorious/gerrit/github diff)
8. The tools team will review, retest and update the tool to OBS

Add a New Package Walkthrough

First we must create an osc package to build the source in.

Checkout a suitable OBS directory with Mer_Core_i486 or similar as a repo target (see Osc Setup for details)

Now create the package:

 osc mkpac powertop
 cd powertop

Now we're in a suitable osc directory we can setup git.

Find the upstream, clone and move the .git dir to the osc dir:

git clone --no-checkout git://github.com/fenrus75/powertop.git
mv powertop/.git .
rm -rf powertop

What tag are we based on?

git checkout -f v2.1.1

This is going to be the source code commit for the Mer 2.1.1-1 release so we'll tag it as such:

git tag mer-2.1.1-1

Now we'll make a detached packaging branch and switch to it (this requires Git pkg):

gp_setup --pkg

At this point you are in the packaging branch In the future gp_setup --pkg=<tag> will do the git checkout <tag> next release

Edit yaml/spec/changes and create some packaging (we'll cheat and use philippe's):

curl -kOL https://github.com/philippedeswert/powertop/raw/pkg-mer/powertop.changes
curl -kOL https://github.com/philippedeswert/powertop/raw/pkg-mer/powertop.spec
curl -kOL https://github.com/philippedeswert/powertop/raw/pkg-mer/powertop.yaml

Describe in the _src file how OBS gets the source (in this case, use simple git archive to make a tar.bz2 based on the tag v2.1.1)

echo git:powertop-v2.1.1.tar.bz2:v2.1.1 > _src
git add powertop.* _src

Check to ensure it builds:

gp_mkpkg
osc build Mer_Core_i486 i586

All good, commit:

git commit -s

This is the commit for our packaging so tag that too

git tag pkg-mer-2.1.1-1

And use standard git to push everything to some remote repo.

At this point you may submit an SR to Mer:Tools:Testing and ask for the package to be cloned into the Mer:Tools github project.

Review and Acceptance

At this point the request is reviewed, the submitter's build is verified; rpms may be downloaded and tested and then if it looks OK the git repo is cloned to mer-tools and the SR accepted into mer-tools:devel.

The acceptance is done by adding a webhook to the git repo and then in https://webhook.merproject.org/webhook/admin/ adding a webhook.

From there the devel repo is checked and the package is promoted to mer-tools:testing for wider testing. Eventually it is promoted to mer-tools:stable where it will be included in the next release.