|
| 1 | +# Building and Testing Angular 2 for JS and Dart |
| 2 | + |
| 3 | +This document describes how to set up your development environment to build and test Angular, both |
| 4 | +JS and Dart versions. It also explains the basic mechanics of using `git`, `node`, and `npm`. |
| 5 | + |
| 6 | +See the [contributing guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md) |
| 7 | +for how to contribute your own code to |
| 8 | + |
| 9 | +1. [Prerequisite Software](#prerequisite-software) |
| 10 | +2. [Getting the Sources](#getting-the-sources) |
| 11 | +3. [Environment Variable Setup](#environment-variable-setup) |
| 12 | +4. [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-packages) |
| 13 | +5. [Running Tests Locally](#running-tests-locally) |
| 14 | +6. [Project Information](#project-information) |
| 15 | +7. [CI using Travis](#ci-using-travis) |
| 16 | +8. [Debugging](#debugging) |
| 17 | + |
| 18 | +## Prerequisite Software |
| 19 | + |
| 20 | +Before you can build and test Angular, you must install and configure the |
| 21 | +following products on your development machine: |
| 22 | + |
| 23 | +* [Dart](https://www.dartlang.org) (version `>=1.9.0-dev.8.0`), specifically the Dart-SDK and |
| 24 | + Dartium (a version of [Chromium](http://www.chromium.org) with native support for Dart through |
| 25 | + the Dart VM). One of the **simplest** ways to get both is to install the **Dart Editor bundle**, |
| 26 | + which includes the editor, SDK and Dartium. See the [Dart tools](https://www.dartlang.org/tools) |
| 27 | + download [page for instructions](https://www.dartlang.org/tools/download.html); note that you can |
| 28 | + download both **stable** and **dev** channel versions from the [download |
| 29 | + archive](https://www.dartlang.org/tools/download-archive). |
| 30 | + |
| 31 | +* [Git](http://git-scm.com) and/or the **Github app** (for [Mac](http://mac.github.com) or |
| 32 | + [Windows](http://windows.github.com)): the [Github Guide to Installing |
| 33 | + Git](https://help.github.com/articles/set-up-git) is a good source of information. |
| 34 | + |
| 35 | +* [Node.js](http://nodejs.org) which is used to run a development web server, run tests, and |
| 36 | + generate distributable files. We also use Node's Package Manager (`npm`). Depending on your |
| 37 | + system, you can install Node either from source or as a pre-packaged bundle. |
| 38 | + |
| 39 | +* [Chrome Canary](https://www.google.com/chrome/browser/canary.html), a version of Chrome with |
| 40 | + bleeding edge functionality, built especially for developers (and early adopters). |
| 41 | + |
| 42 | + |
| 43 | +## Getting the Sources |
| 44 | + |
| 45 | +Forking and cloning the Angular repository: |
| 46 | + |
| 47 | +1. Login to your Github account or create one by following the instructions given |
| 48 | + [here](https://github.com/signup/free). |
| 49 | +2. [Fork](http://help.github.com/forking) the [main Angular |
| 50 | + repository](https://github.com/angular/angular). |
| 51 | +3. Clone your fork of the Angular repository and define an `upstream` remote pointing back to |
| 52 | + the Angular repository that you forked in the first place: |
| 53 | + |
| 54 | +```shell |
| 55 | +# Clone your Github repository: |
| 56 | +git clone [email protected]: <github username >/angular.git |
| 57 | + |
| 58 | +# Go to the Angular directory: |
| 59 | +cd angular |
| 60 | + |
| 61 | +# Add the main Angular repository as an upstream remote to your repository: |
| 62 | +git remote add upstream https://github.com/angular/angular.git |
| 63 | +``` |
| 64 | + |
| 65 | +## Environment Variable Setup |
| 66 | + |
| 67 | +Define the environment variables listed below. These are mainly needed for the testing. The |
| 68 | +notation shown here is for [`bash`](http://www.gnu.org/software/bash); adapt as appropriate for |
| 69 | +your favorite shell. |
| 70 | + |
| 71 | +Examples given below of possible values for initializing the environment variables assume **Mac OS |
| 72 | +X** and that you have installed the Dart Editor in the directory named by |
| 73 | +`DART_EDITOR_DIR=/Applications/dart`. This is only for illustrative purposes. |
| 74 | + |
| 75 | +```shell |
| 76 | +# DARTIUM_BIN: path to a Dartium browser executable; used by Karma to run Dart tests |
| 77 | +export DARTIUM_BIN="$DART_EDITOR_DIR/chromium/Chromium.app/Contents/MacOS/Chromium" |
| 78 | +``` |
| 79 | + |
| 80 | +Add the Dart SDK `bin` directory to your path and/or define `DART_SDK` (this is also detailed |
| 81 | +[here](https://www.dartlang.org/tools/pub/installing.html)): |
| 82 | + |
| 83 | +```shell |
| 84 | +# DART_SDK: path to a Dart SDK directory |
| 85 | +export DART_SDK="$DART_EDITOR_DIR/dart-sdk" |
| 86 | + |
| 87 | +# Update PATH to include the Dart SDK bin directory |
| 88 | +PATH+=":$DART_SDK/bin" |
| 89 | +``` |
| 90 | + |
| 91 | +## Installing NPM Modules and Dart Packages |
| 92 | + |
| 93 | +Next, install the modules and packages needed to build Angular and run tests: |
| 94 | + |
| 95 | +```shell |
| 96 | +# Install Angular project dependencies (package.json) |
| 97 | +npm install |
| 98 | + |
| 99 | +# Ensure protractor has the latest webdriver |
| 100 | +$(npm bin)/webdriver-manager update |
| 101 | + |
| 102 | +# Install Dart packages |
| 103 | +pub install |
| 104 | +``` |
| 105 | + |
| 106 | +**Optional**: In this document, we make use of project local `npm` package scripts and binaries |
| 107 | +(stored under `./node_modules/.bin`) by prefixing these command invocations with `$(npm bin)`; in |
| 108 | +particular `gulp` and `protractor` commands. If you prefer, you can drop this path prefix by |
| 109 | +globally installing these two packages as follows: |
| 110 | + |
| 111 | +* `npm install -g gulp` (you might need to prefix this command with `sudo`) |
| 112 | +* `npm install -g protractor` (you might need to prefix this command with `sudo`) |
| 113 | + |
| 114 | +Since global installs can become stale, we avoid their use in these instructions. |
| 115 | + |
| 116 | +## Build commands |
| 117 | + |
| 118 | +To build Angular and prepare tests run |
| 119 | + |
| 120 | +```shell |
| 121 | +$(npm bin)/gulp build |
| 122 | +``` |
| 123 | + |
| 124 | +Notes: |
| 125 | +* Results are put in the `dist` folder. |
| 126 | +* This will also run `pub get` for the subfolders in `modules` and run `dartanalyzer` for |
| 127 | + every file that matches `<module>/src/<module>.dart`, e.g. `di/src/di.dart` |
| 128 | + |
| 129 | +To clean out the `dist` folder use: |
| 130 | +```shell |
| 131 | +$(npm bin)/gulp clean |
| 132 | +``` |
| 133 | + |
| 134 | +## Running Tests Locally |
| 135 | + |
| 136 | +### Basic tests |
| 137 | + |
| 138 | +1. `$(npm bin)/gulp test.unit.js`: JS tests in a browser; runs in **watch mode** (i.e. karma |
| 139 | + watches the test files for changes and re-runs tests when files are updated). |
| 140 | +2. `$(npm bin)/gulp test.unit.cjs`: JS tests in NodeJS (requires a build before) |
| 141 | +3. `$(npm bin)/gulp test.unit.dart`: Dart tests in Dartium; runs in **watch mode**. |
| 142 | + |
| 143 | +If you prefer running tests in "single-run" mode rather than watch mode use |
| 144 | + |
| 145 | +* `$(npm bin)/gulp test.unit.js/ci` |
| 146 | +* `$(npm bin)/gulp test.unit.dart/ci` |
| 147 | + |
| 148 | +**Note**: If you want to only run a single test you can alter the test you wish |
| 149 | +to run by changing `it` to `iit` or `describe` to `ddescribe`. This will only |
| 150 | +run that individual test and make it much easier to debug. `xit` and `xdescribe` |
| 151 | +can also be useful to exclude a test and a group of tests respectively. |
| 152 | + |
| 153 | +**Note** for transpiler tests: The karma preprocessor is setup in a way so that after every test |
| 154 | +run the transpiler is reloaded. With that it is possible to make changes to the preprocessor and |
| 155 | +run the tests without exiting karma (just touch a test file that you would like to run). |
| 156 | + |
| 157 | +### E2e tests |
| 158 | + |
| 159 | +1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder). |
| 160 | +2. `$(npm bin)/gulp serve.js.prod serve.js.dart2js` (runs local webserver). |
| 161 | +3. `$(npm bin)/protractor protractor-js.conf.js`: JS e2e tests. |
| 162 | +4. `$(npm bin)/protractor protractor-dart2js.conf.js`: Dart2JS e2e tests. |
| 163 | + |
| 164 | +Angular specific command line options when running protractor: |
| 165 | + - `$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help` |
| 166 | + |
| 167 | +### Performance tests |
| 168 | + |
| 169 | +1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder) |
| 170 | +2. `$(npm bin)/gulp serve.js.prod serve.js.dart2js` (runs local webserver) |
| 171 | +3. `$(npm bin)/protractor protractor-js.conf.js --benchmark`: JS performance tests |
| 172 | +4. `$(npm bin)/protractor protractor-dart2js.conf.js --benchmark`: Dart2JS performance tests |
| 173 | + |
| 174 | +Angular specific command line options when running protractor (e.g. force gc, ...): |
| 175 | +`$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help` |
| 176 | + |
| 177 | +## Project Information |
| 178 | + |
| 179 | +### Folder structure |
| 180 | + |
| 181 | +* `modules/*`: modules that will be loaded in the browser |
| 182 | +* `tools/*`: tools that are needed to build Angular |
| 183 | +* `dist/*`: build files are placed here. |
| 184 | + |
| 185 | +### File endings |
| 186 | + |
| 187 | +* `*.js`: javascript files that get transpiled to Dart and EcmaScript 5 |
| 188 | +* `*.es6`: javascript files that get transpiled only to EcmaScript 5 |
| 189 | +* `*.es5`: javascript files that don't get transpiled |
| 190 | +* `*.dart`: dart files that don't get transpiled |
| 191 | + |
| 192 | +## CI using Travis |
| 193 | + |
| 194 | +For instructions on setting up Continuous Integration using Travis, see the instructions given |
| 195 | +[here](https://github.com/angular/angular.dart/blob/master/travis.md). |
| 196 | + |
| 197 | +## Debugging |
| 198 | + |
| 199 | +### Debug the transpiler |
| 200 | + |
| 201 | +If you need to debug the transpiler: |
| 202 | + |
| 203 | +- add a `debugger;` statement in the transpiler code, |
| 204 | +- from the root folder, execute `node debug $(npm bin)/gulp build` to enter the node |
| 205 | + debugger |
| 206 | +- press "c" to execute the program until you reach the `debugger;` statement, |
| 207 | +- you can then type "repl" to enter the REPL and inspect variables in the context. |
| 208 | + |
| 209 | +See the [Node.js manual](http://nodejs.org/api/debugger.html) for more information. |
| 210 | + |
| 211 | +Notes: |
| 212 | +- You can also execute `node $(npm bin)/karma start karma-dart.conf.js` depending on which |
| 213 | + code you want to debug (the former will process the "modules" folder while the later processes |
| 214 | + the transpiler specs). |
| 215 | +- You can also add `debugger;` statements in the specs (JavaScript). The execution will halt when |
| 216 | + the developer tools are opened in the browser running Karma. |
| 217 | + |
| 218 | +### Debug the tests |
| 219 | + |
| 220 | +If you need to debug the tests: |
| 221 | + |
| 222 | +- add a `debugger;` statement to the test you want to debug (oe the source code), |
| 223 | +- execute karma `$(npm bin)/gulp test.js`, |
| 224 | +- press the top right "DEBUG" button, |
| 225 | +- open the dev tools and press F5, |
| 226 | +- the execution halt at the `debugger;` statement |
| 227 | + |
| 228 | +**Note (WebStorm users)**: |
| 229 | +You can create a Karma run config from WebStorm. |
| 230 | +Then in the "Run" menu, press "Debug 'karma-js.conf.js'", WebStorm will stop in the generated code |
| 231 | +on the `debugger;` statement. |
| 232 | +You can then step into the code and add watches. |
| 233 | +The `debugger;` statement is needed because WebStorm will stop in a transpiled file. Breakpoints in |
| 234 | +the original source files are not supported at the moment. |
| 235 | + |
0 commit comments