Mobile/Build/Windows Mobile DebuggingIt

From MozillaWiki
< Mobile‎ | Build
Jump to: navigation, search

Windows Mobile Debugging

Debugging XULRunner and Fennec Mobile Browser on Windows Mobile generally requires the use of the Microsoft Visual Studio IDE.

This page covers some of the information we have learned (usually the hard way) about debugging XULRunner and Fennec for Windows Mobile.


Visual Studio 2005 / Visual Studio 8 Debugging

Visual Studio 2005 (VS8) has the following issues when debugging:

  • VS8 is available for free from Microsoft, with is a great thing for part-time hackers.
  • You can compile xulrunner and fennec, then copy the executables to a device and try running the executables.
  • The main people working on WinMobile are using VS9 for compiling and debugging.
  • VS8 Emulator's shared-directory driver does not work properly. If you try to use the Emulator supplied with VS8, you will receive LOTS of random errors and faults. You might be able to eventually get a good run of the xulrunner application, but you will also get very frustrated at the same time.
  • Installing Windows Mobile 6.1 Professional Localized Emulator Images fixes the issue with Emulator Shared Directory use, allowing you to point your Emulator at your BIN directory for running your executables without needing to copy the executables.
  • The WinMobile 6.1 Emulator Images installation also fixes a bug with setting the amount of memory within an Emulator Image.


Visual Studio 2008 / Visual Studio 9 Debugging

Visual Studio 2008 (VS9) has the following issues when debugging:

  • If the Mozilla WinCE Shunt Library fails compiling with an error message about a missing CeGetCanonicalPathName() function, you will need to select the "Windows Mobile 6 Professional" platform in the VS9 IDE platform selection drop-down list box. On a brand-newly cloned source tree, VS9 selects a platform of Windows Mobile 2003.
  • The WinMobile 6.1 Emulator Images installation updates the VS9 Emulator, fixing a bug with setting the amount of memory within an Emulator Image.
  • The main people working on WinMobile use VS9 to run / debug in the emulator / debug on-device.


Emulator Images

To run / debug xulrunner and fennec, you will need to increase the amount of memory available to the WinMobile 6.1 Emulator Image in which you are running.

To increase the amount of memory available to your Windows Mobile 6.1 Localized Emulator Image, do the following within VS9:

  • Pull down the Tools menu
  • Select the Options... menu item
  • Find the Device Tools section in the list on the left hand side
  • Find and select the Devices sub-section
  • Find and select the desired Emulator Image
  • Press the Properties... button
  • Press the Emulator Options... button
  • Check the Specify RAM Size checkbox
  • Enter a number greater than 192 (and less than or equal to 256) into the edit box.
  • Press OK to close the Emulator Properties dialog box
  • Press OK to close the Emulator Image dialog box
  • Press OK to close the Options dialog box
  • When you start up your Emulator Image, verify that you have the RAM you specified in the Emulator Properties dialog box.
  • If your Emulator Image does not have the RAM you specified, you may need to make a new copy of the Emulator in order to correctly specify the RAM size available to your Emulator Image.


On-Device Debugging

Some devices ship with security settings turned on.

You can debug without having the Microsoft development certificates loaded on your device, but you will constantly encounter prompts asking you to allow some DLL or EXE to run. Loading the Microsoft development certificates onto your physical device before debugging is a helpful thing to do.


Putting Development Certificates On Your Device

To set the development certificates into your device, copy the file C:\Program Files\Windows Mobile 6 SDK\Tools\Security\SDK Development Certificates\Certs.cab onto your device.

Locate and run this CAB file using the device's File Explorer.

Once this CAB file has been installed into your device, the device will be able to run all of the Visual Studio devlopment tools.


Enabling RAPI Commands On Your Device

To allow all RAPI (Remote API function calls from the desktop to your tethered, or connected, device) function calls to succeed, you may need to run a command from a DOS box on your PC.

Run these commands once your device has the development certificates installed and you have your device connected to your PC: 

 C:\> cd "C:\Program Files\Windows Mobile 6 SDK\Tools\Smartphone\RapiSecurity"
 
 C:\> RapiConfig.exe  /P /M RapiAllowed.xml

Instead of running the RapiConfig.exe program, you can copy a Certificate Provisioning File (.CPF) to your device, and run the .CPF file just like you ran the Certs.cab file.

Copy the file C:\Program Files\Windows Mobile 6 SDK\Tools\Smartphone\RapiSecurity\RapiAllow.cpf file onto your device.

Locate and run this .CPF file using the device's File Explorer.


Security Powertoy

Microsoft provides a Security Powertoy application which allows mere mortals to manipulate the security settings on a device from a semi-friendly GUI.

To use the Security Powertoy, run the "C:\Program Files\Windows Mobile 6 SDK\Tools\Security\Security Powertoy\SecCfgMgr.msi" installer.

Once the installer has finished, there will be a shortcut created in your PC's Start Menu named "Security Configuration Manager".

WARNING: The Security Powertoy has the ability to completely mess up your device. Use this tool with extreme caution.

Remember that a Hard Reset can be very helpful when debugging on-device.


Putting XULRunner on a Device

Thanks to Tim Zander for pointing out that no one ever explains how to get XULRunner onto a device.

You currently (as of 19-Feb-2009) have three options for getting XULRunner on to a device: 

 (1) Copy a fennec.cab file onto your device.  
     Locate and then run the fennec.cab file on your device.
     You can create your own fennec.cab file by going into your 
     $(OBJDIR)/mobile/mobile/installer directory and running make.
 
 (2) If your device takes a plug-in expansion card, copy the directory 
     $(OBJDIR)/mobile/dist/fennec on to a expansion card from your PC, 
     then place that expansion card into your device. 
 
 (3) If your device has a LOT of internal storage (i.e., the HTC Touch Diamond 
     has 4GBytes of internal storage), then you can teather your device to 
     your PC, and use ActiveSync's File Explorer to copy the directory 
     $(OBJDIR)/mobile/dist/fennec onto your device.

On my PC, the $(OBJDIR)/mobile/dist/fennec directory is located at c:\hg\mozilla-central\objdir-wm6-dbg\mobile\dist\fennec, and is approximately 32 MBytes large.

Once you have the executables on your device, you can launch the executables via: 

 (A) The Visual Studio IDE (for debugging) 
     (i.e., "\Storage bin\fennec\xulrunner\xulrunner.exe ..\application.ini")
 
 (B) Via RAPI remote execute command
 
 (C) Via File Explorer on the device
 
 (D) Via specially-created shortcut to directly launch xulrunner.exe


Creating Shortcut for XULRunner

You can make a shortcut link to execute the command you want under Windows Mobile / WinCE. Here is how:

A Shortcut Link File is a text file with an extension .LNK with one line in a very particular format: 

 NN#THE_COMMAND_LINE_GOES_HERE
 
 Where:
 
   NN: Number of characters in the whole command line
 
   THE_COMMAND_LINE_GOES_HERE: The actual command you would execute 
     (as if you were running in a DOS box on WinXP)
 
 Some things to watch out for:
 
   (1) It is a LOT safer to use a full path to your executable
 
   (2) If the full path to your executable contains any spaces, you 
       HAVE to wrap the full path to your executable with double-quotes
 
   (3) Any space not wrapped inside a double-quote will signal the OS that 
       an argument has ended and another argument is beginning
 
   (4) If your arguments have spaces in them, again wrap the whole single 
       argument in double-quotes
 
 Here is an example:
 
   64#"\Program Files\MyDir\MyExe.exe" "First Argument" SecondArgument

There is also an app that you can use called Shortcut Creator.

Place your newly created shortcut in \Windows\Start Menu\Programs (or one of its sub-folders).

If you are trying the executable on Windows Mobile 5, you MAY want to place your shortcut in the \Windows\Start Menu\Programs\Games folder, because WinMobile 6 does not automatically update the Start Menu's contents until its next reboot. However, each sub-directory of the Start menu is re-evaluated every time you open the corresponding folder in the Start menu. 

 Suppose you have your fennec dist directory installed to 
 \Internal Storage\Program Files\Fennec
 
 Your shortcut to directly launch XULRunner with the Fennec app is:
 
 83#"\Internal Storage\Program Files\Fennec\xulrunner\xulrunner.exe" ..\application.ini

 Now suppose you have your fennec dist directory installed to 
 \Program Files\Fennec
 
 Your shortcut to directly launch XULRunner with the Fennec app is:
 
 66#"\Program Files\Fennec\xulrunner\xulrunner.exe" ..\application.ini


Setting Up Debugging of Fennec On A Device

You can debug the Fennec XULapp from within Visual Studio by creating a simple Visual Studio Project, then adjusting the deployment device and executable to be run. 

1. Build both xulrunner and mobile via the instructions found on this page.

2. Make an installer by running the make installer command from 
   the directory $(OBJDIR)/mobile/mobile/installer  

   This step will create both a CAB file AND a fennec directory within
   the $(OBJDIR)/mobile/dist directory

3. Copy the $(OBJDIR)/mobile/dist/fennec directory on to your device's
   Storage Card, creating a \Storage Card\fennec directory

4. Open Visual Studio 2005 (Visual Studio 8) Integrated Development Environment (IDE)

5. Open the solution you have created for use in debugging

6. In the Solution Explorer, right mouse click on the debugging project

7. Select the Properties pop-up menu item

8. Under the configuration properties, highlight the Deployment section

9. Make the selected Deployment Device be "Windows Mobile 6 Professional Device"

10. Press the Apply button if necessary to save your new selection

11. Under the configuration properties, highlight the Debugging section

12. For Remote Executable, enter \Storage Card\fennec\xulrunner\xulrunner.exe

13. For Command Arguments, enter ..\application.ini

14. Press the Apply button if necessary to save your new selection

15. Close the Project Properties dialog box

If your Visual Studio and ActiveSync and Windows Mobile 6 Professional SDK are properly installed, you are now ready to begin a debugging session within Visual Studio's IDE.

Press the F5 key to start debugging the XULRunner.exe Fennec application.

Setting Up MyBrowser Mini Browser

A simple XULRunner application, MyBrowser, can be used to test the XULRunner code.

Download the MyBrowser Application using this link.

The XULApp file is a ZIP file with a number of files and directories. Further explanation of XULRunner and the XULApp format can be found here. 

rename mybrowser-0.2.2.xulapp mybrowser-0.2.2.xulapp.zip

Unzip mybrowser-0.2.2.xulapp.zip into its own subdirectory, 
  while preserving it's ZIP file directory structure.  

rename mybrowser-0.2.2.xulapp mybrowser

Edit mybrowser\application.ini file, replacing:
  MaxVersion=1.8.0.*
with:
  MaxVersion=1.9.*.*

copy -r mybrowser c:\mozilla\unicode\objdir-wm6-debug\dist\bin
(or, rather, copy the mybrowser directory into the same directory that contains xulrunner.exe)


Setting Up a Project To Use For Debugging

The Visual Studio WinCE Shunt Library Project has been removed recently, so you will need to create a simple Visual Studio solution with which you can do debugging.

Here are the steps for creating a simple application within Visual Studio 2008 (a.k.a. Visual Studio 9). 

1. Start Visual Studio

2. Select File | New | Project

3. In the left hand window, select Visual C++ | Smart Device

4. Select Win32 Smart Device Project in the right hand window

5. Enter a project name (I use "DebugMC" as my project name)

6. Select some location - I keep the location on the same hard disk 
     partition as the mozilla-central source.

   NOTE: The location of your newly created project is not important.  
         Set the project location anywhere you like.

7. Click the Next button on the Win32 Smart Device Project Wizard to 
   move to the platform SDK selection page.

8. Using the '<' and '>' buttons, remove the Windows Mobile 5.0 platform SDK 
   and add the Windows Mobile 6 Professional SDK to the list of selected SDKs.

9. Press the Next button to move to the Project Settings page.

10. Keep all the default settings on the Project Settings page
    (or you may want to select Empty Project in Additional options).

11. Press the Finish button to create and open your new project


Setting Up Debugging of MyBrowser In Emulator

You can debug the MyBrowser XULapp from within Visual Studio by creating a simple Visual Studio Project, then adjusting the deployment device and executable to be run. 

1. Open Visual Studio 2005 (Visual Studio 8) Integrated Development Environment (IDE)

2. Open the solution you have created for use in debugging

3. In the Solution Explorer, right mouse click on the debugging project

4. Select the Properties pop-up menu item

5. Under the configuration properties, highlight the Deployment section

6. Make the selected Deployment Device be "Windows Mobile 6 Standard Emulator"

7. Press the Apply button if necessary to save your new selection

8. Under the configuration properties, highlight the Debugging section

9. For Remote Executable, enter \Storage Card\bin\xulrunner.exe

10. For Command Arguments, enter mybrowser\application.ini

11. Press the Apply button if necessary to save your new selection

12. Close the Project Properties dialog box


Actual Debugging In Emulator

You are now ready to begin debugging your XULRunner build. 

1. From the Visual Studio 2005 Build menu, select the Deploy Solution menu item

2. Wait for your chosen Emulator to start

3. In the Emulator's File menu, select the Configure... menu item

4. Press the ... button for the Shared Folder edit box

5. Select the c:\mozilla\unicode\objdir-wm6-debug\dist directory

6. Close the Emulator Properties dialog box by pressing the OK key

7. In the Visual Studio 2005's Debug menu, select the Start Debugging menu item

You should now see the Visual Studio begin a debugging session of XULRunner loading the MyBrowser XULApp.


Tips for Starting Debugging

There are two ways you can enter into a XULRunner/Fennec debugging session on Windows Mobile:

(1) Attach to a currently running XULRunner process. 

Go to the device (or emulator) and run the Fennec shortcut.  

Once XULRunner.exe is started, go to the Visual Studio, pull down the Tools menu
and select the attach to process menu item.

In the Attach to Process dialog, select the "Smart Device" transport, and select
the appropriate emulator image or device type.

Press the Browse button, and wait for the available process list to fill up.
Highlight the XULRunner process and press the Attach button.

(2) Start XULRunner.exe with the appropriate arguments from within Visual Studio 

Visual Studio will start debugging from application launch.
As there is nothing to build and deploy from VS itself, it makes sense to disable that.
Open "Project | Properties", click "Configuration Manager...", and uncheck Build and Deploy.


NOTE: The XULRunner.exe application will create a profile directory if one is not already created, and then may or may not immediately exit. If this happens, simply restart the XULRunner.exe application.

Retrieved from "https://wiki.mozilla.org/index.php?title=Mobile/Build/Windows_Mobile_DebuggingIt&oldid=162172"