angular-cn/docs/DEVELOPER.md

Building and Testing Angular

This document describes how to set up your development environment to build and test Angular. It also explains the basic mechanics of using git, node, and npm.

• Prerequisite Software
• Getting the Sources
• Installing NPM Modules
• Building
• Running Tests Locally

See the contribution guidelines 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:

• Git and/or the GitHub app (for Mac or Windows); GitHub's Guide to Installing Git is a good source of information.

• Node.js, (version >=6.9.5 <7.0.0) which is used to run a development web server, run tests, and generate distributable files. We also use Node's Package Manager, npm (version >=3.10.7 <4.0.0), which comes with Node. Depending on your system, you can install Node either from source or as a pre-packaged bundle.

• Java Development Kit which is used to execute the selenium standalone server for e2e testing.

Getting the Sources

Fork and clone the Angular repository:

1. Login to your GitHub account or create one by following the instructions given here.
2. Fork the main Angular repository.
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.

# Clone your GitHub repository:
git clone git@github.com:<github username>/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

Installing NPM Modules

Next, install the JavaScript modules needed to build and test Angular:

# 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: globally installing the package npm-run by running npm install -g npm-run (you might need to prefix this command with sudo). You will then be able to run locally installed package scripts by invoking: e.g., npm-run gulp build (see npm-run project page for more details).

Option 3: defining a bash alias like alias nbin='PATH=$(npm bin):$PATH' as detailed in this Stack Overflow answer and used like this: e.g., nbin gulp build.

Installing Bower Modules

Now run bower to install additional dependencies:

# Install other Angular project dependencies (bower.json)
bower install

Windows only

In order to create the right symlinks, run as administrator:

./scripts/windows/create-symlinks.sh

Before submitting a PR, do not forget to remove them:

 ./scripts/windows/remove-symlinks.sh

Building

To build Angular run:

./build.sh

• Results are put in the dist folder.

Running Tests Locally

To run tests:

$ ./test.sh node             # Run all angular tests on node

$ ./test.sh browser          # Run all angular tests in browser
$ ./test.sh browserNoRouter  # Optionally run all angular tests without router in browser

$ ./test.sh tools            # Run angular tooling (not framework) tests

You should execute the 3 test suites before submitting a PR to github.

See DEBUG.md for information on debugging the code while running the unit tests.

All the tests are executed on our Continuous Integration infrastructure and a PR could only be merged once the tests pass.

• CircleCI fails if your code is not formatted properly,
• Travis CI fails if any of the test suites described above fails.

Update the public API tests

If you happen to modify the public API of Angular, API golden files must be updated using:

$ gulp public-api:update

Note: The command gulp public-api:enforce fails when the API doesn't match the golden files. Make sure to rebuild the project before trying to verify after an API change.

Formatting your source code

Angular uses clang-format to format the source code. If the source code is not properly formatted, the CI will fail and the PR can not be merged.

You can automatically format your code by running:

$ gulp format

Linting/verifying your source code

You can check that your code is properly formatted and adheres to coding style by running:

$ gulp lint

Publishing snapshot builds

When the master branch successfully builds on Travis, it automatically publishes build artifacts to repositories in the Angular org, eg. the @angular/core package is published to http://github.com/angular/core-builds. The ES2015 version of Angular is published to a different branch in these repos, for example http://github.com/angular/core-builds#master-es2015

You may find that your un-merged change needs some validation from external participants. Rather than requiring them to pull your Pull Request and build Angular locally, you can publish the *-builds snapshots just like our Travis build does.

First time, you need to create the github repositories:

$ export TOKEN=[get one from https://github.com/settings/tokens]
$ CREATE_REPOS=1 TRAVIS= ./scripts/ci/publish-build-artifacts.sh [github username]

For subsequent snapshots, just run

$ ./scripts/publish/publish-build-artifacts.sh [github username]

The script will publish the build snapshot to a branch with the same name as your current branch, and create it if it doesn't exist.