Open Options -> Advanced -> General and click the "Make Firefox the default browser" button. This will open Windows Control Panel where you will need to select the channel build you are testing and set the defaults.

Desktop Launch

To launch within the metro experience follow the registration steps above. To launch the metro front end UI using the win32 widget backend on the desktop (including non-Windows-8 devices) use the -metrodesktop command line option:

(path to firefox build)/firefox.exe -metrodesktop

To set things up such that you can test touch input on the desktop - flip the 'metro.debug.treatmouseastouch' to true in /browser/metro/profile/metro.js.

Note on the desktop we use the desktop's Win32/Widget backend. This can behave differently from the Win8 WinRT backend. The translational layer for Win32 events is location in /browser/metro/content/base/input.js.

Running Desktop and Metro Simultaneously

It's possible to run desktop Firefox and Metro Firefox side-by-side by using different profiles. However, there are some problems caused by the fact that Metro Firefox will only use the default profile (bug 945511), and our startup code will always start in desktop mode if any desktop process is running (bug 945554).

Here's one way to keep desktop Firefox running while testing Metro Firefox in a separate profile:

Create a new profile named "desktop". (You can use Firefox Sync to keep this in sync with your default profile.)

Launch desktop Firefox by running firefox.exe -p desktop -no-remote. (You can create a shortcut to make this more convenient. Instructions for Windows 7+ here)

If you are making changes to the Metro Firefox source code, it's useful to start desktop Firefox from separate installation rather than your objdir, so you don't need to close it each time you rebuild.

Testing

Currently, some of the selection tests may fail (specifically, browser_selection_frame_textarea.js) if the device and CSS pixels are out of sync. To solve this, you may need to change the following pref in about:config to the following value.

JS Console

You can access the JavaScript console by typing Control-Shift-J. You can also set devtools.errorconsole.enabled to "true" in about:config to add an "Open error console" command to the menu button in the navigation bar.

Enable Add-ons

Add-ons are not yet enabled by default in Firefox for Metro, because we have not yet built the UI for users to enable/disable/install/remove add-ons. (We will do this in a future version.) For now, developers and testers can use the following steps to allow Metro Firefox to load add-ons:

Open Firefox for Metro.

Go to "about:config" and set "extensions.defaultProviders.enabled" to "true".

Restart Firefox for Metro.

You can then use Firefox for desktop to install, manage, and remove add-ons. The add-ons that you install in desktop will load in Metro Firefox if they are also marked compatible with the Metro UI. If you are an extension developer, you can make your add-on compatible with Metro Firefox by adding a targetApplication to your install.rdf file with "id" set to {99bceaaa-e3c6-48c1-b981-ef9b46b67d60}. (Metro Firefox will also load extensions with a targetApplication of toolkit@mozilla.org, which are compatible with all XUL applications.)

DOM Inspector

Follow these directions to make the DOM Inspector add-on work in Metro:

Follow the steps above to #Enable Add-ons and install DOM Inspector using Firefox for desktop.

Crash Testing

To test the Crash Reporter UI and other crash-related behavior, you can make use of install the Crash Me addon (sources are on Google Code.) This extension is already Metro Firefox ready, so you can install it using the steps in #Enable Add-ons above.

While in Metro mode, go to about:config and make sure both 'app.crashreporter.prompted' and 'app.crashreporter.autosubmit' preferences are set to false

Open the "Settings" charm and choose the "Crash Now" entry. Tap/click it to crash.

Restart Metro. You should see the crash dialog as shown here: screenshot

Remote Debugging with a VM

(This was last tested with the Win8 RP)

Setup steps -

create a new drive for vm, clone src there, build. obj dir should also be on this drive.

Enable sharing on the drive, set permissions to full access

On workstation, map vm share to a local drive. Use the same drive letter for both the vm drive and the mapped workstation drive!

config vm’s metro firefox as the default Metro browser

on vm, start – ‘debug’ should bring up remote debug tools folder – run the x64 version if on 64 bit os, x86 otherwise

That should be it. OutputDebugString output will land in the workstation debugger console. Breaking in the debugger doesn't kill the browser as long as metro is active and the browser is running in the foreground.

Note – AFAICT, you can’t reverse the relationship here. Metro will not launch a default browser located on a mapped drive that points to an obj dir on workstation. If we could fine a way around this it would be great.

Remote Debugging with a Tablet

Setup steps -

In Explorer on the tablet purge any unused space on C, including old Windows installation files, using the system file cleanup option under the drive's properties panel.

From Control Panel, bring up the disk manager and split the main disk partition into two. A 20GB partition for mozilla related bits is suitable.

Format the second partition and designate a drive letter for it. Use a drive letter your debugging workstation does not use.

Right-click the new mozilla drive in Explorer and select Share. Share the volume using your login credentials or you can also openly share to "Everyone" if your local network is secure. Set permissions on the share to full access.

On your main workstation browse to the tablet share and map it to a local drive using the same drive letter you used for the tablet drive. This insures object source has the same path info on both machines.

Install Visual Studio and mozilla-build on the tablet.

Checkout mozilla-central on the mozilla partition of the tablet, then build and register the browser.

On the tablet, Start + ‘debug’ should bring up a remote debug tools folder via search, open this and launch the remote debug monitor. Run the x64 version if on 64 bit os, x86 otherwise. (Pin this to your start menu for easy access.)

Under the monitor's tools menu, add permission for your login credentials or "Everyone" for remote debugging.

On the workstation, create a blank C++ debugging project for the tablet, set debug settings as follows:

After this you should be able to launch the browser on the tablet and attach to it from Visual Studio on your workstation. You should also be able to browse source on the networked drive, set break points, etc., just like a local debug session. Most debug output the browser spits out should be transferred over to the remote debugger.

Note you might have to fiddle with access permissions a bit. Opening everything up to Everyone saves a lot of time, but might not be the most secure environment, depending on your situation.

Diagnosing Launch Issues

The CEH handles program launch on Windows 8. It's a small win32 program that Explorer launches when the browser is invoked. If issues arise, there are some debugging features built into the program to help diagnose issues.

Open regedit.exe and browse to HKEY_CURRENT_USER/Software/Mozilla/Firefox

Testing Harness

Builds generate a test harness (dist/bin/metrotestharness.exe) that can be used to launch the metro browser into the immersive environment. This harness is also packed up with the test zips used in automation testing.

Metro Firefox can't accept standard command line parameters since it must be launched by Windows. The harness acts as a pass through for mozilla command line parameters firefox.exe can accept. Incoming params are written out to an ini file @ dist/bin and read in via nsBrowserApp when the browser starts up.

By default the test harness assumes the default browser (firefox.exe) is in the same folder metrotestharness.exe is located. If you want to launch the default browser at a different location from metrotestharness.exe, you must specify a firefox path using -firefoxpath (fullpath):

Using Devtools

I usually pair on localhost, using an external monitor so I can see metrofx & classicfx at the same time.

If you are using localhost without an external monitor, beware of windows suspending the metrofx while its waiting for the incoming connection. This will cause the pairing to fail. In Windows 8.1 you can use split-screen to keep the desktop and the Metro browser visible at the same time.

While you can pair classic/metrofx running out of the same obj dir, I frequently experienced unexpected hangs and crashes as a result.

if you close the devtools window, this usually results in the metro browser shutting down

Using DevTools Profiler

Follow all the set up instructions above to get the prefs set right for dev tools / remote debugging.

Note, by default this extension starts with profiling turned on (for the local build). The toolbar icon will be colored when profiling is active, grayed when off. It's best to keep this extension disabled when not in use.

In classic set the pref 'profiler.threads' and 'profiler.stackwalk' to true.

Restart classic

From the toolbar button dropdown, select TCP, enter the metro browser's ip address, and click connect. You should get a remote connection warning in the metro browser.

click the 'analyze' button and wait for the profile view to load. (This may take a while without updating the in tab ui. Give it time.)

After you have finishes collecting data, click 'stop' and wait for the button label to update from 'stop' to 'start'.

Profiling Local Builds

Profiles generated using the above config will have os symbols when working with nightly builds on the metro device. For profiling local builds, you'll need to follow these instructions on setting up and configuring a local snappy symbol server.

Development and Planning Notes

(Older content from the original planning stage)

This is summary of our work / planning for a Win8 Metro browser. For testing purposes we have been working with the /mobile/xul Fennec browser. Moving forward we would like to take the base Fennec XUL code and Metro specific code we've already developed (currently on Elm with some build related work already on mc) and integrate this in with the default Firefox build and install.

What’s different and what’s the same

By in large platform was a nice fit for Metro. We ran into surprisingly few problems. It took us about a week to get a basic version of Fennec running in the environment and most of that time was spent combing through the registration/integration doc Microsoft sent us. Below are some specific details on the areas of the repo we are currently leveraging.

Metro apps are single window applications. The current desktop UI does not fit this new environment. There are no secondary windows we create. Secondary UI (file pickers, warnings, message boxes, toasts) are all displayed and managed by the os. The interfaces to these features are also async. We will provide interfaces for invoking these. Some have already been integrated on Elm (file picker for example).

Due to the differences in view model most of /browser components code can’t be leveraged. Fennec's script based components are currently in use. [1]

The current metro browser leverages the Fennec front end app code but we could switch to firefox’s code base and enable / augment what we need for metro.

toolkit/xre (modest differences)

The app model is slightly different for Metro. UI events and rendering do not occur on the main thread. We have a working model implemented on Elm that breaks up parts of XRE_main so that certain parts (startup & run) can be called on a different ‘main’ thread.

There are significant differences in the view model so we needed a new nsWindow class. nsWindow latches into a new set of apis for events and view management. [2] Generally winrt and winapi code has integrated well together. We are currently leveraging Component Extensions and various winrt runtime classes. We will be able to share a great deal of win32 widget code.

On Windows8 the mechanics of launching the browser have changed. There is a new intermediary (a ‘command execute handler’) which is a small, light weight COM server Windows launches. This application chooses which browser to launch based on the environment requested. This change effects the launch of both browsers and the way we register as the default browser on Windows 8. [3] We currently have a basic Fennec install going for testing purposes, but it shouldn’t be too hard to move this over to the Firefox installer.

Pros and Cons

Con – larger Windows install regardless of what version of the os we install on. metrobrowser would be present on all Windows installs.

Con – builders / release eng. will have to upgrade to VC11 / Win8 SDK to do the build. For the time being however we have a build switch that enables win8 specific components, so we can start landing on mc without breaking existing desktop builds which leverage vc10 build tools. bug 737994

Pro/Con – With this setup we currently assume we will leverage xul lib. On the positive side having xul makes putting together our UI fast and easy. On the negative side startup performance may be an issue. We are working on getting telemetry data going so we can better measure this in the test builds we are distributing. Thus far test builds we have going on Samsung tablets and a few other test machines show promise on startup performance. Windows is obviously optimized for loading our libraries and the browsers we compete against all have the same encumbrance.

Big Issues

Profiles – Certain areas of the user’s profile will need to be shared between two concurrently running browser apps. We’ve just begun exploring ways to do this. Potential solution might involve a mysql database connection shim that leverages a profile broker and IPC so both browsers can talk to the same profile. We also might consider using Sync. There are some hurdles here to overcome. [A decision was made to use Sync initially.]

Accessibility - This area of the code base will be in heavy use in the Metro environment with touch interfaces. Our accessibility code will require performance work and may require a new UI Automation adapter since Win8 leverages UI Automation exclusively.

e10s - (khuey) Certain things are pretty much broken in e10s (e.g. IndexedDB) and other features have not received any testing in several months. Relying on e10s will likely require some investment in the platform to clean this up for metro/desktop parity. Not relying on e10s may decrease the amount of existing XUL Fennec code that can be reused. [question: (jimm) what's the difference in the amount of work we have to do? We've disabled remote tabs on elm for now to see what's broken.] [A decision was made to use in-process content for the foreseeable future.]

Extensions - currently extension support will be off until a suitable extension mechanism can be designed and implemented.