docs(developer): update building and testing instructions (#9903)
fixes #9683
This commit is contained in:
Joel Brewer
Victor Berchet
parent
2de8364de2
commit
426b002897
244
DEVELOPER.md
244
DEVELOPER.md
|
|
@ -7,13 +7,8 @@ JS and Dart versions. It also explains the basic mechanics of using `git`, `node
|
||||||
* [Getting the Sources](#getting-the-sources)
|
* [Getting the Sources](#getting-the-sources)
|
||||||
* [Environment Variable Setup](#environment-variable-setup)
|
* [Environment Variable Setup](#environment-variable-setup)
|
||||||
* [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-packages)
|
* [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-packages)
|
||||||
* [Build commands](#build-commands)
|
* [Building](#building)
|
||||||
* [Running Tests Locally](#running-tests-locally)
|
* [Running Tests Locally](#running-tests-locally)
|
||||||
* [Code Style](#code-style)
|
|
||||||
* [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)
|
See the [contribution guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md)
|
||||||
if you'd like to contribute to Angular.
|
if you'd like to contribute to Angular.
|
||||||
|
|
@ -124,243 +119,22 @@ use in these instructions.
|
||||||
*Option 2*: defining a bash alias like `alias nbin='PATH=$(npm bin):$PATH'` as detailed in this
|
*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`.
|
[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
|
## Building
|
||||||
|
|
||||||
To build Angular and prepare tests, run:
|
To build Angular run:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
$(npm bin)/gulp build
|
./build.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
Notes:
|
* Results are put in the dist folder.
|
||||||
* 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 `<module>/src/<module>.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
|
## Running Tests Locally
|
||||||
|
|
||||||
### Full test suite
|
To run tests:
|
||||||
|
|
||||||
* `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. On Windows, only administrators can create symbolic links by default, but you may change the policy. (see [here](https://technet.microsoft.com/library/cc766301.aspx?f=255&MSPPError=-2147217396).)
|
|
||||||
|
|
||||||
### 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.(sauce|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.sauce --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.sauce --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`
|
|
||||||
|
|
||||||
## Code Style
|
|
||||||
|
|
||||||
### Formatting with <a name="clang-format">clang-format</a>
|
|
||||||
|
|
||||||
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 lint
|
|
||||||
|
|
||||||
Note that the continuous build on CircleCI will 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 `gulp format` to format everything.
|
|
||||||
* Use `gulp lint` 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 --style file' > .git/hooks/pre-commit
|
|
||||||
$ chmod u+x !$
|
|
||||||
```
|
|
||||||
|
|
||||||
**NOTE**: To use ```git clang-format``` use have to make sure that ```git-clang-format``` is in your
|
|
||||||
```PATH```. The easiest way is probably to just ```npm install -g clang-format``` as it comes with
|
|
||||||
```git-clang-format```.
|
|
||||||
|
|
||||||
* **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.).
|
|
||||||
|
|
||||||
### Linting
|
|
||||||
|
|
||||||
We use [tslint](https://github.com/palantir/tslint) for linting. See linting rules in [gulpfile](gulpfile.js). To lint, run
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
$ gulp lint
|
./test.sh node
|
||||||
|
./test.sh browser
|
||||||
|
./test.sh tools
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue