diff options
Diffstat (limited to 'docs/contributing/editors')
| -rw-r--r-- | docs/contributing/editors/emacs.rst | 121 | ||||
| -rw-r--r-- | docs/contributing/editors/others.rst | 41 | ||||
| -rw-r--r-- | docs/contributing/editors/vim.rst | 75 | ||||
| -rw-r--r-- | docs/contributing/editors/vscode.rst | 179 |
4 files changed, 416 insertions, 0 deletions
diff --git a/docs/contributing/editors/emacs.rst b/docs/contributing/editors/emacs.rst new file mode 100644 index 0000000000..fbd41195a1 --- /dev/null +++ b/docs/contributing/editors/emacs.rst @@ -0,0 +1,121 @@ +Emacs +===== + +ESLint +------ + +See `the devtools documentation <https://wiki.mozilla.org/DevTools/CodingStandards#Running_ESLint_in_Emacs>`__ +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 <https://tuhdo.github.io/c-ide.html>`__ + * `Emacs as C++ IDE <https://syamajala.github.io/c-ide.html>`__ + +rtags (LLVM/Clang-based Code Indexing) +-------------------------------------- + +Instructions for the installation of rtags are available at the +`rtags github repo <https://github.com/Andersbakken/rtags>`__. + +rtags requires a :ref:`compilation database <CompileDB back-end-compileflags>`. + +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 <https://github.com/Sarcasm/irony-mode>`__. + +irony-mode requires a :ref:`compilation database <CompileDB back-end-compileflags>`. + +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 <https://github.com/Hylen/irony-mode/tree/compilation-database-guessing-4-pull-request>`__, +which requires the boost System and Filesystem libraries. + +`Checking the bug to get this patch into the mainline of irony-mode <https://github.com/Sarcasm/irony-mode/issues/176>`__ +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 <https://github.com/bbatsov/projectile>`__. + +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 <https://www.gnu.org/software/emacs/manual/html_node/emacs/GDB-User-Interface-Layout.html>`__. + +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 diff --git a/docs/contributing/editors/others.rst b/docs/contributing/editors/others.rst new file mode 100644 index 0000000000..b753ff1042 --- /dev/null +++ b/docs/contributing/editors/others.rst @@ -0,0 +1,41 @@ +Eclipse +======= + +You can generate an Eclipse project by running: + +.. code:: + + ./mach ide eclipse + +See also the `Eclipse CDT <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Eclipse/Eclipse_CDT>`__ docs on MDN. + +Visual Studio +============= + +You can run a Visual Studio project by running: + +.. code:: + + ./mach ide visualstudio + +.. _CompileDB back-end-compileflags: + +CompileDB back-end / compileflags +================================= + +You can generate a :code:`compile_commands.json` in your object directory by +running: + +.. code:: + + ./mach build-backend --backend=CompileDB + +This file, the compilation database, is understood by a variety of C++ editors / IDEs +to provide auto-completion capabilities. You can also get an individual compile command by +running: + +.. code:: + + ./mach compileflags path/to/file + +This is how the :ref:`VIM <VIM>` integration works, for example. diff --git a/docs/contributing/editors/vim.rst b/docs/contributing/editors/vim.rst new file mode 100644 index 0000000000..0cce21d4e9 --- /dev/null +++ b/docs/contributing/editors/vim.rst @@ -0,0 +1,75 @@ +Vim / Neovim +============ + +AutoCompletion +-------------- + +For C++, anything that can use an LSP like :code:`coc.nvim`, +:code:`nvim-lspconfig`, or what not, should work as long as you generate a +:ref:`compilation database <CompileDB back-end-compileflags>` and point to it. + +Additionally, `YouCompleteMe <https://github.com/ycm-core/YouCompleteMe/>`__ +works without the need of a C++ compilation database as long as you have run +:code:`./mach build` or :code:`./mach configure`. Configuration for this lives +in :searchfox:`.ycm_extra_conf <.ycm_extra_conf>` at the root of the repo. + +Rust auto-completion should work both with Rust's LSP :code:`rust-analyzer`. + +Make sure that the LSP is configured in a way that it detects the root of the +tree as a workspace, not the crate you happen to be editing. For example, the +default of :code:`nvim-lspconfig` is to search for the closest +:code:`Cargo.toml` file, which is not what you want. You'd want something like: + +.. code :: + + root_dir = lspconfig.util.root_pattern(".git", ".hg") + +You also need to set some options to get full diagnostics: + +.. code :: + + "rust-analyzer.server.extraEnv": { + "CARGO_TARGET_DIR": "/path/to/objdir" + }, + "rust-analyzer.check.overrideCommand": [ "/path/to/mach", "--log-no-times", "cargo", "check", "--all-crates", "--message-format-json" ], + "rust-analyzer.cargo.buildScripts.overrideCommand": [ "/path/to/mach", "--log-no-times", "cargo", "check", "--all-crates", "--message-format-json" ], + +The easiest way to make these work out of the box is using +`neoconf <https://github.com/folke/neoconf.nvim/>`__, which +automatically supports importing VSCode configuration files. +:code:`./mach ide vscode --no-interactive` will then generate the right +configuration for you. + +ESLint +------ + +The easiest way to integrate ESLint with VIM is using the `Syntastic plugin +<https://github.com/vim-syntastic/syntastic>`__. + +In order for VIM to detect jsm files as JS you might want something like this +in your :code:`.vimrc`: + +.. code:: + + autocmd BufRead,BufNewFile *.jsm set filetype=javascript + +:code:`mach eslint --setup` installs a specific ESLint version and some ESLint +plugins into the repositories' :code:`node_modules`. + +You need something like this in your :code:`.vimrc` to run the checker +automatically on save: + +.. code:: + + autocmd FileType javascript,html,xhtml let b:syntastic_checkers = ['javascript/eslint'] + +You need to have :code:`eslint` in your :code:`PATH`, which you can get with +:code:`npm install -g eslint`. You need at least version 6.0.0. + +You can also use something like `eslint_d +<https://github.com/mantoni/eslint_d.js#editor-integration>`__ which should +also do that automatically: + +.. code:: + + let g:syntastic_javascript_eslint_exec = 'eslint_d' diff --git a/docs/contributing/editors/vscode.rst b/docs/contributing/editors/vscode.rst new file mode 100644 index 0000000000..9830dcbe4f --- /dev/null +++ b/docs/contributing/editors/vscode.rst @@ -0,0 +1,179 @@ +Visual Studio Code +================== + +.. toctree:: + :maxdepth: 1 + :glob: + +General Knowledge +----------------- + +`VSCode <https://code.visualstudio.com/>`__ is a multi-platform open-source programming editor developed by Microsoft and volunteers. +It has support for many programming languages using extensions. +This is the recommended editor for Firefox development. + +For more general information on the VSCode project see the `repository <https://github.com/Microsoft/vscode/>`__. + +Recommended extensions +---------------------- + +VS Code provides number of extensions for JavaScript, Rust, etc. By default, +Firefox source tree comes with its own set of recommendations of Visual Studio +Code extensions. They will be offered when you first open the project. + +If you need to refer to them later, the extensions are listed in +`.vscode/extensions.json <https://searchfox.org/mozilla-central/source/.vscode/extensions.json>`__. + +For Rust development, the `rust-analyzer <https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer>`__ extension is recommended. +`See the manual <https://rust-analyzer.github.io/manual.html>`__ for more information. + +Getting setup +------------- + +Close `VS Code` if it is already open, then build the configuration for `VS Code` +by simplying running from the terminal: + +.. code:: + + ./mach ide vscode + +This will automatically set some of the recommended preferences for the workspace, +and if you are set up for a full build, it will enable clangd and rust integrations. + +If successful, `VS Code` will open at the end. You do not need to run this command +every time to open `VS Code`, you may open it in the normal way. + +If you are running full builds, the command above will set up the `Clangd` +integration so that subsequent invocations of ``./mach build`` run and update the +integration. + +.. note:: + + If `VS Code` is already open with a previous configuration generated, please make sure to + restart `VS Code` otherwise the new configuration will not be used, and the `compile_commands.json` + needed by `clangd` server will not be refreshed. This is a known `bug <https://github.com/clangd/vscode-clangd/issues/42>`__ + in `clangd-vscode` extension + +Ignore Files in Mercurial Repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using Mercurial in mozilla-central, VS Code will treat your build directories as ordinary directories by default, causing some undesirable behavior including long indexing times, Go to Definition will open files in the build directory instead of the source tree, and Search Files by Name will find duplicate files from the source tree and the build directory (note: when using Git, VS Code will not do this since it reads ``.gitignore``). You can follow these directions to have VS Code largely ignore your build directories: + +#. Go to Preferences -> Settings +#. Search "exclude" in the Settings +#. (optional) Select "Workspace" below the search bar to only change this setting for the mozilla-central repository +#. Under "Files: Exclude", click "Add Pattern", type ``obj-*`` (assuming your build directory names start with the default text, ``obj-``), and click "OK" +#. Repeat the step above for the "Files: Watcher Exclude" setting +#. Reload VS Code: the easiest way to do this is to quit and reopen it. + +Despite excluding the build directories above, Go to Definition will still correctly open files that only appear in the build directory such as generated source code. See `Bug 1790517 <https://bugzilla.mozilla.org/show_bug.cgi?id=1790517>`_ for our effort to automatically exclude the build directories. + +Recommended Preferences +~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + These are automatically set when running ``./mach ide vscode`` but may be + changed manually. These are set only for particular file types. + +* ``"editor.formatOnSave": true`` + * This will turn on automatically fixing formatting issues when you save a file. +* ``"editor.defaultFormatter": "esbenp.prettier-vscode"`` + * This sets the default formatter to prettier using the recommended prettier + extension. + +``*.jsm`` and ``*.sjs`` file extensions should also be associated with JavaScript: + +.. code:: + + "files.associations": { + "*.jsm": "javascript", + "*.sjs": "javascript", + }, + +C/C++ Features and Support +-------------------------- + +For C++ support we offer an out of the box configuration based on +`clangd <https://clangd.llvm.org>`__. + +Leveraging the `clang` toolchain compiler we now have support in the IDE for the following features: + +**1.** Syntax highlighting + +**2.** IntelliSense with comprehensive code completion and suggestion + +.. image:: ../img/auto_completion.gif + +**3.** Go-to definition and Go-to declaration + +.. image:: ../img/goto_definition.gif + +**4.** Find all references + +.. image:: ../img/find_references.gif + +**5.** Open type hierarchy + +.. image:: ../img/type_hierarchy.gif + +**6.** Rename symbol, all usages of the symbol will be renamed, including declaration, definition and references + +.. image:: ../img/rename_symbol.gif + +**7.** Code formatting, based on `clang-format` that respects our coding standard using the `.clang-format` and `.clang-format-ignore` files. Format can be performed on an entire file or on a code selection + +.. image:: ../img/format_selection.gif + +**8.** Inline parsing errors with limited auto-fix hints + +.. image:: ../img/diagnostic_error.gif + +**9.** Basic static-code analysis using `clang-tidy` and our list of enabled checkers. (This is still in progress not all checkers are supported by `clangd`) + +Clangd-specific Commands +------------------------ + +Clangd supports some commands that are specific to C/C++: + +.. code:: + + "clangd.switchheadersource" + +This command navigates from the currently open header file to its corresponding source file (if there is one), or vice versa. + +This command can be invoked from the command menu (activated via ``F1``), or using its keybinding of ``Alt+o`` (``Alt+cmd+o`` on Mac). The keybinding can also be customized in ``Keyboard Shortcuts``. + +Remote Development over SSH +--------------------------- + +VS Code provides an `extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh>`__ that lets you use any remote machine with a SSH server as your development environment. No matter if it's Linux based, macOS or Windows, as long as the target machine offers a SSH connection, it can be used for development. + +No source code needs to be on your local machine to use VS Code remotely since the extension runs commands and other extensions directly on the remote machine. + +In order to setup a connection please follow these steps: + +**1.** Open VS Code and select from the left side panel ``Remote Explorer`` + +.. image:: ../img/remote_explorer.png + +**2.** From the ``Remote Explorer`` panel select ``SSH Targets`` and click on ``Add`` and enter the connection details + +.. image:: ../img/remote_explorer_add.png + +.. image:: ../img/remote_explorer_add_wind.png + +**3.** Click on the connection that you just configured at the previous step + +**4.** Finally you should be connected to the desired remote SSH server + +.. image:: ../img/connection_done.png + +Please note that during the first connection VS Code will install itself remotely and also install all of the needed dependencies. + + + +Filing Bugs +----------- + +Bugs should be filed in the `Firefox Build System` product under `Developer Environment Integration`, preferably blocking `Bug 1662709 <https://bugzilla.mozilla.org/show_bug.cgi?id=1662709>`__. |