From 771a8f70da1dcef5a2f63bc3a6a8bc4f2df6f071 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Wed, 27 Oct 2021 03:18:38 +0200 Subject: [PATCH] docs: update development-related documentation (#31043) * docs: update chromium development-related documentation * chore: remove obsolete clang-format doc clang-format linting and fixing is a pre-commit hook now * docs: update debugging documentation * docs: misc updates * Update docs/development/debugging-on-windows.md Co-authored-by: Micha Hanselmann * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/README.md Co-authored-by: Mark Lee * Update docs/development/debugging-on-macos.md Co-authored-by: Mark Lee * Update docs/development/testing.md Co-authored-by: Mark Lee * Update docs/development/testing.md Co-authored-by: Mark Lee Co-authored-by: Micha Hanselmann Co-authored-by: Mark Lee Co-authored-by: Cheng Zhao --- docs/development/README.md | 74 ++++++++++++++--- docs/development/build-instructions-gn.md | 13 +++ docs/development/build-system-overview.md | 80 ------------------- docs/development/chromium-development.md | 44 +++++++--- docs/development/clang-format.md | 35 -------- docs/development/coding-style.md | 5 +- ...uctions-macos.md => debugging-on-macos.md} | 21 +++-- ...ons-windows.md => debugging-on-windows.md} | 19 ++++- ...ver.md => debugging-with-symbol-server.md} | 0 ...macos-xcode.md => debugging-with-xcode.md} | 0 docs/development/debugging.md | 49 ++++++++++++ docs/development/goma.md | 8 +- docs/development/pull-requests.md | 16 +--- docs/development/testing.md | 47 ++++++----- docs/tutorial/windows-arm.md | 2 +- 15 files changed, 227 insertions(+), 186 deletions(-) delete mode 100644 docs/development/build-system-overview.md delete mode 100644 docs/development/clang-format.md rename docs/development/{debugging-instructions-macos.md => debugging-on-macos.md} (86%) rename docs/development/{debug-instructions-windows.md => debugging-on-windows.md} (81%) rename docs/development/{setting-up-symbol-server.md => debugging-with-symbol-server.md} (100%) rename docs/development/{debugging-instructions-macos-xcode.md => debugging-with-xcode.md} (100%) create mode 100644 docs/development/debugging.md diff --git a/docs/development/README.md b/docs/development/README.md index c472d8f485..6ddbbcdbae 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -4,23 +4,77 @@ These guides are intended for people working on the Electron project itself. For guides on Electron app development, see [/docs/README.md](../README.md#guides-and-tutorials). -* [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) -* [Contributing to Electron](https://github.com/electron/electron/blob/main/CONTRIBUTING.md) +## Table of Contents + * [Issues](issues.md) * [Pull Requests](pull-requests.md) * [Documentation Styleguide](coding-style.md#documentation) * [Source Code Directory Structure](source-code-directory-structure.md) * [Coding Style](coding-style.md) -* [Using clang-format on C++ Code](clang-format.md) * [Using clang-tidy on C++ Code](clang-tidy.md) -* [Build System Overview](build-system-overview.md) -* [Build Instructions (macOS)](build-instructions-macos.md) -* [Build Instructions (Windows)](build-instructions-windows.md) -* [Build Instructions (Linux)](build-instructions-linux.md) +* [Build Instructions](build-instructions-gn.md) + * [macOS](build-instructions-macos.md) + * [Windows](build-instructions-windows.md) + * [Linux](build-instructions-linux.md) * [Chromium Development](chromium-development.md) * [V8 Development](v8-development.md) * [Testing](testing.md) -* [Debugging on Windows](debug-instructions-windows.md) -* [Debugging on macOS](debugging-instructions-macos.md) -* [Setting Up Symbol Server in Debugger](setting-up-symbol-server.md) +* [Debugging](debugging.md) * [Patches](patches.md) + +## Getting Started + +In order to contribute to Electron, the first thing you'll want to do is get the code. + +[Electron's `build-tools`](https://github.com/electron/build-tools) automate much of the setup for compiling Electron from source with different configurations and build targets. + +If you would prefer to build Electron manually, see the [build instructions](build-instructions-gn.md). + +Once you've checked out and built the code, you may want to take a look around the source tree to get a better idea +of what each directory is responsible for. The [source code directory structure](source-code-directory-structure.md) gives a good overview of the purpose of each directory. + +## Opening Issues on Electron + +For any issue, there are generally three ways an individual can contribute: + +1. By opening the issue for discussion + * If you believe that you have found a new bug in Electron, you should report it by creating a new issue in + the [`electron/electron` issue tracker](https://github.com/electron/electron/issues). +2. By helping to triage the issue + * You can do this either by providing assistive details (a reproducible test case that demonstrates a bug) or by providing suggestions to address the issue. +3. By helping to resolve the issue + * This can be done by demonstrating that the issue is not a bug or is fixed; + but more often, by opening a pull request that changes the source in `electron/electron` + in a concrete and reviewable manner. + +See [issues](issues.md) for more information. + +## Making a Pull Request to Electron + +Most pull requests opened against the `electron/electron` repository include +changes to either the C/C++ code in the `shell/` folder, +the TypeScript code in the `lib/` folder, the documentation in `docs/`, +or tests in the `spec/` and `spec-main/` folders. + +See [pull requests](pull-requests.md) for more information. + +If you want to add a new API module to Electron, you'll want to look in [creating API](creating-api.md). + +## Governance + +Electron has a fully-fledged governance system that oversees activity in Electron and whose working groups are responsible for areas like APIs, releases, and upgrades to Electron's dependencies including Chromium and Node.js. Depending on how frequently and to what end you want to contribute, you may want to consider joining a working group. + +Details about each group and their reponsibilities can be found in the [governance repo](https://github.com/electron/governance). + +## Patches in Electron + +Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases. + +As such, we maintain a collection of patches as part of our source tree. The process for adding or altering one of these patches to Electron's source tree via a pull request can be found in [patches](patches.md). + +## Debugging + +There are many different approaches to debugging issues and bugs in Electron, many of which +are platform specific. + +For an overview of information related to debugging Electron itself (and not an app _built with Electron_), see [debugging](debugging.md). diff --git a/docs/development/build-instructions-gn.md b/docs/development/build-instructions-gn.md index 9ea0e419fb..3da281866e 100644 --- a/docs/development/build-instructions-gn.md +++ b/docs/development/build-instructions-gn.md @@ -16,6 +16,19 @@ Check the build prerequisites for your platform before proceeding [Electron's Build Tools](https://github.com/electron/build-tools) automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below. +Electron uses [GN](https://gn.googlesource.com/gn) for project generation and +[ninja](https://ninja-build.org/) for building. Project configurations can +be found in the `.gn` and `.gni` files. + +## GN Files + +The following `gn` files contain the main rules for building Electron: + +* `BUILD.gn` defines how Electron itself is built and + includes the default configurations for linking with Chromium. +* `build/args/{testing,release,all}.gn` contain the default build arguments for + building Electron. + ## GN prerequisites You'll need to install [`depot_tools`][depot-tools], the toolset diff --git a/docs/development/build-system-overview.md b/docs/development/build-system-overview.md deleted file mode 100644 index bb5a0d60cc..0000000000 --- a/docs/development/build-system-overview.md +++ /dev/null @@ -1,80 +0,0 @@ -# Build System Overview - -Electron uses [GN](https://gn.googlesource.com/gn) for project generation and -[ninja](https://ninja-build.org/) for building. Project configurations can -be found in the `.gn` and `.gni` files. - -## GN Files - -The following `gn` files contain the main rules for building Electron: - -* `BUILD.gn` defines how Electron itself is built and - includes the default configurations for linking with Chromium. -* `build/args/{debug,release,all}.gn` contain the default build arguments for - building Electron. - -## Component Build - -Since Chromium is quite a large project, the final linking stage can take -quite a few minutes, which makes it hard for development. In order to solve -this, Chromium introduced the "component build", which builds each component as -a separate shared library, making linking very quick but sacrificing file size -and performance. - -Electron inherits this build option from Chromium. In `Debug` builds, the -binary will be linked to a shared library version of Chromium's components to -achieve fast linking time; for `Release` builds, the binary will be linked to -the static library versions, so we can have the best possible binary size and -performance. - -## Tests - -**NB** _this section is out of date and contains information that is no longer -relevant to the GN-built electron._ - -Test your changes conform to the project coding style using: - -```sh -$ npm run lint -``` - -Test functionality using: - -```sh -$ npm test -``` - -Whenever you make changes to Electron source code, you'll need to re-run the -build before the tests: - -```sh -$ npm run build && npm test -``` - -You can make the test suite run faster by isolating the specific test or block -you're currently working on using Mocha's -[exclusive tests](https://mochajs.org/#exclusive-tests) feature. Append -`.only` to any `describe` or `it` function call: - -```js -describe.only('some feature', () => { - // ... only tests in this block will be run -}) -``` - -Alternatively, you can use mocha's `grep` option to only run tests matching the -given regular expression pattern: - -```sh -$ npm test -- --grep child_process -``` - -Tests that include native modules (e.g. `runas`) can't be executed with the -debug build (see [#2558](https://github.com/electron/electron/issues/2558) for -details), but they will work with the release build. - -To run the tests with the release build use: - -```sh -$ npm test -- -R -``` diff --git a/docs/development/chromium-development.md b/docs/development/chromium-development.md index 6b7b6d47b5..6ad450dfbc 100644 --- a/docs/development/chromium-development.md +++ b/docs/development/chromium-development.md @@ -1,13 +1,39 @@ # Chromium Development -> A collection of resources for learning about Chromium and tracking its development - -- [@ChromiumDev](https://twitter.com/ChromiumDev) on Twitter -- [@googlechrome](https://twitter.com/googlechrome) on Twitter -- [Blog](https://blog.chromium.org) -- [Code Search](https://cs.chromium.org/) -- [Source Code](https://cs.chromium.org/chromium/src/) -- [Development Calendar and Release Info](https://www.chromium.org/developers/calendar) -- [Discussion Groups](https://www.chromium.org/developers/discussion-groups) +> A collection of resources for learning about Chromium and tracking its development. See also [V8 Development](v8-development.md) + +## Contributing to Chromium + +- [Checking Out and Building](https://chromium.googlesource.com/chromium/src/+/main/docs/#checking-out-and-building) + - [Windows](https://chromium.googlesource.com/chromium/src/+/main/docs/windows_build_instructions.md) + - [macOS](https://chromium.googlesource.com/chromium/src/+/main/docs/mac_build_instructions.md) + - [Linux](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md) + +- [Contributing](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/contributing.md) - This document outlines the process of getting a code change merged to the Chromium source tree. + - Assumes a working Chromium checkout and build. + +## Resources for Chromium Development + +### Code Resources + +- [Code Search](https://cs.chromium.org/) - Indexed and searchable source code for Chromium and associated projects. +- [Source Code](https://cs.chromium.org/chromium/src/) - The source code for Chromium itself. +- [Chromium Review](https://chromium-review.googlesource.com) - The searchable code host which facilitates code reviews for Chromium and related projects. + +### Informational Resources + +- [Chromium Dash](https://chromiumdash.appspot.com/home) - Chromium Dash ties together multiple data sources in order to present a consolidated view of what's going on in Chromium and Chrome, plus related projects like V8, WebRTC & Skia. + - [Schedule](https://chromiumdash.appspot.com/schedule) - Review upcoming Chromium release schedule. + - [Branches](https://chromiumdash.appspot.com/branches) - Look up which branch corresponds to which milestone. + - [Releases](https://chromiumdash.appspot.com/releases) - See what version of Chromium is shipping to each release channel and look up changes between each version. + - [Commits](https://chromiumdash.appspot.com/commits) - See and search for commits to the Chromium source tree by commit SHA or committer username. +- [Discussion Groups](https://www.chromium.org/developers/discussion-groups) - Subscribe to the following groups to get project updates and discuss the Chromium projects, and to get help in developing for Chromium-based browsers. +- [Chromium Slack](https://www.chromium.org/developers/slack) - a virtual meeting place where Chromium ecosystem developers can foster community and coordinate work. + +## Social Links + +- [Blog](https://blog.chromium.org) - News and developments from Chromium. +- [@ChromiumDev](https://twitter.com/ChromiumDev) - Twitter account containing news & guidance for developers from the Google Chrome Developer Relations team. +- [@googlechrome](https://twitter.com/googlechrome) - Official Twitter account for the Google Chrome browser. diff --git a/docs/development/clang-format.md b/docs/development/clang-format.md deleted file mode 100644 index 410a721bd5..0000000000 --- a/docs/development/clang-format.md +++ /dev/null @@ -1,35 +0,0 @@ -# Using clang-format on C++ Code - -[`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) is a tool to -automatically format C/C++/Objective-C code, so that developers don't need to -worry about style issues during code reviews. - -It is highly recommended to format your changed C++ code before opening pull -requests, which will save you and the reviewers' time. - -You can install `clang-format` and `git-clang-format` via -`npm install -g clang-format`. - -To automatically format a file according to Electron C++ code style, run -`clang-format -i path/to/electron/file.cc`. It should work on macOS/Linux/Windows. - -The workflow to format your changed code: - -1. Make codes changes in Electron repository. -2. Run `git add your_changed_file.cc`. -3. Run `git-clang-format`, and you will probably see modifications in - `your_changed_file.cc`, these modifications are generated from `clang-format`. -4. Run `git add your_changed_file.cc`, and commit your change. -5. Now the branch is ready to be opened as a pull request. - -If you want to format the changed code on your latest git commit (HEAD), you can -run `git-clang-format HEAD~1`. See `git-clang-format -h` for more details. - -## Editor Integration - -You can also integrate `clang-format` directly into your favorite editors. -For further guidance on setting up editor integration, see these pages: - -* [Atom](https://atom.io/packages/clang-format) -* [Vim & Emacs](https://clang.llvm.org/docs/ClangFormat.html#vim-integration) -* [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) diff --git a/docs/development/coding-style.md b/docs/development/coding-style.md index 498740061f..ac12d05979 100644 --- a/docs/development/coding-style.md +++ b/docs/development/coding-style.md @@ -25,9 +25,8 @@ You can run `npm run lint` to show any style issues detected by `cpplint` and ## C++ and Python For C++ and Python, we follow Chromium's [Coding -Style](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md). You can use -[clang-format](clang-format.md) to format the C++ code automatically. There is -also a script `script/cpplint.py` to check whether all files conform. +Style](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md). +There is also a script `script/cpplint.py` to check whether all files conform. The Python version we are using now is Python 2.7. diff --git a/docs/development/debugging-instructions-macos.md b/docs/development/debugging-on-macos.md similarity index 86% rename from docs/development/debugging-instructions-macos.md rename to docs/development/debugging-on-macos.md index e059ac5f97..163df8e5aa 100644 --- a/docs/development/debugging-instructions-macos.md +++ b/docs/development/debugging-on-macos.md @@ -2,25 +2,22 @@ If you experience crashes or issues in Electron that you believe are not caused by your JavaScript application, but instead by Electron itself, debugging can -be a little bit tricky, especially for developers not used to native/C++ -debugging. However, using lldb, and the Electron source code, you can enable +be a little bit tricky especially for developers not used to native/C++ +debugging. However, using `lldb` and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code. -You can also use [XCode for debugging](debugging-instructions-macos-xcode.md) if -you prefer a graphical interface. +You can also use [XCode for debugging](debugging-with-xcode.md) if you prefer a graphical interface. ## Requirements -* **A debug build of Electron**: The easiest way is usually building it - yourself, using the tools and prerequisites listed in the - [build instructions for macOS](build-instructions-macos.md). While you can - attach to and debug Electron as you can download it directly, you will - find that it is heavily optimized, making debugging substantially more - difficult: The debugger will not be able to show you the content of all +* **A testing build of Electron**: The easiest way is usually to build it from source, + which you can do by following the instructions in the [build instructions](./build-instructions-macos.md). While you can attach to and debug Electron as you can download it directly, you will + find that it is heavily optimized, making debugging substantially more difficult. + In this case the debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations. -* **Xcode**: In addition to Xcode, also install the Xcode command line tools. - They include LLDB, the default debugger in Xcode on macOS. It supports +* **Xcode**: In addition to Xcode, you should also install the Xcode command line tools. + They include [LLDB](https://lldb.llvm.org/), the default debugger in Xcode on macOS. It supports debugging C, Objective-C and C++ on the desktop and iOS devices and simulator. * **.lldbinit**: Create or edit `~/.lldbinit` to allow Chromium code to be properly source-mapped. diff --git a/docs/development/debug-instructions-windows.md b/docs/development/debugging-on-windows.md similarity index 81% rename from docs/development/debug-instructions-windows.md rename to docs/development/debugging-on-windows.md index f53c34d472..aa047bf680 100644 --- a/docs/development/debug-instructions-windows.md +++ b/docs/development/debugging-on-windows.md @@ -22,7 +22,7 @@ with breakpoints inside Electron's source code. * **Visual Studio with C++ Tools**: The free community editions of Visual Studio 2013 and Visual Studio 2015 both work. Once installed, - [configure Visual Studio to use Electron's Symbol server](setting-up-symbol-server.md). + [configure Visual Studio to use Electron's Symbol server](debugging-with-symbol-server.md). It will enable Visual Studio to gain a better understanding of what happens inside Electron, making it easier to present variables in a human-readable format. @@ -90,3 +90,20 @@ out [this video tutorial][procmon-instructions] provided by Microsoft. [sys-internals]: https://technet.microsoft.com/en-us/sysinternals/processmonitor.aspx [procmon-instructions]: https://channel9.msdn.com/shows/defrag-tools/defrag-tools-4-process-monitor + +## Using WinDbg + + +It's possible to debug crashes and issues in the Renderer process with [WinDbg](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/getting-started-with-windbg). + +To attach to a debug a process with WinDbg: + +1. Add `--renderer-startup-dialog` as a command line flag to Electron. +2. Launch the app you are intending to debug. +3. A dialog box will appear with a pid: “Renderer starting with pid: 1234”. +4. Launch WinDbg and choose “File > Attach to process” in the application menu. +5. Enter in pid from the dialog box in Step 3. +6. See that the debugger will be in a paused state, and that there is a command line in the app to enter text into. +7. Type “g” into the above command line to start the debuggee. +8. Press the enter key to continue the program. +9. Go back to the dialog box and press “ok”. diff --git a/docs/development/setting-up-symbol-server.md b/docs/development/debugging-with-symbol-server.md similarity index 100% rename from docs/development/setting-up-symbol-server.md rename to docs/development/debugging-with-symbol-server.md diff --git a/docs/development/debugging-instructions-macos-xcode.md b/docs/development/debugging-with-xcode.md similarity index 100% rename from docs/development/debugging-instructions-macos-xcode.md rename to docs/development/debugging-with-xcode.md diff --git a/docs/development/debugging.md b/docs/development/debugging.md new file mode 100644 index 0000000000..4c6cc27b06 --- /dev/null +++ b/docs/development/debugging.md @@ -0,0 +1,49 @@ +# Electron Debugging + +There are many different approaches to debugging issues and bugs in Electron, many of which +are platform specific. + +Some of the more common approaches are outlined below. + +## Generic Debugging + +Chromium contains logging macros which can aid debugging by printing information to console in C++ and Objective-C++. + +You might use this to print out variable values, function names, and line numbers, amonst other things. + +Some examples: + +```cpp +LOG(INFO) << "bitmap.width(): " << bitmap.width(); + +LOG(INFO, bitmap.width() > 10) << "bitmap.width() is greater than 10!"; +``` + +There are also different levels of logging severity: `INFO`, `WARN`, and `ERROR`. + +See [logging.h](https://chromium.googlesource.com/chromium/src/base/+/refs/heads/main/logging.h) in Chromium's source tree for more information and examples. + +## Printing Stacktraces + +Chromium contains a helper to print stack traces to console without interrrupting the program. + +```cpp +#include "base/debug/stack_trace.h" +... +base::debug::StackTrace().Print(); +``` + +This will allow you to observe call chains and identify potential issue areas. + +## Platform-Specific Debugging + + +- [macOS Debugging](debugging-on-macos.md) + - [Debugging with Xcode](debugging-with-xcode.md) +- [Windows Debugging](debugging-on-windows.md) + +## Debugging with the Symbol Server + +Debug symbols allow you to have better debugging sessions. They have information about the functions contained in executables and dynamic libraries and provide you with information to get clean call stacks. A Symbol Server allows the debugger to load the correct symbols, binaries and sources automatically without forcing users to download large debugging files. + +For more information about how to set up a symbol server for Electron, see [debugging with a symbol server](debugging-with-symbol-server.md). diff --git a/docs/development/goma.md b/docs/development/goma.md index 1ba7962c4d..f0d2f37d1c 100644 --- a/docs/development/goma.md +++ b/docs/development/goma.md @@ -25,16 +25,14 @@ in your config file. When you are using Goma you can run `ninja` with a substantially higher `j` value than would normally be supported by your machine. -Please do not set a value higher than **200** on Windows or Linux and -**50** on macOS. We monitor Goma system usage, and users found to be abusing -it with unreasonable concurrency will be de-activated. +Please do not set a value higher than **200**. We monitor Goma system usage, and users +found to be abusing it with unreasonable concurrency will be de-activated. ```bash ninja -C out/Testing electron -j 200 ``` -If you're using `build-tools`, appropriate `-j` values will automatically -be used for you. +If you're using `build-tools`, appropriate `-j` values will automatically be used for you. ## Monitoring Goma diff --git a/docs/development/pull-requests.md b/docs/development/pull-requests.md index f58ceee1a8..492b3caa6a 100644 --- a/docs/development/pull-requests.md +++ b/docs/development/pull-requests.md @@ -79,7 +79,7 @@ $ git add my/changed/files $ git commit ``` -Note that multiple commits often get squashed when they are landed. +Note that multiple commits get squashed when they are landed. #### Commit message guidelines @@ -180,18 +180,10 @@ $ git push origin my-branch ### Step 9: Opening the Pull Request From within GitHub, opening a new pull request will present you with a template -that should be filled out: +that should be filled out. It can be found [here](../../.github/PULL_REQUEST_TEMPLATE.md). -```markdown - -``` +If you do not adequately complete this template, your PR may be delayed in being merged as maintainers +seek more information or clarify ambiguities. ### Step 10: Discuss and update diff --git a/docs/development/testing.md b/docs/development/testing.md index aae9f9c76f..88a7a92432 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -12,29 +12,18 @@ coding style, please see the [coding-style](coding-style.md) document. ## Linting -To ensure that your JavaScript is in compliance with the Electron coding -style, run `npm run lint-js`, which will run `standard` against both -Electron itself as well as the unit tests. If you are using an editor -with a plugin/addon system, you might want to use one of the many -[StandardJS addons][standard-addons] to be informed of coding style -violations before you ever commit them. +To ensure that your changes are in compliance with the Electron coding +style, run `npm run lint`, which will run a variety of linting checks +against your changes depending on which areas of the code they touch. -To run `standard` with parameters, run `npm run lint-js --` followed by -arguments you want passed to `standard`. - -To ensure that your C++ is in compliance with the Electron coding style, -run `npm run lint-cpp`, which runs a `cpplint` script. We recommend that -you use `clang-format` and prepared [a short tutorial](clang-format.md). - -There is not a lot of Python in this repository, but it too is governed -by coding style rules. `npm run lint-py` will check all Python, using -`pylint` to do so. +Many of these checks are included as precommit hooks, so it's likely +you error would be caught at commit time. ## Unit Tests If you are not using [build-tools](https://github.com/electron/build-tools), ensure that that name you have configured for your -local build of Electron is one of `Testing`, `Release`, `Default`, `Debug`, or +local build of Electron is one of `Testing`, `Release`, `Default`, or you have set `process.env.ELECTRON_OUT_DIR`. Without these set, Electron will fail to perform some pre-testing steps. @@ -43,12 +32,34 @@ app (surprise!) that can be found in the `spec` folder. Note that it has its own `package.json` and that its dependencies are therefore not defined in the top-level `package.json`. +To run only tests in a specific process, run `npm run test --runners=PROCESS` +where `PROCESS` is one of `main` or `remote`. + To run only specific tests matching a pattern, run `npm run test -- -g=PATTERN`, replacing the `PATTERN` with a regex that matches the tests you would like to run. As an example: If you want to run only IPC tests, you would run `npm run test -- -g ipc`. -[standard-addons]: https://standardjs.com/#are-there-text-editor-plugins +## Node.js Smoke Tests + +If you've made changes that might affect the way Node.js is embedded into Electron, +we have a test runner that runs all of the tests from Node.js, using Electron's custom fork +of Node.js. + +To run all of the Node.js tests: + +```bash +$ node script/node-spec-runner.js +``` + +To run a single Node.js test: + +```bash +$ node script/node-spec-runner.js parallel/test-crypto-keygen +``` + +where the argument passed to the runner is the path to the test in +the Node.js source tree. ### Testing on Windows 10 devices diff --git a/docs/tutorial/windows-arm.md b/docs/tutorial/windows-arm.md index 27b16b122c..1d990dda27 100644 --- a/docs/tutorial/windows-arm.md +++ b/docs/tutorial/windows-arm.md @@ -93,7 +93,7 @@ Debugging native modules can be done with Visual Studio 2017 (running on your de 1. Launch your app `.exe` on the target device via the _Command Prompt_ (passing `--inspect-brk` to pause it before any native modules are loaded). 2. Launch Visual Studio 2017 on your development machine. 3. Connect to the target device by selecting _Debug > Attach to Process..._ and enter the device's IP address and the port number displayed by the Visual Studio Remote Debugger tool. -4. Click _Refresh_ and select the [appropriate Electron process to attach](../development/debug-instructions-windows.md). +4. Click _Refresh_ and select the [appropriate Electron process to attach](../development/debugging-on-windows.md). 5. You may need to make sure that any symbols for native modules in your app are loaded correctly. To configure this, head to _Debug > Options..._ in Visual Studio 2017, and add the folders containing your `.pdb` symbols under _Debugging > Symbols_. 6. Once attached, set any appropriate breakpoints and resume JavaScript execution using Chrome's [remote tools for Node](debugging-main-process.md).