|
1 | | -driveshare-gui |
| 1 | +electron-boilerplate |
2 | 2 | ============== |
| 3 | +Comprehensive boilerplate application for [Electron](http://electron.atom.io). |
3 | 4 |
|
4 | | -This code provides for the GUI of the [DriveShare application](https://github.com/Storj/DriveShare). It is written in Python using the Kivy interface. |
| 5 | +This project gives you mainly three things: |
| 6 | + |
| 7 | +1. Cross-platform development environment (works the same way on OSX, Windows and Linux). |
| 8 | +2. Basic structure for Electron app. |
| 9 | +3. Scripts to generate installers of your app for all three operating systems. |
| 10 | + |
| 11 | +By the way, there is a twin project to this one: [nw-boilerplate](https://github.com/szwacz/nw-boilerplate), which is the same thing but for NW.js. |
| 12 | + |
| 13 | +# Quick start |
| 14 | +The only development dependency of this project is [Node.js](https://nodejs.org). So just make sure you have it installed. |
| 15 | +Then type few commands known to every Node developer... |
| 16 | +``` |
| 17 | +git clone https://github.com/szwacz/electron-boilerplate.git |
| 18 | +cd electron-boilerplate |
| 19 | +npm install |
| 20 | +npm start |
| 21 | +``` |
| 22 | +... and boom! You have running desktop application on your screen. |
| 23 | + |
| 24 | +# Structure of the project |
| 25 | + |
| 26 | +There are **two** `package.json` files: |
| 27 | + |
| 28 | +#### 1. For development |
| 29 | +Sits on path: `electron-boilerplate/package.json`. Here you declare dependencies for your development environment and build scripts. **This file is not distributed with real application!** |
| 30 | + |
| 31 | +Also here you declare the version of Electron runtime you want to use: |
| 32 | +```json |
| 33 | +"devDependencies": { |
| 34 | + "electron-prebuilt": "^0.24.0" |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +#### 2. For your application |
| 39 | +Sits on path: `electron-boilerplate/app/package.json`. This is **real** manifest of your application. Declare your app dependencies here. |
| 40 | + |
| 41 | +### Project's folders |
| 42 | + |
| 43 | +- `app` - code of your application goes here. |
| 44 | +- `config` - place for you to declare environment specific stuff. |
| 45 | +- `build` - in this folder lands built, runnable application. |
| 46 | +- `releases` - ready for distribution installers will land here. |
| 47 | +- `resources` - resources for particular operating system. |
| 48 | +- `tasks` - build and development environment scripts. |
| 49 | + |
| 50 | + |
| 51 | +# Development |
| 52 | + |
| 53 | +#### Installation |
| 54 | + |
| 55 | +``` |
| 56 | +npm install |
| 57 | +``` |
| 58 | +It will also download Electron runtime, and install dependencies for second `package.json` file inside `app` folder. |
| 59 | + |
| 60 | +#### Starting the app |
| 61 | + |
| 62 | +``` |
| 63 | +npm start |
| 64 | +``` |
| 65 | + |
| 66 | +#### Adding pure-js npm modules to your app |
| 67 | + |
| 68 | +Remember to add your dependency to `app/package.json` file, so do: |
| 69 | +``` |
| 70 | +cd app |
| 71 | +npm install name_of_npm_module --save |
| 72 | +``` |
| 73 | + |
| 74 | +#### Adding native npm modules to your app |
| 75 | + |
| 76 | +If you want to install native module you need to compile it agains Electron, not Node.js you are firing in command line by typing `npm install` [(Read more)](https://github.com/atom/electron/blob/master/docs/tutorial/using-native-node-modules.md). |
| 77 | +``` |
| 78 | +npm run app-install -- name_of_npm_module |
| 79 | +``` |
| 80 | +Of course this method works also for pure-js modules, so you can use it all the time if you're able to remember such an ugly command. |
| 81 | + |
| 82 | +#### Module loader |
| 83 | + |
| 84 | +How about splitting your JavaScript code into modules? This project supports it by new ES6 syntax (thanks to [babel](https://babeljs.io/)). ES6 modules are translated into AMD (RequireJS) modules. The main advantage of this setup is that you can use ES6 -> RequireJS for your own modules, and at the same time have normal access to node's `require()` to obtain stuff from npm. |
| 85 | +```javascript |
| 86 | +// Modules you write are required through new ES6 syntax |
| 87 | +// (It will be translated into AMD definition). |
| 88 | +import myOwnModule from './my_own_module'; |
| 89 | +// Node.js (npm) modules are required the same way as always |
| 90 | +// (so you can still access all the goodness of npm). |
| 91 | +var moment = require('moment'); |
| 92 | +``` |
| 93 | + |
| 94 | +#### Unit tests |
| 95 | + |
| 96 | +electron-boilerplate has preconfigured [jasmine](http://jasmine.github.io/2.0/introduction.html) unit test runner. To run it go with standard: |
| 97 | +``` |
| 98 | +npm test |
| 99 | +``` |
| 100 | +You don't have to declare paths to spec files in any particular place. The runner will search through the project for all `*.spec.js` files and include them automatically. |
| 101 | + |
| 102 | + |
| 103 | +# Making a release |
| 104 | + |
| 105 | +**Note:** There are various icon and bitmap files in `resources` directory. Those are used in installers and are intended to be replaced by your own graphics. |
| 106 | + |
| 107 | +To make ready for distribution installer use command: |
| 108 | +``` |
| 109 | +npm run release |
| 110 | +``` |
| 111 | +It will start the packaging process for operating system you are running this command on. Ready for distribution file will be outputted to `releases` directory. |
| 112 | + |
| 113 | +You can create Windows installer only when running on Windows, the same is true for Linux and OSX. So to generate all three installers you need all three operating systems. |
| 114 | + |
| 115 | + |
| 116 | +## Special precautions for Windows |
| 117 | +As installer [NSIS](http://nsis.sourceforge.net/Main_Page) is used. You have to install it (version 3.0), and add NSIS folder to PATH in Environment Variables, so it is reachable to scripts in this project (path should look something like `C:/Program Files (x86)/NSIS`). |
| 118 | + |
| 119 | + |
| 120 | +# License |
| 121 | + |
| 122 | +The MIT License (MIT) |
| 123 | + |
| 124 | +Copyright (c) 2015 Jakub Szwacz |
| 125 | + |
| 126 | +Permission is hereby granted, free of charge, to any person obtaining a copy |
| 127 | +of this software and associated documentation files (the "Software"), to deal |
| 128 | +in the Software without restriction, including without limitation the rights |
| 129 | +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 130 | +copies of the Software, and to permit persons to whom the Software is |
| 131 | +furnished to do so, subject to the following conditions: |
| 132 | + |
| 133 | +The above copyright notice and this permission notice shall be included in all |
| 134 | +copies or substantial portions of the Software. |
| 135 | + |
| 136 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 137 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 138 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 139 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 140 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 141 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 142 | +SOFTWARE. |
0 commit comments