diff --git a/.npmignore b/.npmignore deleted file mode 100644 index 84c048a73c..0000000000 --- a/.npmignore +++ /dev/null @@ -1 +0,0 @@ -/build/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 246d4d05c4..21b96ec87b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,66 +55,6 @@ Your pull request must: * Be possible to merge automatically. -### The `check` build target - -It is strongly recommended that you run - - $ make check - -before every commit. This will catch many problems quickly, and it is much -faster than waiting for the Travis CI integration tests to run. - -The `check` build target runs a number of quick tests on your code. These -include: - - * Lint - * Compile - * Tests - - -### Follow OpenLayers's coding style - -OpenLayers follows [Google's JavaScript Style -Guide](https://google.github.io/styleguide/javascriptguide.xml). -This is checked using [ESLint](http://eslint.org/), you -can run the linter locally on your machine before committing using the `lint` -target: - - $ make lint - -In addition to fixing problems identified by the linter, please also follow the -style of the existing OpenLayers code, which includes: - - * Always wrap the body of `for`, `if`, and `while` statements in braces. - - * Class methods should be in alphabetical order. - - * `var` declarations should not span multiple lines. If you cannot fit all - the declarations in a single line, then start a new `var` declaration on a - new line. Within a single line, variables should be declared in - alphabetical order. - - * Do not use assignments inside expressions. - - * Use uppercase for `@const` variables. - -### Configure your editor - -If possible, configure your editor to follow the coding conventions of the -library. A `.editorconfig` file is included at the root of the repository that -can be used to configure whitespace and charset handling in your editor. See -that file for a description of the conventions. The [EditorConfig]( -http://editorconfig.org/#download) site links to plugins for various editors. - -### Pass the integration tests run automatically by the Travis CI system - -The integration tests contain a number of automated checks to ensure that the -code follows the OpenLayers style and does not break tests or examples. You -can run the integration tests locally using the `ci` target: - - $ make ci - - ### Address a single issue or add a single item of functionality Please submit separate pull requests for separate issues. This allows each to @@ -168,33 +108,3 @@ Occasionally other changes to `master` might mean that your pull request cannot be merged automatically. In this case you may need to rebase your branch on a more recent `master`, resolve any conflicts, and `git push --force` to update your branch so that it can be merged automatically. - -## Building on Windows - -Most developers build on Linux. Building on Windows is possible under Cygwin. -When installing Cygwin from https://www.cygwin.com/, include the developer -tools to get GNU make. - -First (before npm install), to avoid file permission problems between Windows -and Cygwin, edit Cygwin's /etc/fstab file to disable ACLs like this -`none /cygdrive cygdrive binary,noacl,posix=0,user 0 0` - -Python is normally installed with Cygwin so need not be installed separately. -By default Cygwin will use its own version of Python rather than Window's, -so the Python modules should be installed for Cygwin's Python. - -The build targets `check-deps`, `serve`, `lint`, `build`, `test`, `check` and -`host-examples` described above should all work. `host-examples` takes quite a -while to run. If a target does not run properly first time, try it again. - -Currently, Firefox fails to run http://localhost:3000/build/examples -from make serve, but Chrome and Internet Explorer will. - -Microsoft Visual Studio's javascript debugger may be used to debug the -build/hosted/your-branch/examples. It will be convenient to set -build/hosted/your-branch/examples/index.html as the startup page. - -Your OpenLayers source tree need not be under the Cygwin root. -if you checkout to c:/openlayers then you can build under Cygwin at /cygdrive/c/openlayers . -However, keep the path to the OpenLayers files short otherwise you may see -`ENAMETOOLONG` errors. diff --git a/DEVELOPING.md b/DEVELOPING.md index c5bc2d4143..8e785f8b3b 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -15,103 +15,32 @@ pull requests will not be merged. The minimum requirements are: -* GNU Make * Git * [Node.js](http://nodejs.org/) (version 8 and above) -* Python 2.6 or 2.7 -* Java 7 (JRE and JDK) -The executables `git`, `node`, and `java` should be in your `PATH`. - -You can check your configuration by running: - - $ make check-deps +The executables `git` and `node` should be in your `PATH`. To install the Node.js dependencies run $ npm install -## Working with the build tool - -As an OpenLayers developer you will use `make` to run build targets defined in the -`Makefile` located at the root of the repository. The `Makefile` includes -targets for running the linter, the compiler, the tests, etc. - -The usage of `make` is as follows: - - $ make - -where `` is the name of the build target you want to execute. For -example: - - $ make test - -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 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. - -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). - -## 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`. - -To run the `check` target: - - $ make check - -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 dev server: - $ make serve + $ npm run serve-examples -Then, just point your browser in your browser. For example . - -Run examples against the `ol.js` standalone build: - -The examples can also be run against the `ol.js` standalone build, just like -the examples [hosted](https://openlayers.org/en/master/examples/) on GitHub. -Start by executing the `host-examples` build target: - - $ make host-examples - -After running `host-examples` you can now open the examples index page in the browser: . (This assumes that you still have the dev server running.) - -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). +Then, load in your browser. ## Running tests -To run the tests in a browser start the dev server (`make serve`) and open in the browser. +To run the tests once: -To run the tests on the console (headless testing with PhantomJS) use the `test` target: + $ npm test - $ make test +To run the tests continuously during development: -See also the test-specific [README](../master/test/README.md). - -## Running the integration tests - -When you submit a pull request the [Travis continuous integration -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. - -To run the full suite of integration tests use the `ci` target: - - $ make ci - -Running the full suite of integration tests currently takes 5-10 minutes. - -This makes sure that your commit won't break the build. It also runs JSDoc3 to -make sure that there are no invalid API doc directives. + $ npm run karma ## Adding examples @@ -123,14 +52,3 @@ implies creating two or three files in this directory, an `.html` file, a `.js` file, and, optionally, a `.css` file. You can use `simple.js` and `simple.html` as templates for new examples. - -### Use of the `goog` namespace in examples - -Short story: the OpenLayers examples should not use the `goog` namespace, except -for `goog.require`. - -Longer story: we want that the OpenLayers examples work in multiple modes, with the -standalone lib (which has implications of the symbols and properties we -export), and compiled together with the OpenLayers library. - -Compiling the examples together with the library makes it mandatory to declare dependencies with `goog.require` statements. diff --git a/config/example.json b/config/example.json deleted file mode 100644 index ee41151bf4..0000000000 --- a/config/example.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - "exports": [], - "src": [ - "src/**/*.js", - "build/ol.ext/*.js", - "build/examples/{{id}}.js" - ], - "compile": { - "js": [ - "externs/olx.js", - "externs/oli.js" - ], - "externs": [ - "externs/bingmaps.js", - "externs/cartodb.js", - "externs/bootstrap.js", - "externs/closure-compiler.js", - "externs/esrijson.js", - "externs/example.js", - "externs/geojson.js", - "externs/jquery-1.9.js", - "externs/proj4js.js", - "externs/tilejson.js", - "externs/topojson.js" - ], - "jscomp_error": [ - "*" - ], - "jscomp_off": [ - "lintChecks", - "analyzerChecks", - "missingProvide", - "unknownDefines" - ], - "extra_annotation_name": [ - "api", "observable" - ], - "rewrite_polyfills": "false", - "compilation_level": "ADVANCED", - "warning_level": "VERBOSE", - "output_wrapper": "(function(){%output%})();", - "use_types_for_optimization": true, - "manage_closure_dependencies": true - } -} diff --git a/config/examples-all.json b/config/examples-all.json deleted file mode 100644 index 253554441b..0000000000 --- a/config/examples-all.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - "exports": [], - "src": [ - "src/**/*.js", - "build/ol.ext/*.js", - "build/compiled-examples/all.js" - ], - "compile": { - "js": [ - "externs/olx.js", - "externs/oli.js" - ], - "externs": [ - "externs/bingmaps.js", - "externs/bootstrap.js", - "externs/cartodb.js", - "externs/closure-compiler.js", - "externs/esrijson.js", - "externs/example.js", - "externs/geojson.js", - "externs/jquery-1.9.js", - "externs/proj4js.js", - "externs/tilejson.js", - "externs/topojson.js" - ], - "jscomp_error": [ - "*" - ], - "jscomp_off": [ - "lintChecks", - "analyzerChecks", - "unusedLocalVariables" - ], - "extra_annotation_name": [ - "api", "observable" - ], - "rewrite_polyfills": "false", - "compilation_level": "ADVANCED", - "warning_level": "VERBOSE", - "output_wrapper": "(function(){%output%})();", - "use_types_for_optimization": true, - "manage_closure_dependencies": true - - } -} diff --git a/config/ol-debug.json b/config/ol-debug.json deleted file mode 100644 index cf20571932..0000000000 --- a/config/ol-debug.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "exports": ["*"], - "umd": true -} diff --git a/config/ol.json b/config/ol.json deleted file mode 100644 index d0479e5b70..0000000000 --- a/config/ol.json +++ /dev/null @@ -1,38 +0,0 @@ -{ - "exports": ["*"], - "umd": true, - "compile": { - "externs": [ - "externs/bingmaps.js", - "externs/cartodb.js", - "externs/closure-compiler.js", - "externs/esrijson.js", - "externs/geojson.js", - "externs/oli.js", - "externs/olx.js", - "externs/proj4js.js", - "externs/tilejson.js", - "externs/topojson.js" - ], - "define": [ - "ol.DEBUG_WEBGL=false" - ], - "jscomp_error": [ - "*" - ], - "jscomp_off": [ - "lintChecks", - "analyzerChecks" - ], - "extra_annotation_name": [ - "api", "observable" - ], - "rewrite_polyfills": "false", - "compilation_level": "ADVANCED", - "warning_level": "VERBOSE", - "use_types_for_optimization": true, - "manage_closure_dependencies": true, - "create_source_map": "build/ol.js.map", - "source_map_format": "V3" - } -} diff --git a/config/readme.md b/config/readme.md deleted file mode 100644 index 200d20e8f7..0000000000 --- a/config/readme.md +++ /dev/null @@ -1,3 +0,0 @@ -# Configuration Files - -This directory includes configuration files for the build scripts in and documentation templates. diff --git a/package.json b/package.json index 58c12130b2..ac82d2be9f 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ ], "homepage": "https://openlayers.org/", "scripts": { - "lint": "eslint tasks test src/ol examples transforms", + "lint": "eslint tasks test src/ol examples", "pretest": "npm run lint", "posttest": "npm run typecheck", "test": "npm run karma -- --single-run", @@ -61,7 +61,6 @@ "html-webpack-plugin": "^3.0.1", "istanbul": "0.4.5", "jquery": "3.3.1", - "jscodeshift": "^0.4.0", "jsdoc": "3.5.5", "karma": "^2.0.0", "karma-chrome-launcher": "2.2.0", @@ -82,7 +81,6 @@ "url-polyfill": "^1.0.7", "walk": "^2.3.9", "webpack": "3.11.0", - "webpack-dev-server": "2.11.1", "webpack-merge": "4.1.2" }, "eslintConfig": { diff --git a/package/.eslintrc b/package/.eslintrc deleted file mode 100644 index bd14a19ef2..0000000000 --- a/package/.eslintrc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "parserOptions": { - "sourceType": "module" - } -} diff --git a/package/package.json b/package/package.json deleted file mode 100644 index b11c98e9ed..0000000000 --- a/package/package.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "name": "ol", - "version": "4.6.4", - "description": "OpenLayers as ES2015 modules", - "main": "index.js", - "module": "index.js", - "license": "BSD-2-Clause", - "dependencies": { - "pbf": "3.1.0", - "pixelworks": "1.1.0", - "rbush": "2.0.1" - }, - "browserify": { - "transform": [ - [ - "babelify", - { - "plugins": ["transform-es2015-modules-commonjs"] - } - ] - ] - } -} diff --git a/package/readme.md b/package/readme.md deleted file mode 100644 index a0b84c37f0..0000000000 --- a/package/readme.md +++ /dev/null @@ -1,49 +0,0 @@ -# ol - -OpenLayers as ES2015 modules. - -## Usage - -Add the `ol` package as a dependency to your project. - - npm install ol --save - -Import just what you need for your application: - -```js -import Map from 'ol/map'; -import View from 'ol/view'; -import TileLayer from 'ol/layer/tile'; -import XYZ from 'ol/source/xyz'; - -new Map({ - target: 'map', - layers: [ - new TileLayer({ - source: new XYZ({ - url: 'https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png' - }) - }) - ], - view: new View({ - center: [0, 0], - zoom: 2 - }) -}); -``` - -See the following examples for more detail on bundling OpenLayers with your application: - - * Using [Rollup & Uglify](https://gist.github.com/tschaub/8beb328ea72b36446fc2198d008287de) - * Using [Rollup & Closure Compiler](https://gist.github.com/tschaub/32a5692bedac5254da24fa3b12072f35) - * Using [Webpack & Uglify](https://gist.github.com/tschaub/79025aef325cd2837364400a105405b8) - * Using [Webpack & Closure Compiler](https://gist.github.com/ahocevar/8ceafc6293455ba491dd9be12c15761f) - * Using [Browserify & Uglify](https://gist.github.com/tschaub/4bfb209a8f809823f1495b2e4436018e) - -## Module Identifiers - -The module identifiers above (e.g. `ol/map`) are like the `ol.Map` names in the [API documentation](http://openlayers.org/en/latest/apidoc/) with `/` instead of `.` and all lowercase. Each module only has a `default` export (there are no other named exports). - -Constructors are exported from dedicated modules. For example, the `ol/layer/tile` module exports the `Tile` layer constructor. - -Utility functions are available as properties of the default export from utility modules. For example, the `getCenter` function is a property of the default export from the `ol/extent` utility module. diff --git a/tasks/generate-exports.js b/tasks/generate-exports.js deleted file mode 100644 index 7b85e93554..0000000000 --- a/tasks/generate-exports.js +++ /dev/null @@ -1,243 +0,0 @@ -const fs = require('fs-extra'); - -const async = require('async'); -const nomnom = require('nomnom'); - -const generateInfo = require('./generate-info'); - - -/** - * Get the configuration from the config file. If configPath is provided - * it is assumed to be a JSON file with an 'exports' member that is a list - * of symbol names or patterns. - * - * @param {string} configPath Path to config file. - * @param {function(Error, Object)} callback Called with config object. - */ -function getConfig(configPath, callback) { - if (configPath) { - fs.readFile(configPath, function(err, data) { - if (err) { - callback(err); - return; - } - let obj; - try { - obj = JSON.parse(String(data)); - } catch (err2) { - callback(new Error('Trouble parsing file as JSON: ' + configPath)); - return; - } - const patterns = obj.exports; - if (patterns && !Array.isArray(patterns)) { - callback(new Error('Expected an exports array, got: ' + patterns)); - return; - } - const namespace = obj.namespace; - if (namespace && typeof namespace !== 'string') { - callback(new Error('Expected an namespace string, got: ' + - namespace)); - return; - } - callback(null, obj); - }); - } else { - process.nextTick(function() { - callback(null, {exports: ['*']}); - }); - } -} - - -/** - * Read the symbols from info file. - * @param {Array.} patterns List of patterns to pass along. - * @param {function(Error, Array., Array.)} callback Called - * with the patterns and symbols (or any error). - */ -function getSymbols(patterns, callback) { - generateInfo(function(err) { - if (err) { - callback(new Error('Trouble generating info: ' + err.message)); - return; - } - const symbols = require('../build/info.json').symbols; - callback(null, patterns, symbols); - }); -} - - -/** - * Generate a list of symbol names given a list of patterns. Patterns may - * include a * wildcard at the end of the string, in which case all symbol names - * that start with the preceding string will be matched (e.g 'foo.Bar#*' will - * match all symbol names that start with 'foo.Bar#'). - * - * @param {Array.} patterns A list of symbol names to match. Wildcards - * at the end of a string will match multiple names. - * @param {Array.} symbols List of symbols. - * @param {function(Error, Array., Array.)} callback Called with - * the filtered list of symbols and a list of all provides (or any error). - */ -function filterSymbols(patterns, symbols, callback) { - const matches = []; - - const provides = {}; - const lookup = {}; - symbols.forEach(function(symbol) { - lookup[symbol.name] = symbol; - symbol.provides.forEach(function(provide) { - provides[provide] = true; - }); - }); - - patterns.forEach(function(name) { - let match = false; - const pattern = (name.substr(-1) === '*'); - if (pattern) { - name = name.substr(0, name.length - 1); - symbols.forEach(function(symbol) { - if (symbol.name.indexOf(name) === 0) { - matches.push(symbol); - match = true; - } - }); - } else { - const symbol = lookup[name]; - if (symbol) { - matches.push(symbol); - match = true; - } - } - if (!match) { - const message = 'No matching symbol found: ' + name + (pattern ? '*' : ''); - callback(new Error(message)); - } - }); - - callback(null, matches, Object.keys(provides).sort()); -} - - -/** - * Generate goog code to export a named symbol. - * @param {string} name Symbol name. - * @param {string|undefined} namespace Target object for exported - * symbols. - * @return {string} Export code. - */ -function formatSymbolExport(name, namespace) { - return 'goog.exportSymbol(\n' + - ' \'' + name + '\',\n' + - ' ' + name + - (namespace ? ',\n ' + namespace : '') + ');\n'; -} - - -/** - * Generate goog code to export a property. - * @param {string} name Property long name (e.g. foo.Bar#baz). - * @return {string} Export code. - */ -function formatPropertyExport(name) { - const parts = name.split('#'); - const prototype = parts[0] + '.prototype'; - const property = parts[1]; - return 'goog.exportProperty(\n' + - ' ' + prototype + ',\n' + - ' \'' + property + '\',\n' + - ' ' + prototype + '.' + property + ');\n'; -} - - -/** - * Generate export code given a list symbol names. - * @param {Array.} symbols List of symbols. - * @param {string|undefined} namespace Target object for exported symbols. - * @param {Array.} provides List of all provides. - * @return {string} Export code. - */ -function generateExports(symbols, namespace, provides) { - const blocks = []; - provides.forEach(function(provide) { - blocks.push('goog.require(\'' + provide + '\');'); - }); - blocks.push('\n\n'); - symbols.forEach(function(symbol) { - const name = symbol.name; - if (name.indexOf('#') > 0) { - blocks.push(formatPropertyExport(name)); - } else { - blocks.push(formatSymbolExport(name, namespace)); - } - }); - blocks.unshift( - '/**\n' + - ' * @fileoverview Custom exports file.\n' + - ' * @suppress {checkVars,extraRequire}\n' + - ' */\n'); - return blocks.join('\n'); -} - - -/** - * Generate the exports code. - * - * @param {Object} config Config object with exports and (optional) namespace. - * @param {function(Error, string)} callback Called with the exports code or any - * error generating it. - */ -function main(config, callback) { - async.waterfall([ - getSymbols.bind(null, config.exports), - filterSymbols, - function(symbols, provides, done) { - let code, err; - try { - code = generateExports(symbols, config.namespace, provides); - } catch (e) { - err = e; - } - done(err, code); - } - ], callback); -} - - -/** - * If running this module directly, read the config file, call the main - * function, and write the output file. - */ -if (require.main === module) { - const options = nomnom.options({ - output: { - position: 0, - required: true, - help: 'Output file path' - }, - config: { - abbr: 'c', - help: 'Path to JSON config file', - metavar: 'CONFIG' - } - }).parse(); - - async.waterfall([ - getConfig.bind(null, options.config), - main, - fs.outputFile.bind(fs, options.output) - ], function(err) { - if (err) { - process.stderr.write(err.message + '\n'); - process.exit(1); - } else { - process.exit(0); - } - }); -} - - -/** - * Export main function. - */ -module.exports = main; diff --git a/tasks/generate-externs.js b/tasks/generate-externs.js deleted file mode 100644 index 79a81e8393..0000000000 --- a/tasks/generate-externs.js +++ /dev/null @@ -1,228 +0,0 @@ -const async = require('async'); -const fs = require('fs-extra'); -const nomnom = require('nomnom'); - -const generateInfo = require('./generate-info'); - -const googRegEx = /^goog\..*$/; - -/** - * Read the symbols from info file. - * @param {function(Error, Array., Array.)} callback Called - * with the patterns and symbols (or any error). - */ -function getInfo(callback) { - generateInfo(function(err) { - if (err) { - callback(new Error('Trouble generating info: ' + err.message)); - return; - } - const info = require('../build/info.json'); - callback(null, info.typedefs, info.symbols, info.externs, info.base); - }); -} - - -/** - * Generate externs code given a list symbols. - * @param {Array.} typedefs List of typedefs. - * @param {Array.} symbols List of symbols. - * @param {Array.} externs List of externs. - * @param {Array.} base List of base. - * @param {string|undefined} namespace Target object for exported symbols. - * @return {string} Export code. - */ -function generateExterns(typedefs, symbols, externs, base) { - const lines = []; - const processedSymbols = {}; - const constructors = {}; - const constructorOptionsTypes = {}; - - function addNamespaces(name) { - const parts = name.split('.'); - parts.pop(); - const namespace = []; - parts.forEach(function(part) { - namespace.push(part); - const partialNamespace = namespace.join('.'); - if (!(partialNamespace in processedSymbols || - partialNamespace in constructors)) { - lines.push('/**'); - lines.push(' * @type {Object}'); - lines.push(' */'); - lines.push(nameToJS(partialNamespace) + ';'); - lines.push('\n'); - } - }); - } - - function nameToJS(name) { - processedSymbols[name] = true; - if (name.indexOf('.') === -1) { - name = 'var ' + name; - } - return name; - } - - // Store in "constructorOptionsTypes" type names that start - // with "ol." and end with "Options". - function findConstructorOptionsTypes(types) { - types.forEach(function(type) { - if (type.match(/^ol\..*Options$/)) { - constructorOptionsTypes[type] = true; - } - }); - } - - function processSymbol(symbol) { - addNamespaces(symbol.name.split('#')[0]); - - let name = symbol.name; - if (name.indexOf('#') > 0) { - name = symbol.name.replace('#', '.prototype.'); - const constructor = symbol.name.split('#')[0]; - if (!(constructor in constructors)) { - constructors[constructor] = true; - lines.push('/**'); - lines.push(' * @constructor'); - lines.push(' */'); - lines.push(nameToJS(constructor) + ' = function() {};'); - lines.push('\n'); - } - } - - lines.push('/**'); - if (symbol.kind === 'class') { - constructors[name] = true; - lines.push(' * @constructor'); - if (symbol.extends && !googRegEx.test(symbol.extends)) { - lines.push(' * @extends {' + symbol.extends + '}'); - } - } - if (symbol.types) { - lines.push(' * @type {' + symbol.types.join('|') + '}'); - } - const args = []; - if (symbol.params) { - symbol.params.forEach(function(param) { - findConstructorOptionsTypes(param.types); - args.push(param.name); - lines.push(' * @param {' + - (param.variable ? '...' : '') + - param.types.join('|') + - (param.optional ? '=' : '') + (param.nullable ? '!' : '') + - '} ' + param.name); - }); - } - if (symbol.returns) { - lines.push(' * @return {' + - (symbol.returns.nullable ? '!' : '') + - symbol.returns.types.join('|') + '}'); - } - if (symbol.template) { - lines.push(' * @template ' + symbol.template); - } - lines.push(' */'); - if (symbol.kind === 'function' || symbol.kind === 'class') { - lines.push(nameToJS(name) + ' = function(' + args.join(', ') + ') {};'); - } else { - lines.push(nameToJS(name) + ';'); - } - lines.push('\n'); - } - - externs.forEach(processSymbol); - - base.forEach(processSymbol); - - symbols.forEach(processSymbol); - - typedefs.forEach(function(typedef) { - // we're about to add a @typedef for "typedef.name" so remove that - // type from constructorOptionsTypes - delete constructorOptionsTypes[typedef.name]; - - addNamespaces(typedef.name); - lines.push('/**'); - lines.push(' * @typedef {' + typedef.types.join('|') + '}'); - lines.push(' */'); - lines.push(nameToJS(typedef.name) + ';'); - lines.push('\n'); - }); - - - // At this point constructorOptionsTypes includes options types for which we - // did not have a @typedef yet. For those we add @typedef {Object}. - // - // This is used for abstract base classes. Abstract base classes should be - // defined as types in the ol externs file. But the corresponding @typedef's - // are not marked with an @api annotation because abstract base classes are - // not instantiated by applications. Yet, we need to have a type defined - // in the ol externs file for these options types. So we just use - // @typedef {Object}. - Object.keys(constructorOptionsTypes).forEach(function(key) { - lines.push('/**'); - lines.push(' * No `@api` annotation for `' + key + '`, use `Object`.'); - lines.push(' * @typedef {Object}'); - lines.push(' */'); - lines.push(nameToJS(key) + ';'); - lines.push('\n'); - }); - - return lines.join('\n'); -} - - -/** - * Generate the exports code. - * - * @param {function(Error, string)} callback Called with the exports code or any - * error generating it. - */ -function main(callback) { - async.waterfall([ - getInfo, - function(typedefs, symbols, externs, base, done) { - let code, err; - try { - code = generateExterns(typedefs, symbols, externs, base); - } catch (e) { - err = e; - } - done(err, code); - } - ], callback); -} - - -/** - * If running this module directly, read the config file, call the main - * function, and write the output file. - */ -if (require.main === module) { - const options = nomnom.options({ - output: { - position: 0, - required: true, - help: 'Output path for the generated externs file.' - } - }).parse(); - - async.waterfall([ - main, - fs.outputFile.bind(fs, options.output) - ], function(err) { - if (err) { - process.stderr.write(err.message + '\n'); - process.exit(1); - } else { - process.exit(0); - } - }); -} - - -/** - * Export main function. - */ -module.exports = main; diff --git a/tasks/readme.md b/tasks/readme.md deleted file mode 100644 index 2e92ecb8be..0000000000 --- a/tasks/readme.md +++ /dev/null @@ -1,111 +0,0 @@ -# Tasks - -This directory contains utility scripts for working with the library. - - -## `build.js` - -Builds the library based on a configuration file. See the `--help` option for more detail. - - node tasks/build.js --help - -### Build configuration files - -Build configuration files are JSON files that are used to determine what should be exported from the library and what options should be passed to the compiler. - -**Required configuration properties** - - * **exports** - `Array.` An array of symbol names or patterns to be exported (names that are used in your application). For example, including `"ol.Map"` will export the map namespace including the constructor. Method names are prefixed with `#`. So `"ol.Map#getViewport"` will export the map's `getViewport` method. You can use a `*` at the end to match multiple names. The pattern `"ol.Map#*"` will export all exportable map methods. - Note that only the 'exportable' names can be listed here, that is, those that are part of the supported API (see apidoc/readme.md for more details). If you want to include a property or method that is not part of the API (and be aware that these may change or be removed), you will have to specifically export these yourself, for example, with `goog.exportProperty`. - Note too that the supplied observable properties together with their accessors, like `getView` in `ol.Map`, are always exported (with `goog.exportProperty` in the source). You do not have to include these, though it does not harm if you do. - Finally, although the term 'exports' is not relevant for simple and whitespace builds, you should still list the names you use as you would with advanced. A build will be created with those classes/namespaces that contain these exported methods. - -**Optional configuration properties** - - * **compile** - `Object` An object whose properties are [Closure Compiler options](https://github.com/openlayers/closure-util/blob/master/compiler-options.txt). Property names match the option names without the `--` prefix (e.g. `"compilation_level": "ADVANCED"` would set the `--compilation_level` option). Where an option can be specified multiple times, use an array for the value (e.g. `"externs": ["one.js", "two.js"]`). Where an option is used as a flag, use a boolean value (e.g. `"use_types_for_optimization": true`). - - If the **compile** object is not provided, the build task will generate a "debug" build of the library without any variable naming or other minification. This is suitable for development or debugging purposes, but should not be used in production. - - * **umd** - `boolean` Optional flag to wrap the build in [UMD syntax](https://github.com/umdjs/umd). If set to `true`, the build output can be used with a CommonJS module loader (e.g. [Browserify](http://browserify.org/)), an AMD script loader (e.g. [RequireJS](http://requirejs.org/)), or just loaded with a `