|
|
| (75 intermediate revisions by 11 users not shown) |
| Line 1: |
Line 1: |
| Want to hack on [[DevTools|Firefox Developer Tools]]? You've come to the right place! If you want more information about contributing, check out our guide for [[DevTools/GetInvolved|getting involved]].
| | The contents of this section have been moved to |
|
| |
|
| = First Build =
| | https://firefox-source-docs.mozilla.org/devtools/index.html |
| | |
| Follow the instructions on [https://developer.mozilla.org/En/Simple_Firefox_build how to build Firefox], except that you will need to use:
| |
| | |
| hg clone http://hg.mozilla.org/integration/fx-team
| |
| | |
| Instead of:
| |
| | |
| hg clone http://hg.mozilla.org/mozilla-central
| |
| | |
| For your first build, running <code>./mach build</code> should do the trick after you get the source code. If you are going to be building a lot, you may want to set up your [https://developer.mozilla.org/en-US/docs/Configuring_Build_Options .mozconfig file].
| |
| | |
| == First Run ==
| |
| | |
| Once you have built Firefox, you can run it with
| |
|
| |
| $ ./mach run -P development
| |
| | |
| What is the <code>-P development</code>? It is a flag telling Firefox to use a different [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data profile], named "development" (this name can be anything you want). If it does not exist the first time you run it, Firefox will open a popup and you can create a new profile with the name you passed in. This will prevent you from seeing an error message telling you that you need to close your main browser window, and it will let you make settings changes without worrying about messing up your normal profile.
| |
| | |
| Once this command runs, you should see a new Firefox window, called "Nightly". You will want to make a couple of quick changes to the profile.
| |
| | |
| Open DevTools, and click the "Toolbox Options" gear in the top left. Make sure the following two options are checked: '''Enable Chrome Debugging''' and '''Enable Remote Debugging'''. These settings allow you to use the [https://developer.mozilla.org/en-US/docs/Debugging_JavaScript#JavaScript_Debugger browser debugger] to set breakpoints inside of the DevTools code, and let you run the [https://developer.mozilla.org/en-US/docs/Tools/Scratchpad Scratchpad] in the ''Browser'' environment.
| |
| | |
| [[Image:DevToolsDeveloperSettings.png|center|600px|Settings for developer tools - "Enable Chrome Debugging" and "Enable Remote Debugging"]]
| |
| | |
| = Development workflow =
| |
| | |
| == Incremental Builds ==
| |
| | |
| Once you've already built Firefox once, and you just want to incrementally update your build with your latest devtools changes, you can run:
| |
| | |
| $ ./mach build toolkit/devtools browser
| |
| | |
| Which is much faster than your first build or clobber builds and should only take a few seconds. You can run your build the same way you did before:
| |
| | |
| $ ./mach run -P development
| |
| | |
| Note that whenever you pull the latest changes from <tt>fx-team</tt> into your local repository, you may need to "clobber". A "clobber" is similar to a "<tt>make clean</tt>". You'll know you need to clobber when you get a big error message telling you to do a clobber build after you tried to do an incremental build. To do a clobber build, enter these commands:
| |
| | |
| $ ./mach clobber
| |
| $ ./mach build
| |
| | |
| == Enabling DevTools Logging ==
| |
| | |
| Depending on what you are working on, you may want to make some changes to your profile to enable more logging. If you type '''<tt>about:config</tt>''' in the URL bar, click through the warning page, and search for '''<tt>devtools</tt>''' you can see some of them.
| |
| | |
| Add the global "dump" function to all windows which logs strings to stdout.
| |
| | |
| '''browser.dom.window.dump.enabled''' = true
| |
| | |
| Dumps all packets sent over the remote debugging protocol to stdout (requires browser.dom.window.dump.enabled):
| |
| | |
| '''devtools.debugger.log''' = true
| |
| | |
| Log every event notification from the EventEmitter class (toolkit/devtools/event-emitter.js) (requires browser.dom.window.dump.enabled)
| |
| | |
| '''devtools.dump.emit''' = true
| |
| | |
| Restart the browser to apply configuration changes.
| |
| | |
| = Making and Submitting a Patch =
| |
| | |
| Before you make any changes, read this section on [https://developer.mozilla.org/en-US/docs/Mercurial_FAQ#How_can_I_generate_a_patch_for_somebody_else_to_check-in_for_me.3F creating a patch for someone else to check in] - this will get you set up with a separate Mercurial queue for development of your patch.
| |
| | |
| If you read through the source code about something you do not know about, you may find documentation here:
| |
| | |
| * [http://developer.mozilla.org/ Mozilla Developer Network] has a ton of info about XUL elements, HTML, JS, DOM, Web APIs, Gecko-specific APIs, and more.
| |
| * [http://dxr.mozilla.org/mozilla-central/source/ DXR] is a source code search engine - search for symbols you want to learn about, eg. nsIDocument.
| |
| * You should read our [[DevTools/CodingStandards|Coding Standards]] before writing code.
| |
| ** In general, try to be File Consistent. For new files, follow the standards.
| |
| | |
| We recommend [https://support.mozilla.org/en-US/kb/how-search-from-address-bar adding a smart keyword search] for DXR and MDN.
| |
| | |
| If you still have questions, [[DevTools/GetInvolved#Communication|ask us on IRC]] or leave a comment on the Bugzilla ticket.
| |
| | |
| Once you have a patch file, add it as an attachment to the Bugzilla ticket you are working on and add the '''feedback?''' or '''review?''' flag depending on if you just want feedback and confirmation you're doing the right thing or if you think the patch is ready to land respectively. Read more about [https://developer.mozilla.org/en-US/docs/Developer_Guide/How_to_Submit_a_Patch how to submit a patch and the Bugzilla review cycle here].
| |
| | |
| = Developer Tools Directories Overview =
| |
| | |
| * '''<tt>toolkit/devtools</tt>''': Code for the devtools client and server, and all code shared between the front end and client/server. If we are using any third party libraries, or importing external repositories into our tree, those libraries generally live here (eg, <tt>toolkit/devtools/acorn</tt>).
| |
| ** '''<tt>toolkit/devtools/server</tt>''': Code for the devtools [[Remote Debugging Protocol]] server and transport layer.
| |
| *** '''<tt>toolkit/devtools/server/actors</tt>''': [[Remote_Debugging_Protocol#Actors RDP Actors]]. Note that if you're modifying the RDP, you may need to worry about [[DevTools/Backwards_Compatibility|backwards compatibilty with older protocol implementations]].
| |
| ** '''<tt>toolkit/devtools/client</tt>''': Code for the devtools [[Remote Debugging Protocol]] client.
| |
| * '''<tt>browser/devtools</tt>''': Front end user interfaces for our tools. Should be pretty obvious what is what based on the directory names and each panel we have in our toolbox.
| |
| | |
| = Running the Developer Tools Tests =
| |
| | |
| We use three suites of tests:
| |
| | |
| * '''xpcshell''': More unit-test style of tests. No browser window, just a JavaScript shell. Mostly testing APIs directly.
| |
| * '''mochitest-chrome''': More unit-test style of tests, but with a browser window. Mostly testing APIs that interact with the DOM directly.
| |
| * '''mochitest-devtools''': More of an integration style of tests. Fires up a whole browser window with every test and you can test clicking on buttons, etc.
| |
| | |
| More information about the different types of tests can be found on the [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Automated_testing MDN automated testing page]
| |
| | |
| == xpcshell Tests ==
| |
| | |
| To run all of the xpcshell tests:
| |
| | |
| $ ./mach xpcshell-test toolkit/devtools
| |
| $ ./mach xpcshell-test browser/devtools
| |
| | |
| To run a specific xpcshell test:
| |
| | |
| $ ./mach xpcshell-test toolkit/devtools/path/to/the/test_you_want_to_run.js
| |
| | |
| == Chrome Mochitests ==
| |
| | |
| To run the whole suite of chrome mochitests for devtools:
| |
| | |
| $ ./mach mochitest-chrome toolkit/devtools
| |
| $ ./mach mochitest-chrome browser/devtools
| |
| | |
| To run a specific chrome mochitest:
| |
| | |
| $ ./mach mochitest-chrome toolkit/devtools/path/to/the/test_you_want_to_run.html
| |
| | |
| == DevTools Mochitests ==
| |
| | |
| To run the whole suite of browser mochitests for devtools (sit back and relax):
| |
| | |
| $ ./mach mochitest-devtools browser/devtools
| |
| | |
| To run a specific tool's suite of browser mochitests:
| |
| | |
| $ ./mach mochitest-devtools browser/devtools/<tool>
| |
| | |
| For example, run all of the debugger browser mochitests:
| |
| | |
| $ ./mach mochitest-devtools browser/devtools/debugger
| |
| | |
| To run a specific devtools mochitest:
| |
| | |
| $ ./mach mochitest-devtools browser/devtools/path/to/the/test_you_want_to_run.js
| |
| | |
| To help with writing nice, maintainable and consistent devtools mochitests, please follow our [https://wiki.mozilla.org/DevTools/mochitests_coding_standards devtools mochitests coding guide].
| |
| | |
| Note that the mochitests '''must''' to have focus while running.
| |
| | |
| == Checking your code using JSHint ==
| |
| | |
| You don't have to use JSHint, but you may find it helpful.
| |
| | |
| There are many tools that allow you to run JSHint, for example [https://github.com/victorporof/Sublime-JSHint JSHint Gutter for Sublime Text].
| |
| | |
| Here is an example jshint.rc that conforms pretty closely with our style and use:
| |
| | |
| {
| |
| "esnext": true,
| |
| "maxerr": 9999,
| |
| "trailing": true,
| |
| "undef": true,
| |
| "loopfunc": true,
| |
| "devel": true,
| |
| "unused": true,
| |
| "globals": {
| |
| "loader": true,
| |
| "require": true,
| |
| "exports": true,
| |
| "Components": true,
| |
| "Iterator": true,
| |
| "is": true,
| |
| "isnot": true,
| |
| "ok": true,
| |
| "info": true,
| |
| "EventUtils": true,
| |
| "finish": true,
| |
| "waitForExplicitFinish": true,
| |
| "gBrowser": true,
| |
| "content": true,
| |
| "Services": true,
| |
| "SimpleTest": true,
| |
| "waitForFocus": true,
| |
| "Task": true
| |
| }
| |
| }
| |