Now for the months-long wait for the examiners to review it.

One barrier to switching, for me, was that I have a few GDB commands defined in my .gdbinit file that I use for debugging Firefox. Most of my .gdbinit was cribbed from Boris Zbarsky’s a few years ago, but nowadays there is a .gdbinit file in the tree. So over the last couple of days I’ve ported the commands over to a .lldbinit file in the tree.

LLDB uses Python as its scripting language, and most of the commands that have been ported over are written in Python. The .lldbinit file imports the lldbutils module, which lives in python/lldbutils/. The README.txt file in there documents all of the currently supported Gecko-specific functionality.

For example, the prefcnt command can be used to show the refcount of an object. Unlike the one in .gdbinit, the LLDB version of this command can take an argument that is a reference to a refcounted object, a pointer to one or one of our smart pointers to one:

(lldb) p this
(nsHTMLDocument *) $1 = 0x0000000116e9d800
(lldb) prefcnt this
20
(lldb) p mDocumentURI
(nsCOMPtr) $3 = {
  mRawPtr = 0x0000000117163e50
}
(lldb) prefcnt mDocumentURI
11

In addition to a few commands, I’ve added a couple of type summaries to begin with. In LLDB, a type summary is a rule for how to display a value. This is useful for types like our string types, where you otherwise have to bury in to find the right member variable to get the string out. With the nsAString and nsACString type summaries, you can just print the string object and the string value in it will be shown.

(lldb) frame info
frame #0: 0x000000010400cfea XUL`nsCSSParser::ParseProperty(this=0x00007fff5fbf5248, aPropID=eCSSProperty_margin_top, aPropValue=0x00007fff5fbf53f8, aSheetURI=0x0000000115ae8c00, aBaseURI=0x0000000115ae8c00, aSheetPrincipal=0x000000010ff9e040, aDeclaration=0x00000001826fd580, aChanged=0x00007fff5fbf5247, aIsImportant=false, aIsSVGMode=false) + 74 at nsCSSParser.cpp:12851
(lldb) p aPropValue
(const nsAString_internal) $16 = u"-25px"

(lldb) p this
(nsHTMLDocument *) $18 = 0x0000000115b56000
(lldb) p mContentType
(nsCString) $19 = {
  nsACString_internal = "text/html"
}

LLDB also provides the ability to define synthetic children for a type, which are fake member variables. They can be used to expose the elements of container data structures. For example, synthetic children for nsTArray and friends now let you inspect the array as if it were a plain array type, instead of just seeing an mHdr member:

(lldb) frame info
frame #0: 0x00000001043eb8a8 XUL`SVGTextFrame::DoGlyphPositioning(this=0x000000012f3f8778) + 248 at SVGTextFrame.cpp:4940
(lldb) p charPositions
(nsTArray<nsPoint>) $5 = {
  [0] = {
    mozilla::gfx::BasePoint<int, nsPoint> = {
      x = 0
      y = 816
    }
  }
  [1] = {
    mozilla::gfx::BasePoint<int, nsPoint> = {
      x = 426
      y = 816
    }
  }
  [2] = {
    mozilla::gfx::BasePoint<int, nsPoint> = {
      x = 906
      y = 816
    }
  }
}

(The nsPoint type looks like it could do with type summary to make it more compact, though!)

Loading the .lldbinit

LLDB by default looks in two places to load a .lldbinit file: the current directory when you start it, and your home directory. In addition to the .lldbinit in the root of the source tree (which is where I normally launch my debugger from), the build system puts stub .lldbinit files in your objdir, so that commands like mach reftest --debugger=lldb will pick it up, and next to the final firefox (or other application) binary, in case that’s where you start the debugger from. These stub files just load the main .lldbinit.

So if you are running lldb yourself or through mach, you shouldn’t need to do anything extra to load the in-tree .lldbinit.

Loading it in Xcode

Although the .lldbinit file works fine in Xcode, there is unfortunately no way to add a project-specific .lldbinit file in Xcode that will get loaded automatically. Probably the best approach is to load it from your ~/.lldbinit. If you are happy with the Gecko debugging commands being available regardless of what you’re debugging with LLDB, then add these lines:

script topsrcdir = "/path/to/a/mozilla/tree"
command source -s true "/path/to/a/mozilla/tree/.lldbinit"

where “/path/to/a/mozilla/tree” is any checkout of mozilla-central you’re likely to keep up to date. The topsrcdir Python variable is used to tell the in-tree .lldbinit where the lldbutils module can be found.

If instead you want to manually enable the commands within Xcode whenever you want to use them, you could make the command source an alias:

script topsrcdir = "/path/to/a/mozilla/tree"
command alias gk command source -s true "/path/to/a/mozilla/tree/.lldbinit"

and then you can type gk at the LLDB prompt in the Xcode debugger window to load it.

In addition to the Gecko debugging commands being available, type summaries and synthetic children will be used whereever values are shown in the Xcode interface, like the Variables panel of the Debug area or when mousing over variables in a source file while debugging.

See how the mContent of the nsTextFrame, which is an nsTextNode, has its type summary displayed next to its pointer value.

Here the elements of the nsTArray<nsPoint> are shown and can be expanded as if they were plain array elements.

What’s available now?

So far these commands are available:

• frametree (ft), frametreelimited (ftl)
  These commands dump out information about the layout frame tree. The “limited” version dumps a subtree, rather than the tree for the whole document.
• js
  Prints a backtrace of the current JS stack.
• prefcnt
  Prints the refcount of a refcounted object.
• pstate
  Prints the state bits of an nsIFrame in symbolic form, rather than as a uint64_t (once bug 960848 relands).
• ptag
  Prints the tag name of a given nsINode.

These types have type summaries:

• nsAString, nsACString
  Shows the contents of the string.
• nsIAtom
  Shows the atom’s string.
• nsTextNode
  Shows the text node’s string value.

And the only type to have synthetic children so far is nsTArray, as mentioned above.

Check the README file for examples and more information.

Let’s add more!

If you have any GDB commands that you’d like to see ported over to LLDB, or have ideas for other useful commands and type summaries, file a bug CCing me and I’ll see what I can do!

Custom properties that declare variables all must be named beginning with var-. The value of these custom properties is nearly freeform. They can take nearly any stream of tokens, as long as it is balanced.

For example, an author might declare some common values on a style rule that matches the root element, so that they are available on every element in the document:

:root {
  var-theme-colour-1: #009EE0; 
  var-theme-colour-2: #FFED00; 
  var-theme-colour-3: #E2007A; 
  var-spacing: 24px;
}

Variables can be referenced at any position within the value of another property, including other custom properties. The variables in the style sheet above can be used, for example, as follows:

h1, h2 {
  color: var(theme-colour-1);
}
h1, h2, p {
  margin-top: var(spacing);
}
em {
  background-color: var(theme-colour-2);
}
blockquote {
  margin: var(spacing) calc(var(spacing) * 2);
  padding: calc(var(spacing) / 2) 0;
  border-top: 2px solid var(theme-colour-3);
  border-bottom: 1px dotted var(theme-colour-3);
  font-style: italic;
}

When applied to this document:

<!DOCTYPE html>
<h1>The title of the document</h1>
<h2>A witty subtitle</h2>
<p><em>Please</em> consider the following quote:</p>
<blockquote>Text of the quote goes here.</blockquote>

the result would be something that looks like this:

Variables are resolved based on the value of the variable on the element that the property with a variable reference is applied to. If the h2 element had a style="var-theme-colour-1: black" attribute on it, then the h2 { color: var(theme-colour-1); } rule would be resolved using that value rather than the one specified in the :root rule.

Variable references can also include fallback to use in case the variable is not defined or is invalid (due to being part of a variable reference cycle). The first rule in the style sheet using the variables could be rewritten as:

h1, h2 {
  color: var(theme-colour-1, rgb(14, 14, 14));
}

which would result in the colour being a dark grey if the theme-colour-1 variable is not defined on one of the heading elements.

Since variable references are expanded using the variable value on the element, this process must be done while determining the computed value of a property. Whenever there is an error during the variable substitution process, it causes the property to be “invalid at computed-value time”. These errors can be due to referencing an undeclared variable with no fallback, or because the substituted value for the property does not parse (e.g. if we assigned a non-colour value to the theme-colour-1 variable and then used that variable in the ‘color’ property). When a property is invalid at computed-value time, the property declaration itself is parsed successfully and will be visible if you inspect the CSSStyleDeclaration object in the DOM. The computed value of the property will take on a default value, however. For inherited properties, like ‘color’, the default value will be ‘inherit’. For non-inherited properties, it is ‘initial’.

Implementation

An initial implementation of CSS Variables has just landed in Firefox Nightly, which is currently at version 29. The feature is not yet enabled for release builds (that is, Firefox Beta and the release version of Firefox), as we are waiting for a few issues to be resolved in the specification and for it to advance a little further in the W3C Process before making it more widely available. It will however continue to be available in Nightly and, after the February 3 merge, in Firefox Aurora.

The only part of the specification that has not yet been implemented is the CSSVariableMap part, which provides an object that behaves like an ECMAScript Map, with get, set and other methods, to get the values of variables on a CSSStyleDeclaration. Note however that you can still get at them in the DOM by using the getPropertyValue and setProperty methods, as long as you use the full property names such as "var-theme-colour-1".

The work for this feature was done in bug 773296, and my thanks to David Baron for doing the reviews there and to Emmanuele Bassi who did some initial work on the implementation. If you encounter any problems using the feature, please file a bug!

The CSS Cascading and Inheritance specification adds a new shorthand named ‘all’ that can be used in conjunction with a new CSS-wide keyword ‘unset’. These can be used to the same effect as a reset style sheet. ‘all’ is a shorthand property that is considered to have all properties that a user agent supports – except for ‘direction’ and ‘unicode-bidi’ – as component longhands. ‘unset’ is a value that means the same as ‘inherit’, if used as the value of an inherited property, or the same as ‘initial’, if used as the value of a non-inherited property.

The effect of ‘unset’ is that it effectively removes any earlier matching declarations for that property at the same origin and with the same or lower specificity, and any matching declarations at all from earlier origins, while still respecting the precedence of !important declarations. For example, in the following document, the ‘all: unset’ declaration is equivalent to ‘background-color: initial; color: inherit; display: initial; margin-top: initial; margin-left: initial; font-style: inherit; …’:

<!DOCTYPE html>
<style>
blockquote { background-color: skyblue; }
#quote { color: red; }
blockquote { all: unset; }
blockquote { font-style: italic; }
</style>
<blockquote id="quote">The blade itself incites to deeds of violence.</blockquote>

In a user agent that does not yet implement ‘all: unset’, the document would be rendered like this:

and in a user agent that does implement it, like this:

(If you’re reading this in a feed reader that has other styles applied, and in a browser that does not yet implement ‘all: inherit’, the renderings above might not look exactly right.)

The quote is rendered with red, italic text, but without its typical margins, which come from the user agent style sheet. The ‘all’ declaration wins over the ‘background-color: skyblue’ declaration, which has the same origin and specificity, while the ‘color: red’ declaration wins due to its higher specificity.

One thing to be aware of is that the initial value of the ‘display’ property is ‘inline’, which is different from the ‘block’ that would be set on blockquote elements in the user agent style sheet. If we had two consecutive blockquote elements, they would be shown in the one run of inline text, as if they were spans.

Although the ‘all’ shorthand would typically be used with the ‘unset’ value, the other CSS-wide values ‘inherit’ and ‘initial’ can be used with it, and ‘unset’ can also be used on any other individual property.

Bugs 842329 and 921731 landed in Firefox Nightly builds a couple of days ago, and will therefore be available in Firefox 27.

First, Robert Longson pointed out to me that there were a couple more features that SVG text now supports since the rewrite landed:

• You can use ‘font-variant: small-caps’.
• SVG text can be copied to the clipboard with Cmd/Ctrl+C once selected.
• SVG DOM methods for selecting text – selectSubString and deselectAll – are now implemented.

Second, the latest Firefox Nightly (2013-07-08) now supports the textLength="" and lengthAdjust="" attributes on the <text> element (but not yet on child text content elements). These attributes are useful if, for example, you have some text in a diagram that you want to ensure does not run over some other elements, which might happen if the font used is not present on the client, or if text layout resulted in a total text width different from what the author expected.

You can see the effect of using textLength="..." lengthAdjust="spacingAndGlyphs" in this example:

If you mouse over the ellipses, the text is changed to use a monospaced font. This would normally make the text wider than the ellipse, but the use of lengthAdjust="spacingAndGlyphs" scales the text so that it retains its specified width.

Improvements resulting from this work include the following:

• The ‘text-decoration’ property is now honoured, so underlines, strike-throughs and overlines are painted.
• Searching for text on a page will now search through and highlight SVG text.
• Text can be selected with the mouse.
• Layout of bidirectional text when there are multiple child nodes of a <text> element is now correct.
• The ‘white-space’ property now applies to SVG text. In the future, in SVG 2, ‘white-space’ will be recommended method to control white space handling rather than xml:space="". ‘white-space’ can be used to render manually wrapped text when using the pre and pre-line values. ‘line-height’ is used to determine the spacing between lines.
• Various CSS3 Font properties, including the new ‘font-variant’ related properties to turn on and off OpenType features, now apply to SVG text.
• The :first-letter and :first-line pseudo-elements now apply to SVG text.

If you work with SVG content, please download the latest Firefox Nightly and test out the new functionality, and if you encounter any issues, please do file a bug.

My thanks to roc, jwatt, longsonr, bz and dbaron for their help and reviews!

Update 3 July 2013: Here is a page demonstrating these features.

For example, consider this document:

<!DOCTYPE html>
<title>Scoped style example</title>
<body>
  <style>
    p { font-style: italic; }
  </style>
  <p>The first paragraph.</p>
  <p>
    <style scoped>
      p { color: crimson; }
    </style>
    The second paragraph.
  </p>
</body>

It would be rendered as follows:

Rules in the style sheet only match an element if all of the elements matched by a selector are within the style scope. Thus, if the rule were instead body > p { color: crimson; }, it would not match that second paragraph.

The CSS Cascading and Inheritance Level 3 specification defines that when there are nested style scopes, rules on inner scopes override those from outer scopes, regardless of the specificity of the rules. Using !important reverses this, and allows outer scopes to win over inner scopes. Global style sheets, including <style> elements without a scoped="" attribute or those loaded using a <link> element, are treated as if they are scoped to the root element.

One use case for scoped style sheets is to isolate a set of style rules that apply to a single article or comment within a page to ensure that they cannot affect the style of other elements on the page. On a web site that aggregates articles from different authors, this could allow the designer of the overall site to know that the elements of the page outside the article itself will not be affected by the article’s styles.

Another is to be able to specify style for a given element’s pseudo-element, or only when it matches a pseudo-class, which is not possible just by using the style="" on the element or without giving the element an ID and defining the style in a global style sheet. For example if you have an element styled like this:

<p>
  ...
  <span style="text-decoration: underline;">looks like a link</span>
  ...
</p>

and you decide you want the underline to be applied only when the element is hovered, then it’s not possible to use the :hover pseudo-class within the style="" attribute. A scoped style sheet can be used:

<p>
  ...
  <span>
    <style scoped>:hover { text-decoration: underline; }</style>
    looks like a link
  </span>
  ...
</p>

Implementation

Firefox 21, currently on the Nightly channel, supports scoped style sheets now that bug 508725 has landed. This feature is not prefixed or behind a pref. The scoped="" attribute can be placed on SVG <style> elements, too.

There are two aspects of the Firefox implementation that don’t match the specification yet:

1. The @global at-rule, to allow all elements during selector matching except for the subject to be outside the style scope, is not implemented. The name “global” doesn’t quite convey the meaning it has, and given there are no other at-rules that can be used as a prefix to a list of selectors, some other syntax might be better. (Filed as bug 830058.)
2. Other at-rules that have global effects, including @font-face and @keyframes, are not processed at all within scoped style sheets. The HTML specification states that these should have effects limited to the style scope. (Filed as bug 830056.)

[Edited 16 January 2013 – fixed the typo pointed out by Pablo]

SVG 2 adds a simple property that allows the author to control the painting order of the components of a shape or text content element: the paint-order property. The initial value of the property is normal, which gets you the default, SVG 1.1 behaviour. To specify a different order, a sequence of fill, stroke and markers keywords is used. The keywords cannot be repeated, but some can be omitted, in which case all of the remaining unspecified components are painted in their default order, after the ones that were explicitly specified. For example, paint-order="stroke" is equivalent to paint-order="stroke fill markers".

Where I often want to place the stroke underneath the fill is when stroking text. The problem with placing the stroke above the fill of a text element is that the stroke straddles the boundary of the fill, half lying inside the glyphs and half outside. This results in the apparent glyph shape changing, the thicker the stroke you use.

The following example demonstrates the use of paint-order on a <text> element to produce stroked text that looks nicer:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200">
  <linearGradient id="g" x1="0" y1="0" x2="0" y2="1">
    <stop stop-color="#888"/>
    <stop stop-color="#ccc" offset="1"/>
  </linearGradient>
  <rect width="400" height="200" fill="url(#g)"/>
  <g fill="crimson" stroke="white" stroke-width="6" stroke-linejoin="round"
     text-anchor="middle" font-family="sans-serif" font-size="50px" font-weight="bold">
    <text x="200" y="75">stroke over</text>
    <text x="200" y="150" paint-order="stroke">stroke under</text>
  </g>
</svg>

The example would be rendered like this:

Perhaps this comparison is a bit unfair; the apparent thickness of the stroke on the element with paint-order="stroke" is half that of the text with the default paint-order since half of it is occluded by the fill. Here is what it would look like if the first text element had stroke-width="3":

It’s clearer to see here that due to the stroke paint intruding on the fill of the first text element, the red glyphs end up looking eroded, while those in the second element appear normal.

Implementation

Since bug 828805 landed yesterday, support for the paint-order property is now available in Firefox Nightly. It currently is enabled only when the svg.paint-order.enabled property is set to true, which is the default on the Firefox Nightly and Aurora channels. Once the SVG 2 specification matures further, support will be enabled across all channels.

Here is a simple use of an SVG mask:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 512 341" width="512" height="341">
  <defs>
    <mask id="m">
      <circle cx="256" cy="200" r="150"/>
    </mask>
  </defs>
  <g mask="url(#m)">
    <image width="512" height="341.5" xlink:href="http://farm8.staticflickr.com/7063/6860283873_b9f2e6d511_b.jpg"/>
    <!-- original: http://www.flickr.com/photos/yewenyi/6860283873/
         http://creativecommons.org/licenses/by-nc/2.0/ -->
  </g>
</svg>

And here is how it renders:

Er, what? This should be a simple raster image masked by a circle. What went wrong?

If you’re like me, you would have made this mistake a thousand times. The problem is that the mask element looks at the luminance of the mask child content to determine how much of the masked graphics to let show through. Luminance is a measure of brightness – black has luminance of 0 and white has a luminance of 1. The different red, green and blue component values contribute with different weights, and the luminance value is then multiplied with the alpha of the mask content pixel to determine the final mask value. For each pixel, the mask value is multiplied by the RGBA pixel in the masked content. Since our mask consists only of a black circle (black is the initial value of the fill property), the mask value over the entire mask is 0, letting nothing of the masked content through! What we should have done is specified fill="white" on the circle.

It is a very common misconception that SVG masks look just at the alpha of the mask content, and this is also a common way that masks are used in authoring tools. To accommodate this, SVG 2 uses the new CSS Masking specification, which, among other things, allows an author to specify that the alpha of a mask’s content, and not the luminance, is used to determine mask values. This is done by the use of the mask-type property. We can use it in our example as follows:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 512 341" width="512" height="341">
  <defs>
    <mask id="m" mask-type="alpha">
      <circle cx="256" cy="200" r="150"/>
    </mask>
  </defs>
  <g mask="url(#m)">
    <image width="512" height="341.5" xlink:href="http://farm8.staticflickr.com/7063/6860283873_b9f2e6d511_b.jpg"/>
    <!-- original: http://www.flickr.com/photos/yewenyi/6860283873/
         http://creativecommons.org/licenses/by-nc/2.0/ -->
  </g>
</svg>

and the resulting image would look like this:

Now, obviously this example is simple enough that if you could remember that you needed to change something to make the mask work, you would probably remember that fill="white" would work just as well as mask-type="alpha". The mask-type property could become more useful if you already have some graphics (either SVG content, perhaps referencing some raster images too) that has alpha. Although it would be possible to use an SVG filter to convert the alpha channel into an opaque image with just the right shade of white, this seems unnecessary work for the author.

Since mask-type is a CSS property, it means you can also set it once for all masks in a document with a single style rule, mask { mask-type: alpha }.

Implementation

Bug 793617 has just landed, which means that the mask-type property is now available in Firefox. As with other new features we have been implementing recently, this property is not prefixed. Instead, it lives behind a pref – layout.css.masking.enabled in this case. The pref will default to being true for Nightly and Aurora builds, and false for Beta and Release. Once the CSS Masking specification has matured further, the feature will be enabled by default on all builds. This means that you can begin experimenting with the property, but don’t write productions web sites that rely on it just yet!

In WebKit land, Dirk Schulze has implemented the property, also without a prefix.

[Edited 29 December 2012 – fix the examples to not use fill="white" as pointed out by roc]