devtools/docs/contributor/getting-started/development-profiles.md

   1 # Setting up a development profile
   2
   3 You can have various [Firefox profiles](https://developer.mozilla.org/en-US/Firefox/Multiple_profiles) (think of something like "user accounts"), each one with different settings, addons, appearance, etc.
   4
   5 This page will guide you through configuring a new profile to enable development features such as additional logging, dumping of network packets, remote debugging, etc. which will help when working in DevTools.
   6
   7 Many of these changes are achieved by modifying preferences in `about:config`, a special page you can access by typing in `about:config` in Firefox's URL bar. The first time, it will show you a warning page. Click through or disable the warning for the future, and then you can start searching for preferences to modify.
   8
   9 (If you're curious, here's more information about [about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox))
  10
  11 ## Default profile
  12
  13 The following command line expression will run Firefox using a default profile. It'll create the default profile if there isn't one already.
  14
  15
  16 ```
  17 ./mach run
  18 ```
  19
  20 ## Using temporary profile
  21
  22 The following command line expression will run Firefox using a temporary profile which is discarded when you close the browser. It also means that any preferences we set will not persist.
  23
  24 ```
  25 ./mach run --temp-profile
  26 ```
  27
  28 ## Create a permanent profile
  29
  30 Create a permanent profile can be done as follows:
  31
  32 ```
  33 ./mach run -P development
  34 ```
  35
  36 If this profile doesn't exist yet (quite likely), a window will open offering you options to create a new profile, and asking you for the name you want to use.
  37
  38 Create a new profile, and name it `development`. Then start Firefox by clicking on `Start Nightly`.
  39
  40 Next time you start Firefox with `./mach run -P development`, the new profile will be automatically used, and settings will persist between browser launches.
  41
  42 It's now time to [start contributing](../contributing.md)! 😃
  43
  44 ---
  45
  46 ## Advanced settings
  47
  48 The following section describes how to enable additional development features; don't worry if you don't understand what some of these are or what they're for. Feel free to skip these if you're new; you probably don't need them yet.
  49
  50 ### Enable additional logging
  51
  52 You can change the value of these preferences by going to `about:config`:
  53
  54 | Preference name | Value | Comments |
  55 | --------------- | --------------- | -------- |
  56 | `browser.dom.window.dump.enabled` | `true` | Adds global `dump` function to log strings to `stdout` |
  57 | `devtools.console.stdout.chrome` | `true` | Allows console API to write to `stdout` when used by chrome content |
  58 | `devtools.console.stdout.content` | `true` | Allows console API to write to `stdout` when used by content |
  59 | `devtools.debugger.log` (*) | `true` | Dump packets sent over remote debugging protocol to `stdout`.<!-- TODO: I think this is outdated and there isn't a compatible addon anymore <br /><br />The [remote protocol inspector add-on](https://github.com/firebug/rdp-inspector/wiki) might be useful too.--> |
  60 | `devtools.dump.emit` (*) | `true` | Log event notifications from the EventEmitter class<br />(found at `devtools/shared/event-emitter.js`). |
  61
  62 Preferences marked with a (`*`) also require `browser.dom.window.dump.enabled` in order to work. You might not want to enable *all* of those all the time, as they can cause the output to be way too verbose, but they might be useful if you're working on a server actor, for example<!--TODO link to actors doc-->.
  63
  64 Restart the browser to apply configuration changes.
  65
  66 ### Enable remote debugging and the Browser Toolbox
  67
  68 <!--TODO: aren't some of these preferences enabled by default now in local builds? -->
  69
  70 These settings allow you to use the [browser toolbox](https://firefox-source-docs.mozilla.org/devtools-user/browser_toolbox/) to inspect the DevTools themselves, set breakpoints inside of DevTools code in the *Browser* environment.
  71
  72 Open DevTools, and click the "Toolbox Options" gear icon in the top right (the image underneath is outdated). <!--TODO update image-->
  73
  74 Make sure the following two options are checked:
  75
  76 - Enable browser chrome and add-on debugging toolboxes
  77 - Enable remote debugging
  78
  79 ![Settings for developer tools - "Enable Chrome Debugging" and "Enable Remote Debugging"](../resources/DevToolsDeveloperSettings.png)
  80
  81 In `about:config`, set `devtools.debugger.prompt-connection` to `false`.
  82
  83 This will get rid of the prompt displayed every time you open the browser toolbox.
  84
  85 ### Enable DevTools assertions
  86
  87 When assertions are enabled, assertion failures are fatal, log console warnings, and throw errors.
  88
  89 When assertions are not enabled, the `assert` function is a no-op.
  90
  91 It also enables the "debug" builds of certain third party libraries, such as React.
  92
  93 To enable assertions, add this to your `mozconfig` file:
  94
  95 ```
  96 ac_add_options --enable-debug-js-modules
  97 ```
  98
  99 And assert your own invariants like this:
 100
 101 ```
 102 const { assert } = require("devtools/shared/DevToolsUtils");
 103 // ...
 104 assert(1 + 1 === 2, "I really hope this is true...");
 105 ```