MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Integrating Qt Creator with Scratchbox in Mac OS X environment


Qt Creator is a cross-platform C++ integrated development environment which includes a visual debugger and an integrated GUI layout and forms designer. The editor's features includes syntax highlighting and autocompletion.

When you have added support for Scratchbox toolchain:

  • You can develop complex applications that use Linux build tools.
  • You can run applications under simulated ARM or x86 environment with full MeeGo 1.2 Harmattan library and style support.

Scratchbox can be installed only on Linux systems, a virtualisation environment is needed for Linux installation on other platforms. VirtualBox is a powerful x86 and AMD64/Intel64 virtualisation product which is available for multiple operating systems including Mac OS X.

This section describes how to set up the Scratchbox target for Qt Creator and how to compile and run an application under Scratchbox from Qt Creator when Scratchbox is running inside the virtualised Linux (Ubuntu) installation on Mac OS X.

To use Qt Creator with Scratchbox in Mac OS X environment, you must do the following:

  1. Install Qt and Qt Creator.
  2. Install the virtualisation environment.
  3. Install Scratchbox.
  4. Set up the connections between the workstation and the guest operating system.
  5. Create a Scratchbox Qt version in Qt Creator.

Installing Qt and Qt Creator

Download and install Qt environment and Qt Creator from Qt web site.

Installing the virtualisation environment

1. Download and install VirtualBox 4.0.12.

Note: You must use VirtualBox version 4.0.12. The commands are used differently in later versions, and they cannot be used for this purpose.

2. Configure VirtualBox. To configure network settings, do either of the following:

  • Select the "bridged" mode for easy remote access.
  • Use network address translation (NAT) and port forwarding for SSH by selecting Settings > Network > Advanced > Port Forward from guest 22 to host 22222.

Note: If you use NAT, you also need to modify sbox-make, sbox-qmake and sbox-run scripts (which are created later) to use 127.0.0.1 as IP and add -p22222 to SSH_OPTS.

For more information on how to set up and use virtualisation using VirtualBox, see Oracle VM VirtualBox manual.

3. Install the guest operating system. In this section the latest Ubuntu (11.04 / Natty) is used as the guest operating system running in a virtualised environment. To install a Linux guest in VirtualBox, download an ISO installation image for the corresponding distro (for example Ubuntu 11.04) and mount the image into the CD-ROM of the created virtual machine.

Note: It is recommended that you use the same name as the user name in Linux and short user name in Mac OS X.

4. Install a corresponding server package (openssh-server) on the guest system to allow communication between the host and the guest system using SSH.

5. Install VirtualBox Guest Additions to the guest machine.

Note: If Xephyr crashes on execution inside guest system, you need to replace the VirtualBox video driver in xorg.conf with vesa driver.

Replacing the video driver

1. Create an SSH connection to the guest system.

2. Enter the following commands:

sudo service gdm stop
sudo X -configure

3. Replace vboxvideo with vesa in xorg.conf.new. Enter the following commands:

sudo cp xorg.conf.new /etc/X11/xorg.conf
sudo service gdm start

Installing Scratchbox

When the Linux guest operating system is up and running, install Scratchbox. For instructions, see Installing Harmattan Platform SDK.

Setting up the connections between the OS X and the virtualised Linux installation

SSH is used for executing commands in the Scratchbox installation through Qt Creator. The SSH keys are required for authentication without a password.

Generating and deploying SSH keys

To generate SSH keys on the host workstation (OS X) and deploy them to the guest system (Linux):

1. In host (OS X), generate SSH keys (public and private). Enter the following commands:

$ ssh-keygen -t rsa -N '' -f ~/.ssh/vbox-scratchbox-qtc-rsa
$ ssh-add ~/.ssh/vbox-scratchbox-qtc-rsa

2. To transfer the created key from host workstation (OS X) to the guest system (Linux), enter the following commands:

$ scp /Users/<USERNAME>/.ssh/vbox-scratchbox-qtc-rsa.pub <GUEST_USERNAME>@<GUEST_IP>:/home/<USERNAME>/

3. In the guest system (Linux), append the created public key to the authorized_keys file. Enter the following command:

$ cat ./vbox-scratchbox-qtc-rsa.pub >> .ssh/authorized_keys

Shared folder and symmetric paths

To allow access between the work directories in the guest and host environments, you need to set up a shared folder between the systems.

Prerequisites:

Shared Folders functionality in VirtualBox requires special drivers that are included in the VirtualBox Guest Additions. To install them, start VirtualBox and do either of the following:

  • Select Devices > Install Guest Additions.
  • Press <host>+D.

For more information about folder sharing in VirtualBox, see Shared folders in Oracle VM VirtualBox manual.

To set up the connection:

1. Create a folder with same name in your home folder on the host system (OS X) and the Scratchbox inside the guest system (Linux). Enter the following commands:

In the host system:

$ mkdir /Users/<USERNAME>/scratchbox
$ VBoxManage sharedfolder add "VM name" --name "SHARENAME" --hostpath "/Users/<USERNAME>/scratchbox"

In the guest system:

$ mkdir /scratchbox/users/<USERNAME>/home/<USERNAME>/scratchbox

2. Share the folder created in host (OS X) system with the guest (Linux) system. In the guest system, mount the folder to the created folder in Scratchbox. Enter the following command:

$ sudo mount -t vboxsf "SHARENAME" /scratchbox/users/<USERNAME>/home/<USERNAME>/scratchbox/ -o rw,exec,uid=<USERNAME>,gid=<USERNAME>,dev

Note: It is recommended that you add the mount point to /etc/fstab, for example for SHARENAME=share USERNAME=tester:

 share     /scratchbox/users/tester/home/tester/scratchbox vboxsf  rw,exec,uid=tester,gid=tester,dev       0 0

3. Create a symbolic link called Users to point to Scratchbox's home folder. Enter the following command:

$ cd /scratchbox/users/<USERNAME>/
$ ln -s home Users

Note: VirtualBox handles the file ownership according to the host or guest system. Thus, a user who is running the VirtualBox in the host can access the files that you create in the shared folder on the guest system.

Note: The directory structures need to be symmetrical on the host and guest systems.

Creating compiler shell scripts in the host workstation

To run Scratchbox commands inside your guest system over SSH, you need to create two shell scripts for triggering qmake and make commands in Scratchbox in the host system. Since in most cases the IPs of the systems are not static in the scripts, the IP of the guest is resolved using VBoxManage command-line interface in VirtualBox.

When you add the qmake script as a new Qt version in Qt Creator, the script checks the Qt version with qmake --version and qmake -query commands. However, since the host and guest file systems and system paths are slightly different in the script, you need to execute the actual command in the host system whenever qmake --version or qmake -query is triggered through the script.

1. Create the /Users/$USER/sbox/qmake script with the following contents:

$ sudo vi /Users/$USER/sbox/qmake

#!/bin/sh
##############

### Change these to match your environment
VIRTUAL_MACHINE="VM_NAME"
VM_USERNAME="YOUR_USERNAME"
VM_PASSWORD="YOUR_USERNAME"
HOST_USERNAME="YOUR_USERNAME"

### lets _disable_ the knownhosts warning
SSH_OPTS="-q -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -i /Users/$HOST_USERNAME/.ssh/vbox-scratchbox-qtc-rsa"

### will execute /sbin/ifconfig on virtual machine
### and parse the ipv4 address
IP=`VBoxManage guestcontrol execute $VIRTUAL_MACHINE /sbin/ifconfig --username $VM_USERNAME --password $VM_PASSWORD --timeout 2000 --wait-for stdout|grep "inet addr"|grep -v 127|sed "s/.*addr://"|sed "s/ Bcast:.*//"|sed "s/ //"`

### lets check the command line arguments
if [[ $1 == "--version" ]]; then
  
  ### lets execute the sbox-qmake -version on host machine
  RES=`qmake $@`
else
  if [[ $1 == "-query" ]]; then
    ### lets execute sbox-qmake -query on host machine
    RES=`qmake $@`
  else 
    ### every other than -query and -version are executed on the remote machine inside scratchbox qmake
    FILTERED=`echo $@|sed "s/macx\-g\+\+/linux\-g\+\+\-maemo/"`
    RES=`ssh $SSH_OPTS $VM_USERNAME@$IP "scratchbox -d $PWD qmake $FILTERED"`
  fi
fi

### lets split to new line for each <space> and echo it to stdout
for RE in $RES; do
 echo $RE
done

2. Create the /Users/$USER/sbox/make script with the following contents:

$ sudo vi /Users/$USER/sbox/make

#!/bin/sh
##################

## Change these to match your environment
VIRTUAL_MACHINE="VM_NAME"
VM_USERNAME="YOUR_USERNAME"
VM_PASSWORD="YOUR_USERNAME"
HOST_USERNAME="YOUR_USERNAME"


### lets _disable_ the knownhosts warning
SSH_OPTS="-q -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -i /Users/$HOST_USERNAME/.ssh/vbox-scratchbox-qtc-rsa"


IP=`VBoxManage guestcontrol execute $VIRTUAL_MACHINE /sbin/ifconfig --username $VM_USERNAME --password $VM_PASSWORD --timeout 2000 --wait-for stdout|grep "inet addr"|grep -v 127|sed "s/.*addr://"|sed "s/ Bcast:.*//"|sed "s/ //"`

ssh $SSH_OPTS $VM_USERNAME@$IP "scratchbox -d $PWD make $@"

3. To set the access and execution rights for the scripts, enter the following command:

$ chmod +x /Users/$USER/sbox/make /Users/$USER/sbox/qmake

Creating Scratchbox Qt version under Qt Creator

In Qt Creator, create a new project or select an existing one that uses at least the desktop target. Harmattan and Qt Simulator targets do not allow you to choose a custom Qt version.

Configuring Qt Creator

1. When you have the project open in Qt Creator, select Tools > Options and open the Qt4 tab.

2. Click Add and enter a name for the new Qt version.

In this example, the name Qt (sbox) is used.

3. In the qmake location field, click Browse and select the recently created /Users/$USER/sbox/qmake script.

If everything went right, Qt version for Desktop is displayed in Qt Creator.

4. Click OK.

Configuring build settings for the current project

1. Switch to Projects mode button.

2. On the target toolbar, select Desktop > Build to configure the build settings.

3. Select the build configuration from Build Settings.

4. Select the recently created Qt (sbox) version in Qt Version.

5. Clear Shadow build check box to ensure better compatibility and select 32-bit toolchain.

6. You need to set make to be overridden with the /Users/$USER/sbox/make script. To do this, select Details from Make and browse for /Users/$USER/sbox/make in the Override make field.

You now have a working Build Configuration for the current project.

Note: You must execute the above steps for each project that you compile with this setup.

Testing the new build settings

1. To test the setup, select Build > Rebuild Project: <your project name> from the top menu.

2. Switch to Edit to view the output.

The following figure shows an example output:

Executing your application in Scratchbox using Qt Creator

Configuring run settings of the current project in Qt Creator

1. Switch to Projects mode button.

2. On the target toolbar, select Desktop > Run to configure the run settings.

3. Click Add next to Run configuration.

4. Select Custom executable from the pop-up menu.

5. In the Executable field, browse for the /Users/$USER/sbox/run script.

6. In the Arguments field, add the binary name of your application (usually the project name by default).

Note: You need to use ./ in front of the application name.

You have now successfully configured the run settings for the current project.

Configuring the environment

To execute your application from Scratchbox using Qt Creator, you must create one more script in /usr/bin/ directory of your host.

Because Qt Creator expands symbolic links, /home/$USER/scratchbox becomes /scratchbox/users/$USER/home/$USER. Thus, you must remove the prefix to ensure that the scratchbox meego-run script works correctly.

In the host operating system (OS X), enter the following contents in the /Users/$USER/sbox/run script to remove the prefix:

#!/bin/sh

## Change these to match your environment
VIRTUAL_MACHINE="VM_NAME"
VM_USERNAME="<YOUR_USERNAME>"
VM_PASSWORD="<YOUR_USERNAME>"
HOST_USERNAME="<YOUR_USERNAME>"

### lets _disable_ the knownhosts warning
SSH_OPTS="-q -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -i /Users/$HOST_USERNAME/.ssh/vbox-scratchbox-qtc-rsa"

IP=`VBoxManage guestcontrol execute $VIRTUAL_MACHINE /sbin/ifconfig --username $VM_USERNAME --password $VM_PASSWORD --timeout 2000 --wait-for stdout|grep "inet addr"|grep -v 127|sed "s/.*addr://"|sed "s/ Bcast:.*//"|sed "s/ //"`

ssh $SSH_OPTS $VM_USERNAME@$IP "/usr/bin/scratchbox -d `echo $PWD| sed -e "s_/scratchbox/users/[A-Za-z0-9]*/_/_"` meego-run $@"

After you have created the script, add execution rights for it:

sudo chmod +x /Users/$USER/sbox/run

Executing the application in Scratchbox using Qt Creator

1. To start the framebuffer X server (Xephyr), enter the following command inside Virtual Machine:

Xephyr :2 -host-cursor -screen 480x854x16 -dpi 96 -ac +extension Composite

Note If you get following error, switch to vesa xorg driver.

 Xephyr: ../../../../include/privates.h:116: dixGetPrivateAddr: Assertion `key->initialized' failed.
 Aborted

2. Now that Xephyr is running, launch meego-sb-session on it. Enter the following commands:

/scratchbox/login
[sbox-HARMATTAN_X86: ~]> meego-sb-session start

3. To run your Qt application, click Run.

Your application appears in the Xephyr window.