|
| 1 | +--- |
| 2 | +--- |
| 3 | + |
| 4 | +# Building DevTools |
| 5 | + |
| 6 | +The code for our tools is split in two different locations, so if you want to work on a specific tool you will first need to locate *where* it is. |
| 7 | + |
| 8 | +Before you start modifying any aspect of DevTools, you'll want to make sure you can build them successfully first. This might require setting up your computer to obtain and compile Firefox's source code. |
| 9 | + |
| 10 | +## Where is the code? `mozilla-central` vs `devtools-html` |
| 11 | + |
| 12 | +Most of the code is hosted in the Firefox repository (we call it `mozilla-central`, often abbreviated as `m-c`), in the [devtools](https://dxr.mozilla.org/mozilla-central/source/devtools) folder. Development of newer pieces of the tools is happening in GitHub, on the [devtools-html](https://github.com/devtools-html/) organisation. |
| 13 | + |
| 14 | +<!--TODO: table listing components and locations (m-c vs github)--> |
| 15 | + |
| 16 | +Code in `m-c` takes longer to obtain and build, as it involves checking out Firefox's repository and installing tools such as compiler to build a version of Firefox in your machine. |
| 17 | + |
| 18 | +On the other hand, the repositories in `devtools-html` are more straightforward if you're used to *the GitHub workflow*: you clone them, and then run `npm install && npm run` or similar. Roughly, you can work with each repository individually, and we periodically generate JavaScript bundles that are then copied into `m-c`. |
| 19 | + |
| 20 | +Even if you only want to work on a tool whose code is on `devtools-html`, you might still need to go through the step of getting and compiling the code from `mozilla-central` in order to do integration work (such as updating a tool bundle). |
| 21 | + |
| 22 | +From now on, this document will focus on building the full DevTools within Firefox. Please refer to individual project instructions for tools hosted in `devtools-html`. |
| 23 | + |
| 24 | +These are the steps we're going to look at: |
| 25 | + |
| 26 | +* [Getting the code](#getting-the-code) |
| 27 | + * [using Mercurial](#using-mercurial-hg) |
| 28 | + * [using Git](#using-git) |
| 29 | +* [Building and running locally](#building-and-running-locally) |
| 30 | + * [Rebuilding](#rebuilding) |
| 31 | + * [Artifact builds](#building-even-faster-with-artifact-builds) for even faster builds |
| 32 | + * [Maybe you don't even need to build](#maybe-you-dont-even-need-to-build) |
| 33 | + |
| 34 | +## Getting the code |
| 35 | + |
| 36 | +The code is officially hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/). Despair not! There are ways of accessing this via git. We will explain this too. |
| 37 | + |
| 38 | +Either way takes a long time, because the repository is **B I G**. So be prepared to be patient. |
| 39 | + |
| 40 | +### Using Mercurial (hg) |
| 41 | + |
| 42 | +```bash |
| 43 | +hg clone http://hg.mozilla.org/mozilla-central |
| 44 | +``` |
| 45 | + |
| 46 | +### Using git |
| 47 | + |
| 48 | +There is a tool called [git-cinnabar](https://github.com/glandium/git-cinnabar/) that lets you use git on top of a Mercurial repository. There's a bit of setup involved, so we've written [a script to automate](https://github.com/sole/cinnabarify) installing `git-cinnabar` and obtaining the code. |
| 49 | + |
| 50 | +## Building and running locally |
| 51 | + |
| 52 | +Whatever method you used to obtain the code, the build step is the same. Fortunately, the Firefox team has made a very good job of automating this with bootstrap scripts and putting [documentation](https://developer.mozilla.org/En/Simple_Firefox_build) together. |
| 53 | + |
| 54 | +Run: |
| 55 | + |
| 56 | +```bash |
| 57 | +./mach build |
| 58 | +``` |
| 59 | + |
| 60 | +If your system needs additional dependencies installed (for example, Python, or a compiler, etc), various diagnostic messages will be printed to your screen. Follow their advice and try building again. |
| 61 | + |
| 62 | +Building also takes a long time (specially on slow computers). |
| 63 | + |
| 64 | +**Note:** if using Windows, you might need to type `mach build` instead (without the `./`). |
| 65 | + |
| 66 | +### Running your own compiled version of Firefox |
| 67 | + |
| 68 | +To run the Firefox you just compiled: |
| 69 | + |
| 70 | +```bash |
| 71 | +./mach run |
| 72 | +``` |
| 73 | + |
| 74 | +This will run using an empty temporary profile which is discarded when you close the browser. We will look more into persistent development profiles later.<!--TODO: add link to that section when it's written--> |
| 75 | + |
| 76 | +### Rebuilding |
| 77 | + |
| 78 | +Suppose you pulled the latest changes from the remote repository (or made your own changes) and want to build again. |
| 79 | + |
| 80 | +You can ask the `mach` script to build only changed files: |
| 81 | + |
| 82 | +```bash |
| 83 | +./mach build faster |
| 84 | +``` |
| 85 | + |
| 86 | +This should be faster (a matter of seconds). |
| 87 | + |
| 88 | +Sometimes, if you haven't updated in a while, you'll be told that you need to *clobber*, or basically delete precompiled stuff and start from scratch, because there are too many changes. The way to do it is: |
| 89 | + |
| 90 | +```bash |
| 91 | +./mach clobber |
| 92 | +./mach build |
| 93 | +``` |
| 94 | + |
| 95 | +### Building even faster with artifact builds |
| 96 | + |
| 97 | +If you are *not* going to modify any C/C++ code (which is rare when working on DevTools), you can use artifact builds. This method downloads prebuilt binary components, and then the build process becomes faster. |
| 98 | + |
| 99 | +Create a file on the root of the repository, called `mozconfig`, with the following content: |
| 100 | + |
| 101 | +``` |
| 102 | +# Automatically download and use compiled C++ components: |
| 103 | +ac_add_options --enable-artifact-builds |
| 104 | + |
| 105 | +# Write build artifacts to: |
| 106 | +mk_add_options MOZ_OBJDIR=./objdir-frontend |
| 107 | +``` |
| 108 | + |
| 109 | +And then you can follow the normal build process again (only *faster*!) |
| 110 | + |
| 111 | +On MacOS you might want to use `MOZ_OBJDIR=./objdir-frontend.noindex` instead. Using the `.noindex` file extension prevents the Spotlight from indexing your `objdir`, which is slow. |
| 112 | + |
| 113 | +For more information on aspects such as technical limitations of artifact builds, read the [Artifact Builds](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds) page. |
| 114 | + |
| 115 | +## Maybe you don't even need to build |
| 116 | + |
| 117 | +Working in DevTools generally involves editing JavaScript files only. This means that often you don't even need to run `./mach build`. |
| 118 | + |
| 119 | +Instead, what you need to do is to save the files you modified, quit Firefox, and reopen it again to use the recently saved files. |
| 120 | + |
| 121 | +With pseudocode: |
| 122 | + |
| 123 | +``` |
| 124 | +# 1. Build |
| 125 | +./mach build |
| 126 | +# 2. Run |
| 127 | +./mach run |
| 128 | +# 3. you try out things in the browser that opens |
| 129 | +# 4. fully close the browser, e.g. ⌘Q in MacOS |
| 130 | +# 5. edit JS files on the `devtools` folder, save |
| 131 | +# 6. Back to step 2! |
| 132 | +./mach run |
| 133 | +``` |
| 134 | + |
| 135 | +While not as fast as the average "save file and reload the website" *web development workflow*, or newer workflows such as React's reloading, this can still be quite fast. |
| 136 | + |
| 137 | +And certainly faster than building each time, even with artifact builds. |
| 138 | + |
0 commit comments