Firefox/Windows 8 Integration: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
(134 intermediate revisions by 12 users not shown)
Line 1: Line 1:
== Wiki ==
== Links ==


[https://wiki.mozilla.org/Firefox/Metro Metro Project] - meeting times, bug lists, project goals, team info, etc.  
* [[Firefox/Metro|Metro project page]] - meeting times, bug lists, project goals, team info, etc.
* [[Windows 8 Integration]] - General 3rd party browser collaboration page dedicated to overview, architecture, and challenges for vendors. Early research with Google.
* [[Firefox/Windows 8 Metro Style Guides]] - coding standards and UI guidelines
* [https://mail.mozilla.org/listinfo/metro Mailing list] - archive and subscription info for the metro@mozilla.org discussion list


[[Firefox/Features|General Firefox Product Feature Tracking]] - Firefox feature tracking.
== Getting Involved ==


[https://wiki.mozilla.org/Firefox_Metro_UI Firefox Metro UI wiki] - including comp work and UX bug tracking.
Contact Brian Bondy with questions (bbondy on [http://irc.mozilla.org IRC]). The Windows 8 integration team can be found in in #windev.


[[Windows8|Metro Project Status]] - not really in use.
=== Bugzilla ===


[[Windows_8_Integration]] - General 3rd party browser collaboration page dedicated to overview, architecture, and challenges for vendors. Early research with Google.
Please file front end bugs under the product [https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox%20for%20Metro Firefox for Metro]. Back end bugs should be filed in the appropriate Platform component.
 
== Desktop Development ==
 
[https://bugzilla.mozilla.org/buglist.cgi?resolution=---;op_sys=Windows%208;query_format=advanced;list_id=2566504 General Windows 8 bug list]
 
== Metro Development ==
 
[https://bugzilla.mozilla.org/buglist.cgi?status_whiteboard_type=notregexp;query_format=advancedresolution=---;op_sys=Windows%208%20Metro;list_id=3868779 Bug List] - all open "Windows 8 Metro" bugs
 
[https://bugzilla.mozilla.org/buglist.cgi?status_whiteboard_type=notregexp;query_format=advanced;status_whiteboard=completed-elm;resolution=---;op_sys=Windows%208%20Metro;list_id=3868779 Bug List] - all open "Windows 8 Metro" bugs minus 'completed-elm' white board tag
 
=== General Platform Integration ===
 
[https://bugzilla.mozilla.org/buglist.cgi?list_id=4351876;resolution=---;op_sys=Windows%208%20Metro;status_whiteboard_type=notregexp;query_format=advanced;product=Core;product=Toolkit;product=www.mozilla.org Platform Bug List] - Core, Toolkit, mozilla.org
 
[https://bugzilla.mozilla.org/buglist.cgi?list_id=4351876;resolution=---;op_sys=Windows%208%20Metro;status_whiteboard_type=notregexp;query_format=advanced;status_whiteboard=completed-elm;product=Core;product=Toolkit;product=www.mozilla.org Platform Bug List] - Core, Toolkit, mozilla.org minus 'completed-elm'
 
=== General Front End ===
 
[https://bugzilla.mozilla.org/buglist.cgi?list_id=4638979;resolution=---;op_sys=Windows%208%20Metro;query_format=advanced;product=Firefox;product=Firefox%20for%20Metro Front End Buglist]
 
[https://bugzilla.mozilla.org/buglist.cgi?list_id=4188841;resolution=---;op_sys=Windows%208%20Metro;status_whiteboard_type=notregexp;query_format=advanced;status_whiteboard=completed-elm;product=Firefox;product=Firefox%20for%20Metro Front End Buglist] - minus 'completed-elm'
 
=== Q3 Firefox Goals ===
 
[https://bugzilla.mozilla.org/buglist.cgi?quicksearch=sw%3Ametro-preview%20-sw%3Acompleted-elm;list_id=4454405 Tagged Bug List] - metro-preview tagged bugs minus completed-elm.
 
End of September: "Implement Firefox Metro UI preview: This preview will include primary browser UI for navigation and tabs and will be delivered as a combined classic+metro browser."
 
Important platform / build bugs:
 
* <strike>{{bug|755724}}</strike> - split dist/bin resources bug
* <strike>{{bug|737833}}</strike> - basic installer work on elm
* <strike>{{bug|779902}}</strike> - enable nightly metro builds on elm
* <strike>{{bug|782451}}</strike> - copy/paste fails for winrt backend
* <strike>{{bug|787786}}</strike> - UA string
* <strike>{{bug|771238}} / {{bug|785750}}</strike> - file picker freeze
 
=== Q4 Firefox Goals ===
 
* WinRT vc10 backport / Merge to mc
* TSF / Soft keyboard contexts
* OMTC / Pinch and Zoom
* Suspend / resume handling
* Local Sync
* Dual-mode scrollbars
* Immersive automated test support w/infrastructure
 
=== Q1 Firefox Goals ===
 
* Flash interop
* Accessibility / UIA interop
*
 
=== Sync specific ===
 
TBD - new plan based on recent Sync meetings. Need to update this.
 
Relying on the Sync service for syncing the metro profile with a default desktop profile presents various issues:
 
* simple sync setup - setting up a new sync account in both browsers is problematic. Device pairing will be troublesome between metro/desktop due to suspend issues. Potentially the installer could be used to do initial setup for both browsers. We could  also use a local connection or the registry to populate sync account info in both browsers.
* interprocess communication - when flipping back and forth between metro and the desktop, running instances need to know when they need to sync. {{bug|769424}}
* interprocess identification - the metro browser should communicate it's sync account id when signaling the default desktop browser to sync. {{bug|769424}}
* browser startup - AFAICT from testing, Firefox is configured to sync any new data on delayed startup, then recheck every 90 seconds. Need to confirm metrofx does the same. Assuming this is the default, missed interprocess events shouldn't be an issue.
* smarter interprocess signaling - when signaling another browser the signalee should be aware of whether data was actually updated before triggering events. {{bug|770298}}
* Sync service load - syncing regularly between two browsers will add considerable load on the sync service. TBD how serious this is and whether or not sync 2.0 apis can alleviate the problem.
* network reliance - we would like to avoid this down the road in some TBD way. The current test implementation using the Sync 1.0 service relies on the computer being connected to a network. {{bug|768638}}
* local sync -
** one possible solution would be to add support for importing/exporting changesets over a specific time period. Two clients using the same account could then share changesets rather than hitting the network. Data would be transmitted as json between processes. For security purposes clients would only import data associated with the same account (w/a check before the eval), and data should be obfuscated.
** another solution would be to use a local sync server run by one browser. How would this integrate with the networked sync service?
* mirroring - is there data that doesn't get mirrored between two clients? (deleting a bookmark for example) Mirroring between metrofx and the desktop browser should to be strict both browser should feel as if they are sharing the same profile.
* Sync 1.0 or 2.0 - the sync team has expressed the need for the use of sync 2.0 apis for metro integration. ETA of development.
 
[https://etherpad.mozilla.org/metro-sync Sync Team etherpad]
 
=== Plugin specific ===
 
* Flash: [https://github.com/mozilla/shumway Shumway]
* PDF: {{bug|771250}}
* General plugin support bug: {{bug|738600}}
 
=== Tests specific ===
 
Metro browser chrome tests can be run using 'make mochitest-metro-chrome' in the top level of the objdir, or './mach mochitest-metro' in the top level of the source repository.
 
Rel-Eng related tracking bugs for Win8 Classic and Metro work:
 
<bugzilla>
    {
        "id": "754399,731280"
    }
</bugzilla>


Metro testing:
===Blockers===


<bugzilla>
We are using the following whiteboard tags to track bugs that block our release with Firefox 28:
    {
        "id": "771271,759905,773817"
    }
</bugzilla>


=== Accessibility specific ===
* [beta28] - for bugs that must be fixed before Firefox 28 reaches the beta channel
* [release28] - for bugs that mut be fixed before Firefox 28 reaches the release channel


<bugzilla>
Queries:
    {
        "id": "778493,762769, 741750"
    }
</bugzilla>


[https://wiki.mozilla.org/Accessibility Accessibility Team wiki]<br>
* [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=ALL+sw:beta28,release28 all blockers]
{{bug|648121}} - Accessibility telemetry tracking bug
* [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=sw:beta28,release28+-sw:fixed-in-fx-team open blockers]
 
* [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=sw:beta28,release28+@nobody unassigned blockers]
== Getting Involved ==
* [http://mzl.la/1gU09QW blockers awaiting Beta nomination]
Contact Brian Bondy with questions (bbondy on [http://irc.mozilla.org IRC]). The Windows 8 integration team can be found in in #windev.
* [http://mzl.la/1ngxYJp blockers awaiting Beta landing]
 
=== Bugzilla ===
 
Please file front end bugs under the product [https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox%20for%20Metro Firefox for Metro]. Back end bugs should be filed in the appropriate Platform component.


=== Front End Windows 8 Development ===
=== Front End Windows 8 Development ===
Line 135: Line 35:
* Follow the steps in the Metro Builds section below to get setup
* Follow the steps in the Metro Builds section below to get setup
* The front end code is located in browser/metro
* The front end code is located in browser/metro
* You can find Windows 8 front end bugs here http://goo.gl/YQZiy or by doing an advanced bugzilla search for: OS = Windows 8 Metro, Product = Firefox, Component = General
* Style guidelines of all types can be found on https://wiki.mozilla.org/Firefox/Windows_8_Metro_Style_Guides


=== Platform Integration Windows 8 Development ===
=== Platform Integration Windows 8 Development ===


* To contribute to platform integration bugs, you will use: C++, C++/CX
* To contribute to platform integration bugs, you will use: C++
* You do need Windows 8 to work on the platform integration code
* You do need Windows 8 to work on the platform integration code
* You can obtain a 90 day free Windows 8 evaluation for developers from Microsoft
* You can obtain a 90 day free Windows 8 evaluation for developers from Microsoft
Line 146: Line 46:
* You can find Windows 8 platform integration bugs here http://goo.gl/B0Xjo or by doing an advanced bugzilla search for: OS = Windows 8 Metro, Product = Core, Component = Widget: Win32
* You can find Windows 8 platform integration bugs here http://goo.gl/B0Xjo or by doing an advanced bugzilla search for: OS = Windows 8 Metro, Product = Core, Component = Widget: Win32


== Metro Builds ==
== Firefox for Windows 8 Builds ==


=== Elm Nightly Builds ===
Firefox for Windows 8 is currently included in Nightly, Aurora, and Beta builds of Firefox for Windows. It will reach the release channel with Firefox 28 around March 17th, 2014.


Nightly builds off the Elm repository where metro development is taking place are currently available in the [http://ftp.mozilla.org/pub/mozilla.org/firefox/nightly/latest-elm/ Firefox build archives].
For more detailed help on installing / setting the browser as the default, visit the [https://support.mozilla.org/en-US/kb/how-do-i-install-windows-8-metro-style-firefox Metro Firefox support page].


To set these builds up:
=== Browser Crash Reports ===


* Install the browser using the latest installer
[https://crash-stats.mozilla.com/home/products/MetroFirefox Firefox for Metro crash stats]
* Open the desktop browser - when the default browser check occurs, select yes to set Firefox as the default. You should also receive a Windows prompt, select Nightly. This will associate Firefox with various protocol handlers and create the Firefox tile.
* To set file handler associations use Window's Control Panel for default program associations. (Options -> Advanced -> General and click the default browser button at the bottom to open this panel.) 
 
For the time being, <strong>only the desktop browser can do browser updates</strong> to new builds ({{bug|794936}}, {{bug|794937}}). If prompted to update, make sure to shut the metro browser down first to allow the update to complete.
 
=== Nightly Crash Reports ===
 
[https://crash-stats.mozilla.com/query/query?product=MetroFirefox&version=ALL%3AALL&do_query=1&range_value=2&range_unit=weeks Previous two weeks]


=== Switching Default Browsers ===
=== Switching Default Browsers ===
Line 178: Line 70:
Note pinned taskbar shortcuts can't be trusted to open the right browser.
Note pinned taskbar shortcuts can't be trusted to open the right browser.


=== Elm Zip Builds ===
=== Zip Builds ===
 
Zip installs from daily checkins are currently available on the [http://ftp.mozilla.org/pub/mozilla.org/firefox/nightly/latest-mozilla-central/ Firefox build archives].


Zip installs from daily checkins are currently available on the [http://ftp.mozilla.org/pub/mozilla.org/firefox/tinderbox-builds/elm-win32-metro/ metro builder archives]. Note these are not nightlies, they do not self update. To install:
To install:


* Download the newest firefox-18.0a1.en-US.win32.zip to your Win8 device
* Download the newest firefox-(rev).0a1.en-US.win32.zip to your Win8 device
* Unpack the main firefox folder to a suitable location
* Unpack the main firefox folder to a suitable location
* Run firefox.exe
* Run firefox.exe on the desktop
* Set Metro Firefox as the default browser through Firefox preferences, which launches Control Panel -> Default Programs
* If prompted by Windows, select Nightly/Aurora/Firefox as the default.
 
* 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.
==== Elm Symbols ====
 
(Obsolete - dep build symbols no longer uploaded. Use Nightly builds for debugging w/symbols.)
 
Win8 Metro builders <strong>do not</strong> upload dep build symbols to the symbol server. However they do upload full symbol packages to the [http://ftp.mozilla.org/pub/mozilla.org/firefox/tinderbox-builds/elm-win32-metro/ metro builder archives]. For debugging zip builds using pdbs, download the full symbols package, unzip to a suitable folder, and unpack the pdbs using the shell command below in the root of the folder. Then add this folder location to the debugging -> symbols paths in Visual Studio under the Tools menu.
 
<pre>find . -name "*.pd_"  | while read FILENAME; do expand -r $FILENAME; done</pre>


=== Building Locally ===
=== Building Locally ===


Updated 10/31/2012
Updated 5/21/2013


* Install Visual Studio 2010 or 2012.
* Install Visual Studio 2010 or 2012.
* Install [https://developer.mozilla.org/en-US/docs/Developer_Guide/Build_Instructions/Windows_Prerequisites MozillaBuild]
* Install [https://developer.mozilla.org/en-US/docs/Developer_Guide/Build_Instructions/Windows_Prerequisites MozillaBuild] (version 1.7 required)
* Install the [http://msdn.microsoft.com/en-us/windows/desktop/hh852363.aspx Windows 8.0 SDK]
* Install the [http://msdn.microsoft.com/en-us/windows/desktop/hh852363.aspx Windows 8.0 SDK]
* Install [http://www.microsoft.com/en-us/download/confirmation.aspx?id=6812 DirectX SDK (June 2010)]


: For VS 2010/8.0 SDK builds, update to the latest start-msvc2010 batch script from [https://hg.mozilla.org/mozilla-build/summary mozilla-build repo].
* For VC 2010 builds:
: For VS2012 builds, use the current start-msvc2011 batch scripts distributed with MozillaBuild.
** Modify the the following header in the sdk:
 
* Modify the the following header in the sdk:
 
<pre>
<pre>
C:\Program Files (x86)\Windows Kits\8.0\Include\winrt\asyncinfo.h
C:\Program Files (x86)\Windows Kits\8.0\Include\winrt\asyncinfo.h
Line 220: Line 105:
</pre>
</pre>


* Check out Elm.  Make sure the obj directory has "Modify" permissions given to the current user.
If you use both VC 2010 and VC 2012 (or plan to install VC 2012 in the near future) you might want to instead use the following patch, which reverts to the original code under VC 2012 and later:
<pre>
--- asyncinfo.h.orig 2013-05-21 08:47:49 -0400
+++ asyncinfo.h 2013-05-21 08:48:55 -0400
@@ -58,17 +58,21 @@
/* interface __MIDL_itf_asyncinfo_0000_0000 */
/* [local] */
//  Microsoft Windows
//  Copyright (c) Microsoft Corporation. All rights reserved.
#pragma once
#ifdef __cplusplus
namespace ABI { namespace Windows { namespace Foundation {
+#if defined (_MSC_VER) && _MSC_VER >= 1700
enum class AsyncStatus {
+#else
+enum AsyncStatus {
+#endif
  Started = 0,
  Completed,
  Canceled,
  Error,
};
} } } // ABI::Windows:::Foundation
using ABI::Windows::Foundation::AsyncStatus;
#ifndef _HIDE_GLOBAL_ASYNC_STATUS
</pre>
 
* For Express versions of VS:
** Install [http://www.microsoft.com/en-us/download/details.aspx?id=11800 the Windows Driver Toolkit, version 7.1.0] - Version 7.1.0 is needed because it contains the necessary ATL headers that express VS lacks.
** Add the following to start-msvc*.bat file near the end just before the line that reads cd "%USERPROFILE%" (assumes WinDDK was installed in "C:\WinDDK\7600.16385.1"):
<pre>
set "INCLUDE=C:\WinDDK\7600.16385.1\inc\atl71;%INCLUDE%"
set "LIB=C:\WinDDK\7600.16385.1\lib\ATL\i386;%LIB%"
</pre>
 
* [https://developer.mozilla.org/en-US/docs/Simple_Firefox_build#Get_the_source Check out mozilla-central].  Make sure the obj directory has "Modify" permissions given to the current user.
* Create a standard browser .mozconfig file with the options you prefer and add
* Create a standard browser .mozconfig file with the options you prefer and add


Line 227: Line 148:
</pre>
</pre>


* Config and build Elm
* [https://developer.mozilla.org/en-US/docs/Simple_Firefox_build#Building Build Firefox].


At this point, you should be able to launch the metro browser on the desktop using a command line switch:
At this point, you should be able to launch the metro browser on the desktop using a command line switch:


<pre>
<pre>
(obj)/dist/bin/firefox.exe -metrodesktop
./mach run -metrodesktop
</pre>
</pre>


To register local builds as the default browser:
To run in the real "immersive" (full-screen) Metro environment, first launch the desktop browser by typing:


* For debug builds: run the resulting firefox.exe on the desktop and set as the default through Options menu -> Advanced -> General tab -> Make default button.
<pre>
* For release builds: run the resulting firefox.exe on the desktop and click yes to the default settings dialog, then select 'Nightly' in the Windows 8 prompt.
./mach run
* Open up Control Panel -> Default Programs. You should see 'Metro Firefox' in the list of applications.
</pre>
* Set all Metro Firefox defaults in Default Programs.


At which point you should have a Firefox tile in Win8 that launches the browser.
Then press the "Relaunch in Windows 8 Touch" button in the menu to switch to Metro mode.  See [https://support.mozilla.org/en-US/kb/how-do-i-install-windows-8-metro-style-firefox#w_step-2-launch-windows-8-metro-style-firefox this support page] for details.


Note, for debug builds, see [[Windows_8_Integration#Logging_Assertions]].
Note, for debug builds, see [[Firefox/Windows_8_Integration#Logging_Assertions]].


=== Desktop Launch ===
=== Desktop Launch ===
Line 255: Line 175:


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.
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:
# [https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles 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 <code>firefox.exe -p desktop -no-remote</code>.  (You can create a [http://kb.mozillazine.org/Shortcut_to_a_specific_profile shortcut] to make this more convenient. Instructions for Windows 7+ [http://lifehacker.com/5475752/customize-pinned-shortcuts-on-the-windows-7-taskbar 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.
# To launch Metro Firefox, run <code>firefox.exe -no-remote</code> (or <code>./mach run</code>) and then press the ''Windows 8 Touch'' menu button.
#* Or you can launch the Metro UI in a desktop window by running <code>firefox.exe -no-remote -metrodesktop</code> (or <code>./mach run -metrodesktop</code>).
# Use alt-tab or edge/corner gestures to switch between the Metro app and the desktop.


=== Testing ===
=== Testing ===
Line 260: Line 193:
[https://developer.mozilla.org/en-US/docs/Browser_chrome_tests Browser-chrome tests] for Metro Firefox are located in [http://hg.mozilla.org/projects/elm/file/default/browser/metro/base/tests/ browser/metro/base/tests].  The tests run in the Metro environment; Windows 8 is required.
[https://developer.mozilla.org/en-US/docs/Browser_chrome_tests Browser-chrome tests] for Metro Firefox are located in [http://hg.mozilla.org/projects/elm/file/default/browser/metro/base/tests/ browser/metro/base/tests].  The tests run in the Metro environment; Windows 8 is required.


To start the tests, run the following command in the mozilla-build shell, at the top level of your obj-dir:
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.


  make mochitest-metro-chrome
  layout.css.devPixelsPerPx = 1.0 (default is -1.0, which makes Firefox autoscale CSS pixels)
 
To run all the tests, run the following [[mach]] command in the mozilla-build shell in your mozilla-central source directory:
 
./mach mochitest-metro
To run a single test file or directory,
 
./mach mochitest-metro path/to/test/file.js


The Metro browser will launch, run the tests and exit.  Any failures will be printed to the console.  The complete test log will be written to the file <code>mochitest-metro-chrome.log</code> in the objdir.
The Metro browser will launch, run the tests and exit.  Any failures will be printed to the console.  The complete test log will be written to the file <code>mochitest-metro-chrome.log</code> in the objdir.
We have a library of convenience functions for use in metro-chrome tests, which you can find in '''[http://dxr.mozilla.org/mozilla-central/source/browser/metro/base/tests/mochitest/head.js head.js]'''.  Note: These tests make heavy use of Promises and [https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Task.jsm Task.jsm].


=== Building on Linux or Mac OS X ===
=== Building on Linux or Mac OS X ===
'''This configuration is not official supported or tested.'''  It might break without anyone noticing for a while.  If it doesn't work, let us know and we can help fix it.


You can use the ''--enable-metro'' configure option and the ''-metrodesktop'' command-line flag to build and run the Metro UI on other platforms too.  For details, see [http://limpet.net/mbrubeck/2012/09/19/metro-firefox-without-windows.html Metro Firefox without Windows 8].
You can use the ''--enable-metro'' configure option and the ''-metrodesktop'' command-line flag to build and run the Metro UI on other platforms too.  For details, see [http://limpet.net/mbrubeck/2012/09/19/metro-firefox-without-windows.html Metro Firefox without Windows 8].
On Mac, you might need to run "./mach build browser" after your build completes.  For details, see {{bug|847807}}.
* there is a problem with html5 EMBED tag. '''an EMBED tag is basically to play media files.''' but we can't use this on mac.


=== Logging Assertions ===
=== Logging Assertions ===


When you're running Metro Firefox with --enable-debug, there will be assertion failure messages that pop up.  Because they appear on the desktop and block the UI, they will make the Metro UI appear to hang until you dismiss them on the desktop. You can set the following environment variable to ensure that they're logged rather than displayed as popups:
When you're running Metro Firefox with --enable-debug, there will be assertion failure messages that show up in the console. The following environment variable is assumed for the Metro environment:


<pre>
<pre>
XPCOM_DEBUG_BREAK=warn
XPCOM_DEBUG_BREAK=warn
</pre>
</pre>
Set up steps:
* From the start screen, type "advanced settings"
* Open View Advanced System Settings
* Click the "Environment Variables" button
* Add the user variable "XPCOM_DEBUG_BREAK" with value "warn"


=== Remote Debug Output ===
=== Remote Debug Output ===
Line 301: Line 243:
<strike>{{bug|762519}}</strike> was filed on getting javascript's dump output going to OutputDebugString as well.
<strike>{{bug|762519}}</strike> was filed on getting javascript's dump output going to OutputDebugString as well.


=== DOM Inspector ===
=== JS Console ===


Getting DOM Inspector attached to builds running on the desktop takes a few tweaks.  
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.
* Install the dom inspector addon (if you do not have it already) on your desktop firefox
* Copy the 'inspector@mozilla.org' folder under your Firefox profile's extension directory over to your MetroFirefox profile extensions directory. (Example: C:\Users\Brian\AppData\Roaming\Mozilla\MetroFirefox\Profiles\amrcb8eg.default\extensions)
* add an entry in inspector's install.rdf file for metrofx and make sure the maxVersion is set correctly.


<pre>
=== Enable Add-ons ===
<em:targetApplication>
  <Description>
    <em:id>{99bceaaa-e3c6-48c1-b981-ef9b46b67d60}</em:id>
    <em:minVersion>1.0a1</em:minVersion>
    <em:maxVersion>19.0a1</em:maxVersion>
  </Description>
</em:targetApplication>
</pre>
 
* Add the [https://developer.mozilla.org/en/XULRunner_tips startDOMi function] to /browser/metro/base/content/browser.js.
* Add a call to startDOMi() below the BrowserUI.init() call.
* Tweak the following extension prefs in metro.js:
<pre>
pref("extensions.autoDisableScopes", 15);
pref("extensions.minCompatibleAppVersion", "4.0");
pref("extensions.strictCompatibility", false);
</pre>


* The extensions.sqlite database file will be created the first time MetroFirefox is run and discovers the inspector@mozilla.org extension content in the profile, but you have to flip a couple of values to make it actually work. Using your favorite sqlite tool (the [https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/ SQLite Manager Add-on] works), find the inspector's entry in the 'addon' table and set the 'active' field to integer 1, and the userDisabled field to integer value 0.
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:


=== Venkman Debugger ===
* Open Firefox for Metro.
* Go to "about:config" and set "extensions.defaultProviders.enabled" to "true".
* Restart Firefox for Metro.


(10/5/12 - Note, since we've changed the app id, this probably doesn't work.)
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.)


* Copy the '{f13b157f-b174-47e7-a34d-4815ddfdfeb8}' xpi under your Firefox profile's extension directory over to your MetroFirefox profile extensions directory.
=== DOM Inspector ===


* Launch the browser with the '-venkman' command line option.
Follow these directions to make the [https://addons.mozilla.org/en-US/firefox/addon/dom-inspector-6622/ DOM Inspector] add-on work in Metro:


=== JS Shell ===
* Follow the steps above to [[#Enable Add-ons]] and install DOM Inspector using Firefox for desktop.
* Add the [https://developer.mozilla.org/en/XULRunner_tips startDOMi function] to /browser/metro/base/content/browser.js.


For debugging the ede js shell and javascript console are available on the app bar in desktop builds.
=== Crash Testing ===


=== WinRT Compiler Generated Code ===
To test the Crash Reporter UI and other crash-related behavior, you can make use of install the [http://people.mozilla.com/~tmielczarek/crashme/ Crash Me addon] (sources are on [http://code.google.com/p/crashme/ Google Code].) This extension is already Metro Firefox ready, so you can install it using the steps in [[#Enable Add-ons]] above.


Compiler switches:
* While in Metro mode, go to about:config and make sure both 'app.crashreporter.prompted' and 'app.crashreporter.autosubmit' preferences are set to false
* /d1ZWtokens - dump C++ code generated code for C++/CX.  
* Open the "Settings" charm and choose the "Crash Now" entry.  Tap/click it to crash.
* /d1reportAllClassLayout - dump class layouts
* Restart Metro. You should see the crash dialog as shown here: [https://bug903426.bugzilla.mozilla.org/attachment.cgi?id=8343538 screenshot]
* /d1reportSingleClassLayoutXXX - where XXX performs substring matches against the class name.


=== Remote Debugging with a VM ===
=== Remote Debugging with a VM ===
Line 377: Line 301:
Setup steps -
Setup steps -


* Install Win8 on the tablet, use the same login/password you use on the workstation you'll be debugging from.
* 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 Explorer 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.
* From Control Panel, bring up the disk manager and split the main partition into two. A 80GB/20GB split is suitable.
* Format the second partition and designate a drive letter for it. Use a drive letter your debugging workstation does not use.
* Format the second partition and designate a drive letter for it. Use a drive letter your main workstation doesn't 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.
* Right-click the new drive in Explorer and select Share. Share this volume for your login credentials, you can also openly share it 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.
* On your main workstation, map the tablet share to a local drive. Use the same drive letter for both the tablet drive and the mapped workstation drive. This insures object source has the same path info.
* Install Visual Studio and mozilla-build on the tablet.
* Checkout Elm on the second drive of the tablet, build and register the browser.
* Checkout mozilla-central on the mozilla partition of the tablet, then build and register the browser.
* On the tablet, Start + ‘debug’ should bring up remote debug tools folder – run the x64 version if on 64 bit os, x86 otherwise.
* 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.)
* On the workstation, create a debugging project for the tablet, set debug settings as follows:
* 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:
** Remote command: (common  letter drive):\(path to obj dir)\dist\bin\firefox.exe
** Remote command: (common  letter drive):\(path to obj dir)\dist\bin\firefox.exe
** Working dir – same
** Working dir – same
Line 391: Line 316:
** Attach: Yes
** Attach: Yes


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.
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
* Add a new DWORD value names 'CEHDump', value 01
* Run a debug output viewer such as [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx DebugView].
* Launch the browser.
 
Output from the ceh and launch info from the browser will get dumped to DebugView. You can save this logging info out via the DebugView file menu and post it to bugs for diagnosis.
 
To turn off debug output for the CEH, change the registry value from 01 to 00, or delete the CEHDump key.
 
=== Localized Build ===
 
Language Pack extensions are not yet enabled by default in Firefox for Metro, but you can use l10n binary repack method described [https://developer.mozilla.org/en/docs/Creating_a_Language_Pack here] to get localized build.
 
To create localized binary repack for ''x-testing'' locale that is based on current sources from Mozilla Central create package locally via [https://developer.mozilla.org/en-US/docs/pymake Pymake] instead of downloading it from Mozilla's ftp servers.
 
<pre>
$ cd ../firefox-build
$ pymake package
$ cd ../firefox-build/browser/locales
$ pymake unpack
$ pymake merge-x-testing LOCALE_MERGEDIR=$(PWD)/mergedir
$ pymake installers-x-testing LOCALE_MERGEDIR=$(PWD)/mergedir
</pre>


== Hardware ==
Your localized repack will be available at ''../firefox-build/dist'' folder.


[https://docs.google.com/spreadsheet/ccc?key=0AowtJTCuyojddHpMeDV5czhDMkU0bFBKTktQLUhkbnc Asa's Google Docs list of Win8 touch friendly hardware]
Appropriate l10n sources (to use with --with-l10n-base parameter in .mozconfig) can be downloaded from the following locations:


== Samsung Series 7 ==
* [http://hg.mozilla.org/l10n-central/ http://hg.mozilla.org/l10n-central/x-testing]
* [http://hg.mozilla.org/releases/l10n/mozilla-aurora/ http://hg.mozilla.org/releases/l10n/mozilla-aurora/x-testing]
* [http://hg.mozilla.org/releases/l10n/mozilla-beta/ http://hg.mozilla.org/releases/l10n/mozilla-beta/x-testing]
* [http://hg.mozilla.org/releases/l10n/mozilla-release/ http://hg.mozilla.org/releases/l10n/mozilla-release/x-testing]


The Series seven is the first device we started developing with. Details below on getting the hardware set up with Windows 8.
Please note that you may need to install [https://developer.mozilla.org/en/docs/Compare-locales compare-locale] python script to successfully perform merge locale step.


* To order, file a bug under mozilla.org, Server Operations: Desktop Issues. See {{bug|738613}}, CC your PM or Asa.
== Testing Harness ==


* Once you have the tablet, dock, and keyboard, unpack. Charge up the device. It'll be running Win7, ignore all the default software.
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.


* Download the 64-bit (3.6 gig) Win8 ISO from \\fs2\IT\Microsoft. Add your name to the list of people who will need product keys in {{bug|783811}}. Burn the ISO to a suitable memory stick. For burning on Windows you'll need to download and install the [http://www.microsoftstore.com/store/msstore/html/pbPage.Help_Win7_usbdvd_dwnTool Windows 7 USB DVD Download Tool] from Microsoft. For burning on mac?
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 [http://mxr.mozilla.org/mozilla-central/source/browser/app/nsBrowserApp.cpp nsBrowserApp] when the browser starts up.


* Once you have the ISO burned, plug the USB stick into the tablet's dock. Browse to the USB drive and run "setup.exe". When prompted choose that you want to save nothing from the previous install.
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):


* Samsung provides an instruction manual on hooking up the Bluetooth keyboard. You can do this after you've installed Win8 as the Win7 desktop instructions are applicable on Win8 desktop.
<pre>metrotestharness.exe -firefoxpath T:\Mozilla\objmcrel\dist\bin\ -url www.mozilla.org</pre>


* After the tablet is set up, download Firefox nightly or build a local copy and start debugging!
The test harness will need *write* permission to this location to write out a command line arg ini file.


=== Firmware Updates ===
[http://mxr.mozilla.org/mozilla-central/source/browser/metro/shell/testing/metrotestharness.cpp harness source]


For more precise touch input, especially with tap and hold, install the "Touch Screen Sensor Firmware Configuration Updater Tool". Updating the system bios from 7 to 10 doesn't hurt either. Make sure to reboot the system after the install.
== Using Devtools ==


[http://www.samsung.com/global/windowspreview/ Samsung Link]
See [https://developer.mozilla.org/en-US/docs/Tools/Remote_Debugging/Firefox_for_Metro Remotely debugging Firefox for Metro] on MDN for instructions.


=== Samsung Series 7 Tweaks ===
Notes:


* To fix auto changing brightness problems for wipe Win8 installs:
* I usually pair on localhost, using an external monitor so I can see metrofx & classicfx at the same time.
** Open desktop
* 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.
** click/tap on the battery icon in the taskbar, select "More power options"
* While you can pair classic/metrofx running out of the same obj dir, I frequently experienced unexpected hangs and crashes as a result.
** Select your current power plan or create a new plan via the link on the left.
* if you close the devtools window, this usually results in the metro browser shutting down
** Under the power plan select "Change advanced power settings"
** scroll down to "Display" and expand
** Find the sub-option "Enable adaptive brightness" and expand
** disable both options under this sub-option


== Metro Planning ==
=== Using DevTools Profiler ===
 
* Follow all the set up instructions above to get the prefs set right for dev tools / remote debugging.
* In classic install the profiler extension from: https://github.com/bgirard/Gecko-Profiler-Addon/raw/master/geckoprofiler.xpi
** 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'.
 
For additional detail read {{bug|886555}} on getting things going.
 
For reference: [https://developer.mozilla.org/en-US/docs/Performance/Profiling_with_the_Built-in_Profiler Profiler Wiki].
 
=== 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 [https://developer.mozilla.org/en-US/docs/Performance/Profiling_with_the_Built-in_Profiler_and_Local_Symbols_on_Windows these instructions] on setting up and configuring a local snappy symbol server.
 
Example snappy symbol server config:
<pre>
[General]
hostname = 127.0.0.1
portNumber = 8000
enableTracing = 1
remoteSymbolServer = http://symbolapi.mozilla.org:80/
maxCacheEntries = 20000000
prefetchInterval = 12
prefetchThreshold = 48
prefetchMaxSymbolsPerLib = 500
defaultApp = Firefox
defaultOs = Windows
 
[SymbolPaths]
Firefox = T:\Mozilla\MC-REL\dist\crashreporter-symbols\
Windows = T:\Temp
</pre>
 
If you run into problems resolving xul symbols, try restarting the symbol server and generating a new profile. Also make sure prefetchMaxSymbolsPerLib in the ini is set to a large value.
 
Note, for switching back to nightly profiling, set the default symbol server url in classic back to http://symbolapi.mozilla.org/.
 
== Development and Planning Notes ==


(Older content from the original planning stage)
(Older content from the original planning stage)
Line 436: Line 432:
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.  
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.  


We are interested in getting as much feedback as possible from stake holders and from people who have worked with these newer platforms. If you have Win8 up and running in a vm or on a test system, there are details here on how to get builds going, how to register the browser, and test builds for installing.
* [https://bugzilla.mozilla.org/buglist.cgi?resolution=---;op_sys=Windows%208%20Metro;query_format=advanced;list_id=2566518 Metro specific bug list]
* [http://piercedotzler.com/asa/Developing_a_Metro-Style_Enabled_Desktop_Browser.html#_Toc318127097 Developing Metro Style Enabled Desktop Browsers]
* [http://piercedotzler.com/asa/Developing_a_Metro-Style_Enabled_Desktop_Browser.html#_Toc318127097 Developing Metro Style Enabled Desktop Browsers]


Line 444: Line 437:


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.
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.
<strong>nsBrowserApp</strong>
<strike>Currently using fennec’s nsBrowserApp.</strike>
<strong>chrome interface markup and css</strong> (different)


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).
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).


<strong>browser comps</strong> (different)
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. [http://mxr.mozilla.org/mozilla-central/source/browser/metro/components/]
 
<strong>dictionaries, hyphenation, res, searchplugins, extensions, plugins</strong> (shared)
 
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. [http://mxr.mozilla.org/mozilla-central/source/mobile/xul/components/]


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.
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.
Line 479: Line 462:
Generally we’re currently leveraging a majority of our common code base without issue. Threading, timers, networking, ssl, layout, gfx, etc. have all fit in really well. Misc. detail -  
Generally we’re currently leveraging a majority of our common code base without issue. Threading, timers, networking, ssl, layout, gfx, etc. have all fit in really well. Misc. detail -  


* gfx - not currently using accelerated layers but plan to in the near future. The surface rendered to in Metro is D2D and there is no GDI fallback. As such there are some issues with blacklisted hardware.
* gfx - The surface rendered to in Metro is D2D and there is no GDI fallback. As such there are some issues with blacklisted hardware.
* e10s - currently using Fennec’s out of process tabs.
* e10s - Currently using in-process content (no child processes).
* Accessibility - not integrated yet.
* Accessibility - not integrated yet.
* Netwerk - no issues.
* Netwerk - no issues.
Line 489: Line 472:
* toolkit - very little of this is in use. Crash reporter UI will need work/integration.
* toolkit - very little of this is in use. Crash reporter UI will need work/integration.
* xpcom - no issues.
* xpcom - no issues.
=== A tentative proposal ===
* Copy mobile/xul code down to browser level in /browser/metro.
* Integrate metro startup into firefox's nsBrowserApp {{bug|747347}}.
* Integrate building this new area into the current desktop firefox build. {{bug|747347}}
* Fixup the firefox installer so that we bring both browsers down in a single unified windows install. {{bug|737833}}
* Share the runtime between the two apps in the install. <strong>[completed]</strong>
* Have nsBrowserApp communicate to xul lib what environment we are running in. <strong>[completed]</strong>
* Dynamically switch out which code path we want in xul lib where necessary. <strong>[completed]</strong>
* Organize dist interface code and browser comps such that desktop firefox install layout remains unchanged. Layer metro specific resources down in such a way that the two sets of resources do not conflict. {{bug|755724}}
* <strike>Share a single profile between both browsers</strike> or Sync two profiles on the same machine.
Elm to mozilla-central migration tracking bug: {{bug|747347}}


==== Pros and Cons ====
==== Pros and Cons ====
Line 516: Line 485:
=== Big Issues ===
=== Big Issues ===


* Windows XP - The current VC11 Beta redist runtime is not compatible with XP. ({{bug|744942}})
* Windows XP - The current VC11 Beta redist runtime is not compatible with XP. (<strike>{{bug|744942}}</strike> - FIXED)
* 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. <strong>[A decision was made to use Sync initially.]</strong>
* 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. <strong>[A decision was made to use Sync initially.]</strong>
* 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.
* 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.

Latest revision as of 22:26, 19 February 2014

Links

Getting Involved

Contact Brian Bondy with questions (bbondy on IRC). The Windows 8 integration team can be found in in #windev.

Bugzilla

Please file front end bugs under the product Firefox for Metro. Back end bugs should be filed in the appropriate Platform component.

Blockers

We are using the following whiteboard tags to track bugs that block our release with Firefox 28:

  • [beta28] - for bugs that must be fixed before Firefox 28 reaches the beta channel
  • [release28] - for bugs that mut be fixed before Firefox 28 reaches the release channel

Queries:

Front End Windows 8 Development

  • To contribute to front end bugs, you will use: JS, CSS, XUL, XBL
  • You do not actually need Windows 8 to work on the front end code
  • Follow the steps in the Metro Builds section below to get setup
  • The front end code is located in browser/metro
  • Style guidelines of all types can be found on https://wiki.mozilla.org/Firefox/Windows_8_Metro_Style_Guides

Platform Integration Windows 8 Development

  • To contribute to platform integration bugs, you will use: C++
  • You do need Windows 8 to work on the platform integration code
  • You can obtain a 90 day free Windows 8 evaluation for developers from Microsoft
  • Follow the steps in the Metro Builds section below to get setup
  • The platform integration code is located in widget/windows/winrt
  • You can find Windows 8 platform integration bugs here http://goo.gl/B0Xjo or by doing an advanced bugzilla search for: OS = Windows 8 Metro, Product = Core, Component = Widget: Win32

Firefox for Windows 8 Builds

Firefox for Windows 8 is currently included in Nightly, Aurora, and Beta builds of Firefox for Windows. It will reach the release channel with Firefox 28 around March 17th, 2014.

For more detailed help on installing / setting the browser as the default, visit the Metro Firefox support page.

Browser Crash Reports

Firefox for Metro crash stats

Switching Default Browsers

This can be a little tedious when working with multiple builds / installs on a single device. Steps:

  • Close Firefox both in Metro and on Desktop
  • Open Control Panel's default programs and set IE as the default
  • With debug builds: run the resulting firefox.exe on the desktop and set as the default through Options menu -> Advanced -> General tab -> Make default button.
  • For release builds: run the resulting firefox.exe on the desktop and click yes to the default settings dialog, then select 'Nightly' in the Windows 8 prompt.
  • In Control Panel's default programs, set firefox as the default browser.

To confirm the right browser is set, launch the browser in Metro, switch to desktop, open task manager, right-click the Firefox process, and select open file location.

Note pinned taskbar shortcuts can't be trusted to open the right browser.

Zip Builds

Zip installs from daily checkins are currently available on the Firefox build archives.

To install:

  • Download the newest firefox-(rev).0a1.en-US.win32.zip to your Win8 device
  • Unpack the main firefox folder to a suitable location
  • Run firefox.exe on the desktop
  • If prompted by Windows, select Nightly/Aurora/Firefox as the default.
  • 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.

Building Locally

Updated 5/21/2013

  • For VC 2010 builds:
    • Modify the the following header in the sdk:
C:\Program Files (x86)\Windows Kits\8.0\Include\winrt\asyncinfo.h

line 67:

enum class AsyncStatus {

to

enum /*class*/ AsyncStatus {

If you use both VC 2010 and VC 2012 (or plan to install VC 2012 in the near future) you might want to instead use the following patch, which reverts to the original code under VC 2012 and later:

--- asyncinfo.h.orig	2013-05-21 08:47:49 -0400
+++ asyncinfo.h	2013-05-21 08:48:55 -0400
@@ -58,17 +58,21 @@
 /* interface __MIDL_itf_asyncinfo_0000_0000 */
 /* [local] */ 
 
 //  Microsoft Windows
 //  Copyright (c) Microsoft Corporation. All rights reserved.
 #pragma once
 #ifdef __cplusplus
 namespace ABI { namespace Windows { namespace Foundation {
+#if defined (_MSC_VER) && _MSC_VER >= 1700
 enum class AsyncStatus {
+#else
+enum AsyncStatus {
+#endif
   Started = 0,
   Completed, 
   Canceled, 
   Error,
 };
 } } } // ABI::Windows:::Foundation
 using ABI::Windows::Foundation::AsyncStatus;
 #ifndef _HIDE_GLOBAL_ASYNC_STATUS
  • For Express versions of VS:
    • Install the Windows Driver Toolkit, version 7.1.0 - Version 7.1.0 is needed because it contains the necessary ATL headers that express VS lacks.
    • Add the following to start-msvc*.bat file near the end just before the line that reads cd "%USERPROFILE%" (assumes WinDDK was installed in "C:\WinDDK\7600.16385.1"):
set "INCLUDE=C:\WinDDK\7600.16385.1\inc\atl71;%INCLUDE%"
set "LIB=C:\WinDDK\7600.16385.1\lib\ATL\i386;%LIB%"
  • Check out mozilla-central. Make sure the obj directory has "Modify" permissions given to the current user.
  • Create a standard browser .mozconfig file with the options you prefer and add
ac_add_options --enable-metro

At this point, you should be able to launch the metro browser on the desktop using a command line switch:

./mach run -metrodesktop

To run in the real "immersive" (full-screen) Metro environment, first launch the desktop browser by typing:

./mach run

Then press the "Relaunch in Windows 8 Touch" button in the menu to switch to Metro mode. See this support page for details.

Note, for debug builds, see Firefox/Windows_8_Integration#Logging_Assertions.

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:

  1. Create a new profile named "desktop". (You can use Firefox Sync to keep this in sync with your default profile.)
  2. 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.
  3. To launch Metro Firefox, run firefox.exe -no-remote (or ./mach run) and then press the Windows 8 Touch menu button.
    • Or you can launch the Metro UI in a desktop window by running firefox.exe -no-remote -metrodesktop (or ./mach run -metrodesktop).
  4. Use alt-tab or edge/corner gestures to switch between the Metro app and the desktop.

Testing

Browser-chrome tests for Metro Firefox are located in browser/metro/base/tests. The tests run in the Metro environment; Windows 8 is required.

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.

layout.css.devPixelsPerPx = 1.0 (default is -1.0, which makes Firefox autoscale CSS pixels)

To run all the tests, run the following mach command in the mozilla-build shell in your mozilla-central source directory:

./mach mochitest-metro

To run a single test file or directory,

./mach mochitest-metro path/to/test/file.js

The Metro browser will launch, run the tests and exit. Any failures will be printed to the console. The complete test log will be written to the file mochitest-metro-chrome.log in the objdir.

We have a library of convenience functions for use in metro-chrome tests, which you can find in head.js. Note: These tests make heavy use of Promises and Task.jsm.

Building on Linux or Mac OS X

This configuration is not official supported or tested. It might break without anyone noticing for a while. If it doesn't work, let us know and we can help fix it.

You can use the --enable-metro configure option and the -metrodesktop command-line flag to build and run the Metro UI on other platforms too. For details, see Metro Firefox without Windows 8.

On Mac, you might need to run "./mach build browser" after your build completes. For details, see bug 847807.

  • there is a problem with html5 EMBED tag. an EMBED tag is basically to play media files. but we can't use this on mac.

Logging Assertions

When you're running Metro Firefox with --enable-debug, there will be assertion failure messages that show up in the console. The following environment variable is assumed for the Metro environment:

XPCOM_DEBUG_BREAK=warn

Remote Debug Output

NSPR logging can be dumped to OutputDebugString using the NSPR_LOG_FILE environment variable:

NSPR_LOG_FILE=WinDebug

To log NS assertions and warnings in debug builds add the nsDebug log module:

NSPR_LOG_MODULES=nsDebug:4

bug 762519 was filed on getting javascript's dump output going to OutputDebugString as well.

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:

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
  • start remote debugger on vm
  • create empty remote debugging project on workstation
  • in project set debug settings:
    • Remote command: (common letter drive):\(path to obj dir)\dist\bin\firefox.exe
    • Working dir – same
    • Remove Server Name: vm network name w/ port
    • Attach: Yes
  • Launch browser in vm
  • F5 in project on workstation

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:
    • Remote command: (common letter drive):\(path to obj dir)\dist\bin\firefox.exe
    • Working dir – same
    • Remove Server Name: Tablet network name w/ port. The remote debugging tools window on the tablet can provide this.
    • Attach: Yes

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
  • Add a new DWORD value names 'CEHDump', value 01
  • Run a debug output viewer such as DebugView.
  • Launch the browser.

Output from the ceh and launch info from the browser will get dumped to DebugView. You can save this logging info out via the DebugView file menu and post it to bugs for diagnosis.

To turn off debug output for the CEH, change the registry value from 01 to 00, or delete the CEHDump key.

Localized Build

Language Pack extensions are not yet enabled by default in Firefox for Metro, but you can use l10n binary repack method described here to get localized build.

To create localized binary repack for x-testing locale that is based on current sources from Mozilla Central create package locally via Pymake instead of downloading it from Mozilla's ftp servers.

$ cd ../firefox-build
$ pymake package
$ cd ../firefox-build/browser/locales
$ pymake unpack
$ pymake merge-x-testing LOCALE_MERGEDIR=$(PWD)/mergedir
$ pymake installers-x-testing LOCALE_MERGEDIR=$(PWD)/mergedir 

Your localized repack will be available at ../firefox-build/dist folder.

Appropriate l10n sources (to use with --with-l10n-base parameter in .mozconfig) can be downloaded from the following locations:

Please note that you may need to install compare-locale python script to successfully perform merge locale step.

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):

metrotestharness.exe -firefoxpath T:\Mozilla\objmcrel\dist\bin\ -url www.mozilla.org

The test harness will need *write* permission to this location to write out a command line arg ini file.

harness source

Using Devtools

See Remotely debugging Firefox for Metro on MDN for instructions.

Notes:

  • 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.
  • In classic install the profiler extension from: https://github.com/bgirard/Gecko-Profiler-Addon/raw/master/geckoprofiler.xpi
    • 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'.

For additional detail read bug 886555 on getting things going.

For reference: Profiler Wiki.

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.

Example snappy symbol server config:

[General]
hostname = 127.0.0.1
portNumber = 8000
enableTracing = 1
remoteSymbolServer = http://symbolapi.mozilla.org:80/
maxCacheEntries = 20000000
prefetchInterval = 12
prefetchThreshold = 48
prefetchMaxSymbolsPerLib = 500
defaultApp = Firefox
defaultOs = Windows

[SymbolPaths]
Firefox = T:\Mozilla\MC-REL\dist\crashreporter-symbols\
Windows = T:\Temp

If you run into problems resolving xul symbols, try restarting the symbol server and generating a new profile. Also make sure prefetchMaxSymbolsPerLib in the ini is set to a large value.

Note, for switching back to nightly profiling, set the default symbol server url in classic back to http://symbolapi.mozilla.org/.

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.

widget (mostly shared widget/windows code base with different nsIWidget classes)

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.

default browser integration (new registration / launch characteristics for both desktop and metro for win8, older os remains unchanged)

installer/helper/uninstall (shared codebase w/new registration for win8)

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.

everything else in runtime (shared)

Generally we’re currently leveraging a majority of our common code base without issue. Threading, timers, networking, ssl, layout, gfx, etc. have all fit in really well. Misc. detail -

  • gfx - The surface rendered to in Metro is D2D and there is no GDI fallback. As such there are some issues with blacklisted hardware.
  • e10s - Currently using in-process content (no child processes).
  • Accessibility - not integrated yet.
  • Netwerk - no issues.
  • Layout - no issues.
  • dom & dom/system & hal - DOM interfaces for device info / sensor input and events. Currently there isn't much here for Windows.
  • media - no issues.
  • storage - works, although there are some profile corruption problems from early termination which can occur in metro. We also have a 'shared profile' problem (see Big Issues).
  • toolkit - very little of this is in use. Crash reporter UI will need work/integration.
  • xpcom - no issues.

Pros and Cons

  • Pro – single unified Windows installer / unified browser build.
  • Pro – shared runtime without multiple copies of key files like xul.dll.
  • 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

  • Windows XP - The current VC11 Beta redist runtime is not compatible with XP. (bug 744942 - FIXED)
  • 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.

Links