The Mer Wiki now uses your Mer user account and password (create account on https://bugs.merproject.org/)
Platform SDK
(restructuring and removing the initial release proposal) |
(fixed archive path) |
||
(114 intermediate revisions by 24 users not shown) | |||
Line 1: | Line 1: | ||
+ | Mer platform SDK contains [[Tools]] like Scratchbox2, [[Image_Creation| MIC (Image Creation)]], [[Spectacle]], osc, qemu, etc, to make it easier for a developer to work with Mer. | ||
+ | |||
+ | = tl;dr = | ||
+ | |||
+ | Install and enter the SDK under /srv/mer (HADK followers pls point home e.g. MER_ROOT=$HOME/mer instead, and your $HOME should not be mounted with nosuid or nodev options! Then perform mkdir without sudo. It will cause less issue along the way, until proper fix): | ||
+ | |||
+ | export MER_ROOT=/srv/mer | ||
+ | cd $HOME; curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 ; | ||
+ | sudo mkdir -p $MER_ROOT/sdks/sdk ; | ||
+ | cd $MER_ROOT/sdks/sdk ; | ||
+ | sudo tar --numeric-owner -p -xjf $HOME/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 ; | ||
+ | echo "export MER_ROOT=$MER_ROOT" >> ~/.bashrc | ||
+ | echo 'alias sdk=$MER_ROOT/sdks/sdk/mer-sdk-chroot' >> ~/.bashrc ; exec bash ; | ||
+ | echo 'PS1="MerSDK $PS1"' >> ~/.mersdk.profile ; | ||
+ | cd $HOME | ||
+ | sdk | ||
+ | |||
+ | It's recommended that you read sections below for pre-requisites, options and details on installing extra tools etc. | ||
+ | |||
+ | = Install on VirtualBox = | ||
+ | |||
+ | The platform SDK aims to offer an alternative image that can be run like a virtual machine using the guide [[Platform_SDK_on_VirtualBox]] | ||
+ | Don't bother with this unless you're running Windows or something too non-linuxy to make the chroot SDK work. | ||
+ | |||
= Mer platform SDK = | = 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. | 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 | + | The platform SDK offers an image that typically can be run in a chroot environment or in a virtual machine, which contains tools like gcc, Scratchbox2, MIC (image creator), spectacle, osc, qemu, etc, to make it easier for a developer to work with Mer. |
+ | |||
+ | The default download contains: | ||
+ | |||
+ | * Mer development tools | ||
+ | * Mer image creation | ||
+ | * Mer OBS development | ||
+ | * ARMv7hl toolchain | ||
+ | |||
+ | You can also install : | ||
+ | |||
+ | * Cross-build tools for armv6l armv7l armv7hl mipsel | ||
+ | * Mer debug tools | ||
+ | * Mer testing tools | ||
+ | * Mer python development | ||
+ | * Mer ruby development | ||
− | + | You may also like to contribute to [[Platform SDK Development|developing the SDK]]. | |
= Using the platform SDK = | = Using the platform SDK = | ||
− | + | == SDK Requirements == | |
+ | |||
+ | The chroot SDK will run on most modern linux machines. It needs: | ||
+ | * Linux distribution (one in a virtual machine works well), running 2.6.37 or newer kernel | ||
+ | * about 400Mb free space to install | ||
+ | * The SDK must be installed on a standard filesystem and "nosuid" must not be set. (Note: [http://askubuntu.com/questions/210048/error-when-running-binary-with-root-setuid-under-encrypted-home-directory recent ecryptfs] will automatically use and enforce nosuid. Automounted usb drives typically have "nosuid" set too.) | ||
+ | * hundreds of Mb for rpm caches for osc and mic | ||
+ | * Generic x86 CPU | ||
+ | * user must have sudo rights | ||
== 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. | ||
− | + | Filesystem requirements: | |
+ | * 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). | ||
+ | * The installation path must contain an intermediate directory called 'sdks' which only has Mer SDKs inside. eg /srv/mer/sdks/sdk/... | ||
To setup the SDK: | To setup the SDK: | ||
− | * Download the latest stable SDK rootfs tarball | + | * Download the latest stable SDK rootfs tarball with the common armv7hl toolchain preinstalled: |
cd $HOME | cd $HOME | ||
− | curl -k -O https://img.merproject.org/images/sdk | + | curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 |
− | + | Note that there is a version with 'all' cross compilation toolchains in the same dir in case you're working with a different target architecture. | |
− | + | ||
− | + | ||
− | + | * Create a directory for the SDK rootfs and extract the tarball as root or with sudo | |
− | + | sudo mkdir -p /srv/mer/sdks/sdk | |
+ | cd /srv/mer/sdks/sdk | ||
+ | sudo tar --numeric-owner -p -xjf $HOME/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.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 in 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. | |
− | + | == 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. This also reads the bash autocompletion scripts from inside the chroot. | |
+ | cat << 'EOF' >> ~/.mersdk.profile | ||
+ | PS1="MerSDK $PS1" | ||
+ | if [ -d /etc/bash_completion.d ]; then | ||
+ | for i in /etc/bash_completion.d/*; | ||
+ | do | ||
+ | . $i | ||
+ | done | ||
+ | fi | ||
+ | EOF | ||
− | + | To enter the rootfs with the helper script run | |
+ | /srv/mer/sdks/sdk/mer-sdk-chroot | ||
− | + | 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. If sudo fails within the sdk, make sure that the filesystem the sdk is on is not mounted with the "nosuid" parameter. "mount" on the host system gives you this information, add "suid" as parameter in fstab, if necessary. | |
− | + | == Useful Alias == | |
− | + | ||
− | + | ||
− | + | If you tend to use a single instance of the sdk then this alias is useful | |
− | + | echo alias sdk=/srv/mer/sdks/sdk/mer-sdk-chroot >> ~/.bashrc ; exec bash | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
== Basic tasks == | == Basic tasks == | ||
=== Building an image === | === Building an image === | ||
+ | <span style="color:red">'''ATTENTION: If you are making image for i586 target, use --arch=i686 !'''</span> | ||
+ | |||
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 | 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 | + | As a test this should make a new local SDK rootfs image: |
− | + | ||
− | + | ||
+ | Check: https://img.merproject.org/images/mer-sdk/ for the name of the latest KickStart file and use it in the first command below: | ||
+ | |||
+ | for chroot version: | ||
+ | curl -k -o mer-latest-sdk-rolling-chroot.ks https://img.merproject.org/images/mer-sdk/mer-latest-sdk-rolling-chroot.ks | ||
+ | sudo mic create fs mer-latest-sdk-rolling-chroot.ks -o . --pkgmgr=zypp --arch i486 --pack-to=mer-latest-sdk-rolling-chroot.tar.bz2 | ||
+ | |||
+ | for VM version: | ||
+ | curl -k -o mer-next-sdk-rolling-vm.ks https://img.merproject.org/images/mer-sdk/mer-next-sdk-rolling-vm.ks | ||
+ | sudo mic create raw mer-next-sdk-rolling-vm.ks -o . --pkgmgr=zypp --arch i486 | ||
+ | |||
+ | Please check bugzilla if you encounter problems: | ||
+ | ; extlinux issue : https://bugs.merproject.org/show_bug.cgi?id=576 | ||
=== Running osc === | === Running osc === | ||
+ | |||
+ | (This section needs to be improved) | ||
+ | |||
Since your home directory has been linked into the SDK then osc commands should work as normal. | Since your home directory has been linked into the SDK then osc commands should work as normal. | ||
− | osc ls | + | osc -A API_URL ls |
− | |||
− | |||
− | + | Where API_URL can be: | |
− | + | https://api.merproject.org Mer Community OBS | |
− | + | https://api.ci.merproject.org Mer's continous integration OBS (not for regular use) | |
+ | or the API url for your own, or your company's OBS. | ||
− | == Compiling with the SDK | + | === Compiling with the SDK === |
− | + | Mer and the SDK uses Scratchbox2 as a cross compile tool; it can be installed into a minimal SDK by installing a cross-build environment suitable for your project. | |
− | + | You should install one or more of the following SB2 patterns to get a suitable environment: | |
− | + | sudo zypper in -t pattern Mer-SB2-armv6l | |
+ | sudo zypper in -t pattern Mer-SB2-armv7l | ||
+ | sudo zypper in -t pattern Mer-SB2-armv7hl | ||
+ | sudo zypper in -t pattern Mer-SB2-armv7tnhl | ||
+ | sudo zypper in -t pattern Mer-SB2-mipsel | ||
− | + | '''NOTE:''' in case of facing "not enough disk space left" or similar the problem is most probably that the kernel on your host is too old. To run Mer SDK you should be running kernel 2.6.37 or newer on your host. | |
− | === | + | These patterns provide: |
− | + | * sb2 configurations | |
+ | * qemu | ||
+ | * gcc and binutils for your architecture | ||
+ | |||
+ | Once the SDK is setup, see the documentation on using the [[Platform SDK and SB2]] | ||
+ | |||
+ | === Packaging === | ||
− | |||
The SDK includes tools needed to create rpm packages for Mer. | The SDK includes tools needed to create rpm packages for Mer. | ||
− | See https://build. | + | See https://build.merproject.org/package/files?package=sdk-kickstarter-configs&project=mer-tools%3Atesting |
=== Hosting repositories === | === Hosting repositories === | ||
Line 108: | Line 176: | ||
TODO | TODO | ||
− | = | + | == 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 | ||
+ | * spectacle | ||
+ | * vim | ||
+ | |||
+ | |||
+ | === Adding New Tools === | ||
+ | |||
+ | New tools can be installed using | ||
+ | sudo zypper in <package> | ||
+ | or | ||
+ | sudo zypper in -t pattern <pattern> | ||
+ | |||
+ | The following patterns are available: | ||
+ | |||
+ | ; Mer-SB2-armv6l, Mer-SB2-armv7l, Mer-SB2-armv7hl, Mer-SB2-mipsel : Cross-build tools for various architectures | ||
+ | ; Mer-debug-tools : A range of low-level debug tools | ||
+ | ; Mer-testing-tools : testrunner, eat and qttas | ||
+ | ; Mer-python-development : all your slithery needs | ||
+ | ; Mer-ruby-development : to add sparkle | ||
+ | |||
+ | Zypper search is useful to find available packages. | ||
+ | |||
+ | == Upgrading the SDK == | ||
+ | |||
+ | Don't just do zypper up! | ||
+ | |||
+ | The SDK image is (as of 5 June 2012) pinned to specific static repositories and upgrades are carried out using "sdk-upgrade" which allows the repos to be updated to latest, next or set to point to any Mer Core/SDK release pairing. | ||
+ | |||
+ | Recent SDK versions no longer have "sdk-upgrade" and you will need to run "sdk-version"(with different arguments) in order to upgrade different components of the SDK. | ||
+ | |||
+ | === Upgrading Older SDKs === | ||
+ | |||
+ | (ie one without sdk-version or sdk-upgrade tool) | ||
+ | |||
+ | You may be prompted to remove the unstable Tools:Testing repo - and you really should as that's now going to be used by the Tools team for sharing experimental packages. Then follow the steps indicated. | ||
+ | |||
+ | Old SDKs which don't have sdk-version should execute these steps before moving on to the appropriate upgrade process: | ||
+ | sudo zypper ref | ||
+ | sudo zypper in sdk-chroot | ||
+ | |||
+ | Now run the following command | ||
+ | sudo sdk-upgrade | ||
+ | |||
+ | If it fails skip this part; if it succeeds then run: | ||
+ | sudo zypper ref | ||
+ | sudo zypper in sdk-chroot | ||
+ | |||
+ | This release needs to install the correct script and then exit/re-enter the SDK: | ||
+ | exit | ||
+ | |||
+ | # unmount, re-mount and re-enter the SDK to clean up | ||
+ | /srv/mer/sdks/sdk/mer-sdk-chroot umount | ||
+ | /srv/mer/sdks/sdk/mer-sdk-chroot mount | ||
+ | /srv/mer/sdks/sdk/mer-sdk-chroot enter | ||
+ | |||
+ | Now move on to the normal upgrade | ||
+ | |||
+ | === Normal Upgrade === | ||
+ | Simply run: | ||
+ | sdk-version --core latest --sdk rolling --go | ||
+ | |||
+ | === Documentation for sdk-version === | ||
+ | |||
+ | usage: [--latest | --next] [--core <release>] [--sdk <release>] [-h|--help] | ||
+ | |||
+ | By default reports the current versions from the repos | ||
+ | Alternatively updates the zypper repos to point to the "latest", | ||
+ | "next" or specified Mer / SDK releases. It does not run zypper | ||
+ | ref or zypper up by default (use --go for that). | ||
+ | --core <release> : Use Mer Core <release> | ||
+ | eg: --core 0.20120517.1 | ||
+ | <release> can be "next" or "latest" from | ||
+ | http://releases.merproject.org/releases/{latest,next}-release | ||
+ | |||
+ | --sdk <release> : Use SDK/Tools <release> | ||
+ | eg: --sdk 0.5.1 | ||
+ | <release> can be "next" or "latest" from | ||
+ | http://repo.merproject.org/releases/mer-tools/latest-release | ||
+ | |||
+ | --latest : short for: --sdk latest --core latest | ||
+ | --next : short for: --sdk next --core next | ||
+ | --go : actually run the zypper upgrade | ||
+ | |||
+ | == Advanced details == | ||
+ | |||
+ | === Documentation for mer-sdk-chroot === | ||
+ | The usage for the helper script is: | ||
+ | |||
+ | usage: /srv/mer/sdks/sdk3/mer-sdk-chroot [-u <user>] [-m <all|none|root|home>] [-r <SDK root path>] [<command> <args> ..] | ||
+ | /srv/mer/sdks/sdk3/mer-sdk-chroot -h | ||
+ | |||
+ | This is the Mer chroot SDK. | ||
+ | For information see http://wiki.merproject.org/wiki/Platform_SDK | ||
+ | |||
+ | If command is not present, | ||
+ | used to enter the SDK and begin working. The SDK bash shell is a | ||
+ | login shell. See below for .profile handling | ||
+ | Must be preceded by a 'mount' to setup the SDK. | ||
+ | May be used in multiple terminals and simply enters the | ||
+ | chroot | ||
+ | |||
+ | If command is present, | ||
+ | used to execute an arbitrary command from within the SDK chroot | ||
+ | environment. The environment variable MERSDK is set to 1 to allow | ||
+ | SDK detection. | ||
+ | |||
+ | Options: | ||
+ | |||
+ | -u System user to link into SDK (not needed if using sudo) | ||
+ | -m Devices to bind mount from host: none, all (default) | ||
+ | root, home | ||
+ | -r The root of the SDK to use - normally derived from the | ||
+ | pathname of /srv/mer/sdks/sdk3/mer-sdk-chroot | ||
+ | -h Show this help | ||
+ | |||
+ | Profile | ||
+ | |||
+ | Entering the SDK runs the user's normal .profile and any (SDK) | ||
+ | system profile entries. It will not execute the host's system | ||
+ | profile entries. | ||
+ | |||
+ | The environment variable MERSDK is set to 1 to allow .profile to | ||
+ | detect the SDK. | ||
+ | |||
+ | If the user has a ~/.mersdk.profile then it is sourced after the | ||
+ | normal .profile handling (this allows the common use case of | ||
+ | setting a profile to be handled). | ||
+ | |||
+ | Hooks | ||
+ | |||
+ | If the user specified has a .mersdkrc in their /root, it will be | ||
+ | sourced to allow hook functions to be defined. Hooks are run as | ||
+ | root. No commands should be executed immediately. | ||
+ | |||
+ | These hooks are usually used to define symbolic links from any | ||
+ | /parentroot/data type filesystems into the SDK root to setup | ||
+ | system specific shared caches or filesystem layouts etc | ||
+ | |||
+ | === Sharing mic and osc caches === | ||
+ | |||
+ | You can use the ~/.mersdkrc file to check and link the standard mic and osc cache directories to those in parentroot. | ||
+ | |||
+ | Note that multiple *concurrent* instances of mic should not share the same cache (it's OK to share from different SDKs and different terminals provided they're not running and accessing the cache at the same time). | ||
+ | |||
+ | Here's some code you can use in ~/.mersdkrc to share a mic cache: | ||
+ | |||
+ | <nowiki> | ||
+ | if [[ ! -e ${sdkroot}/var/tmp/mic ]]; then | ||
+ | mkdir -p ${sdkroot}/var/tmp/mic | ||
+ | fi | ||
+ | if [[ ! -e /parentroot/var/tmp/mic/cache ]]; then | ||
+ | mkdir -p /parentroot/var/tmp/mic/cache | ||
+ | fi | ||
+ | if [[ ! -e ${sdkroot}/var/tmp/mic/cache && ! -h ${sdkroot}/var/tmp/mic/cache ]]; then | ||
+ | ln -s /parentroot/var/tmp/mic/cache ${sdkroot}/var/tmp/mic/cache | ||
+ | fi | ||
+ | </nowiki> | ||
+ | |||
+ | In your ~/.oscrc file there is a line: | ||
+ | packagecachedir = <something>/build-pkg-cache | ||
+ | |||
+ | If this is under $HOME then it will be shared anyway; otherwise do something similar to the mic cache code above. | ||
+ | |||
+ | === Multiple SDKs === | ||
+ | You should be able to install and connect to multiple SDKs at the same time. | ||
+ | |||
+ | === .mersdk.profile tricks === | ||
+ | ==== work around bug #554 ==== | ||
+ | To work around [https://bugs.merproject.org/show_bug.cgi?id=554 bug #554] add the following to <tt>~/.mersdk.profile</tt> (e.g. Fedora >= 17 needs that): | ||
+ | export PATH=$PATH:/sbin | ||
+ | |||
+ | ==== export SSH_AUTH_SOCK ==== | ||
+ | If you want <tt>SSH_AUTH_SOCK</tt> to be exported in Mer SDK you can do the following. | ||
+ | |||
+ | Add this to your <tt>~/.mersdkrc</tt>, set <tt>YOURHOME</tt> to your home dir, '''NOTE:''' this part of code is run as root, but still contains the users <tt>SSH_AUTH_SOCK</tt>! So <tt>$HOME</tt> will point to <tt>/root</tt>! | ||
+ | function enter_sdk { | ||
+ | YOURHOME="/home/USERNAME" | ||
+ | echo "set SSH_AUTH_SOCK env..." | ||
+ | cp $YOURHOME/.mersdk.profile $YOURHOME/.mersdk.profile.tmp | ||
+ | sed "s#^SSH_AUTH_SOCK_TEMP=.*#SSH_AUTH_SOCK_TEMP=${SSH_AUTH_SOCK}#" $YOURHOME/.mersdk.profile.tmp > $YOURHOME/.mersdk.profile | ||
+ | rm $YOURHOME/.mersdk.profile.tmp | ||
+ | } | ||
+ | |||
+ | Add this to your <tt>~/.mersdk.profile</tt>: | ||
− | = | + | SSH_AUTH_SOCK_TEMP=/tmp/#this line will be overwritten! |
− | + | export SSH_AUTH_SOCK="/parentroot${SSH_AUTH_SOCK_TEMP}" | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | == | + | == Removing the SDK == |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | Exit all instances and remove /srv/mers/sdks/sdk | |
− | + | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
[[Category:image]] [[Category:sdk]] | [[Category:image]] [[Category:sdk]] |
Latest revision as of 20:41, 24 June 2016
Mer platform SDK contains Tools like Scratchbox2, MIC (Image Creation), Spectacle, osc, qemu, etc, to make it easier for a developer to work with Mer.
Contents |
[edit] tl;dr
Install and enter the SDK under /srv/mer (HADK followers pls point home e.g. MER_ROOT=$HOME/mer instead, and your $HOME should not be mounted with nosuid or nodev options! Then perform mkdir without sudo. It will cause less issue along the way, until proper fix):
export MER_ROOT=/srv/mer cd $HOME; curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 ; sudo mkdir -p $MER_ROOT/sdks/sdk ; cd $MER_ROOT/sdks/sdk ; sudo tar --numeric-owner -p -xjf $HOME/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 ; echo "export MER_ROOT=$MER_ROOT" >> ~/.bashrc echo 'alias sdk=$MER_ROOT/sdks/sdk/mer-sdk-chroot' >> ~/.bashrc ; exec bash ; echo 'PS1="MerSDK $PS1"' >> ~/.mersdk.profile ; cd $HOME sdk
It's recommended that you read sections below for pre-requisites, options and details on installing extra tools etc.
[edit] Install on VirtualBox
The platform SDK aims to offer an alternative image that can be run like a virtual machine using the guide Platform_SDK_on_VirtualBox Don't bother with this unless you're running Windows or something too non-linuxy to make the chroot SDK work.
[edit] 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 offers an image that typically can be run in a chroot environment or in a virtual machine, which contains tools like gcc, Scratchbox2, MIC (image creator), spectacle, osc, qemu, etc, to make it easier for a developer to work with Mer.
The default download contains:
- Mer development tools
- Mer image creation
- Mer OBS development
- ARMv7hl toolchain
You can also install :
- Cross-build tools for armv6l armv7l armv7hl mipsel
- Mer debug tools
- Mer testing tools
- Mer python development
- Mer ruby development
You may also like to contribute to developing the SDK.
[edit] Using the platform SDK
[edit] SDK Requirements
The chroot SDK will run on most modern linux machines. It needs:
- Linux distribution (one in a virtual machine works well), running 2.6.37 or newer kernel
- about 400Mb free space to install
- The SDK must be installed on a standard filesystem and "nosuid" must not be set. (Note: recent ecryptfs will automatically use and enforce nosuid. Automounted usb drives typically have "nosuid" set too.)
- hundreds of Mb for rpm caches for osc and mic
- Generic x86 CPU
- user must have sudo rights
[edit] 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.
Filesystem requirements:
- 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).
- The installation path must contain an intermediate directory called 'sdks' which only has Mer SDKs inside. eg /srv/mer/sdks/sdk/...
To setup the SDK:
- Download the latest stable SDK rootfs tarball with the common armv7hl toolchain preinstalled:
cd $HOME curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2
Note that there is a version with 'all' cross compilation toolchains in the same dir in case you're working with a different target architecture.
- Create a directory for the SDK rootfs and extract the tarball as root or with sudo
sudo mkdir -p /srv/mer/sdks/sdk cd /srv/mer/sdks/sdk sudo tar --numeric-owner -p -xjf $HOME/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2
[edit] SDK control script
The platform SDK rootfs contains a helper script to enter the chroot named 'mer-sdk-chroot'. The helper script is located in 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.
[edit] 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. This also reads the bash autocompletion scripts from inside the chroot.
cat << 'EOF' >> ~/.mersdk.profile PS1="MerSDK $PS1" if [ -d /etc/bash_completion.d ]; then for i in /etc/bash_completion.d/*; do . $i done fi EOF
To enter the rootfs with the helper script run
/srv/mer/sdks/sdk/mer-sdk-chroot
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. If sudo fails within the sdk, make sure that the filesystem the sdk is on is not mounted with the "nosuid" parameter. "mount" on the host system gives you this information, add "suid" as parameter in fstab, if necessary.
[edit] Useful Alias
If you tend to use a single instance of the sdk then this alias is useful
echo alias sdk=/srv/mer/sdks/sdk/mer-sdk-chroot >> ~/.bashrc ; exec bash
[edit] Basic tasks
[edit] Building an image
ATTENTION: If you are making image for i586 target, use --arch=i686 !
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:
Check: https://img.merproject.org/images/mer-sdk/ for the name of the latest KickStart file and use it in the first command below:
for chroot version: curl -k -o mer-latest-sdk-rolling-chroot.ks https://img.merproject.org/images/mer-sdk/mer-latest-sdk-rolling-chroot.ks sudo mic create fs mer-latest-sdk-rolling-chroot.ks -o . --pkgmgr=zypp --arch i486 --pack-to=mer-latest-sdk-rolling-chroot.tar.bz2
for VM version: curl -k -o mer-next-sdk-rolling-vm.ks https://img.merproject.org/images/mer-sdk/mer-next-sdk-rolling-vm.ks sudo mic create raw mer-next-sdk-rolling-vm.ks -o . --pkgmgr=zypp --arch i486
Please check bugzilla if you encounter problems:
- extlinux issue
- https://bugs.merproject.org/show_bug.cgi?id=576
[edit] Running osc
(This section needs to be improved)
Since your home directory has been linked into the SDK then osc commands should work as normal.
osc -A API_URL ls
Where API_URL can be:
https://api.merproject.org Mer Community OBS https://api.ci.merproject.org Mer's continous integration OBS (not for regular use)
or the API url for your own, or your company's OBS.
[edit] Compiling with the SDK
Mer and the SDK uses Scratchbox2 as a cross compile tool; it can be installed into a minimal SDK by installing a cross-build environment suitable for your project.
You should install one or more of the following SB2 patterns to get a suitable environment:
sudo zypper in -t pattern Mer-SB2-armv6l sudo zypper in -t pattern Mer-SB2-armv7l sudo zypper in -t pattern Mer-SB2-armv7hl sudo zypper in -t pattern Mer-SB2-armv7tnhl sudo zypper in -t pattern Mer-SB2-mipsel
NOTE: in case of facing "not enough disk space left" or similar the problem is most probably that the kernel on your host is too old. To run Mer SDK you should be running kernel 2.6.37 or newer on your host.
These patterns provide:
- sb2 configurations
- qemu
- gcc and binutils for your architecture
Once the SDK is setup, see the documentation on using the Platform SDK and SB2
[edit] Packaging
The SDK includes tools needed to create rpm packages for Mer.
[edit] 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
[edit] 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
- spectacle
- vim
[edit] Adding New Tools
New tools can be installed using
sudo zypper in <package>
or
sudo zypper in -t pattern <pattern>
The following patterns are available:
- Mer-SB2-armv6l, Mer-SB2-armv7l, Mer-SB2-armv7hl, Mer-SB2-mipsel
- Cross-build tools for various architectures
- Mer-debug-tools
- A range of low-level debug tools
- Mer-testing-tools
- testrunner, eat and qttas
- Mer-python-development
- all your slithery needs
- Mer-ruby-development
- to add sparkle
Zypper search is useful to find available packages.
[edit] Upgrading the SDK
Don't just do zypper up!
The SDK image is (as of 5 June 2012) pinned to specific static repositories and upgrades are carried out using "sdk-upgrade" which allows the repos to be updated to latest, next or set to point to any Mer Core/SDK release pairing.
Recent SDK versions no longer have "sdk-upgrade" and you will need to run "sdk-version"(with different arguments) in order to upgrade different components of the SDK.
[edit] Upgrading Older SDKs
(ie one without sdk-version or sdk-upgrade tool)
You may be prompted to remove the unstable Tools:Testing repo - and you really should as that's now going to be used by the Tools team for sharing experimental packages. Then follow the steps indicated.
Old SDKs which don't have sdk-version should execute these steps before moving on to the appropriate upgrade process:
sudo zypper ref sudo zypper in sdk-chroot
Now run the following command
sudo sdk-upgrade
If it fails skip this part; if it succeeds then run:
sudo zypper ref sudo zypper in sdk-chroot
This release needs to install the correct script and then exit/re-enter the SDK:
exit
# unmount, re-mount and re-enter the SDK to clean up /srv/mer/sdks/sdk/mer-sdk-chroot umount /srv/mer/sdks/sdk/mer-sdk-chroot mount /srv/mer/sdks/sdk/mer-sdk-chroot enter
Now move on to the normal upgrade
[edit] Normal Upgrade
Simply run:
sdk-version --core latest --sdk rolling --go
[edit] Documentation for sdk-version
usage: [--latest | --next] [--core <release>] [--sdk <release>] [-h|--help] By default reports the current versions from the repos Alternatively updates the zypper repos to point to the "latest", "next" or specified Mer / SDK releases. It does not run zypper ref or zypper up by default (use --go for that). --core <release> : Use Mer Core <release> eg: --core 0.20120517.1 <release> can be "next" or "latest" from http://releases.merproject.org/releases/{latest,next}-release
--sdk <release> : Use SDK/Tools <release> eg: --sdk 0.5.1 <release> can be "next" or "latest" from http://repo.merproject.org/releases/mer-tools/latest-release
--latest : short for: --sdk latest --core latest --next : short for: --sdk next --core next --go : actually run the zypper upgrade
[edit] Advanced details
[edit] Documentation for mer-sdk-chroot
The usage for the helper script is:
usage: /srv/mer/sdks/sdk3/mer-sdk-chroot [-u <user>] [-m <all|none|root|home>] [-r <SDK root path>] [<command> <args> ..] /srv/mer/sdks/sdk3/mer-sdk-chroot -h
This is the Mer chroot SDK. For information see http://wiki.merproject.org/wiki/Platform_SDK
If command is not present, used to enter the SDK and begin working. The SDK bash shell is a login shell. See below for .profile handling Must be preceded by a 'mount' to setup the SDK. May be used in multiple terminals and simply enters the chroot
If command is present, used to execute an arbitrary command from within the SDK chroot environment. The environment variable MERSDK is set to 1 to allow SDK detection.
Options:
-u System user to link into SDK (not needed if using sudo) -m Devices to bind mount from host: none, all (default) root, home -r The root of the SDK to use - normally derived from the pathname of /srv/mer/sdks/sdk3/mer-sdk-chroot -h Show this help
Profile
Entering the SDK runs the user's normal .profile and any (SDK) system profile entries. It will not execute the host's system profile entries.
The environment variable MERSDK is set to 1 to allow .profile to detect the SDK.
If the user has a ~/.mersdk.profile then it is sourced after the normal .profile handling (this allows the common use case of setting a profile to be handled).
Hooks
If the user specified has a .mersdkrc in their /root, it will be sourced to allow hook functions to be defined. Hooks are run as root. No commands should be executed immediately.
These hooks are usually used to define symbolic links from any /parentroot/data type filesystems into the SDK root to setup system specific shared caches or filesystem layouts etc
[edit] Sharing mic and osc caches
You can use the ~/.mersdkrc file to check and link the standard mic and osc cache directories to those in parentroot.
Note that multiple *concurrent* instances of mic should not share the same cache (it's OK to share from different SDKs and different terminals provided they're not running and accessing the cache at the same time).
Here's some code you can use in ~/.mersdkrc to share a mic cache:
if [[ ! -e ${sdkroot}/var/tmp/mic ]]; then mkdir -p ${sdkroot}/var/tmp/mic fi if [[ ! -e /parentroot/var/tmp/mic/cache ]]; then mkdir -p /parentroot/var/tmp/mic/cache fi if [[ ! -e ${sdkroot}/var/tmp/mic/cache && ! -h ${sdkroot}/var/tmp/mic/cache ]]; then ln -s /parentroot/var/tmp/mic/cache ${sdkroot}/var/tmp/mic/cache fi
In your ~/.oscrc file there is a line:
packagecachedir = <something>/build-pkg-cache
If this is under $HOME then it will be shared anyway; otherwise do something similar to the mic cache code above.
[edit] Multiple SDKs
You should be able to install and connect to multiple SDKs at the same time.
[edit] .mersdk.profile tricks
[edit] work around bug #554
To work around bug #554 add the following to ~/.mersdk.profile (e.g. Fedora >= 17 needs that):
export PATH=$PATH:/sbin
[edit] export SSH_AUTH_SOCK
If you want SSH_AUTH_SOCK to be exported in Mer SDK you can do the following.
Add this to your ~/.mersdkrc, set YOURHOME to your home dir, NOTE: this part of code is run as root, but still contains the users SSH_AUTH_SOCK! So $HOME will point to /root!
function enter_sdk { YOURHOME="/home/USERNAME" echo "set SSH_AUTH_SOCK env..." cp $YOURHOME/.mersdk.profile $YOURHOME/.mersdk.profile.tmp sed "s#^SSH_AUTH_SOCK_TEMP=.*#SSH_AUTH_SOCK_TEMP=${SSH_AUTH_SOCK}#" $YOURHOME/.mersdk.profile.tmp > $YOURHOME/.mersdk.profile rm $YOURHOME/.mersdk.profile.tmp }
Add this to your ~/.mersdk.profile:
SSH_AUTH_SOCK_TEMP=/tmp/#this line will be overwritten! export SSH_AUTH_SOCK="/parentroot${SSH_AUTH_SOCK_TEMP}"
[edit] Removing the SDK
Exit all instances and remove /srv/mers/sdks/sdk