mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

Merge branch 'master' into add-env-to-release-docs

Browse source
This commit is contained in:
Charles Kerr 2018-03-07 16:38:14 +09:00
commit 35a512310a
453 changed files with 13682 additions and 6855 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/development/build-instructions-linux.md
View file

@ -8,7 +8,7 @@ Follow the guidelines below for building Electron on Linux.
* Python 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x
so you may need to check your Python version with `python -V`.
* Node.js. There are various ways to install Node. You can download
source code from [nodejs.org](http://nodejs.org) and compile it.
source code from [nodejs.org](https://nodejs.org) and compile it.
Doing so permits installing Node on your own home directory as a standard user.
Or try repositories such as [NodeSource](https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories).
* [clang](https://clang.llvm.org/get_started.html) 3.4 or later.
@ -17,7 +17,7 @@ Follow the guidelines below for building Electron on Linux.
On Ubuntu, install the following libraries:
```sh
$ sudo apt-get install build-essential clang libdbus-1-dev libgtk2.0-dev \
$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \
libnotify-dev libgnome-keyring-dev libgconf2-dev \
libasound2-dev libcap-dev libcups2-dev libxtst-dev \
libxss1 libnss3-dev gcc-multilib g++-multilib curl \
@ -27,7 +27,7 @@ $ sudo apt-get install build-essential clang libdbus-1-dev libgtk2.0-dev \
On RHEL / CentOS, install the following libraries:
```sh
$ sudo yum install clang dbus-devel gtk2-devel libnotify-devel \
$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \
libgnome-keyring-devel xorg-x11-server-utils libcap-devel \
cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \
GConf2-devel nss-devel
@ -36,7 +36,7 @@ $ sudo yum install clang dbus-devel gtk2-devel libnotify-devel \
On Fedora, install the following libraries:
```sh
$ sudo dnf install clang dbus-devel gtk2-devel libnotify-devel \
$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \
libgnome-keyring-devel xorg-x11-server-utils libcap-devel \
cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \
GConf2-devel nss-devel
@ -155,12 +155,12 @@ information may help you.
### Building `libchromiumcontent` locally
To avoid using the prebuilt binaries of `libchromiumcontent`, you can build `libchromiumcontent` locally. To do so, follow these steps:
To avoid using the prebuilt binaries of `libchromiumcontent`, you can build `libchromiumcontent` locally. To do so, follow these steps:
1. Install [depot_tools](https://chromium.googlesource.com/chromium/src/+/master/docs/linux_build_instructions.md#Install)
2. Install [additional build dependencies](https://chromium.googlesource.com/chromium/src/+/master/docs/linux_build_instructions.md#Install-additional-build-dependencies)
3. Fetch the git submodules:
```sh
$ git submodule update --init --recursive
```
@ -179,11 +179,11 @@ $ ./script/build.py -c R
### Using system `clang` instead of downloaded `clang` binaries
By default Electron is built with prebuilt
By default Electron is built with prebuilt
[`clang`](https://clang.llvm.org/get_started.html) binaries provided by the
Chromium project. If for some reason you want to build with the `clang`
installed in your system, you can call `bootstrap.py` with `--clang_dir=<path>`
switch. By passing it the build script will assume the `clang` binaries reside
Chromium project. If for some reason you want to build with the `clang`
installed in your system, you can call `bootstrap.py` with `--clang_dir=<path>`
switch. By passing it the build script will assume the `clang` binaries reside
in `<path>/bin/`.
For example if you installed `clang` under `/user/local/bin/clang`:
@ -208,8 +208,8 @@ $ ./script/build.py -c R
### Environment variables
Apart from `CC` and `CXX`, you can also set following environment variables to
custom the building configurations:
Apart from `CC` and `CXX`, you can also set the following environment variables to
customise the build configuration:
* `CPPFLAGS`
* `CPPFLAGS_host`
@ -226,4 +226,4 @@ custom the building configurations:
* `LDFLAGS`
The environment variables have to be set when executing the `bootstrap.py`
script, it won't work in the `build.py` script.
script, it won't work in the `build.py` script.

2
docs/development/build-instructions-osx.md
View file

@ -6,7 +6,7 @@ Follow the guidelines below for building Electron on macOS.
* macOS >= 10.11.6
* [Xcode](https://developer.apple.com/technologies/tools/) >= 8.2.1
* [node.js](http://nodejs.org) (external)
* [node.js](https://nodejs.org) (external)
If you are using the Python downloaded by Homebrew, you also need to install
the following Python modules:

4
docs/development/build-instructions-windows.md
View file

@ -8,7 +8,7 @@ Follow the guidelines below for building Electron on Windows.
* Visual Studio 2015 Update 3 - [download VS 2015 Community Edition for
free](https://www.visualstudio.com/vs/older-downloads/)
* [Python 2.7](http://www.python.org/download/releases/2.7/)
* [Node.js](http://nodejs.org/download/)
* [Node.js](https://nodejs.org/download/)
* [Git](http://git-scm.com)
* [Debugging Tools for Windows](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063.aspx)
if you plan on creating a full distribution since `symstore.exe` is used for
@ -143,7 +143,7 @@ Try reinstalling 32bit Node.js.
### Error: ENOENT, stat 'C:\Users\USERNAME\AppData\Roaming\npm'
Simply making that directory [should fix the problem](http://stackoverflow.com/a/25095327/102704):
Simply making that directory [should fix the problem](https://stackoverflow.com/a/25095327/102704):
```powershell
$ mkdir ~\AppData\Roaming\npm

28
docs/development/coding-style.md
View file

@ -5,10 +5,27 @@ These are the style guidelines for coding in Electron.
You can run `npm run lint` to show any style issues detected by `cpplint` and
`eslint`.
## General Code
* End files with a newline.
* Place requires in the following order:
* Built in Node Modules (such as `path`)
* Built in Electron Modules (such as `ipc`, `app`)
* Local Modules (using relative paths)
* Place class properties in the following order:
* Class methods and properties (methods starting with a `@`)
* Instance methods and properties
* Avoid platform-dependent code:
* Use `path.join()` to concatenate filenames.
* Use `os.tmpdir()` rather than `/tmp` when you need to reference the
temporary directory.
* Using a plain `return` when returning explicitly at the end of a function.
* Not `return null`, `return undefined`, `null`, or `undefined`
## C++ and Python
For C++ and Python, we follow Chromium's [Coding
Style](http://www.chromium.org/developers/coding-style). You can use
Style](https://www.chromium.org/developers/coding-style). 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.
@ -21,9 +38,16 @@ document. The document mentions some special types, scoped types (that
automatically release their memory when going out of scope), logging mechanisms
etc.
## Documentation
* Write [remark](https://github.com/remarkjs/remark) markdown style
You can run `npm run lint-docs` to ensure that your documentation changes are
formatted correctly.
## JavaScript
* Write [standard](http://npm.im/standard) JavaScript style.
* Write [standard](https://npm.im/standard) JavaScript style.
* File names should be concatenated with `-` instead of `_`, e.g.
`file-name.js` rather than `file_name.js`, because in
[github/atom](https://github.com/github/atom) module names are usually in

52
docs/development/debugging-instructions-macos-xcode.md Normal file
View file

@ -0,0 +1,52 @@
## Debugging with XCode
### Build Debug Electron with Release libchromiumcontent
You can create a debug build of electron by following [build instructions for macOS](build-instructions-osx.md).
The bootstrap process will download Release version of libchromiumcontent by default,
so you will not be able to step through the chromium source.
### Build Debug Electron with Debug libchromiumcontent
If you want to debug and step through libchromiumcontent, you will have to run the
bootsrap script with the `--build_debug_libcc` argument.
```sh
$ cd electron
$ ./script/bootstrap.py -v --build_debug_libcc
```
This can take a significant amount of time depending on build machine as it has to
build all of the libchromium source.
Once, the lib is built, create a symlink to the built directory under download
`ln -s vendor/libchromiumcontent/dist/main/shared_library vendor/download/libchromiumcontent/shared_library`
Electron debug builds will use this shared library to link against.
```sh
$ ./script/build.py -c D --libcc
```
This will build debug electron with debug version of libchromiumcontent.
### Generate xcode project for debugging sources (cannot build code from xcode)
Run the update script with the --xcode argument.
```sh
$ ./script/update.py --xcode
```
This will generate the electron.ninjs.xcworkspace. You will have to open this workspace
to set breakpoints and inspect.
### Debugging and breakpoints
Launch electron app after build.
You can now open the xcode workspace created above and attach to the electron process
through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug
the renderer process, you need to attach to the Electron Helper as well.]
You can now set breakpoints in any of the indexed files. However, you will not be able
to set breakpoints directly in the chromium source.
To set break points in the chromium source, you can choose Debug > Breakpoints > Create
Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint
for all functions with that name, from all the classes if there are more than one.
You can also do this step of setting break points prior to attaching the debugger,
however, actual breakpoints for symbolic breakpoint functions may not show up until the
debugger is attached to the app.

2
docs/development/debugging-instructions-macos.md
View file

@ -5,6 +5,8 @@ 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, it is fairly easy
to 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.
## Requirements

109
docs/development/issues.md Normal file
View file

@ -0,0 +1,109 @@
# Issues In Electron
# Issues
* [How to Contribute in Issues](#how-to-contribute-in-issues)
* [Asking for General Help](#asking-for-general-help)
* [Submitting a Bug Report](#submitting-a-bug-report)
* [Triaging a Bug Report](#triaging-a-bug-report)
* [Resolving a Bug Report](#resolving-a-bug-report)
## How to Contribute in Issues
For any issue, there are fundamentally 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.
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.
## Asking for General Help
Because the level of activity in the `electron/electron` repository is
so high, questions or requests for general help using Electron should
be directed at the [community slack channel](https://atomio.slack.com)
or the [forum](https://discuss.atom.io/c/electron).
## Submitting a Bug Report
When opening a new issue in the `electron/electron` issue tracker, users
will be presented with a template that should be filled in.
```markdown
<!--
Thanks for opening an issue! A few things to keep in mind:
- The issue tracker is only for bugs and feature requests.
- Before reporting a bug, please try reproducing your issue against
the latest version of Electron.
- If you need general advice, join our Slack: http://atom-slack.herokuapp.com
-->
* Electron version:
* Operating system:
### Expected behavior
<!-- What do you think should happen? -->
### Actual behavior
<!-- What actually happens? -->
### How to reproduce
<!--
Your best chance of getting this bug looked at quickly is to provide a REPOSITORY that can be cloned and run.
You can fork https://github.com/electron/electron-quick-start and include a link to the branch with your changes.
If you provide a URL, please list the commands required to clone/setup/run your repo e.g.
$ git clone $YOUR_URL -b $BRANCH
$ npm install
$ npm start || electron .
-->
```
If you believe that you have found a bug in Electron, please fill out this
form to the best of your ability.
The two most important pieces of information needed to evaluate the report are
a description of the bug and a simple test case to recreate it. It easier to fix
a bug if it can be reproduced.
See [How to create a Minimal, Complete, and Verifiable example](https://stackoverflow.com/help/mcve).
## Triaging a Bug Report
It's common for open issues to involve discussion. Some contributors may
have differing opinions, including whether the behavior is a bug or feature.
This discussion is part of the process and should be kept focused, helpful,
and professional.
Terse responses that provide neither additional context nor supporting detail
are not helpful or professional. To many, such responses are annoying and
unfriendly.
Contributors are encouraged to solve issues collaboratively and help one
another make progress. If encounter an issue that you feel is invalid, or
which contains incorrect information, explain *why* you feel that way with
additional supporting context, and be willing to be convinced that you may
be wrong. By doing so, we can often reach the correct outcome faster.
## Resolving a Bug Report
Most issues are resolved by opening a pull request. The process for opening and
reviewing a pull request is similar to that of opening and triaging issues, but
carries with it a necessary review and approval workflow that ensures that the
proposed changes meet the minimal quality and functional guidelines of the
Electron project.

235
docs/development/pull-requests.md Normal file
View file

@ -0,0 +1,235 @@
# Pull Requests
* [Dependencies](#dependencies)
* [Setting up your local environment](#setting-up-your-local-environment)
* [Step 1: Fork](#step-1-fork)
* [Step 2: Build](#step-2-build)
* [Step 3: Branch](#step-3-branch)
* [Making Changes](#making-changes)
* [Step 4: Code](#step-4-code)
* [Step 5: Commit](#step-5-commit)
* [Commit message guidelines](#commit-message-guidelines)
* [Step 6: Rebase](#step-6-rebase)
* [Step 7: Test](#step-7-test)
* [Step 8: Push](#step-8-push)
* [Step 9: Opening the Pull Request](#step-8-opening-the-pull-request)
* [Step 10: Discuss and Update](#step-9-discuss-and-update)
* [Approval and Request Changes Workflow](#approval-and-request-changes-workflow)
* [Step 11: Landing](#step-10-landing)
* [Continuous Integration Testing](#continuous-integration-testing)
## Setting up your local environment
### Step 1: Fork
Fork the project [on GitHub](https://github.com/electron/electron) and clone your fork
locally.
```sh
$ git clone git@github.com:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream
```
### Step 2: Build
Build steps and dependencies differ slightly depending on your operating system.
See these detailed guides on building Electron locally:
* [Building on MacOS](https://electronjs.org/docs/development/build-instructions-osx)
* [Building on Linux](https://electronjs.org/docs/development/build-instructions-linux)
* [Building on Windows](https://electronjs.org/docs/development/build-instructions-windows)
Once you've built the project locally, you're ready to start making changes!
### Step 3: Branch
To keep your development environment organized, create local branches to
hold your work. These should be branched directly off of the `master` branch.
```sh
$ git checkout -b my-branch -t upstream/master
```
## Making Changes
### Step 4: Code
Most pull requests opened against the `electron/electron` repository include
changes to either the C/C++ code in the `atom/` or `brightray/` folders,
the JavaScript code in the `lib/` folder, the documentation in `docs/api/`
or tests in the `spec/` folder.
Please be sure to run `npm run lint` from time to time on any code changes
to ensure that they follow the project's code style.
See [coding style](https://electronjs.org/docs/development/coding-style) for
more information about best practice when modifying code in different parts of
the project.
### Step 5: Commit
It is recommended to keep your changes grouped logically within individual
commits. Many contributors find it easier to review changes that are split
across multiple commits. There is no limit to the number of commits in a
pull request.
```sh
$ git add my/changed/files
$ git commit
```
Note that multiple commits often get squashed when they are landed.
#### Commit message guidelines
A good commit message should describe what changed and why.
1. The first line should:
- contain a short description of the change (preferably 50 characters or less,
and no more than 72 characters)
- be entirely in lowercase with the exception of proper nouns, acronyms, and
the words that refer to code, like function/variable names
Examples:
- `updated osx build documentation for new sdk`
- `fixed typos in atom_api_menu.h`
2. Keep the second line blank.
3. Wrap all other lines at 72 columns.
See [this article](https://chris.beams.io/posts/git-commit/) for more examples
of how to write good git commit messages.
### Step 6: Rebase
Once you have committed your changes, it is a good idea to use `git rebase`
(not `git merge`) to synchronize your work with the main repository.
```sh
$ git fetch upstream
$ git rebase upstream/master
```
This ensures that your working branch has the latest changes from `electron/electron`
master.
### Step 7: Test
Bug fixes and features should always come with tests. A
[testing guide](https://electronjs.org/docs/development/testing) has been
provided to make the process easier. Looking at other tests to see how they
should be structured can also help.
Before submitting your changes in a pull request, always run the full
test suite. To run the tests:
```sh
$ npm run test
```
Make sure the linter does not report any issues and that all tests pass.
Please do not submit patches that fail either check.
If you are updating tests and just want to run a single spec to check it:
```sh
$ npm run test -match=menu
```
The above would only run spec modules matching `menu`, which is useful for
anyone who's working on tests that would otherwise be at the very end of
the testing cycle.
### Step 8: Push
Once your commits are ready to go -- with passing tests and linting --
begin the process of opening a pull request by pushing your working branch
to your fork on GitHub.
```sh
$ 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:
```markdown
<!--
Thank you for your pull request. Please provide a description above and review
the requirements below.
Bug fixes and new features should include tests and possibly benchmarks.
Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTING.md
-->
```
### Step 10: Discuss and update
You will probably get feedback or requests for changes to your pull request.
This is a big part of the submission process so don't be discouraged! Some
contributors may sign off on the pull request right away. Others may have
detailed comments or feedback. This is a necessary part of the process
in order to evaluate whether the changes are correct and necessary.
To make changes to an existing pull request, make the changes to your local
branch, add a new commit with those changes, and push those to your fork.
GitHub will automatically update the pull request.
```sh
$ git add my/changed/files
$ git commit
$ git push origin my-branch
```
There are a number of more advanced mechanisms for managing commits using
`git rebase` that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are
awaiting an answer on something. If you encounter words or acronyms that
seem unfamiliar, refer to this
[glossary](https://sites.google.com/a/chromium.org/dev/glossary).
#### Approval and Request Changes Workflow
All pull requests require approval from a [Code Owner](https://github.com/orgs/electron/teams/code-owners) of the area you
modified in order to land. Whenever a maintainer reviews a pull request they
may request changes. These may be small, such as fixing a typo, or may involve
substantive changes. Such requests are intended to be helpful, but at times
may come across as abrupt or unhelpful, especially if they do not include
concrete suggestions on *how* to change them.
Try not to be discouraged. If you feel that a review is unfair, say so or seek
the input of another project contributor. Often such comments are the result of
a reviewer having taken insufficient time to review and are not ill-intended.
Such difficulties can often be resolved with a bit of patience. That said,
reviewers should be expected to provide helpful feeback.
### Step 11: Landing
In order to land, a pull request needs to be reviewed and approved by
at least one Electron Code Owner and pass CI. After that, if there are no
objections from other contributors, the pull request can be merged.
Congratulations and thanks for your contribution!
### Continuous Integration Testing
Every pull request is tested on the Continuous Integration (CI) system to
confirm that it works on Electron's supported platforms.
Ideally, the pull request will pass ("be green") on all of CI's platforms.
This means that all tests pass and there are no linting errors. However,
it is not uncommon for the CI infrastructure itself to fail on specific
platforms or for so-called "flaky" tests to fail ("be red"). Each CI
failure must be manually inspected to determine the cause.
CI starts automatically when you open a pull request, but only
[Releasers](https://github.com/orgs/electron/teams/releasers/members)
can restart a CI run. If you believe CI is giving a false negative,
ask a Releaser to restart the tests.

4
docs/development/setting-up-symbol-server.md
View file

@ -5,7 +5,7 @@ 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. The server functions like
[Microsoft's symbol server](http://support.microsoft.com/kb/311503) so the
[Microsoft's symbol server](https://support.microsoft.com/kb/311503) so the
documentation there can be useful.
Note that because released Electron builds are heavily optimized, debugging is
@ -38,7 +38,7 @@ or by typing the `.sympath` command. If you would like to get symbols from
Microsoft's symbol server as well, you should list that first:
```powershell
SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols\*https://electron-symbols.githubapp.com
SRV*c:\code\symbols\*https://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols\*https://electron-symbols.githubapp.com
```
## Using the symbol server in Visual Studio

23
docs/development/source-code-directory-structure.md
View file

@ -4,12 +4,12 @@ The source code of Electron is separated into a few parts, mostly
following Chromium on the separation conventions.
You may need to become familiar with [Chromium's multi-process
architecture](http://dev.chromium.org/developers/design-documents/multi-process-architecture)
architecture](https://dev.chromium.org/developers/design-documents/multi-process-architecture)
to understand the source code better.
## Structure of Source Code
```sh
```diff
Electron
├── atom/ - C++ source code.
| ├── app/ - System entry code.
@ -30,6 +30,7 @@ Electron
| loop into Chromium's message loop.
| └── api/ - The implementation of common APIs, and foundations of
| Electron's built-in modules.
├── brightray/ - Thin shim over libcc that makes it easier to use.
├── chromium_src/ - Source code copied from Chromium. See below.
├── default_app/ - The default page to show when Electron is started without
| providing an app.
@ -49,15 +50,15 @@ Electron
## `/chromium_src`
The files in `/chromium_src` tend to be pieces of Chromium that aren't part of
the content layer. For example to implement Pepper API, we need some wiring
similar to what official Chrome does. We could have built the relevant
sources as a part of [libcc](../glossary.md#libchromiumcontent) but most
often we don't require all the features (some tend to be proprietary,
analytics stuff) so we just took parts of the code. These could have easily
been patches in libcc, but at the time when these were written the goal of
libcc was to maintain very minimal patches and chromium_src changes tend to be
big ones. Also, note that these patches can never be upstreamed unlike other
The files in `/chromium_src` tend to be pieces of Chromium that aren't part of
the content layer. For example to implement Pepper API, we need some wiring
similar to what official Chrome does. We could have built the relevant
sources as a part of [libcc](../glossary.md#libchromiumcontent) but most
often we don't require all the features (some tend to be proprietary,
analytics stuff) so we just took parts of the code. These could have easily
been patches in libcc, but at the time when these were written the goal of
libcc was to maintain very minimal patches and chromium_src changes tend to be
big ones. Also, note that these patches can never be upstreamed unlike other
libcc patches we maintain now.
## Structure of Other Directories

44
docs/development/testing.md Normal file
View file

@ -0,0 +1,44 @@
# Testing
We aim to keep the code coverage of Electron high. We ask that all pull
request not only pass all existing tests, but ideally also add new tests
to cover changed code and new scenarios. Ensuring that we capture as
many code paths and use cases of Electron as possible ensures that we
all ship apps with fewer bugs.
This repository comes with linting rules for both JavaScript and C++ –
as well as unit and integration tests. To learn more about Electron's
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 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.
## Unit Tests
To run all unit tests, run `npm run test`. The unit tests are an Electron
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 a selected number of tests, run `npm run test -match=NAME`,
replacing the `NAME` with the file name of the test suite you would like
to run. As an example: If you want to run only IPC suites, you would run
`npm run test -match=ipc`.
[standard-addons]: https://standardjs.com/#are-there-text-editor-plugins

31
docs/development/upgrading-chromium.md
View file

@ -12,10 +12,11 @@ This is an overview of the steps needed to upgrade Chromium in Electron.
## Upgrade `libcc` to a new Chromium version
1. Get the code and initialize the project:
- ```sh
```sh
$ git clone git@github.com:electron/libchromiumcontent.git
$ cd libchromiumcontent
$ ./script/bootstrap -v```
$ ./script/bootstrap -v
```
2. Update the Chromium snapshot
- Choose a version number from [OmahaProxy](https://omahaproxy.appspot.com/)
and update the `VERSION` file with it
@ -36,7 +37,7 @@ This is an overview of the steps needed to upgrade Chromium in Electron.
- If some patches are no longer compatible with the Chromium code,
fix compilation errors.
6. When the build succeeds, create a `dist` for Electron
- `$ ./script/create-dist --no_zip`
- `$ ./script/create-dist --no_zip`
- It will create a `dist/main` folder in the libcc repo's root.
You will need this to build Electron.
7. (Optional) Update script contents if there are errors resulting from files
@ -47,18 +48,18 @@ This is an overview of the steps needed to upgrade Chromium in Electron.
## Update Electron's code
1. Get the code:
- ```sh
$ git clone git@github.com:electron/electron.git
$ cd electron
```
```sh
$ git clone git@github.com:electron/electron.git
$ cd electron
```
2. If you have libcc built on your machine in its own repo,
tell Electron to use it:
- ```sh
$ ./script/bootstrap.py -v \
--libcc_source_path <libcc_folder>/src \
--libcc_shared_library_path <libcc_folder>/shared_library \
--libcc_static_library_path <libcc_folder>/static_library
```
```sh
$ ./script/bootstrap.py -v \
--libcc_source_path <libcc_folder>/src \
--libcc_shared_library_path <libcc_folder>/shared_library \
--libcc_static_library_path <libcc_folder>/static_library
```
3. If you haven't yet built libcc but it's already supposed to be upgraded
to a new Chromium, bootstrap Electron as usual
`$ ./script/bootstrap.py -v`
@ -106,7 +107,7 @@ Follow all the steps above to fix Electron code on all supported platforms.
If there are any compilation errors related to the Crashpad, it probably means
you need to update the fork to a newer revision. See
[Upgrading Crashpad](https://github.com/electron/electron/tree/master/docs/development/upgrading-crashpad.md)
[Upgrading Crashpad](upgrading-crashpad.md)
for instructions on how to do that.
@ -115,7 +116,7 @@ for instructions on how to do that.
Upgrade `vendor/node` to the Node release that corresponds to the v8 version
used in the new Chromium release. See the v8 versions in Node on
See [Upgrading Node](https://github.com/electron/electron/tree/master/docs/development/upgrading-node.md)
See [Upgrading Node](upgrading-node.md)
for instructions on this.
## Verify ffmpeg support

9
docs/development/upgrading-crashpad.md
View file

@ -2,7 +2,7 @@
1. Get the version of crashpad that we're going to use.
- `libcc/src/third_party/crashpad/README.chromium` will have a line `Revision:` with a checksum
- We need to check out the correponding branch.
- We need to check out the corresponding branch.
- Clone Google's crashpad (https://chromium.googlesource.com/crashpad/crashpad)
- `git clone https://chromium.googlesource.com/crashpad/crashpad`
- Check out the branch with the revision checksum:
@ -16,10 +16,10 @@
2. Make a checklist of the Electron patches that need to be applied
with `git log --oneline`
- Or view http://github.com/electron/crashpad/commits/previous-branch-name
- Or view https://github.com/electron/crashpad/commits/previous-branch-name
3. For each patch:
- In `electron-crashpad-vA.B.C.D`, cherry-pick the patch's checksum
- In `electron-crashpad-vA.B.C.D`, cherry-pick the patch's checksum
- `git cherry-pick <checksum>`
- Resolve any conflicts
- Make sure it builds then add, commit, and push work to electron's crashpad fork
@ -37,6 +37,3 @@
6. Push changes to submodule reference
- (From electron root) `git add vendor/crashpad`
- `git push origin upgrade-to-chromium-62`

54
docs/development/upgrading-node.md
View file

@ -3,8 +3,8 @@
## Discussion
One upgrade issue is building all of Electron with a single copy
of V8 to ensure compatability. This is important because
upstream Node and [libchromiumcontent](upgrading-chrome.md)
of V8 to ensure compatibility. This is important because
upstream Node and [libchromiumcontent](upgrading-chromium.md)
both use their own versions of V8.
Upgrading Node is much easier than upgrading libchromiumcontent,
@ -38,9 +38,10 @@ So in short, the primary steps are:
## Updating Electron's Node [fork](https://github.com/electron/node)
1. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X`
1. Ensure that `master` on `electron/node` has updated release tags from `nodejs/node`
2. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X` where the base that you're branching from is the tag for the desired update
- `vX.X.X` Must use a version of node compatible with our current version of chromium
2. Re-apply our commits from the previous version of node we were using (`vY.Y.Y`) to `v.X.X.X`
3. Re-apply our commits from the previous version of node we were using (`vY.Y.Y`) to `v.X.X.X`
- Check release tag and select the range of commits we need to re-apply
- Cherry-pick commit range:
1. Checkout both `vY.Y.Y` & `v.X.X.X`
@ -82,7 +83,7 @@ We need to generate a patch file from each patch applied to V8.
Manually edit the `.patch` file to match upstream V8's directory:
- If a diff section has no instances of `deps/V8`, remove it altogether.
- We don’t want those patches because we’re only patching V8.
- Replace instances of `a/deps/v8`/filename.ext` with `a/filename.ext`
- Replace instances of `a/deps/v8/filename.ext` with `a/filename.ext`
- This is needed because upstream Node keeps its V8 files in a subdirectory
- Ensure that local status is clean: `git status` to make sure there are no unstaged changes.
- Confirm that the patch applies cleanly with
@ -96,7 +97,7 @@ We need to generate a patch file from each patch applied to V8.
- `mv test.patch patches/v8/xxx-patch_name.patch`
- Add the patched code to the index _without_ committing:
- `cd src/v8 && git add . && cd ../..`
- We don't want to commit the changes (they're kept in the patchfiles)
- We don't want to commit the changes (they're kept in the patchfiles)
but need them locally so that they don't show up in subsequent diffs
while we iterate through more patches
- Add the patch file to the index:
@ -105,20 +106,20 @@ We need to generate a patch file from each patch applied to V8.
- `git commit patches/v8/`
8. Update `patches/v8/README.md` with references to all new patches that have been added so that the next person will know which need to be removed.
9. Update Electron's submodule references:
- ```sh
cd electron/vendor/node
electron/vendor/node$ git fetch
electron/vendor/node$ git checkout electron-node-vA.B.C
electron/vendor/node$ cd ../libchromiumcontent
electron/vendor/libchromiumcontent$ git fetch
electron/vendor/libchromiumcontent$ git checkout upgrade-to-chromium-X
electron/vendor/libchromiumcontent$ cd ../..
electron$ git add vendor
electron$ git commit -m "update submodule referefences for node and libc"
electron$ git pso upgrade-to-chromium-62
electron$ script/bootstrap.py -d
electron$ script/build.py -c -D
```
```sh
$ cd electron/vendor/node
electron/vendor/node$ git fetch
electron/vendor/node$ git checkout electron-node-vA.B.C
electron/vendor/node$ cd ../libchromiumcontent
electron/vendor/libchromiumcontent$ git fetch
electron/vendor/libchromiumcontent$ git checkout upgrade-to-chromium-X
electron/vendor/libchromiumcontent$ cd ../..
electron$ git add vendor
electron$ git commit -m "update submodule referefences for node and libc"
electron$ git pso upgrade-to-chromium-62
electron$ script/bootstrap.py -d
electron$ script/build.py -c -D
```
## Notes
@ -143,16 +144,3 @@ We need to generate a patch file from each patch applied to V8.
- Building node:
- There’s a chance we need to change our build configuration
to match the build flags that node wants in `node/common.gypi`