mirror of
https://github.com/balena-io/etcher.git
synced 2025-07-24 19:56:37 +00:00
doc: Merge running locally into contributing guide (#1640)
As recently several people have been asking for things that are described in `RUNNING-LOCALLY.md`, but couldn't be found in the `CONTRIBUTING.md`, this consilidates the two into one single resource to look for on how to get started developing. Change-Type: patch
This commit is contained in:
Jonas Hermsmeier
GitHub
parent
07ac2ecf4c
commit
25d50fed74
@ -10,47 +10,87 @@ High-level Etcher overview
|
||||
Make sure you checkout our [ARCHITECTURE.md][ARCHITECTURE] guide, which aims to
|
||||
explain how all the pieces fit together.
|
||||
|
||||
Running locally
|
||||
---------------
|
||||
|
||||
See the [RUNNING-LOCALLY.md][RUNNING-LOCALLY] guide.
|
||||
|
||||
Developing
|
||||
----------
|
||||
|
||||
We rely on various `make` targets to perform some common tasks:
|
||||
### Prerequisites
|
||||
|
||||
- `make lint`: Run the linter.
|
||||
- `make sass`: Compile SCSS files.
|
||||
#### Common
|
||||
|
||||
We make use of [EditorConfig] to communicate indentation, line endings and
|
||||
other text editing default. We encourage you to install the relevant plugin in
|
||||
your text editor of choice to avoid having to fix any issues during the review
|
||||
process.
|
||||
- [NodeJS](https://nodejs.org) (at least v6)
|
||||
- [Python](https://www.python.org)
|
||||
- [jq](https://stedolan.github.io/jq/)
|
||||
- [curl](https://curl.haxx.se/)
|
||||
|
||||
Commit Guidelines
|
||||
-----------------
|
||||
```sh
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
See [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES] for a thorough guide on how to
|
||||
write commit messages.
|
||||
You might need to run this with `sudo` or administrator permissions.
|
||||
|
||||
Updating a dependency
|
||||
---------------------
|
||||
#### Windows
|
||||
|
||||
Given we use [npm shrinkwrap][shrinkwrap], we have to take extra steps to make
|
||||
sure the `npm-shrinkwrap.json` file gets updated correctly when we update a
|
||||
dependency.
|
||||
- [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work)
|
||||
- Either one of the following:
|
||||
- [Visual C++ 2015 Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) containing standalone compilers, libraries and scripts
|
||||
- Install the [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) via npm with `npm install --global windows-build-tools`
|
||||
- [Visual Studio Community 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48146) (free) (other editions, like Professional and Enterprise, should work too)
|
||||
**NOTE:** Visual Studio 2015 doesn't install C++ by default. You have to rerun the
|
||||
setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual
|
||||
C++ 2015` (see http://stackoverflow.com/a/31955339)
|
||||
- [MinGW](http://www.mingw.org)
|
||||
|
||||
Use the following steps to ensure everything goes flawlessly:
|
||||
The following MinGW packages are required:
|
||||
|
||||
- Run `make electron-develop` to ensure you don't have extraneous dependencies
|
||||
you might have brought during development, or you are running older
|
||||
dependencies because you come from another branch or reference.
|
||||
- `msys-make`
|
||||
- `msys-unzip`
|
||||
- `msys-zip`
|
||||
- `msys-bash`
|
||||
- `msys-coreutils`
|
||||
|
||||
- Install the new version of the dependency. For example: `npm install --save
|
||||
<package>@<version>`. This will update the `npm-shrinkwrap.json` file.
|
||||
#### OS X
|
||||
|
||||
- Commit *both* `package.json` and `npm-shrinkwrap.json`.
|
||||
- [XCode](https://developer.apple.com/xcode/) or [XCode Command Line Tools],
|
||||
which can be installed by running `xcode-select --install`.
|
||||
|
||||
### Cloning the project
|
||||
|
||||
```sh
|
||||
git clone https://github.com/resin-io/etcher
|
||||
cd etcher
|
||||
```
|
||||
|
||||
### Installing npm dependencies
|
||||
|
||||
**Make sure you have all the pre-requisites listed above installed in your
|
||||
system before running the `install` script.**
|
||||
|
||||
**NOTE:** Please make use of the following scripts to install npm dependencies rather
|
||||
than simply running `npm install` given that we need to do extra configuration
|
||||
to make sure native dependencies are correctly compiled for Electron, otherwise
|
||||
the application might not run successfully.
|
||||
|
||||
If you're on Windows, **run the command from the _Developer Command Prompt for
|
||||
VS2015_**, to ensure all Visual Studio command utilities are available in the
|
||||
`%PATH%`.
|
||||
|
||||
```sh
|
||||
make electron-develop
|
||||
```
|
||||
|
||||
### Running the application
|
||||
|
||||
#### GUI
|
||||
|
||||
```sh
|
||||
npm start
|
||||
```
|
||||
|
||||
#### CLI
|
||||
|
||||
```sh
|
||||
node bin/etcher
|
||||
```
|
||||
|
||||
Testing
|
||||
-------
|
||||
@ -75,6 +115,34 @@ systems as they can before sending a pull request.
|
||||
*The test suite is run automatically by CI servers when you send a pull
|
||||
request.*
|
||||
|
||||
We also rely on various `make` targets to perform some common tasks:
|
||||
|
||||
- `make lint`: Run the linter.
|
||||
- `make sass`: Compile SCSS files.
|
||||
|
||||
We make use of [EditorConfig] to communicate indentation, line endings and
|
||||
other text editing default. We encourage you to install the relevant plugin in
|
||||
your text editor of choice to avoid having to fix any issues during the review
|
||||
process.
|
||||
|
||||
Updating a dependency
|
||||
---------------------
|
||||
|
||||
Given we use [npm shrinkwrap][shrinkwrap], we have to take extra steps to make
|
||||
sure the `npm-shrinkwrap.json` file gets updated correctly when we update a
|
||||
dependency.
|
||||
|
||||
Use the following steps to ensure everything goes flawlessly:
|
||||
|
||||
- Run `make electron-develop` to ensure you don't have extraneous dependencies
|
||||
you might have brought during development, or you are running older
|
||||
dependencies because you come from another branch or reference.
|
||||
|
||||
- Install the new version of the dependency. For example: `npm install --save
|
||||
<package>@<version>`. This will update the `npm-shrinkwrap.json` file.
|
||||
|
||||
- Commit *both* `package.json` and `npm-shrinkwrap.json`.
|
||||
|
||||
Diffing Binaries
|
||||
----------------
|
||||
|
||||
@ -97,6 +165,12 @@ $ git config --global diff.hex.binary true
|
||||
If you don't have `hexdump` available on your platform,
|
||||
you can try [hxd], which is also a bit faster.
|
||||
|
||||
Commit Guidelines
|
||||
-----------------
|
||||
|
||||
See [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES] for a thorough guide on how to
|
||||
write commit messages.
|
||||
|
||||
Sending a pull request
|
||||
----------------------
|
||||
|
||||
@ -133,8 +207,8 @@ systems we support.
|
||||
Don't hesitate to get in touch if you have any questions or need any help!
|
||||
|
||||
[ARCHITECTURE]: https://github.com/resin-io/etcher/blob/master/docs/ARCHITECTURE.md
|
||||
[RUNNING-LOCALLY]: https://github.com/resin-io/etcher/blob/master/docs/RUNNING-LOCALLY.md
|
||||
[COMMIT-GUIDELINES]: https://github.com/resin-io/etcher/blob/master/docs/COMMIT-GUIDELINES.md
|
||||
[EditorConfig]: http://editorconfig.org
|
||||
[shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap
|
||||
[hxd]: https://github.com/jhermsmeier/hxd
|
||||
[XCode Command Line Tools]: https://developer.apple.com/library/content/technotes/tn2339/_index.html
|
||||
|
||||
@ -1,87 +0,0 @@
|
||||
Running locally
|
||||
===============
|
||||
|
||||
This document aims to serve as a guide to get Etcher running locally on your
|
||||
development machine.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
### Common
|
||||
|
||||
- [NodeJS](https://nodejs.org) (at least v6)
|
||||
- [Python](https://www.python.org)
|
||||
- [jq](https://stedolan.github.io/jq/)
|
||||
- [curl](https://curl.haxx.se/)
|
||||
|
||||
```sh
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
You might need to run this with `sudo` or administrator permissions.
|
||||
|
||||
### Windows
|
||||
|
||||
- [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work)
|
||||
- Either one of the following:
|
||||
- [Visual C++ 2015 Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) containing standalone compilers, libraries and scripts
|
||||
- Install the [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) via npm with `npm install --global windows-build-tools`
|
||||
- [Visual Studio Community 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48146) (free) (other editions, like Professional and Enterprise, should work too)
|
||||
**NOTE:** Visual Studio 2015 doesn't install C++ by default. You have to rerun the
|
||||
setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual
|
||||
C++ 2015` (see http://stackoverflow.com/a/31955339)
|
||||
- [MinGW](http://www.mingw.org)
|
||||
|
||||
The following MinGW packages are required:
|
||||
|
||||
- `msys-make`
|
||||
- `msys-unzip`
|
||||
- `msys-zip`
|
||||
- `msys-bash`
|
||||
- `msys-coreutils`
|
||||
|
||||
### OS X
|
||||
|
||||
- [XCode](https://developer.apple.com/xcode/)
|
||||
|
||||
Cloning the project
|
||||
-------------------
|
||||
|
||||
```sh
|
||||
git clone https://github.com/resin-io/etcher
|
||||
cd etcher
|
||||
```
|
||||
|
||||
Installing npm dependencies
|
||||
---------------------------
|
||||
|
||||
**Make sure you have all the pre-requisites listed above installed in your
|
||||
system before running the `install` script.**
|
||||
|
||||
Please make use of the following scripts to install npm dependencies rather
|
||||
than simply running `npm install` given that we need to do extra configuration
|
||||
to make sure native dependencies are correctly compiled for Electron, otherwise
|
||||
the application might not run successfully.
|
||||
|
||||
If you're on Windows, **run the command from the _Developer Command Prompt for
|
||||
VS2015_**, to ensure all Visual Studio command utilities are available in the
|
||||
`%PATH%`.
|
||||
|
||||
```sh
|
||||
make electron-develop
|
||||
```
|
||||
|
||||
Running the application
|
||||
-----------------------
|
||||
|
||||
### GUI
|
||||
|
||||
```sh
|
||||
npm start
|
||||
```
|
||||
|
||||
### CLI
|
||||
|
||||
```sh
|
||||
node bin/etcher
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user