From 9f12d77771d89cba8812a61d6f13989a00531291 Mon Sep 17 00:00:00 2001 From: usernamealreadyis Date: Wed, 6 Jan 2016 05:16:17 +0700 Subject: [PATCH] Create DEVELOPER.MD --- DEVELOPER.MD | 358 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 358 insertions(+) create mode 100644 DEVELOPER.MD diff --git a/DEVELOPER.MD b/DEVELOPER.MD new file mode 100644 index 000000000000..5b077fb92960 --- /dev/null +++ b/DEVELOPER.MD @@ -0,0 +1,358 @@ +# Building and Testing Angular 2 for JS and Dart + +This document describes how to set up your development environment to build and test Angular, both +JS and Dart versions. It also explains the basic mechanics of using `git`, `node`, and `npm`. + +* [Prerequisite Software](#prerequisite-software) +* [Getting the Sources](#getting-the-sources) +* [Environment Variable Setup](#environment-variable-setup) +* [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-packages) +* [Build commands](#build-commands) +* [Running Tests Locally](#running-tests-locally) +* [Formatting](#clang-format) +* [Project Information](#project-information) +* [CI using Travis](#ci-using-travis) +* [Transforming Dart code](#transforming-dart-code) +* [Debugging](#debugging) + +See the [contribution guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md) +if you'd like to contribute to Angular. + +## Prerequisite Software + +Before you can build and test Angular, you must install and configure the +following products on your development machine: + +* [Dart](https://www.dartlang.org) (version ` >=1.12.0 <2.0.0`), specifically the Dart-SDK and + Dartium (a version of [Chromium](http://www.chromium.org) with native support for Dart through + the Dart VM). One of the **simplest** ways to get both is to install the **Dart Editor bundle**, + which includes the editor, SDK and Dartium. See the [Dart tools](https://www.dartlang.org/tools) + download [page for instructions](https://www.dartlang.org/tools/download.html). + You can also download both **stable** and **dev** channel versions from the [download + archive](https://www.dartlang.org/tools/download-archive). In that case, on Windows, Dart must be added + to the `Path` (e.g. `path-to-dart-sdk-folder\bin`) and a new `DARTIUM_BIN` environment variable must be + created, pointing to the executable (e.g. `path-to-dartium-folder\chrome.exe).` + +* [Git](http://git-scm.com) and/or the **GitHub app** (for [Mac](http://mac.github.com) or + [Windows](http://windows.github.com)); [GitHub's Guide to Installing + Git](https://help.github.com/articles/set-up-git) is a good source of information. + +* [Node.js](http://nodejs.org), (version `>=4.2.1 <5`) which is used to run a development web server, + run tests, and generate distributable files. We also use Node's Package Manager, `npm` + (version `>=2.14.7 <3.0`), which comes with Node. Depending on your system, you can install Node either from + source or as a pre-packaged bundle. + +* [Chrome Canary](https://www.google.com/chrome/browser/canary.html), a version of Chrome with + bleeding edge functionality, built especially for developers (and early adopters). + +* [Bower](http://bower.io/). + + +## Getting the Sources + +Fork and clone the Angular repository: + +1. Login to your GitHub account or create one by following the instructions given + [here](https://github.com/signup/free). +2. [Fork](http://help.github.com/forking) the [main Angular + repository](https://github.com/angular/angular). +3. Clone your fork of the Angular repository and define an `upstream` remote pointing back to + the Angular repository that you forked in the first place. + +```shell +# Clone your GitHub repository: +git clone git@github.com:/angular.git + +# Go to the Angular directory: +cd angular + +# Add the main Angular repository as an upstream remote to your repository: +git remote add upstream https://github.com/angular/angular.git +``` + +## Environment Variable Setup + +Define the environment variables listed below. These are mainly needed for the testing. The +notation shown here is for [`bash`](http://www.gnu.org/software/bash); adapt as appropriate for +your favorite shell. + +Examples given below of possible values for initializing the environment variables assume **Mac OS +X** and that you have installed the Dart Editor in the directory named by +`DART_EDITOR_DIR=/Applications/dart`. This is only for illustrative purposes. + +```shell +# DARTIUM_BIN: path to a Dartium browser executable; used by Karma to run Dart tests +export DARTIUM_BIN="$DART_EDITOR_DIR/chromium/Chromium.app/Contents/MacOS/Chromium" +``` + +Add the Dart SDK `bin` directory to your path and/or define `DART_SDK` (this is also detailed +[here](https://www.dartlang.org/tools/pub/installing.html)): + +```shell +# DART_SDK: path to a Dart SDK directory +export DART_SDK="$DART_EDITOR_DIR/dart-sdk" + +# Update PATH to include the Dart SDK bin directory +PATH+=":$DART_SDK/bin" +``` + +And specify where the pub’s dependencies are downloaded. By default, this directory is located under .pub_cache +in your home directory (on Mac and Linux), or in AppData\Roaming\Pub\Cache (on Windows). + +```shell +# PUB_CACHE: location of pub dependencies +export PUB_CACHE="/Users//.pub-cache" +``` + +## Installing NPM Modules and Dart Packages + +Next, install the JavaScript modules and Dart packages needed to build and test Angular: + +```shell +# Install Angular project dependencies (package.json) +npm install +``` + +**Optional**: In this document, we make use of project local `npm` package scripts and binaries +(stored under `./node_modules/.bin`) by prefixing these command invocations with `$(npm bin)`; in +particular `gulp` and `protractor` commands. If you prefer, you can drop this path prefix by either: + +*Option 1*: globally installing these two packages as follows: + +* `npm install -g gulp` (you might need to prefix this command with `sudo`) +* `npm install -g protractor` (you might need to prefix this command with `sudo`) + +Since global installs can become stale, and required versions can vary by project, we avoid their +use in these instructions. + +*Option 2*: defining a bash alias like `alias nbin='PATH=$(npm bin):$PATH'` as detailed in this +[Stackoverflow answer](http://stackoverflow.com/questions/9679932/how-to-use-package-installed-locally-in-node-modules/15157360#15157360) and used like this: e.g., `nbin gulp build`. + +## Build commands + +To build Angular and prepare tests, run: + +```shell +$(npm bin)/gulp build +``` + +Notes: +* Results are put in the `dist` folder. +* This will also run `pub get` for the subfolders in `modules` and run `dartanalyzer` for + every file that matches `/src/.dart`, e.g. `di/src/di.dart`. + +You can selectively build either the JS or Dart versions as follows: + +* `$(npm bin)/gulp build.js` +* `$(npm bin)/gulp build.dart` + +To clean out the `dist` folder, run: + +```shell +$(npm bin)/gulp clean +``` + +## Running Tests Locally + +### Full test suite + +* `npm test`: full test suite for both JS and Dart versions of Angular. These are the same tests + that run on Travis. + +You can selectively run either the JS or Dart versions as follows: + +* `$(npm bin)/gulp test.all.js` +* `$(npm bin)/gulp test.all.dart` + +### Unit tests + +You can run just the unit tests as follows: + +* `$(npm bin)/gulp test.unit.js`: JS tests in a browser; runs in **watch mode** (i.e. + watches the test files for changes and re-runs tests when files are updated). +* `$(npm bin)/gulp test.unit.cjs`: JS tests in NodeJS; runs in **watch mode**. +* `$(npm bin)/gulp test.unit.dart`: Dart tests in Dartium; runs in **watch mode**. + +If you prefer running tests in "single-run" mode rather than watch mode use: + +* `$(npm bin)/gulp test.unit.js/ci` +* `$(npm bin)/gulp test.unit.cjs/ci` +* `$(npm bin)/gulp test.unit.dart/ci` + +The task updates the dist folder with transpiled code whenever a source or test file changes, and +Karma is run against the new output. + +**Note**: If you want to only run a single test you can alter the test you wish to run by changing +`it` to `iit` or `describe` to `ddescribe`. This will only run that individual test and make it +much easier to debug. `xit` and `xdescribe` can also be useful to exclude a test and a group of +tests respectively. + +**Note**: **watch mode** needs symlinks to work, so if you're using windows, ensure you have the +rights to built them in your operating system. + +### Unit tests with Sauce Labs or Browser Stack + +First, in a terminal, create a tunnel with [Sauce Connect](https://docs.saucelabs.com/reference/sauce-connect/) or [Browser Stack Local](https://www.browserstack.com/local-testing#command-line), and valid credentials. + +Then, in another terminal: + - Define the credentials as environment variables, e.g.: +``` +export SAUCE_USERNAME='my_user'; export SAUCE_ACCESS_KEY='my_key'; +export BROWSER_STACK_USERNAME='my_user'; export BROWSER_STACK_ACCESS_KEY='my_key'; +``` + - Then run `gulp test.unit.js.(saucelabs|browserstack) --browsers=option1,option2,..,optionN` +The options are any mix of browsers and aliases which are defined in the [browser-providers.conf.js](https://github.com/angular/angular/blob/master/browser-providers.conf.js) file. +They are case insensitive, and the `SL_` or `BS_` prefix must not be added for browsers. + +Some examples of commands: +``` +gulp test.unit.js.saucelabs --browsers=Safari8,ie11 //run in Sauce Labs with Safari 8 and IE11 +gulp test.unit.js.browserstack --browsers=Safari,IE //run in Browser Stack with Safari 7, Safari 8, Safari 9, IE 9, IE 10 and IE 11 +gulp test.unit.js.saucelabs --browsers=IOS,safari8,android5.1 //run in Sauce Labs with iOS 7, iOS 8, iOs 9, Safari 8 and Android 5.1 +``` + +### E2E tests + +1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder). +2. `$(npm bin)/gulp serve.js.prod serve.dart` (runs a local webserver). +3. `$(npm bin)/protractor protractor-js.conf.js`: JS e2e tests. +4. `$(npm bin)/protractor protractor-dart2js.conf.js`: dart2js e2e tests. + +Angular specific command line options when running protractor: + - `$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help` + +### Performance tests + +1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder) +2. `$(npm bin)/gulp serve.js.prod serve.dart` (runs a local webserver) +3. `$(npm bin)/protractor protractor-js.conf.js --benchmark`: JS performance tests +4. `$(npm bin)/protractor protractor-dart2js.conf.js --benchmark`: dart2js performance tests + +Angular specific command line options when running protractor (e.g. force gc, ...): +`$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help` + +## Formatting with clang-format + +We use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) to automatically enforce code +style for our TypeScript code. This allows us to focus our code reviews more on the content, and +less on style nit-picking. It also lets us encode our style guide in the `.clang-format` file in the +repository, allowing many tools and editors to share our settings. + +To check the formatting of your code, run + + gulp check-format + +Note that the continuous build on Travis runs `gulp enforce-format`. Unlike the `check-format` task, +this will actually fail the build if files aren't formatted according to the style guide. + +Your life will be easier if you include the formatter in your standard workflow. Otherwise, you'll +likely forget to check the formatting, and waste time waiting for a build on Travis that fails due +to some whitespace difference. + +* Use `$(npm bin)/clang-format -i [file name]` to format a file (or multiple). +* Use `gulp enforce-format` to check if your code is `clang-format` clean. This also gives + you a command line to format your code. +* `clang-format` also includes a git hook, run `git clang-format` to format all files you + touched. +* You can run this as a **git pre-commit hook** to automatically format your delta regions when you + commit a change. In the angular repo, run + +``` + $ echo -e '#!/bin/sh\nexec git clang-format' > .git/hooks/pre-commit + $ chmod u+x !$ +``` + +* **WebStorm** can run clang-format on the current file. + 1. Under Preferences, open Tools > External Tools. + 1. Plus icon to Create Tool + 1. Fill in the form: + - Name: clang-format + - Description: Format + - Synchronize files after execution: checked + - Open console: not checked + - Show in: Editor menu + - Program: `$ProjectFileDir$/node_modules/.bin/clang-format` + - Parameters: `-i -style=file $FilePath$` + - Working directory: `$ProjectFileDir$` +* `clang-format` integrations are also available for many popular editors (`vim`, `emacs`, + `Sublime Text`, etc.). + +## Generating the API documentation + +The following gulp task will generate the API docs in the `dist/angular.io/partials/api/angular2`: + +```shell +$(npm bin)/gulp docs/angular.io +``` + +You can serve the generated documentation to check how it would render on [angular.io](https://angular.io/): +- check out the [angular.io repo](https://github.com/angular/angular.io) locally, +- install dependencies as described in the [angular.io README](https://github.com/angular/angular.io/blob/master/README.md), +- copy the generated documentation from your local angular repo at `angular/dist/angular.io/partials/api/angular2` to your local angular.io repo at `angular.io/public/docs/js/latest/api`, +- run `harp compile` at the root of the angular.io repo to check the generated documentation for errors, +- run `harp server` and open a browser at `http://localhost:9000/docs/js/latest/api/` to check the rendered documentation. + +## Project Information + +### Folder structure + +* `modules/*`: modules that will be loaded in the browser +* `tools/*`: tools that are needed to build Angular +* `dist/*`: build files are placed here. + +### File suffixes + +* `*.ts`: TypeScript files that get transpiled to Dart and EcmaScript 5/6 +* `*.dart`: Dart files that don't get transpiled + +## CI using Travis + +For instructions on setting up Continuous Integration using Travis, see the instructions given +[here](https://github.com/angular/angular.dart/blob/master/travis.md). + +## Transforming Dart code + +See the [wiki](//github.com/angular/angular/wiki/Angular-2-Dart-Transformer). + +## Debugging + +### Debug the transpiler + +If you need to debug the transpiler: + +- add a `debugger;` statement in the transpiler code, +- from the root folder, execute `node debug $(npm bin)/gulp build` to enter the node + debugger +- press "c" to execute the program until you reach the `debugger;` statement, +- you can then type "repl" to enter the REPL and inspect variables in the context. + +See the [Node.js manual](http://nodejs.org/api/debugger.html) for more information. + +Notes: +- You can also execute `node $(npm bin)/karma start karma-dart.conf.js` depending on which + code you want to debug (the former will process the "modules" folder while the later processes + the transpiler specs). +- You can also add `debugger;` statements in the specs (JavaScript). The execution will halt when + the developer tools are opened in the browser running Karma. + +### Debug the tests + +If you need to debug the tests: + +- add a `debugger;` statement to the test you want to debug (or the source code), +- execute karma `$(npm bin)/gulp test.js`, +- press the top right "DEBUG" button, +- open the DevTools and press F5, +- the execution halts at the `debugger;` statement + +**Note (WebStorm users)**: + +1. Create a Karma run config from WebStorm. +2. Then in the "Run" menu, press "Debug 'karma-js.conf.js'", and WebStorm will stop in the generated + code on the `debugger;` statement. +3. You can then step into the code and add watches. + +The `debugger;` statement is needed because WebStorm will stop in a transpiled file. Breakpoints in +the original source files are not supported at the moment. + +#### wants to merge 7 commits into GistIcon:usernamealreadyis-patch-100000000 from angular:master