From 0b2e28cb2e23f45d0dd6af7c1ef711d719a2863d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emilio=20Cobos=20=C3=81lvarez?= Date: Wed, 15 Apr 2020 14:47:15 +0000 Subject: [PATCH] Bug 1629708 - Port emacs docs to the in-tree docs. r=sylvestre Differential Revision: https://phabricator.services.mozilla.com/D71052 --HG-- extra : moz-landing-system : lando --- docs/contributing/editor.rst | 134 +++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/docs/contributing/editor.rst b/docs/contributing/editor.rst index 6ce28890a92d..74d6e5e831eb 100644 --- a/docs/contributing/editor.rst +++ b/docs/contributing/editor.rst @@ -82,6 +82,140 @@ also do that automatically: let g:syntastic_javascript_eslint_exec = 'eslint_d' +Emacs +----- + +Mozilla-specific packages +~~~~~~~~~~~~~~~~~~~~~~~~~ + +dxr.el +^^^^^^ + +dxr.el is an elisp package that enables searching of DXR Code Indexer results +from within emacs. Using this can sometimes be easier than doing localized code +indexing with rtags, as rtags processing of code trees can be very processing +intensive. + +dxr.el is available via `github repo `__, or +via the Marmalade package manager. + +ESLint +~~~~~~ + +See `the devtools documentation `__ +that describes how to integrate ESLint into Emacs. + +C/C++ Development Packages +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +General Guidelines to Emacs C++ Programming +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following guides give an overview of the C++ editing capabilities of emacs. + +It is worth reading through these guides to see what features are available. +The rest of this section is dedicated to Mozilla/Gecko specific setup for +packages. + + + * `C/C++ Development Environment for Emacs `__ + * `Emacs as C++ IDE `__ + +rtags (LLVM/Clang-based Code Indexing) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instructions for the installation of rtags are available at the +`rtags github repo `__. + +rtags requires a :ref:`compilation database `. + +In order for rtags to index correctly, included files need to be copied and +unified compilation files need to be created. Either run a full build of the +tree, or if you only want indexes to be generated for the moment, run the +following commands (assuming you're in the gecko repo root): + +.. code:: + cd gecko_build_directory + make export + ./config.status + +To increase indexing speed, it's best to remove unified build files and test +files from database updates. This can be done by creating a :code:`~/.rdmrc` +file with the following contents, with :code:`[src_dir]` replaced with either +the repo or build directory for your checkout: + +.. code:: + + -X */[src_dir]/*Unified*;*/[src_dir]/*/test/*;*/[src_dir]/*/tests/* + +Once the rdm daemon is running, the compilation database can be added to rtags +like so: + +.. code:: + + rc -J [gecko_build_directory]/compile_commands.json + +Note that this process will take a while initially. However, once the database +is built, it will only require incremental updates. As long as the rdm daemon +is running in the background, the database will be updated based on changes to +files. + +irony (LLVM/Clang-based Code Completion) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instructions on the installation of irony-mode are available at the +`irony-mode github repo `__. + +irony-mode requires a :ref:`compilation database `. + +Note that irony-mode, by default, uses elisp to parse the +:code:`compile_commands.json` file. As gecko is a very large codebase, this +file can easily be multiple megabytes, which can make irony-mode take multiple +seconds to load on a gecko file. + +It is recommended to use `this fork of irony-mode `__, +which requires the boost System and Filesystem libraries. + +`Checking the bug to get this patch into the mainline of irony-mode `__ +is recommended, to see if the fork can be used or if the mainline repo can be +used. Using the Boost version of the irony-mode server brings file load times +to under 1s. + +Projectile (Project Management) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instructions on the installation of projectile are available at the +`projectile github repo `__. + +Projectile comes preconfigured for many project types. Since, gecko uses its +own special build system (mach), a new project type needs to be added. This can +be done via adding the following elisp configuration command to your emacs +configuration file. + +.. code:: + + (projectile-register-project-type 'gecko + '("mach" "moz.build") + "python mach --log-no-times build" + "python mach mochitest" + "python mach run") + +Assuming projectile-global-mode is on, this will allow projectile to run the +correct commands whenever it is working in a gecko repo. + +gdb +^^^ + +Emacs comes with great integration with gdb, especially when using +`gdb-many-windows `__. + +However, when gdb is invoked via mach, some special arguments +need to be passed in order to make sure the correct display mode is used. To +use M-x gdb with mach on firefox, use the following command: + +.. code:: + + gecko_repo_directory/mach run --debug --debugparams=-i=mi Eclipse -------