Firefox/Windows 8 Integration

From MozillaWiki
Jump to navigation Jump to search

Wiki

Useful Bugzilla Queries

Win8 Metro

  • Metro Firefox complete list

Win8 Metro

  • Metro Firefox complete list
  • Minus feature=story, epic, and MetroV1

Untagged Bugs

  • Not blocked by various pm triage tracking bugs
  • Whiteboard does not contain feature=epic, work, change, defect, story
  • Summary does not contain 'MetroV1'

Last three days

  • Bugs filed against product Metro Firefox in the last three days

Platform

  • Core, Toolkit, mozilla.org

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.

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
  • 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

  • To contribute to platform integration bugs, you will use: C++, C++/CX
  • 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

Metro Builds

Nightly Builds

Update: 2/19/2013

Nightly builds are now being generated on mozilla-central.

Nightly builds off the mozilla-central repository are currently available in the Firefox build archives.

To set these builds up:

  • Install the browser using the latest installer
  • 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, only the desktop browser can do browser updates 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

Firefox for Metro

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 builder archives. Note these are not nightlies, they do not self update. 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
  • Set Metro Firefox as the default browser through Firefox preferences, which launches Control Panel -> Default Programs

Building Locally

Updated 10/31/2012

  • Install Visual Studio 2010 or 2012.
  • Install MozillaBuild
  • Install the Windows 8.0 SDK
  • If you are using an express version of VS, install the windows driver toolkit - Don't install WDK 8, version 7.1 is needed because it contains the necessary ATL headers that express VS lacks. Then, add the following to start-msvc*.bat file (assuming it was installed on "C:\WinDDK\7600.16385.1"):
set "INCLUDE=%INCLUDE%;C:\WinDDK\7600.16385.1\inc\atl71"
set "LIB=%LIB%;C:\WinDDK\7600.16385.1\lib\ATL\i386"
For VS 2010/8.0 SDK builds, update to the latest start-msvc2010 batch script from mozilla-build repo.
For VS2012 builds, use the current start-msvc2011 batch scripts distributed with MozillaBuild.
  • 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 {
  • 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
  • Config and build m-c

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

(obj)/dist/bin/firefox.exe -metrodesktop

To register local builds as the default browser:

  • 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.
  • 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.
  • Open up Control Panel -> Default Programs. You should see 'Metro Firefox' in the list of applications.
  • Set all Metro Firefox defaults in Default Programs.

At which point you should have a Firefox tile in Win8 that launches the browser.

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.

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.

To start the tests, run the following command in the mozilla-build shell, at the top level of your obj-dir:

pymake mochitest-metro-chrome

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.

Building on Linux or Mac OS X

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.

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:

XPCOM_DEBUG_BREAK=warn

Set up steps:

  • From the start screen, type "control panel"
  • Search for "Environment"
  • Click "Edit environment variables for your account"
  • Add the user variable "XPCOM_DEBUG_BREAK" with value "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.

DOM Inspector

Getting DOM Inspector attached to builds running on the desktop takes a few tweaks.

  • 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.
<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>
  • Add the 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:
pref("extensions.autoDisableScopes", 15);
pref("extensions.minCompatibleAppVersion", "4.0");
pref("extensions.strictCompatibility", false);
  • 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 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.

Venkman Debugger

(10/5/12 - Note, since we've changed the app id, this probably doesn't work.)

  • Copy the '{f13b157f-b174-47e7-a34d-4815ddfdfeb8}' xpi under your Firefox profile's extension directory over to your MetroFirefox profile extensions directory.
  • Launch the browser with the '-venkman' command line option.

JS Shell

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

WinRT Compiler Generated Code

Compiler switches:

  • /d1ZWtokens - dump C++ code generated code for C++/CX.
  • /d1reportAllClassLayout - dump class layouts
  • /d1reportSingleClassLayoutXXX - where XXX performs substring matches against the class name.

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 -

  • Install Win8 on the tablet, use the same login/password you use on the workstation you'll be debugging from.
  • 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 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 main workstation doesn't use.
  • 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, 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.
  • Checkout Elm on the second drive of the tablet, 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 workstation, create a 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.

Diagnosing Startup Problems

Due to the embedded nature of metro browsers, diagnosing startup problems can be a bit of a pain. There are a few things you can do to help devs figure out what's going wrong.

1) Launch the metro browser interface on desktop to confirm the install is working.

  • Navigate to firefox's install location in explorer
  • Hold shift, right-click the folder with firefox.exe and select open command prompt.
  • in the prompt type 'firefox.exe -metrodesktop'

The metro front end should launch in a window on the desktop. If not, try uninstalling and re-installing. If that doesn't help, please file a bug.

2) Check Direct3D start up check results

Using regedit.exe, check under the following key for a value named 'MetroD3DAvailable':

HKEY_CURRENT_USER\SOFTWARE\Mozilla\Firefox

If the value is 0, Direct3D startup checks failed. Please file a bug, and post the Graphics section of your desktop browser's about:support section to the bug. If there is no value, please file a bug. If the value is 1, startup checks succeeded.

3) Check for submitted crashes reports

To check if metro fx is generating and submitting crash reports open explorer to the following path:

C:\Users\(youraccount)\AppData\Roaming\Mozilla\MetroFirefox\Crash Reports\submitted\

If the folder exists and contains text files please file a bug and copy the contents of a few of the most recent files into the bug.

4) Check for unsubmitted crashes reports

Metro firefox can not submit crashes for analysis unless the browser fully starts (bug 797023).

To check if metro fx is crashing on startup, open explorer to the following path:

C:\Users\(youraccount)\AppData\Roaming\Mozilla\MetroFirefox\Crash Reports\

In this folder look for two files:

LastCrash lastCrashFilename

If both files are present, delete them, and try restarting Metro Firefox again. After doing this, check the folder again. If the files return, a startup crash is likely.

There are two things you can do t this point to help diagnose the problem:

Option 1: Use Desktop Firefox to submit the crash report to Mozilla's crash server -

  • open lastCrashFilename with notepad.exe
  • copy the temp path and note the file name of the crash report
  • open the temp path in explorer and locate the two files associated with the report.

There will be two files, both will have the same file name (a uuid string) and the extensions .dmp and .extra.

  • shutdown desktop firefox if it is running
  • In explorer, copy both files from their location into the follow folder:

C:\Users\(youraccount)\AppData\Roaming\Mozilla\Firefox\Crash Reports\pending\

  • start Desktop Firefox.
  • Navigate to 'about:crashes'.
  • find the uuid of the report you copied and click on its link

If the link does not resolve to a crash server crash report immediately, wait a few minutes and try again. Once the link resolves, file a bug and copy the report's link into the bug report.

Option 2:

File a bug and contact a dev. who you can share your crash report with. Note crash reports can contain user specific info, do not submit these files to bugzilla as attachments.

4) Logging startup

..

5) CEH logging

..

Hardware

Asa's Google Docs list of Win8 touch friendly hardware

Samsung Series 7

The Series seven is the first device we started developing with. Details below on getting the hardware set up with Windows 8.

  • To order, file a bug under mozilla.org, Server Operations: Desktop Issues. See bug 738613, CC your PM or Asa.
  • Once you have the tablet, dock, and keyboard, unpack. Charge up the device. It'll be running Win7, ignore all the default software.
  • 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 Windows 7 USB DVD Download Tool from Microsoft. For burning on mac?
  • 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.
  • 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.
  • After the tablet is set up, download Firefox nightly or build a local copy and start debugging!

Firmware Updates

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.

Samsung Link

Samsung Series 7 Tweaks

  • To fix auto changing brightness problems for wipe Win8 installs:
    • Open desktop
    • click/tap on the battery icon in the taskbar, select "More power options"
    • Select your current power plan or create a new plan via the link on the left.
    • 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

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

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.

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.

nsBrowserApp

Currently using fennec’s nsBrowserApp.

chrome interface markup and css (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).

browser comps (different)

dictionaries, hyphenation, res, searchplugins, extensions, plugins (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. [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 - 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.
  • e10s - currently using Fennec’s out of process tabs.
  • 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.

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. [completed]
  • Have nsBrowserApp communicate to xul lib what environment we are running in. [completed]
  • Dynamically switch out which code path we want in xul lib where necessary. [completed]
  • 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
  • Share a single profile between both browsers or Sync two profiles on the same machine.

Elm to mozilla-central migration tracking bug: bug 747347

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