The Mer Wiki now uses your Mer user account and password (create account on https://bugs.merproject.org/)
Platform SDK
m (Typofix in "mountstats") |
(Rewrite to latest sdk script) |
||
Line 9: | Line 9: | ||
'''Please note that this is a DRAFT and not all bits and pieces are in place yet. Also things might and most likely will change.''' | '''Please note that this is a DRAFT and not all bits and pieces are in place yet. Also things might and most likely will change.''' | ||
+ | |||
+ | == SDK Requirements == | ||
+ | |||
+ | The chroot SDK will run on most modern linux machines. It needs: | ||
+ | * about 400Mb free space to install | ||
+ | * hundreds of Mb for rpm caches for osc and mic | ||
+ | * Generic x86 CPU | ||
+ | * user must have sudo rights | ||
+ | |||
+ | == WARNING == | ||
+ | |||
+ | The SDK consists of a directory tree and when you 'mount' the SDK you will link your home directory, root directory and any data directories within this tree. | ||
+ | |||
+ | '''Because of this you *MUST* 'umount' the SDK before deleting it - if you don't then you *WILL* lose data.''' | ||
+ | |||
+ | If you are unfamiliar with bind mounts, the safest way to uninstall is to reboot your machine and remove the SDK *BEFORE* using the sdk 'mount' command. | ||
+ | |||
+ | Please do not be alarmed by this - we're simply letting you know that running an "rm -rf" command in the wrong place is dangerous. It's better to explain this in big letters than risk someone losing data by mistake :) | ||
+ | |||
+ | Obviously people working on SDK development and testing should take particular care. | ||
== Installation / setup == | == Installation / setup == | ||
+ | |||
The platform SDK is provided as a rootfs tarball that contains essential tools for Mer platform development along with a helper script to enter the rootfs. | The platform SDK is provided as a rootfs tarball that contains essential tools for Mer platform development along with a helper script to enter the rootfs. | ||
− | Please note that the platform SDK requires that you're using a Linux distribution (one in a virtual machine works | + | Please note that the platform SDK requires that you're using a Linux distribution (one in a virtual machine works well). |
+ | |||
+ | The SDK can be installed to any location with enough space - we'll use /srv/ as per the [http://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM Linux FHS] (feel free to adapt the commands to use any other location). | ||
To setup the SDK: | To setup the SDK: | ||
− | * Download the latest stable SDK rootfs tarball | + | * Download the latest stable SDK rootfs tarball. |
cd $HOME | cd $HOME | ||
− | curl -k -O https://img.merproject.org/images/sdk/latest/images/mer-sdk- | + | curl -k -O https://img.merproject.org/images/sdk/latest/images/mer-sdk-i486-chroot/mer-sdk-i486-chroot-latest.tar.bz2 |
* Create directory for the SDK rootfs and extract the tarball as root or with sudo | * Create directory for the SDK rootfs and extract the tarball as root or with sudo | ||
− | mkdir | + | sudo mkdir -p /srv/mer/sdk |
− | sudo tar --numeric-owner -p -xjf $HOME/mer-sdk- | + | cd /srv/mer/sdk |
+ | sudo tar --numeric-owner -p -xjf $HOME/mer-sdk-i486-chroot-latest.tar.bz2 | ||
+ | |||
+ | == SDK control script == | ||
− | |||
The platform SDK rootfs contains a helper script to enter the chroot named 'mer-sdk-chroot'. The helper script is located the the root directory (/) of the rootfs. It requires you to have sudo ability. | The platform SDK rootfs contains a helper script to enter the chroot named 'mer-sdk-chroot'. The helper script is located the the root directory (/) of the rootfs. It requires you to have sudo ability. | ||
− | + | As mentioned, the SDK is location independent so it uses the location of the helper script to determine which SDK to enter. | |
− | + | ||
− | + | == Connect the SDK using 'mount' == | |
+ | |||
+ | You need to connect the SDK before using it. This only needs to be done once (well, once each time you boot your machine) and it connects things like /proc and $HOME in the SDK. It also links /parentroot of the SDK to your normal / directory. | ||
+ | |||
+ | Under normal use the SDK does not need to be disconnected. As per the warning above, you should disconnect using 'umount' before removing the SDK (see [[#Removing_and_disconnecting_the_SDK|remove/disconnect info below]]) | ||
+ | |||
+ | To connect run: | ||
+ | /srv/mer/sdk/mer-sdk-chroot mount | ||
+ | |||
+ | You can now use the SDK from multiple terminals at once. | ||
+ | |||
+ | == Entering chroot == | ||
+ | |||
+ | Before entering the SDK you may want to make an SDK equivalent of ".profile" to give you a nice prompt to remind you that you are in the SDK: | ||
+ | echo 'PS1="MerSDK $PS1"' >> ~/.mersdk.profile | ||
+ | |||
+ | To enter the rootfs with the helper script run | ||
+ | /srv/mer/sdk/mer-sdk-chroot enter | ||
You should find that you are operating under your normal username and that your home directory is available as /home/<username> and any other mountpoints are mounted under /parentroot/* | You should find that you are operating under your normal username and that your home directory is available as /home/<username> and any other mountpoints are mounted under /parentroot/* | ||
Line 36: | Line 78: | ||
You have sudo rights automatically. | You have sudo rights automatically. | ||
− | |||
− | + | == Basic tasks == | |
+ | === Building an image === | ||
+ | Mer images are build using [[Image Creation|mic image creator]]. Mic takes a kickstart file that defines the image to be created as input. To create a Mer image with the platform SDK simply call mic as you would do on any other system. For example | ||
+ | |||
+ | As a test this should make a new local SDK rootfs image | ||
+ | curl -k -O https://img.merproject.org/images/sdk/latest/images/mer-sdk-x86-chroot/mer-sdk-x86-chroot-latest.ks | ||
+ | sudo mic create fs mer-sdk-x86-chroot-latest.ks -o . --pkgmgr=yum --arch i486 --compress-disk-image=tar.bz2 | ||
+ | |||
+ | === Running osc === | ||
+ | Since your home directory has been linked into the SDK then osc commands should work as normal. | ||
+ | |||
+ | osc ls | ||
+ | |||
+ | === Compiling with the SDK === | ||
+ | TBD | ||
+ | |||
+ | === Packaging === | ||
+ | |||
+ | The SDK includes tools needed to create rpm packages for Mer. | ||
+ | |||
+ | See https://build.pub.meego.com/package/show?package=sdk-kickstarter-configs&project=Mer%3ATools%3ATesting | ||
+ | |||
+ | === Hosting repositories === | ||
+ | To make installing created packages easier you can host your own rpm repository with the SDK and install packages to your target device from there. | ||
+ | |||
+ | TODO | ||
+ | |||
+ | == Upgrading the SDK == | ||
+ | |||
+ | Within the SDK you can update and upgrade your tools using: | ||
+ | sudo zypper ref | ||
+ | sudo zypper up | ||
− | + | New tools can be installed using | |
+ | sudo zypper in <package> | ||
− | + | == Advanced details == | |
The usage for the helper script is: | The usage for the helper script is: | ||
Line 66: | Line 139: | ||
} | } | ||
− | == | + | === Multiple SDKs === |
− | + | You should be able to install and connect to multiple SDKs at the same time | |
− | + | ||
− | + | == Removing and disconnecting the SDK == | |
− | + | ||
− | + | ||
− | + | Under normal use the SDK does not need to be disconnected. | |
− | + | ||
− | + | Note: Be sure that the bind-mounts(especialy the home directory) are all umounted after you leave the chroot environment. You can use 'cat /proc/self/mountstats' to check it. If it is not umounted, you should umount it manually after you exit the chroot environment. | |
== SDK contents == | == SDK contents == | ||
Line 84: | Line 153: | ||
* osc and build | * osc and build | ||
* mic | * mic | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
= Development Documentation = | = Development Documentation = |
Revision as of 11:49, 29 February 2012
Contents
|
Mer platform SDK
To avoid any confusion, there are two types of SDKs: Application SDKs and Platform SDKs. Application SDK's are the ones that deal with Qt applications and libraries, HTML5, etc, while Platform SDK's are for developing the platform, compiling native code and other things revolving around the platform developer/hacker needs.
The platform SDK aims to offer a installable disk image that can be run on virtual machines (typically) or actual hardware, which contains tools like Scratchbox2, MIC (image creator), spectacle, osc, qemu, etc preinstalled, to make it easier for a developer to work with Mer.
Please note that the platform SDK is a work on progress. The work for making the sdk was kicked off January 13 2012. If you are willing to contribute to the effort, please do so.
Using the platform SDK
Please note that this is a DRAFT and not all bits and pieces are in place yet. Also things might and most likely will change.
SDK Requirements
The chroot SDK will run on most modern linux machines. It needs:
- about 400Mb free space to install
- hundreds of Mb for rpm caches for osc and mic
- Generic x86 CPU
- user must have sudo rights
WARNING
The SDK consists of a directory tree and when you 'mount' the SDK you will link your home directory, root directory and any data directories within this tree.
Because of this you *MUST* 'umount' the SDK before deleting it - if you don't then you *WILL* lose data.
If you are unfamiliar with bind mounts, the safest way to uninstall is to reboot your machine and remove the SDK *BEFORE* using the sdk 'mount' command.
Please do not be alarmed by this - we're simply letting you know that running an "rm -rf" command in the wrong place is dangerous. It's better to explain this in big letters than risk someone losing data by mistake :)
Obviously people working on SDK development and testing should take particular care.
Installation / setup
The platform SDK is provided as a rootfs tarball that contains essential tools for Mer platform development along with a helper script to enter the rootfs.
Please note that the platform SDK requires that you're using a Linux distribution (one in a virtual machine works well).
The SDK can be installed to any location with enough space - we'll use /srv/ as per the Linux FHS (feel free to adapt the commands to use any other location).
To setup the SDK:
- Download the latest stable SDK rootfs tarball.
cd $HOME curl -k -O https://img.merproject.org/images/sdk/latest/images/mer-sdk-i486-chroot/mer-sdk-i486-chroot-latest.tar.bz2
- Create directory for the SDK rootfs and extract the tarball as root or with sudo
sudo mkdir -p /srv/mer/sdk cd /srv/mer/sdk sudo tar --numeric-owner -p -xjf $HOME/mer-sdk-i486-chroot-latest.tar.bz2
SDK control script
The platform SDK rootfs contains a helper script to enter the chroot named 'mer-sdk-chroot'. The helper script is located the the root directory (/) of the rootfs. It requires you to have sudo ability.
As mentioned, the SDK is location independent so it uses the location of the helper script to determine which SDK to enter.
Connect the SDK using 'mount'
You need to connect the SDK before using it. This only needs to be done once (well, once each time you boot your machine) and it connects things like /proc and $HOME in the SDK. It also links /parentroot of the SDK to your normal / directory.
Under normal use the SDK does not need to be disconnected. As per the warning above, you should disconnect using 'umount' before removing the SDK (see remove/disconnect info below)
To connect run:
/srv/mer/sdk/mer-sdk-chroot mount
You can now use the SDK from multiple terminals at once.
Entering chroot
Before entering the SDK you may want to make an SDK equivalent of ".profile" to give you a nice prompt to remind you that you are in the SDK:
echo 'PS1="MerSDK $PS1"' >> ~/.mersdk.profile
To enter the rootfs with the helper script run
/srv/mer/sdk/mer-sdk-chroot enter
You should find that you are operating under your normal username and that your home directory is available as /home/<username> and any other mountpoints are mounted under /parentroot/*
You have sudo rights automatically.
Basic tasks
Building an image
Mer images are build using mic image creator. Mic takes a kickstart file that defines the image to be created as input. To create a Mer image with the platform SDK simply call mic as you would do on any other system. For example
As a test this should make a new local SDK rootfs image
curl -k -O https://img.merproject.org/images/sdk/latest/images/mer-sdk-x86-chroot/mer-sdk-x86-chroot-latest.ks sudo mic create fs mer-sdk-x86-chroot-latest.ks -o . --pkgmgr=yum --arch i486 --compress-disk-image=tar.bz2
Running osc
Since your home directory has been linked into the SDK then osc commands should work as normal.
osc ls
Compiling with the SDK
TBD
Packaging
The SDK includes tools needed to create rpm packages for Mer.
Hosting repositories
To make installing created packages easier you can host your own rpm repository with the SDK and install packages to your target device from there.
TODO
Upgrading the SDK
Within the SDK you can update and upgrade your tools using:
sudo zypper ref sudo zypper up
New tools can be installed using
sudo zypper in <package>
Advanced details
The usage for the helper script is:
mer-sdk-chroot [-u <user>] [-m <all|none|home>] [<SDK root path>] Use the Mer SDK -u System user to link into SDK (not needed if using sudo) -m Devices to bind mount from host: none, all (default) or just $HOME
The script will bind mount any 'normal' mountpoints it finds into the chroot onto /parentroot in the SDK
Additionally, if the user specified has a .mersdkrc in their $HOME, it will be sourced prior to entry and if an enter_sdk() function is declared this will be run as root. As the user exits the chroot, if a leave_sdk() function is declared, it will be executed. This could be used to create symlinks from any /parentroot/data type filesystems into the SDK root I use the hook to create /maemo and /maemo/mer symlinks to mountpoints in the parentroot. eg:
# This file is sourced by enter_chroot.sh # # This function is called just before the root is entered. # $sdkroot is the path to the SDK / enter_sdk() { [[ -e ${sdkroot}/maemo ]] || ln -s parentroot/maemo ${sdkroot} [[ -e ${sdkroot}/mer ]] || ln -s parentroot/maemo/mer ${sdkroot} }
Multiple SDKs
You should be able to install and connect to multiple SDKs at the same time
Removing and disconnecting the SDK
Under normal use the SDK does not need to be disconnected.
Note: Be sure that the bind-mounts(especialy the home directory) are all umounted after you leave the chroot environment. You can use 'cat /proc/self/mountstats' to check it. If it is not umounted, you should umount it manually after you exit the chroot environment.
SDK contents
The platform SDK's rootfs has some useful packages preinstalled that are listed below. If you're missing something you can use zypper to install the needed extra packages or if not available in the repositories compile them yourself.
- osc and build
- mic
Development Documentation
Below you will find information about the development of the platform SDK itself.
Requirements
The following requirements were agreed on the initial platform sdk brainstorming meeting (things may change)
- Platform SDK needs to be able to function without an OBS account or access to an OBS.
- Offline compilation must be possible
- Clearly document the difference between platform SDK and application SDK.
- Document the SDK tools for easier porting to new Linux distributions (if all SDK tools, and nothing else, comes from a single OBS project, that might be enough documentation).
- seperation of user /home and 'sdk'
- need short path from: code, build, deploy, boo
- minimal http server to SDK for built rpm repo serving
Sources and packages
- COBS project : Mer:Tools:Testing : https://build.pub.meego.com/project/monitor?project=Mer%3ATools%3ATesting
- basic kickstart: https://build.pub.meego.com/package/files?package=sdk-kickstarter-configs&project=home%3Albt%3Abranches%3AMer%3ATools%3ATesting
- rootfs an mount script: https://img.merproject.org/images/
- the script's git version is hosted at https://github.com/lbt/sdk-kickstarter-configs
QA
TBD
SDK team meeting minutes
- 13.1.2012 http://mer.bfst.de/meetings/mer-meeting/2012/mer-meeting.2012-01-13-18.02.html
- 28.1.2012 http://mer.bfst.de/meetings/mer-meeting/2012/mer-meeting.2012-01-28-10.04.log.html
- 24.2.2012 http://mer.bfst.de/meetings/mer-meeting/2012/mer-meeting.2012-02-24-16.01.html