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

Updated Exports Files (markdown)

elemoine
2013-01-21 23:30:23 -08:00
parent 4ace6d6bd1
commit 733e30b87a
1 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
Exports-Files.md

@@ -8,17 +8,17 @@ Alongside js files the src dir includes "exports files" (e.g. `src/ol/map.export
This declares that the `ol.Map` symbol, and that the `ol.Map.prototype.getControls` property, should be exported, i.e. made available to lib users.
Exports files are processed by the `bin/generate-exports` script, using its `--exports` switch. This script receives a list of exports files as its input, and outputs `@exportSymbol` and `@exportProperty` statements. The `Makefile` places the output of the `generate-exports --exports` command in the `build/src/external/src/exports.js` file. This js file is then used as an input file for the `ol.js` build (see `build/ol.json`).
Exports files are processed by the `bin/generate-exports` script, using its `--exports` switch. This script receives a list of exports files as its input, and outputs `@exportSymbol` and `@exportProperty` statements. The `build.py` script places the output of the `generate-exports --exports` command in the `build/src/external/src/exports.js` file. This js file is then used as an input file for the `ol.js` build (see `build/ol.json`).
Note: the `src/google.exports` file just makes the `goog.require` function be exported as a null function. This is just to be able to execute the examples both in dev mode (mode=RAW) – where `goog.require` statements are required – and with the `ol.js` build.
The `src/objectliterals.exports` file is specific. This file declares the config objects and properties for single-arg constructors. These declarations are done with the `@exportObjectLiteral` and `@exportObjectLiteralProperty` directives. This file is also processed with the `bin/generate-exports` script, but using the `--externs` and `--typedef` switches. The `generate-exports --externs` generates Closure externs from the `@exportObjectLiteral` and `@exportObjectLiteralProperty` directives. The Makefile places these externs in the `build/src/external/externs/types.js` file, which is used as a regular externs file by the Closure compiler (see `build/ol.json`). The `generate-exports --typedef` command generate typedef's for the object literals declared with `@exportObjectLiteral` and `@exportObjectLiteralProperty`. The `Makefile` places the typedef's in the `build/src/external/src/types.js`, which, like `exports.js`, is used as an input file for the ol.js build (see `build/ol.json`). Externs define types for config objects created by lib users, while typedef's define types created internally by the lib.
The `src/objectliterals.exports` file is specific. This file declares the config objects and properties for single-arg constructors. These declarations are done with the `@exportObjectLiteral` and `@exportObjectLiteralProperty` directives. This file is also processed with the `bin/generate-exports` script, but using the `--externs` and `--typedef` switches. The `generate-exports --externs` generates Closure externs from the `@exportObjectLiteral` and `@exportObjectLiteralProperty` directives. The `build.py` script places these externs in the `build/src/external/externs/types.js` file, which is used as a regular externs file by the Closure compiler (see `build/ol.json`). The `generate-exports --typedef` command generate typedef's for the object literals declared with `@exportObjectLiteral` and `@exportObjectLiteralProperty`. The `build.py` script places the typedef's in the `build/src/external/src/types.js`, which, like `exports.js`, is used as an input file for the ol.js build (see `build/ol.json`). Externs define types for config objects created by lib users, while typedef's define types created internally by the lib.
OL3 devs need to create new exports files when adding new API elements to the lib. They also need to declare single-arg constructors' config objects and properties in `src/objectliterals.exports`.
## Under the hood
`build/src/internal/src/requireall.js` is used in the `make build` target to ensure that all source files are passed to the compiler.
`build/src/internal/src/requireall.js` is used in the `build.py build-all` target to ensure that all source files are passed to the compiler.
Before reading on, you should have a thorough understand of how the Closure Compiler handles exports and externs.
@@ -34,7 +34,7 @@ Case 3 is more complicated: we need to ensure that the appropriate library funct
Luckily, all this complexity is handled by the `generate-exports` script. The ol3 developer need only add his declarations to the `.exports` files and everything is auto-generated from this single source.
### Approches that don't work
### Approaches that don't work
#### Using the `@export` annotation