2018-02-01 23:08:53 +00:00
# Development Environment Setup
2017-05-04 02:57:57 +00:00
## Setup
You will need to install these tools on your machine:
2017-05-29 11:18:44 +00:00
### macOS
2018-02-01 23:08:53 +00:00
- [Node.js v8.9.0 ](https://nodejs.org/dist/v8.9.0/ )
- [Python 2.7 ](https://www.python.org/downloads/mac-osx/ )
- Xcode and Xcode Command Line Tools (Xcode -> Preferences -> Downloads)
2017-05-29 11:18:44 +00:00
### Windows
2018-02-01 23:08:53 +00:00
- [Node.js v8.9.0 ](https://nodejs.org/dist/v8.9.0/ )
- *Make sure you allow the Node.js installer to add node to the PATH.*
- [Python 2.7 ](https://www.python.org/downloads/windows/ )
- *Let Python install into the default suggested path (`c:\Python27`), otherwise you'll have
to configure node-gyp manually with the path which is annoying.*
- *Ensure the **Add python.exe to Path** option is selected.*
- One of Visual Studio 2015, Visual C++ Build Tools or Visual Studio 2017
- [Visual C++ Build Tools ](http://go.microsoft.com/fwlink/?LinkId=691126 )
- *Run `npm config set msvs_version 2015` to tell node to use this toolchain.*
- Visual Studio 2015
- *Ensure you select the **Common Tools for Visual C++ 2015** feature as that is required by Node.js
for installing native modules.*
- *Run `npm config set msvs_version 2015` to tell node to use this toolchain.*
- [Visual Studio 2017 ](https://www.visualstudio.com/vs/community/ )
- *Ensure you select the **Desktop development with C++** feature as that is required by Node.js for
installing native modules.*
- *Run `npm config set msvs_version 2017` to tell node to use this toolchain.*
2017-05-29 11:18:44 +00:00
2017-10-09 01:44:16 +00:00
### Fedora 26
2017-11-07 04:49:57 +00:00
First, add the NodeJS package repository.
2017-10-09 01:44:16 +00:00
2017-10-19 23:45:04 +00:00
```shellsession
2017-10-09 01:44:16 +00:00
$ curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -
```
After that, install the dependencies to build and test the app:
2017-10-19 23:45:04 +00:00
```shellsession
2017-10-20 21:13:20 +00:00
$ sudo dnf install -y nodejs gcc-c++ make libsecret-devel libXScrnSaver
2017-10-09 01:44:16 +00:00
```
2018-02-01 23:08:53 +00:00
If you want to package Desktop for distribution, you will need these additional dependencies:
2017-10-09 22:24:52 +00:00
2017-10-20 00:08:59 +00:00
```shellsession
2017-10-15 13:22:19 +00:00
$ sudo dnf install fakeroot dpkg rpm rpm-build xz xorriso appstream bzip2-devel
2017-10-20 00:08:59 +00:00
```
2018-02-01 23:08:53 +00:00
If you have problems packaging for AppImage, you may need to force the linker to use the right
version of specific dependencies. More information [here ](https://michaelheap.com/error-while-loading-shared-libraries-libbz2-so-1-0-cannot-open-shared-object-file-on-centos-7 )
and [here ](https://github.com/electron-userland/electron-builder/issues/993#issuecomment-291021974 )
2017-10-20 00:08:59 +00:00
```shellsession
2017-10-09 22:24:52 +00:00
$ sudo ln -s `find /usr/lib64/ -type f -name "libbz2.so.1*"` /usr/lib64/libbz2.so.1.0
$ sudo ln -s `find /usr/lib64/ -type f -name "libreadline.so.7.0"` /usr/lib64/libreadline.so.6
```
2017-10-25 13:37:58 +00:00
### Ubuntu 16.04
First, install curl:
```shellsession
$ sudo apt install curl
```
Then add the NodeJS package repository:
```shellsession
$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
2017-10-09 22:24:52 +00:00
```
2017-10-25 13:37:58 +00:00
After that, install the dependencies to build and test the app:
```shellsession
2017-10-25 17:57:44 +00:00
$ sudo apt update & & sudo apt install -y nodejs gcc make libsecret-1-dev
2017-10-25 13:37:58 +00:00
```
2017-11-23 02:19:53 +00:00
If you want to package Desktop for distribution, install these packages:
```shellsession
$ sudo apt install -y fakeroot dpkg rpm xz-utils xorriso zsync
```
2017-10-25 13:37:58 +00:00
2017-05-29 11:18:44 +00:00
## Verification
2017-06-26 14:33:41 +00:00
2018-02-01 23:08:53 +00:00
With these things installed, open a shell and install `yarn` (you might need
to `sudo` here depending on how Node was installed):
2017-09-26 00:22:11 +00:00
2017-10-19 23:45:04 +00:00
```shellsession
2017-11-03 11:16:55 +00:00
$ npm install -g yarn@1.3.2
2017-09-26 00:22:11 +00:00
```
2017-09-26 00:22:16 +00:00
This is important because yarn uses lock files to pin dependencies. If you find
2018-02-01 23:08:53 +00:00
yourself changing packages, this will prevent mismatches in versions between machines.
2017-09-26 00:22:11 +00:00
2018-02-01 23:08:53 +00:00
Then validate you have these commands available and that the versions look similar:
2017-05-04 02:57:57 +00:00
2017-10-19 23:45:04 +00:00
```shellsession
2017-10-20 00:08:59 +00:00
$ node -v
2017-05-04 02:57:57 +00:00
v7.8.0
2017-10-20 00:08:59 +00:00
$ yarn -v
2017-10-10 23:22:56 +00:00
1.2.0
2017-05-04 02:57:57 +00:00
2017-10-20 00:08:59 +00:00
$ python --version
2017-05-04 02:57:57 +00:00
Python 2.7.13
```
2018-02-01 23:08:53 +00:00
There are also [additional resources ](tooling.md ) to
configure your favorite editor to work nicely with the GitHub Desktop
repository.
2017-05-04 02:57:57 +00:00
## Building Desktop
2018-02-01 23:08:53 +00:00
After cloning the repository, the typical workflow to get up running
is as follows:
2017-05-04 02:57:57 +00:00
2017-09-26 00:22:11 +00:00
* Run `yarn` to get all required dependencies on your machine.
2017-10-10 00:21:43 +00:00
* Run `yarn build:dev` to create a development build of the app.
* Run `yarn start` to launch the application. Changes will be compiled in the
2017-05-04 02:57:57 +00:00
background. The app can then be reloaded to see the changes (Ctrl/Command+R).
2018-02-01 23:08:53 +00:00
**Optional Tip**: On macOS and Linux, you can use `screen` to avoid filling your terminal with logging output:
2017-11-09 00:16:13 +00:00
```shellsession
2017-11-10 01:05:59 +00:00
$ screen -S "desktop" yarn start # -S sets the name of the session; you can pick anything
2017-11-09 00:16:13 +00:00
$ # Your screen clears and shows logs. Press Ctrl+A then D to exit.
[detached]
$ screen -R "desktop" # to reopen the session, read the logs, and exit (Ctrl+C)
[screen is terminating]
```
2017-05-04 02:57:57 +00:00
2018-02-01 23:08:53 +00:00
If you've made changes in the `main-process` folder you need to run `yarn
build:dev` to rebuild the package, and then `yarn start` for these changes to be
reflected in the running app.
2017-05-04 02:57:57 +00:00
If you're still encountering issues with building, refer to our
2018-02-01 23:08:53 +00:00
[troubleshooting ](troubleshooting.md ) guide for more common
problems.
2017-05-04 02:57:57 +00:00
## Running tests
2018-02-01 23:08:53 +00:00
- `yarn test` - Runs all unit and integration tests
- `yarn test:unit` - Runs all unit tests
- `yarn test:integration` - Runs all integration tests
2017-05-04 02:57:57 +00:00
**Pro Tip:** If you're only interested in the results of a single test and don't
wish to run the entire test suite to see it you can pass along a search string
in order to only run the tests that match that string.
2017-10-19 23:45:04 +00:00
```shellsession
$ yarn test:unit -- --grep CloneProgressParser
2017-05-04 02:57:57 +00:00
```
This example will run all test names containing `CloneProgressParser` .
## Debugging
Electron ships with Chrome Dev Tools to assist with debugging, profiling and
other measurement tools.
1. Run the command `npm start` to launch the app
2. Under the **View** menu, select **Toggle Developer Tools**
When running the app in development mode,
[React Dev Tools ](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en )
should automatically install itself on first start when in development mode.
An additional extension, [Devtron ](http://electron.atom.io/devtron/ ), is also
2018-02-01 23:08:53 +00:00
included but is disabled by default. To enable Devtron, select the Console
tab in Chrome Developer Tools and run this command:
2017-05-04 02:57:57 +00:00
```js
require('devtron').install()
```
## The Next Steps
You're almost there! Here's a couple of things we recommend you read next:
2018-02-23 06:13:33 +00:00
- [Help Wanted ](../../.github/CONTRIBUTING.md#help-wanted ) - we've marked some tasks in
2018-02-01 23:08:53 +00:00
the backlog that are ideal for external contributors
- [Code Reviews ](../process/reviews.md ) - some notes on how the team does
code reviews