Testing Console Applications On The Device

 

In one of our other tips, we created and stared console applications in the emulator for functional testing.  This tip shows how to add the console application to the phone applications menu. Note, that this also works for the emulator, which makes it even nicer. This takes a bit of work, but works really nice when testing 2nd and 3rd edition console apps both on the phone and in the emulator.

To make it work we need modify a couple of files and create an application registration file (appname_reg.rss) for our application. The application registration file is mandatory in Symbian OS v9, it’s also supported in v8.1 (but not required).
If you try to look at a registration file generated by e.g. one of the project wizards for Symbian OS v9 or found in the examples folder of v9 SDKs. You’ll see that the registration file defines the applications UID, the filename of the application executable and finally specifies the location and resource id of the resource file defining the icons and captions of our application. However we are only required to specify the UID and filename of the executable.

We’ll use step-1-2-3 from the Testing Console Appliations In The Emulator tip, as a starting point. After creating the project we need to add the registration file to our project. By convention we place our resource files in a \data folder, which we will also follow here - you probably need to create the data folder yourself by pressing New->Folder.
Create new file called testexe_rsg.rss by right clicking the data folder in our testexe project and selecting New->File. Open the new file and enter the following:

 

testexe_rsg.rss

#include <appinfo.rh>
UID2 KUidAppRegistrationResourceFile
UID3 0xea95c658 // Should be your apps v9 UID


RESOURCE APP_REGISTRATION_INFO
{
    app_file = "testexe"; // Our executable filename
}


The next edit before we can try to build for the emulator will be in our project definition file:

 

testexe.mpp

#ifdef EKA2
TARGET                     testexe.exe
TARGETTYPE                 exe
UID                        0 0xea95c658    // v9 UID3
VENDORID                   0
CAPABILITY                 NONE

#else

TARGET                     testexe.app
TARGETTYPE                 epocexe
TARGETPATH                 \system\apps\testexe
UID                        0 0x200031C8  // pre-v9 UID3

#endif

USERINCLUDE               ..\inc
SYSTEMINCLUDE           \epoc32\include

SOURCEPATH                ..\data
#ifdef EKA2    
START RESOURCE        testexe_reg.rss
#ifdef WINSCW 
TARGETPATH         \private\10003a3f\apps
#else 
TARGETPATH         \private\10003a3f\import\apps
#endif
END                             
#endif 

SOURCEPATH                 ..\src
SOURCE                         testexe.cpp


LIBRARY                        euser.lib


Again you’ll notice that I’ve mostly added some code to handle both 2nd and 3rd edition platforms. One thing that might look a bit weird at first is the TARGET and TARGETTYPE for our 2nd edition devices. I won’t go into a lot of specifics here, but as you might know the 2nd edition emulator doesn't support emulation of new processes, so running plain executables in the fully loaded GUI emulator wasn’t possible. However, to overcome this issue the epocexe target type was created. This target type creates a .dll (which we rename to .app by specifying it in the TARGET statement) for the emulator, and an exe for the target device. To launch our .app in the 2nd edition emulator we only need to copy it to the right place, done using the TARGETPATH statement.

The usage of epocexe for the second edition builds mean that we also have to modify our testexe.cpp slightly, all you have to do is to add these couple of lines to the bottom of the file:

 

testexe.cpp 

 #if defined(__WINS__) && !defined(EKA2)

EXPORT_C TInt WinsMain()
    {
    return E32Main();
    }

TInt E32Dll(TDllReason /*aReason*/)
    {
    return KErrNone;
    }

#endif

Unfortunately I’ve not been successfully making this work if we try to build from the Carbide.c++ IDE. So, as so many times before it’s back to the old trustworthy command line. Anyways who needs an IDE :) We open a command prompt navigate to the group dir of our project and issue the usual commands (if you're not familiar with the devices command look here):

C:\...\testexe\group> devices –setdefault @2ndFP3
C:\...\testexe\group> bldmake bldfiles
C:\...\testexe\group> abld build winscw udeb
C:\...\testexe\group> epoc

C:\...\testexe\group> devices –setdefault @3rdMR
C:\...\testexe\group> bldmake bldfiles
C:\...\testexe\group> abld build winscw udeb
C:\...\testexe\group> epoc

The first line uses the devices command to make sure we are using the right SDK, the last line starts the emulator, and volia:



Before we can start building for the target devices we need to update the bld.inf file of our project. The statement we need to modify is the PRJ_PLATFORMS specifying the supported platforms for this project:

 

bld.inf

PRJ_PLATFORMS
DEFAULT

PRJ_MMPFILES
testexe.mmp

 

Now the final step is to create some SIS files and test our project on the target devices. The Carbide.c++ Express application wizard already creates two pkg files for us, one for 3rd edition and one for 2nd edition. I just modified the last lines, so the SIS file would pick up the correct files and put them in the correct directories on the device.


testexe_EKA1.pkg

/** Some other stuff */
"path\Epoc32\release\armi\urel\testexe.exe"-"!:\system\apps\testexe\testexe.exe"

 
testexe_EKA2.pkg

/** Some other stuff */

"path\Epoc32\release\gcce\urel\testexe.exe"-"!:\sys\bin\testexe.exe"
"path\Epoc32\data\z\private\10003a3f\import\apps\testexe_reg.rsc"-
"!:\private\10003a3f\import\apps\testexe_reg.rsc"

   
Now all we need to do is to create the SIS files using e.g. makesis and createsis. Which would look something like this (I'll show all the commands to avoid any confusion):

C:\...\testexe\group> devices –setdefault @2ndFP3
C:\...\testexe\group> bldmake bldfiles
C:\...\testexe\group> abld build armi urel
C:\...\testexe\group> cd ..\sis

C:\...\testexe\sis> makesis testexe_EKA1.pkg

 

C:\...\testexe\gropu> devices –setdefault @3rdMR
C:\...\testexe\gropu> bldmake bldfiles
C:\...\testexe\gropu> abld build gcce urel
C:\...\testexe\gropu> cd ..\sis

C:\...\testexe\sis> createsis -create -cert test.cer -key key.key -pass test testexe_EKA2.pkg

 

You need to replace the certificate and key information with you own. The following screenshots shows the result on the devices (I used an N70 and N80). Note, remember to check that you are using the correct UID3 values in both mmp, appname_reg.rss and pkg files.

 

 

 

Application Wizard - Template

To make this even more easy for you to use in your projects, we've created a template for Carbide.vs (Visual Studio plugin). Download it here, if you've installed the Carbide.vs plugin into its default path you should un-zip the archive into C:\Nokia\Tools\Carbide_vs\Templates\ProjectTemplates.

 

 

 

 

You should now be able to select the S60 3rd Console EXE extra project template from the application wizard as shown in the figure below.

 

 

 

 

 

Unfortunately no template for Carbide.c++ is available yet :(

 

Acknowlegments

Thanks to Itomuta from the discussion boards on forum.nokia.com for sharing the tip about the application registration file, and thanks to Antony Pranata for his Screenshot for Symbian OS application.

Department of Electronic Systems | Aalborg University | Niels Jernes Vej 12 | DK-9220 Aalborg | Denmark
Phone: (+45) 9635 8695 | Fax (+45) 9815 1583 | E-mail ies(at)ies.aau.dk
Copyright © 2006 Department of Electronic Systems

Last update:03-04-2007