ashatora/openlayers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Plovr is not used anymore

Éric Lemoine
2014-07-05 14:06:22 -07:00
parent e3050754fa
commit 0fb1e90f01
1 changed files with 35 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
Developer-Guide.md

@@ -1,14 +1,9 @@
# Developer Guide
Thanks for your interest in contributing to OpenLayers 3 development. Our
preferred means of receiving contributions is through [pull
requests](https://help.github.com/articles/using-pull-requests). Make sure
that your pull request follows our [pull request
guidelines](https://github.com/openlayers/ol3/wiki/Developer-Guide#pull-request-guidelines)
before submitting it.
Thanks for your interest in contributing to OpenLayers 3 development. Our preferred means of receiving contributions is through [pull requests](https://help.github.com/articles/using-pull-requests). Make sure
that your pull request follows our [pull request guidelines](https://github.com/openlayers/ol3/wiki/Developer-Guide#pull-request-guidelines) before submitting it.
This page describes what you need to know to contribute code to ol3 as
a developer.
This page describes what you need to know to contribute code to ol3 as a developer.
## Contributor License Agreement
@@ -88,21 +83,18 @@ example:
The main build targets are `serve`, `lint`, `build`, `test`, and `check`. The
latter is a meta-target that basically runs `lint`, `build`, and `test`.
The `serve` target starts the [Plovr](http://plovr.com/) web server. You'll
need to start the Plovr server for running the examples and the tests. More
information on that further down.
The `serve` target starts a node-based web server, which we will refer to as the *dev server*. You'll need to start that server for running the examples and the tests. More information on that further down.
Other targets include `apidoc` and `integration-test`. The latter is the target
used on Travis CI. See ol3's [Travis configuration file](https://github.com/openlayers/ol3/blob/master/.travis.yml).
Other targets include `apidoc` and `ci`. The latter is the target used on Travis CI. See ol3's [Travis configuration file](https://github.com/openlayers/ol3/blob/master/.travis.yml).
## Running the `check` target
The `check` target is to be run before pushing code to GitHub and opening pull
requests. Branches that don't pass `check` won't pass the integration tests,
and have therefore no chance of being merged into `master`. The `check` target
runs the tests, so it requires that the Plovr server run.
runs the tests, so it requires that the dev server run.
To start the Plovr web server use:
To start the dev server use:
$ ./build.py serve
@@ -110,78 +102,60 @@ To run the `check` target use:
$ ./build.py check
If you get this error
If you get this kind of error:
ReferenceError: Can't find variable: goog
$ ./build.py check
2014-07-05 22:39:16,310 test: ./node_modules/.bin/phantomjs test/mocha-phantomjs.js http://localhost:3000/test/index.html
Failed to load the page. Check the url: http://localhost:3000/test/index.html
2014-07-05 22:39:16,495 test: clean
2014-07-05 22:39:16,495 pake: test: Command '['./node_modules/.bin/phantomjs', 'test/mocha-phantomjs.js', 'http://localhost:3000/test/index.html']' returned non-zero exit status 1
file:///home/elemoine/public_html/openlayers/ol3/test/ol.html:67
Failed to start mocha: Init timeout
it means that you don't have the Plovr server running.
it means that you don't have the dev server running.
If you want to run the full suite of integration tests, see "Running the integration
tests" below.
## Running examples
To run the examples you first need to start the Plovr web server:
To run the examples you first need to start the dev server:
$ ./build.py serve
Then, start a simple web server, for example:
Then, just point your browser <http://localhost:3000/examples> in your browser. For example <http://localhost:3000/examples/side-by-side.html>.
$ python -mSimpleHTTPServer
Run examples against the `ol.js` standalone build:
and explore the `examples/` directory, for example by opening
<http://localhost:8000/examples/side-by-side.html>.
You can turn on compilation by appending `?mode=ADVANCED` to the URL, for example
<http://localhost:8000/examples/side-by-side.html?mode=ADVANCED>. (By default mode
is `RAW`.). If you don't want the social widgets append `?mode=RAW`.
Run examples without Plovr:
The examples can also be run against the `ol.js` standalone lib, without Plovr,
just like the examples
The examples can also be run against the `ol.js` standalone lib, just like the examples
[hosted](http://openlayers.github.com/ol3/master/examples/) on GitHub. Start by
executing the `host-examples` build target:
$ ./build.py host-examples
This target performs a number of things:
1. Build `ol.js`, `ol-simple.js`, `ol-whitespace.js`, and `ol.css`,
1. Create the examples index page,
1. Extract the Closure Library from the Plovr JAR,
1. Copy everything to `build/hosted/<branch_name>/`, where `<branch_name>` is the name of the local checked out Git branch.
After running `host-examples` you can now open the examples index page in the browser, for example: <http://localhost:8000/build/hosted/master/examples/>.
After running `host-examples` you can now open the examples index page in the browser, for example: <http://localhost/~elemoine/ol3/build/hosted/master/examples/>. (This assumes that the `hosted` directory is a web directory, served by Apache for example.)
To make an example use `ol-simple.js` or `ol-whitespace.js` instead of `ol.js`
append `?mode=simple` or `?mode=whitespace` to the example URL.
Append `?mode=debug` or `?mode=raw` to make the example work in full debug mode. In
full debug mode the OpenLayers and Closure scripts are loaded individually by
full debug mode the OpenLayers and Closure Library scripts are loaded individually by
the Closure Library's `base.js` script (which the example page loads and
executes before any other script).
## Running tests
Run the Plovr web server (see above), and either open the `test/ol.html` file
in the browser (e.g. <http://localhost:8000/test/ol.html>), or run `./build.py
test` on the console (headless testing with PhantomJS, make sure to install it
first from http://phantomjs.org/download.html).
Run the dev server (see above), and either open the <http://localhost:3000/test/index.html> in the browser, or run `./build.py test` on the console (headless testing with PhantomJS).
See also the test-specific [README](../blob/master/test/README.md).
If you get this error
ReferenceError: Can't find variable: goog
$ ./build.py check
2014-07-05 22:39:16,310 test: ./node_modules/.bin/phantomjs test/mocha-phantomjs.js http://localhost:3000/test/index.html
Failed to load the page. Check the url: http://localhost:3000/test/index.html
2014-07-05 22:39:16,495 test: clean
2014-07-05 22:39:16,495 pake: test: Command '['./node_modules/.bin/phantomjs', 'test/mocha-phantomjs.js', 'http://localhost:3000/test/index.html']' returned non-zero exit status 1
file:///home/elemoine/public_html/openlayers/ol3/test/ol.html:67
Failed to start mocha: Init timeout
it means that you don't have the Plovr server running.
it means that you don't have the dev server running.
## Running the integration tests
@@ -190,10 +164,10 @@ server](https://travis-ci.org/) will run a full suite of tests, including
building all versions of the library and checking that all of the examples
work. You will receive an email with the results, and the status will be
displayed in the pull request. If you want to run the integration tests
locally, then you'll need to make sure that Plovr is running if it isn't
locally, then you'll need to make sure that the dev server is running (`build.py serve`) if it isn't
already, and then start the tests:
$ ./build.py integration-test
$ ./build.py ci
Running the full suite of integration tests currently takes 5-10 minutes.
@@ -216,22 +190,16 @@ should be set to `myexample`.
You can use `simple.js` and `simple.html` as templates for new examples.
`build.py serve` should be stopped and restarted for the
`loader.js?id=<example_name>` script tag to refer to a valid URL. `build.py
serve` triggers the `examples` target which creates a Plovr JSON file for each
example.
### Use of the `goog` namespace in examples
Short story: the OL3 examples should not use the `goog` namespace, except
Short story: the ol3 examples should not use the `goog` namespace, except
for `goog.require`.
Longer story: we want that the OL3 examples work in multiple modes: with the
Longer story: we want that the ol3 examples work in multiple modes, with the
standalone lib (which has implications of the symbols and properties we
export), with Plovr in ADVANCED mode, and with Plovr in RAW (debug) mode.
export), and compiled together with the ol3 library.
Running the examples with Plovr makes it mandatory to declare dependencies with
`goog.require` statements.
Compiling the examples together with the library makes it mandatory do declare dependencies with `goog.require` statements.
## Pull request guidelines
@@ -299,9 +267,9 @@ style of the existing OpenLayers 3 code, which includes:
The integration tests contain a number of automated checks to ensure that the
code follows the OpenLayers 3 style and does not break tests or examples. You
can run the integration tests locally using the `integration-test` target:
can run the integration tests locally using the `ci` target:
$ ./build.py integration-test
$ ./build.py ci
### Address a single issue or add a single item of functionality