docs/contributing/editor.rst

   1 Editor / IDE integration
   2 ========================
   3
   4 You can use any editor or IDE to contribute to Firefox, as long as it can edit
   5 text files. However, there are some steps specific to mozilla-central that may
   6 be useful for a better development experience. This page attempts to document
   7 them.
   8
   9 .. note::
  10
  11     This page is a work in progress. Please enhance this page with instructions
  12     for your favourite editor.
  13
  14 Visual Studio Code
  15 ------------------
  16
  17 .. toctree::
  18    :hidden:
  19    :maxdepth: 1
  20
  21    vscode
  22
  23
  24 Go to :doc:`Visual Studio Code <vscode>` dedicated page.
  25
  26 .. _VIM:
  27
  28 VIM
  29 ---
  30
  31 AutoCompletion
  32 ~~~~~~~~~~~~~~
  33
  34 There's C++ and Rust auto-completion support for VIM via
  35 `YouCompleteMe <https://github.com/ycm-core/YouCompleteMe/>`__. As long as that
  36 is installed and you have run :code:`./mach build` or :code:`./mach configure`,
  37 it should work out of the box. Configuration for this lives in
  38 :code:`.ycm_extra_conf` at the root of the repo.
  39
  40 If you don't like YouCompleteMe, other solutions also work, but they'll require
  41 you to create a :code:`compile_commands.json` file (see below for instructions).
  42
  43 Rust auto-completion should work both with the default completer (RLS, as of
  44 this writing), or with `rust-analyzer <https://rust-analyzer.github.io/manual.html#youcompleteme>`__.
  45
  46 ESLint
  47 ~~~~~~
  48
  49 The easiest way to integrate ESLint with VIM is using the `Syntastic plugin
  50 <https://github.com/vim-syntastic/syntastic>`__.
  51
  52 In order for VIM to detect jsm files as JS you might want something like this
  53 in your :code:`.vimrc`:
  54
  55 .. code::
  56
  57     autocmd BufRead,BufNewFile *.jsm set filetype=javascript
  58
  59 :code:`mach eslint --setup` installs a specific ESLint version and some ESLint
  60 plugins into the repositories' :code:`node_modules`.
  61
  62 You need something like this in your :code:`.vimrc` to run the checker
  63 automatically on save:
  64
  65 .. code::
  66
  67     autocmd FileType javascript,html,xhtml let b:syntastic_checkers = ['javascript/eslint']
  68
  69 You need to have :code:`eslint` in your :code:`PATH`, which you can get with
  70 :code:`npm install -g eslint`. You need at least version 6.0.0.
  71
  72 You can also use something like `eslint_d
  73 <https://github.com/mantoni/eslint_d.js#editor-integration>`__ which should
  74 also do that automatically:
  75
  76 .. code::
  77
  78     let g:syntastic_javascript_eslint_exec = 'eslint_d'
  79
  80 Emacs
  81 -----
  82
  83 Mozilla-specific packages
  84 ~~~~~~~~~~~~~~~~~~~~~~~~~
  85
  86 ESLint
  87 ~~~~~~
  88
  89 See `the devtools documentation <https://wiki.mozilla.org/DevTools/CodingStandards#Running_ESLint_in_Emacs>`__
  90 that describes how to integrate ESLint into Emacs.
  91
  92 C/C++ Development Packages
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 General Guidelines to Emacs C++ Programming
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 The following guides give an overview of the C++ editing capabilities of emacs.
  99
 100 It is worth reading through these guides to see what features are available.
 101 The rest of this section is dedicated to Mozilla/Gecko specific setup for
 102 packages.
 103
 104
 105   * `C/C++ Development Environment for Emacs <https://tuhdo.github.io/c-ide.html>`__
 106   * `Emacs as C++ IDE <https://syamajala.github.io/c-ide.html>`__
 107
 108 rtags (LLVM/Clang-based Code Indexing)
 109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 110
 111 Instructions for the installation of rtags are available at the
 112 `rtags github repo <https://github.com/Andersbakken/rtags>`__.
 113
 114 rtags requires a :ref:`compilation database <CompileDB back-end-compileflags>`.
 115
 116 In order for rtags to index correctly, included files need to be copied and
 117 unified compilation files need to be created. Either run a full build of the
 118 tree, or if you only want indexes to be generated for the moment, run the
 119 following commands (assuming you're in the gecko repo root):
 120
 121 .. code::
 122     cd gecko_build_directory
 123     make export
 124     ./config.status
 125
 126 To increase indexing speed, it's best to remove unified build files and test
 127 files from database updates. This can be done by creating a :code:`~/.rdmrc`
 128 file with the following contents, with :code:`[src_dir]` replaced with either
 129 the repo or build directory for your checkout:
 130
 131 .. code::
 132
 133     -X */[src_dir]/*Unified*;*/[src_dir]/*/test/*;*/[src_dir]/*/tests/*
 134
 135 Once the rdm daemon is running, the compilation database can be added to rtags
 136 like so:
 137
 138 .. code::
 139
 140     rc -J [gecko_build_directory]/compile_commands.json
 141
 142 Note that this process will take a while initially. However, once the database
 143 is built, it will only require incremental updates. As long as the rdm daemon
 144 is running in the background, the database will be updated based on changes to
 145 files.
 146
 147 irony (LLVM/Clang-based Code Completion)
 148 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 149
 150 Instructions on the installation of irony-mode are available at the
 151 `irony-mode github repo <https://github.com/Sarcasm/irony-mode>`__.
 152
 153 irony-mode requires a :ref:`compilation database <CompileDB back-end-compileflags>`.
 154
 155 Note that irony-mode, by default, uses elisp to parse the
 156 :code:`compile_commands.json` file. As gecko is a very large codebase, this
 157 file can easily be multiple megabytes, which can make irony-mode take multiple
 158 seconds to load on a gecko file.
 159
 160 It is recommended to use `this fork of irony-mode <https://github.com/Hylen/irony-mode/tree/compilation-database-guessing-4-pull-request>`__,
 161 which requires the boost System and Filesystem libraries.
 162
 163 `Checking the bug to get this patch into the mainline of irony-mode <https://github.com/Sarcasm/irony-mode/issues/176>`__
 164 is recommended, to see if the fork can be used or if the mainline repo can be
 165 used. Using the Boost version of the irony-mode server brings file load times
 166 to under 1s.
 167
 168 Projectile (Project Management)
 169 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 170
 171 Instructions on the installation of projectile are available at the
 172 `projectile github repo <https://github.com/bbatsov/projectile>`__.
 173
 174 Projectile comes preconfigured for many project types. Since, gecko uses its
 175 own special build system (mach), a new project type needs to be added. This can
 176 be done via adding the following elisp configuration command to your emacs
 177 configuration file.
 178
 179 .. code::
 180
 181     (projectile-register-project-type 'gecko
 182                                       '("mach" "moz.build")
 183                                       "python mach --log-no-times build"
 184                                       "python mach mochitest"
 185                                       "python mach run")
 186
 187 Assuming projectile-global-mode is on, this will allow projectile to run the
 188 correct commands whenever it is working in a gecko repo.
 189
 190 gdb
 191 ^^^
 192
 193 Emacs comes with great integration with gdb, especially when using
 194 `gdb-many-windows <https://www.gnu.org/software/emacs/manual/html_node/emacs/GDB-User-Interface-Layout.html>`__.
 195
 196 However, when gdb is invoked via mach, some special arguments
 197 need to be passed in order to make sure the correct display mode is used. To
 198 use M-x gdb with mach on firefox, use the following command:
 199
 200 .. code::
 201
 202     gecko_repo_directory/mach run --debug --debugparams=-i=mi
 203
 204 Eclipse
 205 -------
 206
 207 You can generate an Eclipse project by running:
 208
 209 .. code::
 210
 211     ./mach ide eclipse
 212
 213 See also the `Eclipse CDT <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Eclipse/Eclipse_CDT>`__ docs on MDN.
 214
 215 Visual Studio
 216 -------------
 217
 218 You can run a Visual Studio project by running:
 219
 220 .. code::
 221
 222     ./mach ide visualstudio
 223
 224 .. _CompileDB back-end-compileflags:
 225
 226 CompileDB back-end / compileflags
 227 ---------------------------------
 228
 229 You can generate a :code:`compile_commands.json` in your object directory by
 230 running:
 231
 232 .. code::
 233
 234     ./mach build-backend --backend=CompileDB
 235
 236 This file, the compilation database, is understood by a variety of C++ editors / IDEs
 237 to provide auto-completion capabilities. You can also get an individual compile command by
 238 running:
 239
 240 .. code::
 241
 242     ./mach compileflags path/to/file
 243
 244 This is how the :ref:`VIM <VIM>` integration works, for example.