Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 7.13 KB

setup.md

File metadata and controls

204 lines (146 loc) · 7.13 KB

Development Environment Setup

Setup

You will need to install these tools on your machine:

macOS

Windows

  • Node.js v8.9.0
    • Make sure you allow the Node.js installer to add node to the PATH.
  • Python 2.7
    • 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
      • 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
      • 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.

Fedora 26

First, add the NodeJS package repository.

$ curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -

After that, install the dependencies to build and test the app:

$ sudo dnf install -y nodejs gcc-c++ make libsecret-devel libXScrnSaver

If you want to package Desktop for distribution, you will need these additional dependencies:

$ sudo dnf install fakeroot dpkg rpm rpm-build xz xorriso appstream bzip2-devel

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 and here

$ 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

Ubuntu 16.04

First, install curl:

$ sudo apt install curl

Then add the NodeJS package repository:

$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -

After that, install the dependencies to build and test the app:

$ sudo apt update && sudo apt install -y nodejs gcc make libsecret-1-dev

If you want to package Desktop for distribution, install these packages:

$ sudo apt install -y fakeroot dpkg rpm xz-utils xorriso zsync

arm64 builds

Desktop can be built and run on arm64 (aarch64) hardware such as a Raspberry Pi 3. In order to build for arm64, you will need the following:

  • A computer with a 64-bit ARMv8 processor.
  • A 64-bit OS. You can use Ubuntu 16.04 and then follow the instructions on setup there.
  • Instead of running yarn to get all required dependencies on your machine, you will instead need to run script/install-arm64-deps.sh.

Install Yarn

After doing this setup, you also need to install yarn as Desktop uses this for managing packages instead of NPM. Do not install yarn through NPM. Refer to the install instructions for you OS.

This is important because yarn uses lock files to pin dependencies. If you find yourself changing packages, this will prevent mismatches in versions between machines.

If you're not familiar with yarn, please read this document to help familiarize yourself with how to do the common package tasks that are relevant to Desktop.

Verification

Then verify you have these commands available in your shell and that the found versions look similar to the below output:

$ node -v
v8.10.0

$ yarn -v
1.5.1

$ python --version
Python 2.7.13

There are also additional resources to configure your favorite editor to work nicely with the GitHub Desktop repository.

Building Desktop

After cloning the repository, the typical workflow to get up running is as follows:

  • Run yarn to get all required dependencies on your machine.
  • 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 background. The app can then be reloaded to see the changes (Ctrl/Command+Alt+R).

Optional Tip: On macOS and Linux, you can use screen to avoid filling your terminal with logging output:

$ screen -S "desktop" yarn start # -S sets the name of the session; you can pick anything
$ # 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]

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.

If you're still encountering issues with building, refer to our troubleshooting guide for more common problems.

Running tests

  • yarn test - Runs all unit and integration tests
  • yarn test:unit - Runs all unit tests
  • yarn test:integration - Runs all integration tests

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.

$ yarn test:unit -- --grep CloneProgressParser

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 yarn start to launch the app
  2. Under the View menu, select Toggle Developer Tools

When running the app in development mode, React Dev Tools should automatically install itself on first start when in development mode.

An additional extension, Devtron, is also included but is disabled by default. To enable Devtron, select the Console tab in Chrome Developer Tools and run this command:

require('devtron').install()

The Next Steps

You're almost there! Here's a couple of things we recommend you read next:

  • Help Wanted - we've marked some tasks in the backlog that are ideal for external contributors
  • Notes for Contributors - some notes for new contributors getting started