SDK/Docs/1.2/MeeGo SDK with Xephyr

Latest revision as of 13:22, 24 May 2011

The MeeGo SDK with Xephyr provides a development environment on Linux workstations for Netbook and Handheld applications.

This environment consists of a MeeGo image, converted for use as a chroot, combined with Xephyr, an X server for running the image's UX.

Install a chroot

You can make a chroot by unpacking a stock image, as described in Building a MeeGo chroot on Linux. This is only recommended if you are comfortable with using Linux.

If you build your own chroot, you will need to install some extra software into it, as described later.

Configure X on the host

This is to allow Xephyr to access the display:

$ xhost +SI:localuser:<user name>

where <user name> is a name of the user on the host system. For example, for a user named "bob":

$ xhost +SI:localuser:bob

(You need to do this once before running Xephyr or Qt Creator after each reboot)

"Change root" into the MeeGo image

You need MeeGo Image Creator 2 (MIC2) for this: install it using the instructions at http://wiki.meego.com/Image_Creation#Installation if you haven't already.

Run this command to chroot into the unpacked image:

$ sudo mic-chroot /path/to/chroot/dir

The output from running mic-chroot should look like this:

+====================================================================================+
| WARNING: this script is very dangerous, it may damage your system data,            |
| so please use it carefully and read this warning seriously.                        |
|                                                                                    |
| mic-chroot will create some temporary directories under /var/tmp, their names      |
| look like 'mic-tmp-*', mic-chroot also creates a directory to save image           |
| file system for chroot. For such directories, please use mic-rm-chroot-dir to      |
| remove, otherwise, you may remove your whole system by 'rm -rf <yourdir>' if you   |
| terminate mic-chroot because of some exceptions or unknown errors, the root        |
| cause is mic-chroot will bind mount / to chroot directory, exceptional             |
| terminations didn't unmount it, so you may damage your system, we have warned you. |
| Please use it very very carefully, and don't use 'rm -rf' for such directories,    |
| instead, use 'mic-rm-chroot-dir'                                                   |
+====================================================================================+


Launching shell. Exit to continue.
----------------------------------
bind_mount: /proc -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//proc
bind_mount: /proc/sys/fs/binfmt_misc -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//proc/sys/fs/binfmt_misc
bind_mount: /sys -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//sys
bind_mount: /dev -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//dev
bind_mount: /dev/pts -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//dev/pts
bind_mount: /dev/shm -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//dev/shm
bind_mount: /var/lib/dbus -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//var/lib/dbus
bind_mount: /var/run/dbus -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//var/run/dbus
bind_mount: / -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//parentroot
bind_mount: /lib/modules/2.6.33.8-149.fc13.i686 -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//lib/modules/2.6.33.8-149.fc13.i686
bind_mount: /lib/modules/2.6.34.6-54.fc13.i686 -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//lib/modules/2.6.34.6-54.fc13.i686
bind_mount: /lib/modules/2.6.35.3+ -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//lib/modules/2.6.35.3+
bind_mount: /lib/modules/2.6.34.7-56.fc13.i686 -> /home/ell/meego-netbook-ia32-1.1.80.1.20101012.1-chroot//lib/modules/2.6.34.7-56.fc13.i686

This is now a MeeGo chroot terminal. It behaves just like a terminal running in the MeeGo OS: paths, programs, libraries, and environment are all the same as those on a MeeGo OS netbook or handset.

Caution: If you later decide to delete the directory that you unpacked the image into, use mic-rm-chroot-dir to delete it. Otherwise the contents of the host file system may be destroyed.

$ sudo mic-rm-chroot-dir <image destination directory>

Install extra software (if building your own chroot)

You only need to install the software using the instructions for your type of image, below.

Netbook extra software

$ zypper install meego-simulator-launcher-netbook

Handset extra software

$ zypper install meego-simulator-launcher-handset

Tablet extra software

$ zypper install meego-simulator-launcher-tablet

Start the MeeGo UI with Xephyr

Launch Xephyr from inside the MeeGo chroot terminal with:

$ startmeego &

This starts the Xephyr server and runs a script to start the MeeGo UI. http://wiki.meego.com/File:Xephyr-tablet.png

MeeGo Tablet UI in Xephyr

MeeGo Handset UI in Xephyr

MeeGo Netbook UI in Xephyr

When you're done, stop Xephyr by closing the Xephyr window (click X in the upper corner).

Finally, exit the MeeGo chroot terminal with:

$ exit

This closes down any processes started inside the chroot and unmounts directories used by the chroot environment. The output should look something like this:

umount /home/ell/meego-sdk-0524/proc
umount /home/ell/meego-sdk-0524/sys
umount /home/ell/meego-sdk-0524/dev/pts
umount /home/ell/meego-sdk-0524/dev
umount /home/ell/meego-sdk-0524/tmp
umount /home/ell/meego-sdk-0524/var/lib/dbus
umount /home/ell/meego-sdk-0524/var/run/dbus

Customize the resolution

This can be done by editing the Xephyr start command in /usr/bin/startmeego-debug in the chroot. Change the line which starts Xephyr $DISP :

Xephyr $DISP -host-cursor -screen 864x480 -notfp -nodri2 -ac &

Replace the -screen resolution with whatever is appropriate for the image you're running (use the existing Xephyr command as a basis).

Regardless of whether you can run the UX, you can always use the chroot to run MeeGo applications run on your desktop, or compile MeeGo software. Go to Application development, below, for more details.

Debugging Xephyr

If you are having issues running Xephyr, use the debug script to see what's happening:

startmeego-debug

This shows the console output from the script, which may give you some clues if it's not working correctly.

Installing other software into the chroot

You can install additional software into the MeeGo chroot environment. From the MeeGo chroot terminal:

$ zypper install <package>

You can also upgrade the whole MeeGo image using:

$ zypper dup

Application development

The MeeGo chroot terminal can be used to build, run, and debug your application. You can do this with or without Xephyr.

Running without Xephyr: If you run your application from the command-line, it will run normally on your workstation. Although it is not running inside the MeeGo OS UI, it is still using the MeeGo libraries. You can put temporary code in your application to manually set its window size to that of a netbook (1024x800) or handheld (800x480 or 480x800) device.

Running with Xephyr: If you have Xephyr running already, before you start your application from the command-line you need to set the $DISPLAY variable to :2 tell your application to display in the Xephyr window. Otherwise it will use the default DISPLAY value of :0 and show up on your workstation.

$ export DISPLAY=:2
$ <start your application>

Building your application in the MeeGo chroot terminal is the same as doing so on a MeeGo system. You can use gcc, emacs, or any other Linux development tools you are comfortable with. (See Developing with Qt Creator from the chroot, below.)

Source Code Management

Source code is often managed by a version control system and checked in/out on your host workstation. To have your source directory available within the MeeGo chroot, you can mount --bind your source directory to a subdirectory in the MeeGo chroot. From a terminal on your host workstation, outside the MeeGo chroot:

$ sudo mount --bind <full path to source directory on host workstation> <full path to MeeGo chroot directory>/<subdirectory in MeeGo>

For example, using the directories in the example above where the chroot folder is located at /opt/meego-handset, do the following:

$ sudo mkdir /opt/meego-handset/root/src      <-- Create a folder inside MeeGo to mount the source to
$ sudo mount --bind /home/bob/src/ /opt/meego-handset/root/src/

Caution: Be sure to unmount this directory when finished and before rm -rf /path/to/chroot/dir at some later date or your source directory will be destroyed.

Developing with Qt Creator from the chroot

Qt Creator is part of MeeGo and can be installed into your chroot with:

$ zypper in qt-creator

Once installed, you can launch Qt Creator from the MeeGo chroot. The following will open Qt Creator from the chroot, but running on your workstation display (not in Xephyr):

$ export DISPLAY=:0
$ qtcreator

To setup the project:

• Create a new project (File > New File or Project). Under Projects, select Qt Gui Application and click OK.
• Enter helloworld for the name; choose a directory to save it to (such as /root if you're working as the root user). Click on Next.
• Accept the defaults in the Class Information dialog box and click Next.
• In the Project Management dialog box, click Finish.

Next write some code:

• Open the Forms folder and double-click mainwindow.ui to open it in the graphical forms editor.
• Drag a label from the list of widgets on the left-hand side of the forms editor and drop it into the editable area.
• Change the text to something else ("Hello world" works well).
• Put any other junk you like the look of in there.

Then configure the project:

• Click on the Projects icon on the left of the Qt Creator window.
• Configure the Qt version:
  • Under Build Settings > General, click on the More button. This displays the Qt version which will be used when building and running the project.
  • Click on the Manage button next to Qt Version. This displays the Qt Versions panel:
    
  • Select the Qt in PATH entry.
  • Click on Rebuild to set up the Debugging Helper for this version of Qt.
  • Click OK to save your changes.
• Make sure that the Qt Version is now set to Default Qt Version (Qt in PATH).
• Next, configure the run environment to use the Simulator to display the application when it's running:
  • Click on the Run Settings tab.
  • Click on the More button under Run Environment.
  • Double-click in the text entry next to the Display variable; change :0.0 to :2. This tells Qt Creator to run the application on display number :2, the one which Xephyr is in control of.

Running a Qt Creator project inside Xephyr

Now you're all set to run the application.

First don't forget to generate the makefile (apply qmake).

From inside Qt Creator, click on the big green arrow (bottom-left corner) to run the application. This will build it first (using the Qt Version you set up) then run it on display :2 (inside the Xephyr simulated MeeGo desktop).

In the Xephyr window, you might need to click on the MyZone icon (the house icon) to reveal the application running behind it:

Known issues with Xephyr

• Panels which rely on DBus (like the battery, networking) don't report devices properly.
• Applications that rely on DBus might work inconsistently because the host workstation's system bus is used.