1 | # Developing
|
2 |
|
3 | ## Setting up development environment
|
4 |
|
5 | You will obviously start by
|
6 | [forking](https://github.com/openlayers/openlayers/fork) the OpenLayers repository.
|
7 |
|
8 | ### Travis CI
|
9 |
|
10 | The Travis CI hook is enabled on the Github repository. This means every pull request
|
11 | is run through a full test suite to ensure it compiles and passes the tests. Failing
|
12 | pull requests will not be merged.
|
13 |
|
14 | ### Development dependencies
|
15 |
|
16 | The minimum requirements are:
|
17 |
|
18 | * GNU Make
|
19 | * Git
|
20 | * [Node.js](http://nodejs.org/) (higher than 0.12.x)
|
21 | * Python 2.6 or 2.7
|
22 | * Java 7 (JRE and JDK)
|
23 |
|
24 | The executables `git`, `node`, and `java` should be in your `PATH`.
|
25 |
|
26 | You can check your configuration by running:
|
27 |
|
28 | $ make check-deps
|
29 |
|
30 | To install the Node.js dependencies run
|
31 |
|
32 | $ npm install
|
33 |
|
34 | ## Working with the build tool
|
35 |
|
36 | As an OpenLayers developer you will use `make` to run build targets defined in the
|
37 | `Makefile` located at the root of the repository. The `Makefile` includes
|
38 | targets for running the linter, the compiler, the tests, etc.
|
39 |
|
40 | The usage of `make` is as follows:
|
41 |
|
42 | $ make <target>
|
43 |
|
44 | where `<target>` is the name of the build target you want to execute. For
|
45 | example:
|
46 |
|
47 | $ make test
|
48 |
|
49 | The main build targets are `serve`, `lint`, `build`, `test`, and `check`. The
|
50 | latter is a meta-target that basically runs `lint`, `build`, and `test`.
|
51 |
|
52 | 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 in a browser. More information on that further down.
|
53 |
|
54 | Other targets include `apidoc` and `ci`. The latter is the target used on Travis CI. See OpenLayers's [Travis configuration file](https://github.com/openlayers/openlayers/blob/master/.travis.yml).
|
55 |
|
56 | ## Running the `check` target
|
57 |
|
58 | The `check` target is to be run before pushing code to GitHub and opening pull
|
59 | requests. Branches that don't pass `check` won't pass the integration tests,
|
60 | and have therefore no chance of being merged into `master`.
|
61 |
|
62 | To run the `check` target:
|
63 |
|
64 | $ make check
|
65 |
|
66 | If you want to run the full suite of integration tests, see "Running the integration
|
67 | tests" below.
|
68 |
|
69 | ## Running examples
|
70 |
|
71 | To run the examples you first need to start the dev server:
|
72 |
|
73 | $ make serve
|
74 |
|
75 | Then, just point your browser <http://localhost:3000/build/examples> in your browser. For example <http://localhost:3000/build/examples/side-by-side.html>.
|
76 |
|
77 | Run examples against the `ol.js` standalone build:
|
78 |
|
79 | The examples can also be run against the `ol.js` standalone build, just like
|
80 | the examples [hosted](https://openlayers.org/en/master/examples/) on GitHub.
|
81 | Start by executing the `host-examples` build target:
|
82 |
|
83 | $ make host-examples
|
84 |
|
85 | After running `host-examples` you can now open the examples index page in the browser: <http://localhost:3000/build/hosted/master/examples/>. (This assumes that you still have the dev server running.)
|
86 |
|
87 | Append `?mode=raw` to make the example work in full debug mode. In raw 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).
|
88 |
|
89 | ## Running tests
|
90 |
|
91 | To run the tests in a browser start the dev server (`make serve`) and open <http://localhost:3000/test/index.html> in the browser.
|
92 |
|
93 | To run the tests on the console (headless testing with PhantomJS) use the `test` target:
|
94 |
|
95 | $ make test
|
96 |
|
97 | See also the test-specific [README](../master/test/README.md).
|
98 |
|
99 | ## Running the integration tests
|
100 |
|
101 | When you submit a pull request the [Travis continuous integration
|
102 | server](https://travis-ci.org/) will run a full suite of tests, including
|
103 | building all versions of the library and checking that all of the examples
|
104 | work. You will receive an email with the results, and the status will be
|
105 | displayed in the pull request.
|
106 |
|
107 | To run the full suite of integration tests use the `ci` target:
|
108 |
|
109 | $ make ci
|
110 |
|
111 | Running the full suite of integration tests currently takes 5-10 minutes.
|
112 |
|
113 | This makes sure that your commit won't break the build. It also runs JSDoc3 to
|
114 | make sure that there are no invalid API doc directives.
|
115 |
|
116 | ## Adding examples
|
117 |
|
118 | Adding functionality often implies adding one or several examples. This
|
119 | section provides explanations related to adding examples.
|
120 |
|
121 | The examples are located in the `examples` directory. Adding a new example
|
122 | implies creating two or three files in this directory, an `.html` file, a `.js`
|
123 | file, and, optionally, a `.css` file.
|
124 |
|
125 | You can use `simple.js` and `simple.html` as templates for new examples.
|
126 |
|
127 | ### Use of the `goog` namespace in examples
|
128 |
|
129 | Short story: the OpenLayers examples should not use the `goog` namespace, except
|
130 | for `goog.require`.
|
131 |
|
132 | Longer story: we want that the OpenLayers examples work in multiple modes, with the
|
133 | standalone lib (which has implications of the symbols and properties we
|
134 | export), and compiled together with the OpenLayers library.
|
135 |
|
136 | Compiling the examples together with the library makes it mandatory to declare dependencies with `goog.require` statements.
|