|
|
| (7 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| Want to work 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 |
|
| |
|
| = Building, running, updating and rebuilding =
| | https://firefox-source-docs.mozilla.org/devtools/index.html |
| | |
| == First Build ==
| |
| | |
| Follow the instructions on [https://developer.mozilla.org/En/Simple_Firefox_build how to build Firefox]. Roughly:
| |
| | |
| hg clone http://hg.mozilla.org/mozilla-central
| |
| ./mach build
| |
| | |
| For your first build, this should do the trick. 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
| |
| | |
| or
| |
| | |
| $ ./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. If you don't specify a profile, <code>mach</code> will create a temporary profile in the path <code><objdir>/tmp/scratch_user</code>.
| |
| | |
| Once this command runs, you should see a new Firefox window, called "Nightly".
| |
| | |
| == Incremental Builds ==
| |
| | |
| Once you've already built Firefox once, if you want to update with the latest changes from the repo, run:
| |
| | |
| $ hg pull -u
| |
| | |
| To build with the latest changes or with your own DevTools changes, you can run:
| |
| | |
| $ ./mach build faster
| |
| | |
| 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
| |
| | |
| If you happen to change any C++ files (which is pretty rare when working on DevTools), you may need a different command for incremental builds:
| |
| | |
| $ ./mach build binaries
| |
| | |
| A full <code>./mach build</code> will work for any type of change, it just takes longer to run than the incremental options above.
| |
| | |
| 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 "<code>make clean</code>". 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
| |
| | |
| == Artifact builds (or: building faster!) ==
| |
| | |
| If you are '''not''' going to modify any C/C++ code, you could use artifact builds. This method downloads prebuilt components, and then the build process becomes faster.
| |
| | |
| Essentially, add the following lines to your .mozconfig file:
| |
| | |
| # Automatically download and use compiled C++ components:
| |
| ac_add_options --enable-artifact-builds
| |
|
| |
| # Write build artifacts to:
| |
| mk_add_options MOZ_OBJDIR=./objdir-frontend
| |
| | |
| And then you can follow the normal build process.
| |
| | |
| On OSX you might want to use <tt>MOZ_OBJDIR=./objdir-frontend.noindex</tt> instead. Using the .noindex file extension prevents spotlight from indexing your objdir, which is slow.
| |
| | |
| For more information on aspects such as technical limitations, read the [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds Artifact Builds] page.
| |
| | |
| = Configuring your dev profile =
| |
| | |
| You will want to make a couple of quick changes to the profile you use when running your version of Firefox.
| |
| | |
| == Enable remote debugging and the Browser Toolbox ==
| |
| | |
| Open DevTools, and click the "Toolbox Options" gear icon in the top right (the image underneath is outdated). Make sure the following two options are checked:
| |
| | |
| * '''Enable browser chrome and add-on debugging toolboxes'''
| |
| * '''Enable remote debugging'''
| |
| | |
| These settings allow you to use the [https://developer.mozilla.org/docs/Tools/Browser_Toolbox browser toolbox] to set breakpoints inside of the DevTools code, inspect the DevTools themselves, 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"]]
| |
| | |
| You might also want to change the following preference in '''<tt>about:config</tt>''' to <code>false</code>:
| |
| | |
| * '''devtools.debugger.prompt-connection'''
| |
| | |
| This will get rid of the prompt displayed every time you open the browser toolbox.
| |
| | |
| == 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 (devtools/shared/event-emitter.js) (requires browser.dom.window.dump.enabled)
| |
| | |
| '''devtools.dump.emit''' = true
| |
| | |
| Restart the browser to apply configuration changes.
| |
| | |
| You may also be interested in the remote protocol inspector add-on: https://github.com/firebug/rdp-inspector/wiki
| |
| | |
| == Enabling DevTools Assertions ==
| |
| | |
| Highly recommended for DevTools hackers!
| |
| | |
| Add this to your '''<tt>.mozconfig</tt>''':
| |
| | |
| ac_add_options --enable-debug-js-modules
| |
| | |
| Assert your own invariants like this:
| |
| | |
| const { assert } = require("devtools/shared/DevToolsUtils");
| |
| // ...
| |
| assert(1 + 1 === 2, "I really hope this is true...");
| |
| | |
| When assertions are enabled, assertion failures are fatal, log console warnings, and throw errors.
| |
| | |
| When assertions are not enabled, the <tt>assert</tt> function is a no-op.
| |
| | |
| It also enables the "debug" builds of certain third party libraries, such as React.
| |
| | |
| = Developer Tools Directories Overview =
| |
| | |
| * '''<tt>devtools/shared</tt>''': Code shared by both the DevTools client (front-end UI) and server. If we are using any third party libraries, or importing external repositories into our tree, those libraries generally live here (eg, <tt>devtools/shared/acorn</tt>), assuming they are used by both client and server.
| |
| ** '''<tt>devtools/shared/client</tt>''': Code for the DevTools [Remote Debugging Protocol http://searchfox.org/mozilla-central/source/devtools/docs/backend/protocol.md] client. (You may wonder why this is not in <tt>devtools/client</tt> below: it's mainly because tests in server also need access to the RDP client.)
| |
| ** '''<tt>devtools/shared/locales</tt>''': Strings used in either the DevTools server only, or shared with both the client and server
| |
| * '''<tt>devtools/server</tt>''': Code for the DevTools [Remote Debugging Protocol http://searchfox.org/mozilla-central/source/devtools/docs/backend/protocol.md] server and transport layer.
| |
| ** '''<tt>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>devtools/client</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. This directory is only shipped with desktop Firefox, as opposed to other directories above, which are shipped with all Gecko products (Firefox OS, Firefox for Android, etc.)
| |
| ** '''<tt>devtools/client/locales</tt>''': Strings used in the DevTools client (front-end UI)
| |
| ** '''<tt>devtools/client/themes</tt>''': CSS and images used in the DevTools client (front-end UI)
| |
| | |
| = DevTools Automated Tests =
| |
| | |
| The contents of this section have been moved to https://dxr.mozilla.org/mozilla-central/source/devtools/docs/tests/README.md and other files in https://dxr.mozilla.org/mozilla-central/source/devtools/docs/tests/
| |
| | |
| == Debugging Intermittent Test Failures ==
| |
| | |
| When a test fails sometimes, but not always, it is called an "intermittent". Handling these is complicated enough that we have a [[DevTools/Intermittents|separate page]] with tips on debugging.
| |
| | |
| = Finding documentation =
| |
| | |
| 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.
| |
| * There's some technical [https://dxr.mozilla.org/mozilla-central/source/devtools/docs DevTools documentation in the repository] that you should check.
| |
| * And other technical documents on [[DevTools#Internal_Technical_Documentation|on this wiki]]
| |
| | |
| 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.
| |
| | |
| = Making and Submitting a Patch =
| |
| | |
| Before you make any changes, read [http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html the documentation on how to use Mozilla's version control].
| |
| | |
| Before you submit a patch, you should read our [[DevTools/CodingStandards|Coding Standards]] and run [https://wiki.mozilla.org/DevTools/CodingStandards#JS_linting_with_ESLint ESLint] to validate your code changes (to avoid loosing time during code reviews with formatting details for instance). In general, try to be File Consistent. For new files, follow the standards.
| |
| | |
| 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].
| |
| | |
| You can also take a look at the [[DevTools/Code Review Checklist]] as it contains a list of checks that your reviewer is likely to go over when reviewing your code.
| |
| | |
| = Coding Standards =
| |
| | |
| DevTools has some coding standards that your changes should follow:
| |
| | |
| * [[DevTools/CodingStandards|JavaScript coding standards]]
| |
| * [[DevTools/CSSTips|CSS tips]]
| |
| * [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/SVG_Guidelines SVG Best practices] and [https://dxr.mozilla.org/mozilla-central/source/devtools/docs/svgs.md guidelines for creating new DevTools SVGs]
| |
| | |
| = Potential Pitfalls =
| |
| | |
| Today there are a few techniques and conventions we use that can be confusing, especially when you first start working with the code base. We hope to improve these with time to make things easier for everyone, but for now this [https://public.etherpad-mozilla.org/p/devtools-intro-pitfalls etherpad] might be a helpful set of notes if you are having trouble. If you find new pitfalls that aren't listed there, feel free to add your own entries, so we know to address them. Also, please come talk to us in #devtools on IRC, as that might be the fastest path to solving the issue.
| |