From ecec7f8b893e57ed982caae3287bbed0bd11c79a Mon Sep 17 00:00:00 2001 From: ViPuL Date: Tue, 11 Jun 2019 22:44:06 +0530 Subject: [PATCH] docs: Improve development guide. Minifies the current development guide by a significant amount. Also, removes system requirements as no credible source for them. Removes dependency specific instructions and adds links to instructions to install them. Fixes #341. --- development.md | 202 ++++++++++++++++++++----------------------------- 1 file changed, 82 insertions(+), 120 deletions(-) diff --git a/development.md b/development.md index 418b6cb2..48e6913c 100644 --- a/development.md +++ b/development.md @@ -1,152 +1,114 @@ -# Improve development guide +# Development Setup -# Development setup +This is a guide to running the Zulip desktop app from source, +in order to contribute to developing it. -This is a guide to running the Zulip desktop app from a source tree, in order to contribute to developing it. The Zulip electron development environment can be installed on **macOS, Windows, and Linux** (Debian or Ubuntu recommended). You’ll need at least **2GB of available RAM**. Installing the Zulip electron development environment requires downloading several hundred megabytes of dependencies, so you will need an **active, reasonably fast, internet connection throughout the entire installation processes.** +## Prerequisites -# Set up Git & GitHub +To build and run the app from source, you'll need the following: -You can skip this step if you already have Git, GitHub. +* [Git](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + * Use our [Git Guide](https://zulip.readthedocs.io/en/latest/git/setup.html) to get started with Git and GitHub. +* [Node.js](https://nodejs.org) >= v6.9.0 + * [NPM](https://www.npmjs.com/get-npm) and + [node-gyp](https://github.com/nodejs/node-gyp#installation), + if they don't come bundled with your Node.js installation +* [Python](https://www.python.org/downloads/release/python-2713/) + (v2.7.x recommended) +* A C++ compiler compatible with C++11 +* Development headers for the libXext, libXtst, and libxkbfile libraries, which can be installed using apt on Ubuntu using + ```sh + $ sudo apt install libxext-dev libxtst-dev libxkbfile-dev libgconf-2-4 + ``` -Follow our [Git Guide](https://zulip.readthedocs.io/en/latest/git/setup.html) in order to install Git, set up a GitHub account +### Ubuntu/Linux and other Debian-based distributions +On a system running Debian, Ubuntu, or another Debian-based Linux +distribution, you can install all dependencies through the package +manager (see [here][node-debian] for more on the first command): -# Install Prerequisites +```sh +$ curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash - +$ sudo apt install git nodejs python build-essential snapcraft libxext-dev libxtst-dev libxkbfile-dev libgconf-2-4 +``` -Jump to: +[node-debian]: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions -- [MacOS](https://github.com/zulip/zulip-desktop/blob/master/development.md#macos) -- [Ubuntu/Debian](https://github.com/zulip/zulip-desktop/blob/master/development.md#ubuntudebian) -- [Windows](https://github.com/zulip/zulip-desktop/blob/master/development.md#windows) +### MacOS +On a system running MacOS, you can refer to [official nodejs docs][node-mac] to +install nodejs. To ensure Node.js has been installed, run ```node -v``` in terminal to know your node version. -## MacOS +[node-mac]: https://nodejs.org/en/download/package-manager/#macos +If [NPM](https://www.npmjs.com/get-npm) and [node-gyp](https://github.com/nodejs/node-gyp#installation) don't come bundled with your Node.js installation, you will need to install them manually. - **Node JS** - Go to the [Node.js Downloads page](https://nodejs.org/en/download/). Download Node.js for MacOS (`v6.9.0` or above recommended). Run the downloaded Node.js `.pkg` Installer. You're finished! To ensure Node.js has been installed, run `node -v` in your terminal - you should get something like `v6.9.0` or above +### Windows +- Download Node.js for Windows and install it. You can refer to the official docs [here][node-windows] to do so. To ensure Node.js has been installed, run ```node -v``` in Git Bash to know your node version. - **if** [**NPM**](https://www.npmjs.com/get-npm) **and** [**node-gyp**](https://github.com/nodejs/node-gyp#installation) **don't come bundled with your Node.js installation, Download manually** +[node-windows]: https://nodejs.org/en/download/package-manager/#windows +- Also, install install Windows-Build-Tools to compile native node modules by using + ```sh + $ npm install --global windows-build-tools + ``` - Now you are ready for next step [: Get Zulip Desktop Code.](https://github.com/zulip/zulip-desktop/blob/master/development.md#get-zulip-desktop-code) +## Download, build, and run +Clone the source locally: +```sh +$ git clone https://github.com/zulip/zulip-desktop +$ cd zulip-desktop +``` -## Ubuntu/Debian +Install project dependencies: +```sh +$ npm install +``` +Start the app: +```sh +$ npm start +``` -If you’re in a hurry, you can copy and paste the following into your terminal +Start and watch changes: +```sh +$ npm run dev +``` - sudo apt install git nodejs node-gyp python build-essential snapcraft libxext-dev libxtst-dev lib xkbfile-dev libgconf-2-4 +Run tests: +```sh +$ npm test +``` -after pasting you can jump to next step [: Get Zulip Desktop Code](https://github.com/zulip/zulip-desktop/blob/master/development.md#get-zulip-desktop-code). +## How to contribute? +Feel free to fork this repository, test it locally and then report any bugs +you find in the [issue tracker](https://github.com/zulip/zulip-desktop/issues). -**For a step-by-step explanation, read on.** +You can read more about making contributions in our [Contributing Guide](./CONTRIBUTING.md). -1. **Node JS** +## Troubleshooting - `$ sudo apt-get install nodejs` +If you have any problems running the app, see the [most common +issues](./troubleshooting.md). -2. **Install** [**Node-gyp**](https://github.com/nodejs/node-gyp#installation) +## Making a release -3. **Python (v2.7.x recommended)** +To package the app into an installer: +``` +npm run dist +``` - `$ sudo apt install python2.7` +This command will produce distributable packages or installers for the +operating system you're running on: +* on Windows, a .7z nsis file and a .exe WebSetup file +* on macOS, a `.dmg` file +* on Linux, a plain `.zip` file as well as a `.deb` file, `.snap` file and an + `AppImage` file. -4. **C++ compiler compatible with C++11** +To generate all three types of files, you will need all three operating +systems. - `$ sudo apt install build-essential` - -5. **Snapcraft** - - `$ sudo apt install snapcraft` - -6. **Development** **headers** - - `$ sudo apt install libxext-dev libxtst-dev libxkbfile-dev libgconf-2-4` - - -**if** [**NPM**](https://www.npmjs.com/get-npm) **don't come bundled with your Node.js installation, Download manually** - - -Now you are ready for next step [: Get Zulip Desktop Code.](https://github.com/zulip/zulip-desktop/blob/master/development.md#get-zulip-desktop-code) - - -## Windows - - **Node JS** - Go to the [Node.js Downloads page](https://nodejs.org/en/download/). Download Node.js for windows (`v6.9.0` or above recommended). Run the downloaded Node.js `.msi` Installer. You're finished! To ensure Node.js has been installed, run `node -v` in your terminal - you should get something like `v6.9.0` or above - - -**Followings are optional yet recommended prerequisites -** - - **Cmder** - 1. Download the [latest release](https://github.com/cmderdev/cmder/releases/) - 2. Extract the archive. *Note: This path should not be* `C:\Program Files` *or anywhere else that would require Administrator access for modifying configuration files* - 3. (optional) Place your own executable files into the `%cmder_root%\bin` folder to be injected into your PATH. - 4. Run `Cmder.exe` - - **Chocolatey** - You can download chocolatey from here https://chocolatey.org/ and for Installing Chocolatey on your machine follow this steps - 1. First, ensure that you are using an administrative shell. - 2. Copy the text specific to your command shell - [cmd.exe](https://chocolatey.org/install#install-with-cmdexe) or [powershell.exe](https://chocolatey.org/install#install-with-powershellexe). - 3. Paste the copied text into your shell and press Enter. - 4. Wait a few seconds for the command to complete. - 5. If you don't see any errors, you are ready to use Chocolatey! Type `choco` or `choco -?` - - -**System specific dependencies** - -- use only 32bit or 64bit for all of the installers, do not mix architectures -- install using default settings -- open Windows Powershell as Admin and paste this - C:\Windows\system32> npm install --global --production windows-build-tools - - -**if** [**NPM**](https://www.npmjs.com/get-npm) **and** [**node-gyp**](https://github.com/nodejs/node-gyp#installation) **don't come bundled with your Node.js installation, Download manually** - -Now you are ready for next step [: Get Zulip Desktop Code.](https://github.com/zulip/zulip-desktop/blob/master/development.md#get-zulip-desktop-code) - - -# Get Zulip Desktop Code - -1. In your browser, visit https://github.com/zulip/zulip-desktop and click the `fork` button. You will need to be logged in to GitHub to do this. -2. Open Terminal (macOS/Ubuntu) or Git BASH (Windows; must **run as an Administrator**). -3. In Terminal/Git BASH, [clone your fork of the zulip-desktop repository](https://github.com/zulip/zulip-desktop/blob/master/development.md#clone-to-your-machine) and [connect the zulip-desktop upstream repository](https://github.com/zulip/zulip-desktop/blob/master/development.md#connect-your-fork-to-zulip-desktop-upstream) - - -## Clone to your machine - 1. On GitHub, navigate to the main page of your fork repository. - 2. Under the repository name, click **Clone or download**. - 3. In the Clone with HTTPs section, click to copy the clone URL for the repository. - 4. Open Terminal, Change the current working directory to the location where you want the cloned directory to be made. - - git clone https://github.com/YOURUSERNAME/zulip-desktop.git - -Don’t forget to replace YOURUSERNAME with your git username - - -## Connect your fork to zulip-desktop upstream - - cd zulip-desktop - git remote add -f upstream https://github.com/zulip/zulip-desktop.git - - -# build and run - - -## Install project dependencies: - $ npm install - - -## There two ways to start the app: - -**vanilla method** - - $ npm start - -**start and watch changes recommended for dev’s** - - $ npm run dev +The output distributable packages appear in the `dist/` directory. \ No newline at end of file