mirrors/signal-desktop
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 2 Wiki Activity Actions

script to build for electron on install, Electron docs refresh (#1491)

Browse source 
* Add new postinstall script for automatic electron builds

FREEBIE

* Documentation refresh for the world of electron

FREEBIE
This commit is contained in:
Scott Nonnenberg 2017-09-19 15:31:04 -07:00 committed by GitHub
parent 9040677d3c
commit bd78016120
3 changed files with 171 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

257
CONTRIBUTING.md
View file

@ -7,94 +7,126 @@ Start small. The PRs most likely to be merged are the ones that make small,
easily reviewed changes with clear, and specific intentions. See below for more easily reviewed changes with clear, and specific intentions. See below for more
[guidelines on pull requests](#pull-requests). [guidelines on pull requests](#pull-requests).
Stick to issues that are It's a good idea to gauge interest in your intended work by finding the current issue
[on the roadmap](https://github.com/WhisperSystems/Signal-Desktop/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22On+the+roadmap%22). for it or creating a new one yourself. You can use also that issue as a place to signal
Issues that are not included in this milestone may be not yet triaged, your intentions and get feedback from the users most likely to appreciate your changes.
unplanned, or not actionable for one reason or another.
Once you've spent a little bit of time planning your solution, it's a good idea to go
back to the issue and talk about your approach. We'd be happy to provide feedback. [An
ounce of prevention, as they say!](https://www.goodreads.com/quotes/247269-an-ounce-of-prevention-is-worth-a-pound-of-cure)
If you start working on an issue, leave a comment to let others know. It is
also a good idea to outline your approach to the problem in order to get
feedback.
## Developer Setup ## Developer Setup
First, you'll need [Node.js](https://nodejs.org/) installed. Anything 6.x or newer works
as of Summer 2017. You might consider a [version](https://github.com/creationix/nvm)
[manager](https://github.com/coreybutler/nvm-windows) to make this easier for yourself.
Then you need `git`, if you don't have that yet: https://git-scm.com/
And for the final step before we actually get started, you'll need build tools to install
the native modules used by the application. On Windows, it's easiest to open the [Command
Prompt (`cmd.exe`) as Administrator](https://technet.microsoft.com/en-us/library/cc947813(v=ws.10).aspx)
and run this:
```
npm install --global --production windows-build-tools
```
On OSX you can install the [XCode Command-line tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/). On Linux you'll need to take a trip to your
favorite package manager. Python 2.x and GCC two key necessary components.
Now, run these commands in your preferred terminal in a good directory for development:
``` ```
git clone https://github.com/WhisperSystems/Signal-Desktop.git git clone https://github.com/WhisperSystems/Signal-Desktop.git
cd Signal-Desktop cd Signal-Desktop
npm install # install dependencies npm install -g yarn # (only if you don't already have yarn)
npm start # run yarn install # install and build dependencies (this will take a while)
yarn run start # run!
``` ```
Some features, such as native notifications, will not work locally until you ## Setting up standalone
package for your platform:
By default the application will connect to the **staging** servers, which means that you
**will not** be able to link it with your primary mobile device.
Fear not! You don't have to link the app with your phone. During setup in development
mode, you'll be presented with a 'Standalone' button which goes through the registration
process like you would on a phone. But you won't be linked to any other devices.
## The staging environment
Sadly, this default setup results in no contacts and no message history, an entirely
empty application. But you can use the information from your production install of Signal
Desktop to populate your testing application!
First, find your application data:
- OSX: `~/Library/Application Support/Signal`
- Linux: `~/.config/Signal`
- Windows 10: `C:\Users\<YourName>\AppData\Roaming\Signal`
Now make a copy of this production data directory in the same place, and call it
`Signal-development`. Now start up the development version of the app as normal,
and you'll see all of your contacts and messages!
You'll notice a prompt to re-link, because your production credentials won't work on
staging. Click 'Relink', then 'Standalone', then verify the phone number and click
'Send SMS.'
Once you've entered the confirmation code sent to your phone, you are registered as a
standalone staging device with your normal phone number, and a copy of your production
message history and contact list.
Here's the catch: you can't message any of these contacts, since they haven't done the
same thing. Who can you message for testing?
## Additional storage profiles
What you need for proper testing is additional phone numbers, to register additional
standalone devices. You can get them via
[Twilio ($1/mo. per number + $0.0075 per SMS)](https://www.twilio.com/), or via
[Google Voice (one number per Google Account, free SMS)](https://voice.google.com/).
Once you have the additional numbers, you can setup additional storage profiles and switch
between them using the `NODE_APP_INSTANCE` environment variable.
For example, to create an 'alice' profile, put a file called `local-alice.json` in the
`config` directory:
``` ```
npm run pack-staging # build a packaged app dir in ./dist
```
```
npm run dist-staging # build installer (.dmg, .exe, or .deb)
```
For development, you should always be using the staging server.
Registrations on the staging server are completely partitioned from the
production server that the mobile apps use. A production app from the Play
store or iTunes is hard-coded to connect to the production server. If you wish
to pair your phone and computer, or test sending between the browser and
mobile, **you must build a mobile client that targets the staging server**
(see below, under [Linking](#linking)).
## Linking
0. Build Signal for Android or iOS from source, and point its TextSecure service URL to `textsecure-service-staging.whispersystems.org`:
- **on Android:** Replace the `SIGNAL_URL` value in [build.gradle](https://github.com/WhisperSystems/Signal-Android/blob/master/build.gradle)
- **on iOS:** Replace the `textSecureServerURL` value in `TSConstants.h`(located in the SignalServiceKit pod)
This task is 1% search and replace, 99% setting up your build environment. Instructions are available for both
the [Android](https://github.com/WhisperSystems/Signal-Android/blob/master/BUILDING.md)
and [iOS](https://github.com/WhisperSystems/Signal-iOS/blob/master/BUILDING.md) projects.
1. Upon installing the extension you will be presented with a qr code.
2. On your phone, open Signal and navigate to Settings > Devices. Tap the "+"
button and scan the qr code.
3. Click through the confirmation dialog on the phone.
4. The browser will display your phone number and device name. Edit the device
name if desired. Click ok and wait for setup to complete. Key generation can
take up to a minute.
## Standalone Registration
**NOTE:** This is only for developers and will not be presented to users.
* Open the background page and run the following command in the console: `extension.install("standalone")`.
* Enter a real phone number (Google Voice numbers work too) and country
combination and choose to send an SMS. You will receive a real SMS.
* Enter the verification code you received by SMS.
* Wait for key generation to complete.
You should now be able to use the extension.
## Storage profiles
To facilitate registration of multiple clients from one machine/user for
development purposes, you can configure multiple storage profiles and switch
between them using the NODE_APP_INSTANCE environment variable.
```
// config/local-alice.json
{ {
"storageProfile": "aliceProfile" "storageProfile": "aliceProfile"
} }
```
> NODE_APP_INSTANCE=alice npm start Then you can start up the application a little differently to load the profile:
```
NODE_APP_INSTANCE=alice yarn run start
``` ```
This changes the [userData](https://electron.atom.io/docs/all/#appgetpathname) This changes the [userData](https://electron.atom.io/docs/all/#appgetpathname)
directory from `%appData%/Signal` to `%appData%/Signal-aliceProfile`. directory from `%appData%/Signal` to `%appData%/Signal-aliceProfile`.
Each profile can be independently linked or registered as standalone.
Each one will need its own Google account and Google Voice number. # Making changes
Each one will have to repeat the setup process documented above, including
re-accepting the staging server cert under each profile. This is a tedious So you're in the process of preparing that pull request. Here's how to make that go
process, but once you are done you will be able to send messages back and forth smoothly.
between different profiles, allowing you to observe both endpoints of a
conversation.
## Tests
Please write tests! Our testing framework is
[mocha](http://mochajs.org/) and our assertion library is
[chai](http://chaijs.com/api/assert/).
To run tests, you can run them from the command line with `grunt unit-tests` or in an
interactive session with `NODE_ENV=test yarn run start`.
## Pull requests ## Pull requests
@ -103,24 +135,22 @@ So you wanna make a pull request? Please observe the following guidelines.
* Please do not submit pull requests for translation fixes. Anyone can update * Please do not submit pull requests for translation fixes. Anyone can update
the translations in the translations in
[Transifex](https://www.transifex.com/projects/p/signal-desktop). [Transifex](https://www.transifex.com/projects/p/signal-desktop).
* Always localize your strings. Signal Desktop uses the * Never use plain strings right in the source code - pull them from `messages.json`!
[chrome.i18n infrastructure](https://developer.chrome.com/extensions/i18n) You **only** need to modify the default locale
for localization. You **only** need to modify the default locale [`_locales/en/messages.json`](_locales/en/messages.json). Other locales are generated
[`_locales/en/messages.json`](_locales/en/messages.json). Other locales are automatically based on that file and then periodically uploaded to Transifex for
generated automatically based on that file and then periodically uploaded to translation.
Transifex for translation. * [Rebase](https://nathanleclaire.com/blog/2014/09/14/dont-be-scared-of-git-rebase/) your
* Rebase your changes on the latest master branch, resolving any conflicts changes on the latest `master` branch, resolving any conflicts.
that may arise. This ensures that your changes will merge cleanly when you This ensures that your changes will merge cleanly when you open your PR.
open your PR. * Be sure to add and run tests!
* Run the tests locally by opening the test page in your browser. A
test-breaking change will not be merged.
* Make sure the diff between our master and your branch contains only the * Make sure the diff between our master and your branch contains only the
minimal set of changes needed to implement your feature or bugfix. This will minimal set of changes needed to implement your feature or bugfix. This will
make it easier for the person reviewing your code to approve the changes. make it easier for the person reviewing your code to approve the changes.
Please do not submit a PR with commented out code or unfinished features. Please do not submit a PR with commented out code or unfinished features.
* Don't have too many commits. If your branch contains spurious commits along * Avoid meaningless or too-granular commits. If your branch contains commits like
the lines of "Oops, reverted this change" or "Just experiementing, will the lines of "Oops, reverted this change" or "Just experimenting, will
delete this later", please squash or rebase those changes out. delete this later", please [squash or rebase those changes away](https://robots.thoughtbot.com/git-interactive-rebase-squash-amend-rewriting-history).
* Don't have too few commits. If you have a complicated or long lived feature * Don't have too few commits. If you have a complicated or long lived feature
branch, it may make sense to break the changes up into logical atomic chunks branch, it may make sense to break the changes up into logical atomic chunks
to aid in the review process. to aid in the review process.
@ -135,10 +165,58 @@ So you wanna make a pull request? Please observe the following guidelines.
history in the future. When in doubt, err on the side of a longer history in the future. When in doubt, err on the side of a longer
commit message. commit message.
Above all, spend some time with the repository. Follow the pull request template added to
your pull request description automatically. Take a look at recent approved pull requests,
see how they did things.
## Linking to a staging mobile device
Multiple standalone desktop devices are great for testing of a lot of scenarios. But a lot
of the Signal experience requires a primary mobile device: contact management,
synchronizing read and verification states among all linked devices, etc.
This presents a problem - even if you had another phone, the production versions of the
iOS and Android apps are locked to the production servers. To test all secenarios in
staging, your best bet is to pull down the development version of the iOS or Android app,
and register it with one of your extra phone numbers:
First, build Signal for Android or iOS from source, and point its TextSecure service URL to `textsecure-service-staging.whispersystems.org`:
**on Android:** Replace the `SIGNAL_URL` value in [build.gradle](https://github.com/WhisperSystems/Signal-Android/blob/master/build.gradle)
**on iOS:** Replace the `textSecureServerURL` value in `TSConstants.h`(located in the SignalServiceKit pod)
This task is 1% search and replace, 99% setting up your build environment. Instructions are available for both
the [Android](https://github.com/WhisperSystems/Signal-Android/blob/master/BUILDING.md)
and [iOS](https://github.com/WhisperSystems/Signal-iOS/blob/master/BUILDING.md) projects.
Then you can set up your development build of Signal Desktop as normal. If you've already
set up as a standalone install, you can switch by opening the DevTools (View -> Toggle
Developer Tools) and entering this into the Console and pressing enter: `window.owsDesktopApp.appView.openInstaller();`
## Changing to production
If you're completely sure that your changes will have no impact to the production servers,
you can connect your development build to the production server by putting a file called
`local-development.json` in the `config` directory that looks like this:
```
{
"serverUrl": "https://textsecure-service.whispersystems.org",
"cdnUrl": "https://cdn.signal.org"
}
```
**Beware:** Setting up standalone with your primary phone number when connected to the
production servers will _unregister_ your mobile device! All messages from your contacts
will go to your new development desktop app instead of your phone.
## Dependencies ## Dependencies
**Note**: Unless you need to make changes to dependencies, you can skip this **Note**: You probably won't end up doing this. Feel free to skip for now.
section and just use the checked in versions.
Dependencies are managed by [bower](http://bower.io) and built with Dependencies are managed by [bower](http://bower.io) and built with
[grunt](http://gruntjs.com). To change them, you'll need to install node and [grunt](http://gruntjs.com). To change them, you'll need to install node and
@ -169,12 +247,3 @@ Now, run `grunt` to delete unused package files and build `js/components.js`.
Finally, stage and commit changes to bower.json, `js/components.js`, Finally, stage and commit changes to bower.json, `js/components.js`,
and `components/`. The latter should be limited to files we actually use. and `components/`. The latter should be limited to files we actually use.
## Tests
Please write tests! Our testing framework is
[mocha](http://mochajs.org/) and our assertion library is
[chai](http://chaijs.com/api/assert/).
To run tests, use `grunt dev` or `grunt connect watch` to spin up a local
webserver, then point your browser to localhost:9999/test/index.html and
localhost:9999/libtextsecure/test/index.html

8
README.md
View file

@ -1,20 +1,24 @@
[![Build Status](https://travis-ci.org/WhisperSystems/Signal-Desktop.svg?branch=master)](https://travis-ci.org/WhisperSystems/Signal-Desktop) [![Build Status](https://travis-ci.org/WhisperSystems/Signal-Desktop.svg?branch=master)](https://travis-ci.org/WhisperSystems/Signal-Desktop)
Signal Desktop Signal Desktop
========================== ==========================
Get [Signal Private Messenger](https://chrome.google.com/webstore/detail/signal-private-messenger/bikioccmkafdpakkkcpdbppfkghcmihk) on the Chrome Web Store!
Signal Desktop is a chrome packaged app that links with your Install [Signal Desktop](https://support.signal.org/hc/en-us/articles/214507138)!
Signal Desktop is an Electron application that links with your
[Signal Android](https://github.com/WhisperSystems/Signal-Android) [Signal Android](https://github.com/WhisperSystems/Signal-Android)
or [Signal iOS](https://github.com/WhisperSystems/Signal-iOS) app. or [Signal iOS](https://github.com/WhisperSystems/Signal-iOS) app.
## Got a question? ## Got a question?
The best place to ask questions is [http://support.whispersystems.org](http://support.whispersystems.org). The best place to ask questions is [http://support.whispersystems.org](http://support.whispersystems.org).
## Found a Bug? ## Found a Bug?
Please search the existing issues for your bug and create a new one if the issue is not yet tracked! Please search the existing issues for your bug and create a new one if the issue is not yet tracked!
https://github.com/WhisperSystems/Signal-Desktop/issues https://github.com/WhisperSystems/Signal-Desktop/issues
## Contributing Translations ## Contributing Translations
Interested in helping to translate Signal? Contribute here: Interested in helping to translate Signal? Contribute here:

3
package.json
View file

@ -33,6 +33,7 @@
"spectron": "^3.6.2" "spectron": "^3.6.2"
}, },
"scripts": { "scripts": {
"postinstall": "electron-builder install-app-deps",
"test": "grunt test", "test": "grunt test",
"lint": "grunt jshint", "lint": "grunt jshint",
"start": "electron .", "start": "electron .",
@ -41,7 +42,7 @@
"generate": "npm run icon-gen && grunt", "generate": "npm run icon-gen && grunt",
"build": "build --em.environment=$SIGNAL_ENV", "build": "build --em.environment=$SIGNAL_ENV",
"dist": "npm run generate && npm run build", "dist": "npm run generate && npm run build",
"pack": "npm run dist -- --dir", "pack": "npm run generate && npm run build -- --dir",
"pack-prod": "SIGNAL_ENV=production npm run pack", "pack-prod": "SIGNAL_ENV=production npm run pack",
"dist-prod": "SIGNAL_ENV=production npm run dist", "dist-prod": "SIGNAL_ENV=production npm run dist",
"dist-prod-all": "SIGNAL_ENV=production npm run dist -- -mwl", "dist-prod-all": "SIGNAL_ENV=production npm run dist -- -mwl",