Firebug Internals

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Resources)
m (Added categories)
 
(28 intermediate revisions not shown)
Line 1: Line 1:
== Resources ==
== Resources ==
-
 
*[http://www.softwareishard.com/blog/category/firebug/ The best place to learn about this is Honza's site]
*[http://www.softwareishard.com/blog/category/firebug/ The best place to learn about this is Honza's site]
-
*[http://www.softwareishard.com/blog/firebug-tutorial/extending-firebug Extending Firebug]
+
*[http://www.softwareishard.com/blog/firebug-tutorial/extending-firebug Extending Firebug Tutorial]
 +
*[http://getfirebug.com/developer/api/ Firebug API Documentation]
*[[jsd]] The mozilla C++ code that supports Javascript debugging features in Firebug.
*[[jsd]] The mozilla C++ code that supports Javascript debugging features in Firebug.
*[[jsClassName]] Values of the Javascript scope jsClassName
*[[jsClassName]] Values of the Javascript scope jsClassName
Line 9: Line 9:
== Source ==
== Source ==
-
Firebug source is available [http://code.google.com/p/fbug/source via subversion]
+
Firebug's and related software's source is available [https://github.com/firebug via GitHub]. Therefore you will need a git client.
-
Don't use ''/trunk'', it's just old code.
+
{| class="wikitable" style="width:100%; vertical-align:top;"
 +
|- bgcolor=lightgrey
 +
! style="width:180px;" | Repo/folder || Description
 +
|-
 +
| firebug/extension || Contains firebug source
 +
|-
 +
| firebug/tests/FBTest/ || [[Running Automated Test Suite|Firebug test harness]]
 +
|-
 +
| firebug/tests/content/ || [[Running Automated Test Suite|FBTest]] suite
 +
|-
 +
| lite/ || [[Firebug Lite]] (for non-Firefox browsers)
 +
|}
-
The Firebug source is under branches, eg ''branches/firebug1.5''.
+
Most of the remaining repos are extensions.
-
 
+
-
* ''fbtest/'' Firebug test harness
+
-
* ''tests/content'' contains the FBTest suite.
+
-
* ''lite/'' Firebug for non-Firefox browsers
+
-
* ''chromebug/'' Debugger for Firebug (and other Firefox extensions)
+
-
* Most of the remaining directories are extensions (to be under extensions/ some day).
+
== Overview of Firebug ==
== Overview of Firebug ==
-
Visually Firebug is a tab bar over two panels. The tab bar start with some buttons, then a set of tabs, the search box, and finally more buttons. The tabs select content for the panels; each main panel has a bar across the top, then content below; each main panel can have an optional side panel. The side panel may have tabs.
+
Visually Firebug is a tab bar over two panels. The tab bar start with some buttons, then a set of tabs, the search box, and finally more buttons. The tabs select content for the panels; each main panel has a bar across the top, then content below; each main panel can have one or more optional side panels. The side panels may have tabs.
 +
 
 +
As a UI system, Firebug is a XUL wrapper around HTML content in the two panels. The XUL content is mostly static or simple lists. The view is controlled by either collapsing elements or filling the lists. The HTML content is all dynamically created from templates called "[[Domplate|domplates]]".
 +
 
 +
Architecturally Firebug is a Model-View-Controller (MVC) system with the Firefox DOM being the Model and the the XUL/HTML content of Firebug being the View. The Controller, the bulk of the Firebug code, has multiple architectural elements.
 +
 
 +
=== Development Setup ===
 +
==== Link from your runtime profile to your source ====
 +
# Fetch the source code as described above
 +
# [[FAQ#Installing in a clean profile|Create a new Firefox profile]], e.g. "firebug"
 +
# In your git firebug repo folders find the folder containing the install.rdf for firebug, e. g. firebug\extension.
 +
# Copy the full path to this folder, e. g.:
 +
<source lang="dos">
 +
C:\Users\username\firebug\extension\
 +
</source>
 +
# In your new Firefox profile, find the "extensions" subfolder, e. g.:
 +
<source lang="dos">
 +
C:\Users\username\AppData\Roaming\Mozilla\Firefox\Profiles\1dlwezmx.test\extensions\ ''(under Windows 7)''
 +
</source>
 +
# Create a new file named "firebug@software.joehewitt.com" (be sure there's no file extension like .txt after it)
 +
# Open the created file in a text editor, paste the path you copied above into it and save it
 +
# Restart Firefox using the new profile
 +
 
 +
You can do this for all extensions, not just Firebug, the name of the linking file is the 'id' in the install.rdf file.
 +
 
 +
Repeat the process for [[FBTrace]] (firebug/trace/FBTrace/) and [[FBTest]] (firebug/tests/FBTest/).
 +
 
 +
==== Set some useful preferences ====
 +
[https://developer.mozilla.org/en/Setting_up_extension_development_environment#Development_preferences Set these preferences EXCEPT javascript.options.strict = false]
 +
 
 +
==== Launch Firefox with Chromebug ====
 +
 
 +
Run firefox like this:
 +
<source lang="dos">
 +
firefox.exe -jsconsole -p firebug -no-remote
 +
</source>
-
As a UI system, Firebug is a XUL wrapper around HTML content in the two panels. The XUL content is mostly static or simple lists. The view is controlled by either collapsing elements or filling the lists. The HTML content is all dynamically created from templates called "domplates".
+
* <code>-jsconsole</code>: brings up Error Console, check here for JS syntax errors during load
 +
* <code>-p firebug</code>: profile to use
 +
* <code>-no-remote</code>: allows multiple firefox instances to run at the same time
 +
* <code>-purgecaches</code>: needed for Firefox 4.0+
-
Architecturally Firebug is a Model-Controller-View (MCV) system with the Firefox DOM being the Model and the the XUL/HTML content of Firebug being the View. The Controller, the bulk of the Firebug code, has multiple architectural elements.
+
==== Open [[FBTrace]] ====
 +
See [[#How to use FBTrace.3F|How to use FBTrace]] below.
=== Modules and Contexts ===
=== Modules and Contexts ===
-
Every Web page being debugged by Firebug has exactly one 'context', an object containing all kinds of meta-data about the page. The Web page 'window' object and the context are Firebug 'modules' at each stage of the page's lifetime. Each module examines the page and places information in the context for later use or display. The modules should have no internal state related to any page: all of their state about the page should be in the context.
+
* Every Web page being debugged by Firebug has exactly one 'context', an object containing all kinds of meta-data about the page.  
 +
* The Web page 'window' object and the context are Firebug 'modules' at each stage of the page's lifetime.  
 +
* Each module examines the page and places information in the context for later use or display.  
 +
* The modules should have no internal state related to any page: all of their state about the page should be set in the context.
-
Every Firefox browser.xul ChromeWindow creates one instance of every module. A typical Firebug extension will implement one module.  
+
Every Firefox browser.xul ChromeWindow creates one instance of every module. A typical Firebug extension will implement one module.
=== Panels ===
=== Panels ===
Line 49: Line 96:
In general, panels are selected by either user action or by object. That is, you should avoid selecting a panel explicitly in your code, but rather you should select the object and let Firebug's object negotiation select the panel.
In general, panels are selected by either user action or by object. That is, you should avoid selecting a panel explicitly in your code, but rather you should select the object and let Firebug's object negotiation select the panel.
-
=== Components ===
+
=== Components er Modules ===
-
Deep under the visible UI are firebug 'components', non-visual code interacting with the entire Firefox application. For example, firebug-service.js is the firebug adapter for Firefox's Javascript Debugging Service jsd.
+
Deep under the visible UI are firebug 'components', non-visual code interacting with the entire Firefox application.
 +
Confusingly the firebug components are Mozilla platform Javascript 'modules'. For example, firebug-service.js is the firebug adapter for Firefox's Javascript Debugging Service jsd.
 +
 
 +
The Mozilla modules are one per Firefox instance.
=== Scope ===
=== Scope ===
Various parts of Firebug source code compile in various 'scopes', the containers of symbols that can be bound into functions at compile time. There are five exterior scopes to understand, browser.xul, firebug.xul, BackstagePass, FunkyEvent and Web page. In addition, most Firebug source is compiled inside of  
Various parts of Firebug source code compile in various 'scopes', the containers of symbols that can be bound into functions at compile time. There are five exterior scopes to understand, browser.xul, firebug.xul, BackstagePass, FunkyEvent and Web page. In addition, most Firebug source is compiled inside of  
-
with(FBL) { ... }
+
<source lang="javascript">
 +
with(FBL) { ... }
 +
</source>
which causes the content of lib.js to be injected into the scope of the curly braces, in effect augmenting the built in API of the outer scope with all of the functions in lib.js.  Note that the HTML windows inside of the main and side panels of the Firebug UI are themselves each a scope but no Firebug source code is compiled into those scopes.   
which causes the content of lib.js to be injected into the scope of the curly braces, in effect augmenting the built in API of the outer scope with all of the functions in lib.js.  Note that the HTML windows inside of the main and side panels of the Firebug UI are themselves each a scope but no Firebug source code is compiled into those scopes.   
Line 68: Line 120:
'''Web page''' The content of consoleInjected.js and commandLineInjected.js are copied into Web pages and thus they compile into the scope of the page to implement the window.console object and the command line evaluator.
'''Web page''' The content of consoleInjected.js and commandLineInjected.js are copied into Web pages and thus they compile into the scope of the page to implement the window.console object and the command line evaluator.
 +
 +
== Domplate ==
 +
A [[Domplate]] is a template for creating web content. This system is very powerful and makes short work of many complicated UIs. However we have no documentation and the error recovery is primitive.  Persevere, the results you can get are great.
 +
 +
There is a great [http://www.softwareishard.com/blog/firebug-tutorial/extending-firebug-domplate-part-v/ introduction by Jan Odvarko] and Christoph Dorn has started a [http://code.google.com/p/domplate/ separate project] to enable the use of the domplate system in any web page.
 +
 +
== Windows ==
 +
I know of at least 5 meanings of "window":
 +
 +
# The user interface rectangle visible through the OS window management
 +
# The top level nsIXULWindow displaying browser.xul
 +
# Sub-windows of browser.xul
 +
# The nsIDOMWindow objects containing web pages
 +
# sub-windows of the web page, eg iframes.
 +
 +
The vast majority of the time in Firebug a window refers to one of these last two things. In general you can't know which of the last two you have, so you'll see code that walks up or down the chain windows.
 +
 +
* In most of the code 'window' refers to browser.xul: do not use this variable. Only chrome.js should use 'window'.
 +
* Often firebug functions pass 'win', this is a reference to the nsIDOMWindow containing the web page
 +
* If you want to see the Javascript variables in the web page the way the web page sees them, use win.wrappedJSObject. Be careful not to add functions to this object. See [[Using win.wrappedJSObject]]
== How are the XUL files used? ==
== How are the XUL files used? ==
Line 75: Line 147:
* firebugOverlay.xul: overlays browserOverlay.xul or firebug.xul to add placement-independent features by XUL.
* firebugOverlay.xul: overlays browserOverlay.xul or firebug.xul to add placement-independent features by XUL.
-
Each extension will typically have one XUL overlay file, it should only have enough code to load the script tags of the extension source code.
+
Each extension will typically have one XUL overlay file, it should only have enough code to load the script tags of the extension source code. There's also a [[Firebug Overlays|more detailed description of the Firebug overlays]].
== How are panels created? ==
== How are panels created? ==
Line 81: Line 153:
Basically follow the pattern of an existing panel.
Basically follow the pattern of an existing panel.
-
*extend Firebug.Panel
+
* Extend Firebug.Panel
-
*add methods  
+
* Add methods  
-
*use 'this.context' for context dependence
+
* use 'this.context' for context dependence
-
*Add UI to 'this.panelNode' as HTML.
+
* Add UI to 'this.panelNode' as HTML.
-
*Learn about domplate to create the HTML
+
* Learn about [[Domplate]] to create the HTML
-
*registerPanel
+
* registerPanel
== How does debugging work? ==
== How does debugging work? ==
-
See the [[Chromebug User Guide]]
+
See the [[Chromebug|Chromebug User Guide]]
-
== How to write a firebug extension?  ==
+
== How to write a Firebug extension?  ==
-
A Firebug extension is just a Firefox extension that happens to work on top of Firebug.  
+
A Firebug extension is just a Firefox extension, that happens to work on top of Firebug.  
== How to use FBTrace? ==
== How to use FBTrace? ==
-
if (FBTrace.DBG_YOUREXT)
+
If you are working on Firebug or Chromebug, you are definitely going to want to use [[FBTrace]]. Some Firebug extensions use it as well.
-
  FBTrace.sysout(<string>, object);
+
 
 +
== Where is the entry point? ==
 +
 
 +
Starting up and tracking windows is one of the complex areas of Firebug.
 +
 
 +
# Firefox starts, loads its browser.xul into an OS window
 +
# Firefox reads firebug extension directory under profile, finds chrome.manifest, sees an overlay.
 +
# Firefox overlays browser.xul with chrome://firebug/content/browserOverlay.xul
 +
# browserOverlay.xul calls in chrome://firebug/content/firebugOverlay.xul
 +
# firebugOverlay.xul calls in chrome://firebug/content/firebug.css
 +
# firebug.css calls in -moz-binding: url("chrome://firebug/content/bindings.xml#initializer");
 +
# In bindings.xml the first call into Javascript is FirebugChrome.panelBarReady(this);  
 +
 
 +
You can learn more about the rest of the action by setting FBTrace panel options INITIALIZE and PANELS
 +
 
 +
== See also ==
 +
* [[Extension Points]]
 +
* [http://getfirebug.com/developer/api/ API documentation]
 +
* [http://labs.enonic.com/articles/how-to-build-firebug-extensions-part-1-getting-started Tutorial on how to create Firebug extensions]
 +
 
 +
[[Category:Firebug]]
 +
[[Category:Firebug Development]]
 +
[[Category:Extensions]]

Latest revision as of 00:31, 22 November 2013

Contents

[edit] Resources

[edit] Source

Firebug's and related software's source is available via GitHub. Therefore you will need a git client.

Repo/folder Description
firebug/extension Contains firebug source
firebug/tests/FBTest/ Firebug test harness
firebug/tests/content/ FBTest suite
lite/ Firebug Lite (for non-Firefox browsers)

Most of the remaining repos are extensions.

[edit] Overview of Firebug

Visually Firebug is a tab bar over two panels. The tab bar start with some buttons, then a set of tabs, the search box, and finally more buttons. The tabs select content for the panels; each main panel has a bar across the top, then content below; each main panel can have one or more optional side panels. The side panels may have tabs.

As a UI system, Firebug is a XUL wrapper around HTML content in the two panels. The XUL content is mostly static or simple lists. The view is controlled by either collapsing elements or filling the lists. The HTML content is all dynamically created from templates called "domplates".

Architecturally Firebug is a Model-View-Controller (MVC) system with the Firefox DOM being the Model and the the XUL/HTML content of Firebug being the View. The Controller, the bulk of the Firebug code, has multiple architectural elements.

[edit] Development Setup

[edit] Link from your runtime profile to your source

  1. Fetch the source code as described above
  2. Create a new Firefox profile, e.g. "firebug"
  3. In your git firebug repo folders find the folder containing the install.rdf for firebug, e. g. firebug\extension.
  4. Copy the full path to this folder, e. g.:
C:\Users\username\firebug\extension\
  1. In your new Firefox profile, find the "extensions" subfolder, e. g.:
C:\Users\username\AppData\Roaming\Mozilla\Firefox\Profiles\1dlwezmx.test\extensions\ ''(under Windows 7)''
  1. Create a new file named "firebug@software.joehewitt.com" (be sure there's no file extension like .txt after it)
  2. Open the created file in a text editor, paste the path you copied above into it and save it
  3. Restart Firefox using the new profile

You can do this for all extensions, not just Firebug, the name of the linking file is the 'id' in the install.rdf file.

Repeat the process for FBTrace (firebug/trace/FBTrace/) and FBTest (firebug/tests/FBTest/).

[edit] Set some useful preferences

Set these preferences EXCEPT javascript.options.strict = false

[edit] Launch Firefox with Chromebug

Run firefox like this:

firefox.exe -jsconsole -p firebug -no-remote
  • -jsconsole: brings up Error Console, check here for JS syntax errors during load
  • -p firebug: profile to use
  • -no-remote: allows multiple firefox instances to run at the same time
  • -purgecaches: needed for Firefox 4.0+

[edit] Open FBTrace

See How to use FBTrace below.

[edit] Modules and Contexts

  • Every Web page being debugged by Firebug has exactly one 'context', an object containing all kinds of meta-data about the page.
  • The Web page 'window' object and the context are Firebug 'modules' at each stage of the page's lifetime.
  • Each module examines the page and places information in the context for later use or display.
  • The modules should have no internal state related to any page: all of their state about the page should be set in the context.

Every Firefox browser.xul ChromeWindow creates one instance of every module. A typical Firebug extension will implement one module.

[edit] Panels

Panels are view-controllers, they manage the content in the HTML panels. Panels are created on demand by Firebug. On creation they are given a document and a context; they create one panelNode in the document and render HTML into the panelNode to show information out of the DOM and context data stores.

Every Firefox tab DOM window can cause at most one panel instance. A typical Firebug extension will implement one panel.

The panel area is managed cooperatively by the panels. When a panel is selected, 'show' is called; the panel activates elements of the toolbar above the panel content area. When another panel is selected, 'hide' is called on the to-be-deselected panel; the panel deactivates each element it activated on 'show'.

[edit] Reps (representations)

Object displayable in Firebug are mapped into "FirebugReps", system of objects with HTML templates to display their "real objects". For example, FirebugReps.Element is how DOM elements are rendered. The panel operations in firebug.js and chrome.js use the FirebugRep functions to set up generic aspects of the panels, like the status path (bread crumbs) and location list.

In general, panels are selected by either user action or by object. That is, you should avoid selecting a panel explicitly in your code, but rather you should select the object and let Firebug's object negotiation select the panel.

[edit] Components er Modules

Deep under the visible UI are firebug 'components', non-visual code interacting with the entire Firefox application. Confusingly the firebug components are Mozilla platform Javascript 'modules'. For example, firebug-service.js is the firebug adapter for Firefox's Javascript Debugging Service jsd.

The Mozilla modules are one per Firefox instance.

[edit] Scope

Various parts of Firebug source code compile in various 'scopes', the containers of symbols that can be bound into functions at compile time. There are five exterior scopes to understand, browser.xul, firebug.xul, BackstagePass, FunkyEvent and Web page. In addition, most Firebug source is compiled inside of

with(FBL) { ... }

which causes the content of lib.js to be injected into the scope of the curly braces, in effect augmenting the built in API of the outer scope with all of the functions in lib.js. Note that the HTML windows inside of the main and side panels of the Firebug UI are themselves each a scope but no Firebug source code is compiled into those scopes.

browser.xul The Firefox outer window scope. Each operating system Firefox window runs a copy of browser.xul. This is the thing with the Firefox icon and a title bar across the top, some toolbars, and the web page tabs inside. Firebug overlays browser.xul to show the UI in the bottom part of the web page. The file browserOverlay.xul both adds the XUL tags to create the Firebug UI and it adds the script tags that cause Firebug source to be compiled into the 'window' object of browser.xul. As a result there is one Firebug object in browser.xul. Most Firefox extensions and all of Firefox UI also lives in browser.xul.

firebug.xul The Firebug detached or new window scope. When Firebug is detached from Firefox, open in a new or separate window, the new window has its own scope. In that scope, a few Firebug script tags compile to create a connection back to the original browser.xul window. Most important, chrome.js is unique to each top level window, but the Firebug object used by the detached window is the object of the parent browser.xul.

BackStagePass The scope of components is separate from any window. By convention this scope is not used to share data.

FunkyEvent In some rare cases an event or setTimeout handler created by Firebug will run and the functions of lib.js will not be available unless you explicitly say "FBL.". We don't understand why this happens.

Web page The content of consoleInjected.js and commandLineInjected.js are copied into Web pages and thus they compile into the scope of the page to implement the window.console object and the command line evaluator.

[edit] Domplate

A Domplate is a template for creating web content. This system is very powerful and makes short work of many complicated UIs. However we have no documentation and the error recovery is primitive. Persevere, the results you can get are great.

There is a great introduction by Jan Odvarko and Christoph Dorn has started a separate project to enable the use of the domplate system in any web page.

[edit] Windows

I know of at least 5 meanings of "window":

  1. The user interface rectangle visible through the OS window management
  2. The top level nsIXULWindow displaying browser.xul
  3. Sub-windows of browser.xul
  4. The nsIDOMWindow objects containing web pages
  5. sub-windows of the web page, eg iframes.

The vast majority of the time in Firebug a window refers to one of these last two things. In general you can't know which of the last two you have, so you'll see code that walks up or down the chain windows.

  • In most of the code 'window' refers to browser.xul: do not use this variable. Only chrome.js should use 'window'.
  • Often firebug functions pass 'win', this is a reference to the nsIDOMWindow containing the web page
  • If you want to see the Javascript variables in the web page the way the web page sees them, use win.wrappedJSObject. Be careful not to add functions to this object. See Using win.wrappedJSObject

[edit] How are the XUL files used?

  • browserOverlay.xul : puts Firebug into the bottom of the browser window by "overlay" on to Firefox's browser.xul
  • firebug.xul: puts Firebug into its own window.
  • firebugOverlay.xul: overlays browserOverlay.xul or firebug.xul to add placement-independent features by XUL.

Each extension will typically have one XUL overlay file, it should only have enough code to load the script tags of the extension source code. There's also a more detailed description of the Firebug overlays.

[edit] How are panels created?

Basically follow the pattern of an existing panel.

  • Extend Firebug.Panel
  • Add methods
  • use 'this.context' for context dependence
  • Add UI to 'this.panelNode' as HTML.
  • Learn about Domplate to create the HTML
  • registerPanel

[edit] How does debugging work?

See the Chromebug User Guide

[edit] How to write a Firebug extension?

A Firebug extension is just a Firefox extension, that happens to work on top of Firebug.

[edit] How to use FBTrace?

If you are working on Firebug or Chromebug, you are definitely going to want to use FBTrace. Some Firebug extensions use it as well.

[edit] Where is the entry point?

Starting up and tracking windows is one of the complex areas of Firebug.

  1. Firefox starts, loads its browser.xul into an OS window
  2. Firefox reads firebug extension directory under profile, finds chrome.manifest, sees an overlay.
  3. Firefox overlays browser.xul with chrome://firebug/content/browserOverlay.xul
  4. browserOverlay.xul calls in chrome://firebug/content/firebugOverlay.xul
  5. firebugOverlay.xul calls in chrome://firebug/content/firebug.css
  6. firebug.css calls in -moz-binding: url("chrome://firebug/content/bindings.xml#initializer");
  7. In bindings.xml the first call into Javascript is FirebugChrome.panelBarReady(this);

You can learn more about the rest of the action by setting FBTrace panel options INITIALIZE and PANELS

[edit] See also

Personal tools