The Mer Wiki now uses your Mer user account and password (create account on https://bugs.merproject.org/)


Platform SDK

From Mer Wiki
(Difference between revisions)
Jump to: navigation, search
(Entering chroot)
(fixed archive path)
 
(75 intermediate revisions by 18 users not shown)
Line 1: Line 1:
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.
+
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.
  
In a hurry? Here's the tl;dr; version :
+
= tl;dr =
  
  cd $HOME; curl -k -O https://img.merproject.org/images/sdk/mer-sb2sdk-i486-chroot-latest.tar.bz2
+
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):
  sudo mkdir -p /srv/mer/sdks/sdk
+
 
  cd /srv/mer/sdks/sdk
+
export MER_ROOT=/srv/mer
  sudo tar --numeric-owner -p -xjf $HOME/mer-sb2sdk-i486-chroot-latest.tar.bz2
+
  cd $HOME; curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2 ;
  /srv/mer/sdks/sdk/mer-sdk-chroot mount
+
  sudo mkdir -p $MER_ROOT/sdks/sdk ;
  /srv/mer/sdks/sdk/mer-sdk-chroot enter
+
  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
  
Read on for details, '''WARNINGS''', pre-requisites etc...
+
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 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.
+
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]].
 
You may also like to contribute to [[Platform SDK Development|developing the SDK]].
Line 24: Line 50:
  
 
The chroot SDK will run on most modern linux machines. It needs:
 
The chroot SDK will run on most modern linux machines. It needs:
* Linux distribution (one in a virtual machine works well)
+
* Linux distribution (one in a virtual machine works well), running 2.6.37 or newer kernel
 
* about 400Mb free space to install
 
* 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
 
* hundreds of Mb for rpm caches for osc and mic
 
* Generic x86 CPU
 
* Generic x86 CPU
 
* user must have sudo rights
 
* 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 ==
Line 49: Line 64:
 
* 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 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/...
 
* The installation path must contain an intermediate directory called 'sdks' which only has Mer SDKs inside. eg /srv/mer/sdks/sdk/...
* The SDK must not be on a nosuid filesystem - note automounted usb drives typically have this set
 
  
 
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/mer-sb2sdk-i486-chroot-latest.tar.bz2
+
  curl -k -O https://img.merproject.org/images/mer-sdk/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2
  
* Create directory for the SDK rootfs and extract the tarball as root or with sudo
+
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
 
  sudo mkdir -p /srv/mer/sdks/sdk
 
  cd /srv/mer/sdks/sdk
 
  cd /srv/mer/sdks/sdk
  sudo tar --numeric-owner -p -xjf $HOME/mer-sb2sdk-i486-chroot-latest.tar.bz2
+
  sudo tar --numeric-owner -p -xjf $HOME/mer-i486-latest-sdk-rolling-chroot-armv7hl-sb2.tar.bz2
  
 
== SDK control script ==
 
== 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 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.
 
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' ==
+
== Entering chroot ==
  
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.
+
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.
  
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]])
+
cat << 'EOF' >> ~/.mersdk.profile
 
+
PS1="MerSDK $PS1"
To connect run:
+
  if [ -d /etc/bash_completion.d ]; then
  /srv/mer/sdks/sdk/mer-sdk-chroot mount
+
    for i in /etc/bash_completion.d/*;
 
+
    do
You can now use the SDK from multiple terminals at once.
+
. $i
 
+
    done
== Entering chroot ==
+
fi
 
+
  EOF
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
 
To enter the rootfs with the helper script run
  /srv/mer/sdks/sdk/mer-sdk-chroot enter
+
  /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 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 91: Line 105:
 
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.
 
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.
  
for convenience you can create a simple script to handle sdk mounting, entering and umounting.
+
== Useful Alias ==
cd $HOME
+
cat << "EOF" > mersdk.sh
+
/srv/mer/sdks/sdk/mer-sdk-chroot mount
+
/srv/mer/sdks/sdk/mer-sdk-chroot enter
+
/srv/mer/sdks/sdk/mer-sdk-chroot umount
+
EOF
+
chmod +x mersdk.sh
+
  
use the script like this
+
If you tend to use a single instance of the sdk then this alias is useful
./mersdk.sh
+
  echo alias sdk=/srv/mer/sdks/sdk/mer-sdk-chroot >> ~/.bashrc ; exec bash
<hack with the sdk>
+
exit
+
  
 
== 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/sdk/latest/images/mer-sb2sdk-i486-chroot/ for the name of the latest KickStart file and use it in the first command below:
+
Check: https://img.merproject.org/images/mer-sdk/ for the name of the latest KickStart file and use it in the first command below:
curl -k -o mer-sdk-x86-chroot-latest.ks <INSERT URL OF LATEST KICKSTART HERE>
+
sudo mic create fs mer-sdk-x86-chroot-latest.ks -o . --pkgmgr=yum --arch i486 --compress-disk-image=tar.bz2
+
 
+
If you get an error through the build process like so:
+
 
+
    MerSDK sivan@truck:~/MER$ sudo mic create raw nemo.ks -o nemo.raw --pkgmgr=yum --arch i686
+
    Info: Retrieving repo metadata:
+
    Info: Retrieving 8767e9370d0c347ce2fb1add49e0e06a63b8fc7a7ad19a8c7f1ab58effc193b4-group.xml.gz ... DONE
+
    Info: Loading dm_snapshot...
+
    Error <mount>: Error creating ext3 filesystem on disk /dev/loop101
+
    Exception AttributeError: "'NoneType' object has no attribute 'px_proxy_factory_free'" in <bound method ProxyFactory.__del__ of <libproxy.ProxyFactory object at    0xa00924c>> ignored
+
  
Then, '''exit''' the SDK chroot , do this:
+
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
  
    sudo rm /etc/mtab; sudo ln -s /proc/self/mounts /etc/mtab
+
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
  
Then, re-enter the SDK chroot and retry image building.
+
Please check bugzilla if you encounter problems:
 +
; extlinux issue : https://bugs.merproject.org/show_bug.cgi?id=576
  
 
=== Running osc ===
 
=== Running osc ===
Line 140: Line 141:
  
 
Where API_URL can be:
 
Where API_URL can be:
   https://api.pub.meego.com    MeeGo community OBS
+
   https://api.merproject.org      Mer Community OBS
 
   https://api.ci.merproject.org  Mer's continous integration OBS (not for regular use)
 
   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.
 
or the API url for your own, or your company's OBS.
  
 
=== Compiling with the SDK ===
 
=== Compiling with the SDK ===
The SDK is available with Scratchbox2; it is pre-installed in some images or can be installed into a minimal SDK by adding a the Mer 'cross-tools' repository and installing a compiler suitable for your project.
+
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]]
 
Once the SDK is setup, see the documentation on using the [[Platform SDK and SB2]]
Line 153: Line 169:
 
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.pub.meego.com/package/show?package=sdk-kickstarter-configs&project=Mer%3ATools%3ATesting
+
See https://build.merproject.org/package/files?package=sdk-kickstarter-configs&project=mer-tools%3Atesting
  
 
=== Hosting repositories ===
 
=== Hosting repositories ===
Line 164: Line 180:
 
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.
 
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.
  
* sb2 cross compilers
 
 
* osc and build
 
* osc and build
 
* mic
 
* mic
 
* spectacle
 
* spectacle
 
* vim
 
* vim
 +
  
 
=== Adding New Tools ===
 
=== Adding New Tools ===
Line 174: Line 190:
 
New tools can be installed using
 
New tools can be installed using
 
  sudo zypper in <package>
 
  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 ==
 
== Upgrading the SDK ==
Line 180: Line 208:
  
 
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.
 
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 ===
 
=== Upgrading Older SDKs ===
  
(ie one without sdk-upgrade binary)
+
(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.
 
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-upgrade should execute these steps before moving on to the appropriate upgrade process:
+
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 ref
 
  sudo zypper in sdk-chroot
 
  sudo zypper in sdk-chroot
# There is now an sdk-upgrade binary
 
  
=== Special 6.1.0 Upgrade ===
+
Now run the following command
 +
sudo sdk-upgrade
  
This release needs to install the correct script and then exit/re-enter the SDK:
+
If it fails skip this part; if it succeeds then run:
sudo sdk-upgrade --sdk 6.0.2  # <-- this hardcode will be removed
+
 
  sudo zypper ref
 
  sudo zypper ref
 
  sudo zypper in sdk-chroot
 
  sudo zypper in sdk-chroot
# Now you have the latest SDK scripts which will clean up some old issues
+
 
 +
This release needs to install the correct script and then exit/re-enter the SDK:
 
  exit
 
  exit
  
Line 210: Line 240:
 
=== Normal Upgrade ===
 
=== Normal Upgrade ===
 
Simply run:
 
Simply run:
  sudo sdk-upgrade --sdk 6.0.2  # <-- this hardcode will be removed
+
  sdk-version --core latest --sdk rolling --go
and you will then be told what steps to take to upgrade (usually just zypper ref/up).
+
  
=== Documentation for sdk-upgrade ===
+
=== Documentation for sdk-version ===
    usage: sdk-upgrade [--next] [--core <release>] [--sdk <release>]
+
 
+
    usage: [--latest | --next] [--core <release>] [--sdk <release>] [-h|--help]
     Update 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 reports the current versions from the repos
+
    Alternatively updates the zypper repos to point to the "latest",
    By default checks
+
    "next" or specified Mer / SDK releases. It does not run zypper
        http://releases.merproject.org/releases/latest-release
+
    ref or zypper up by default (use --go for that).
        http://repo.pub.meego.com/releases/Mer-Tools/latest-release
+
     --core <release> : Use Mer Core <release>
+
    --next : Check for the 'next' release instead of 'latest'
+
+
     --core <release> : Use Mer Core <release> instead of checking for latest/next
+
 
                         eg: --core 0.20120517.1
 
                         eg: --core 0.20120517.1
     --sdk  <release> : Use SDK <release> instead of checking for latest/next
+
                        <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
 
                         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 ==
 
== Advanced details ==
Line 234: Line 268:
 
=== Documentation for mer-sdk-chroot ===
 
=== Documentation for mer-sdk-chroot ===
 
The usage for the helper script is:
 
The usage for the helper script is:
     usage: mer-sdk-chroot [<enter>] [-u <user>] [-r <SDK root path>]
+
 
          mer-sdk-chroot mount [-u <user>] [-m <all|none|root|home>] [-r <SDK root path>]
+
     usage: /srv/mer/sdks/sdk3/mer-sdk-chroot [-u <user>] [-m <all|none|root|home>] [-r <SDK root path>] [<command> <args> ..]
           mer-sdk-chroot umount [-r <SDK root path>]
+
           /srv/mer/sdks/sdk3/mer-sdk-chroot -h
+
 
 
       This is the Mer chroot SDK.
 
       This is the Mer chroot SDK.
 
       For information see http://wiki.merproject.org/wiki/Platform_SDK
 
       For information see http://wiki.merproject.org/wiki/Platform_SDK
+
 
      The SDK has 3 commands:
+
       If command is not present,
          enter (default)
+
         used to enter the SDK and begin working. The SDK bash shell is a
          mount
+
          umount
+
+
       enter
+
         Used to enter the SDK and begin working. The SDK bash shell is a
+
 
         login shell. See below for .profile handling
 
         login shell. See below for .profile handling
 
         Must be preceded by a 'mount' to setup the SDK.
 
         Must be preceded by a 'mount' to setup the SDK.
 
         May be used in multiple terminals and simply enters the
 
         May be used in multiple terminals and simply enters the
 
         chroot
 
         chroot
+
 
       mount
+
       If command is present,
         Used to setup the SDK mountpoints. Only needed once per login
+
         used to execute an arbitrary command from within the SDK chroot
         session
+
         environment. The environment variable MERSDK is set to 1 to allow
+
         SDK detection.
      umount
+
 
         Used to clean up the SDK mountpoints before removing the SDK.
+
+
 
       Options:
 
       Options:
+
 
 
       -u  System user to link into SDK (not needed if using sudo)
 
       -u  System user to link into SDK (not needed if using sudo)
 
       -m  Devices to bind mount from host: none, all (default)
 
       -m  Devices to bind mount from host: none, all (default)
 
           root, home
 
           root, home
 
       -r The root of the SDK to use - normally derived from the
 
       -r The root of the SDK to use - normally derived from the
           pathname of mer-sdk-chroot
+
           pathname of /srv/mer/sdks/sdk3/mer-sdk-chroot
   
+
      -h Show this help
 +
 
 
       Profile
 
       Profile
+
 
 
       Entering the SDK runs the user's normal .profile and any (SDK)
 
       Entering the SDK runs the user's normal .profile and any (SDK)
 
       system profile entries. It will not execute the host's system
 
       system profile entries. It will not execute the host's system
 
       profile entries.
 
       profile entries.
+
 
 
       The environment variable MERSDK is set to 1 to allow .profile to
 
       The environment variable MERSDK is set to 1 to allow .profile to
 
       detect the SDK.
 
       detect the SDK.
+
 
 
       If the user has a ~/.mersdk.profile then it is sourced after the
 
       If the user has a ~/.mersdk.profile then it is sourced after the
 
       normal .profile handling (this allows the common use case of
 
       normal .profile handling (this allows the common use case of
 
       setting a profile to be handled).
 
       setting a profile to be handled).
+
 
 
       Hooks
 
       Hooks
+
 
       If the user specified has a .mersdkrc in their $HOME, it will be
+
       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
 
       sourced to allow hook functions to be defined. Hooks are run as
 
       root. No commands should be executed immediately.
 
       root. No commands should be executed immediately.
+
 
 
       These hooks are usually used to define symbolic links from any
 
       These hooks are usually used to define symbolic links from any
 
       /parentroot/data type filesystems into the SDK root to setup
 
       /parentroot/data type filesystems into the SDK root to setup
 
       system specific shared caches or filesystem layouts etc
 
       system specific shared caches or filesystem layouts etc
 
  
 
=== Sharing mic and osc caches ===
 
=== Sharing mic and osc caches ===
Line 299: Line 326:
  
 
Here's some code you can use in ~/.mersdkrc to share a mic cache:
 
Here's some code you can use in ~/.mersdkrc to share a mic cache:
 +
 +
    <nowiki>
 
     if [[ ! -e ${sdkroot}/var/tmp/mic ]]; then
 
     if [[ ! -e ${sdkroot}/var/tmp/mic ]]; then
 
         mkdir -p ${sdkroot}/var/tmp/mic
 
         mkdir -p ${sdkroot}/var/tmp/mic
 +
    fi
 +
    if [[ ! -e /parentroot/var/tmp/mic/cache ]]; then
 +
        mkdir -p /parentroot/var/tmp/mic/cache
 
     fi
 
     fi
 
     if [[ ! -e ${sdkroot}/var/tmp/mic/cache && ! -h ${sdkroot}/var/tmp/mic/cache  ]]; then
 
     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
 
         ln -s /parentroot/var/tmp/mic/cache ${sdkroot}/var/tmp/mic/cache
 
     fi
 
     fi
 +
    </nowiki>
  
 
In your ~/.oscrc file there is a line:
 
In your ~/.oscrc file there is a line:
Line 314: Line 347:
 
You should be able to install and connect to multiple SDKs at the same time.
 
You should be able to install and connect to multiple SDKs at the same time.
  
== Removing and disconnecting the SDK ==
+
=== .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
  
Under normal use the SDK does not need to be disconnected; it's only usually needed when you want to remove an instance of the SDK.
+
==== export SSH_AUTH_SOCK ====
 +
If you want <tt>SSH_AUTH_SOCK</tt> to be exported in Mer SDK you can do the following.
  
To disconnect run:
+
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>!
  /srv/mer/sdks/sdk/mer-sdk-chroot umount
+
  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>:
  
Be sure that the bind-mounts(especialy the home directory) are all umounted after you disconnect the SDK. You can use 'cat /proc/self/mountstats' to check it. If it is not umounted cleanly, you should umount it manually after you exit the chroot environment.
+
SSH_AUTH_SOCK_TEMP=/tmp/#this line will be overwritten!
 +
export SSH_AUTH_SOCK="/parentroot${SSH_AUTH_SOCK_TEMP}"
  
The SDK does warn you if umounts fail. It also uses 'lazy' umounts which means that the mountpoints will go away as soon as the kernel can clean them (typically when processes exit or terminals cd out of the mounted directories.)
+
== Removing the SDK ==
  
Once the SDK has been cleanly unmounted, it may be removed manually.
+
Exit all instances and remove /srv/mers/sdks/sdk
  
Note that the mountpoint:
 
  /srv/mer/sdks
 
will stay in the mount list all the time - this is intentional. Also note that it can sometimes appear to show a mount to the same device as another mountpoint (eg /) depending on your distro's configuration. ([https://bugs.merproject.org/show_bug.cgi?id=328 See bug 328 for details])
 
  
  
 
[[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.

See https://build.merproject.org/package/files?package=sdk-kickstarter-configs&project=mer-tools%3Atesting

[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

Personal tools