Skip to content

Latest commit

 

History

History
100 lines (78 loc) · 6.76 KB

README.md

File metadata and controls

100 lines (78 loc) · 6.76 KB
Raw

Build Guide

Get the Code

  • Setup Git if it isn't already (link).
    • Make sure your SSH keys are configured (linux | mac | windows).
    • Double-check your settings for name and email: git config --get-regexp user.*.
    • Recommended Git settings:
      • git config --global pull.rebase preserve - when pulling remote changes, rebase your local changes on top of the remote changes, to avoid unnecessary merge commits.
      • git config --global fetch.prune true - when fetching remote changes, remove any remote branches that no longer exist on the remote.
  • Have commit access to cesium?
    • No
      • Fork cesium.
      • Use the GitHub website to delete all branches in your fork except master.
      • Clone your fork, e.g., git clone [email protected]:yourusername/cesium.git.
      • Make changes in a branch, e.g., git checkout -b my-feature.
    • Yes
      • Clone the cesium repo, e.g., git clone [email protected]:AnalyticalGraphicsInc/cesium.git
      • Make changes in a branch, e.g., git checkout -b my-feature.

Build the Code

Prerequisites:

Cesium uses npm modules for development, so after syncing, you need to run npm install from the Cesium root directory:

npm install

Once all modules have been installed, run npm run build to actually build the code:

npm run build

Cesium ships with a simple HTTP server for testing, run npm start after building to use it:

npm start

Then browse to http://localhost:8080/.

By default, the server only allows connections from your local machine. Too allow connections from other machines, pass the --public option to npm. Note the extra -- is intentional and required by npm.

npm start -- --public

The development server has a few other options as well, which you can see by pasing the --help parameter:

npm start -- --help

While you can use the editor of your choice to develop Cesium, certain files, such as glsl and new tests, require that the build task be executed in order for the changes to take affect. You can use the build-watch script to have this happen automatically.

Build Scripts

Cesium uses gulp for build tasks, but they are all abstracted away by npm run scripts.

Specify the target(s) at the command line:

npm run [target-name]

Here's the full set of scripts and what they do.

  • build - A fast, developer-oriented build that prepares the source tree for use as standard Asynchronous Module Definition (AMD) modules, suitable for running tests and most examples (some Sandcastle examples require running combine). This runs automatically when saving files in Eclipse.
  • build-watch - A never-ending task that watches your file system for changes to Cesium and runs build on the source code as needed.
  • combine - Runs build, plus the the RequireJS optimizer to combine Cesium and the Almond AMD loader to produce all-in-one files in the Build/Cesium directory that expose the entire Cesium API attached to a single global Cesium object. This version is useful if you don't want to use the modules directly with a standard AMD loader.
  • minify - Runs combine, plus minifies Cesium.js using UglifyJS2 for a smaller deployable file.
  • combineRelease - Runs combine, plus uses the optimizer to remove debugging code that validates function input and throws DeveloperErrors. The removed sections are marked with //>>includeStart('debug', pragmas.debug); blocks in the code.
  • minifyRelease - Runs minify, and removes debugging code.
  • requirejs - Used internally by the build system and can not be called directly.
  • buildApps - Builds the example applications (such as Cesium Viewer) to produce self-contained, minified, deployable versions in the Build directory.
  • generateDocumentation - Generates HTML documentation in Build/Documentation using JSDoc 3.
  • release - A full release build that creates a shippable product, including building apps and generating documentation.
  • instrumentForCoverage - Runs JSCoverage on the source tree to allow running tests with coverage information. Use the link in index.html. Currently Windows only.
  • jsHint - Runs JSHint on the entire source tree.
  • jsHint-watch - A never-ending task that watches your file system for changes to Cesium and runs JSHint on any changed source files.
  • makeZipFile - Builds a zip file containing all release files. This includes the source tree (suitable for use from an AMD-aware application), plus the combined and minified Cesium.js files, the generated documentation, the test suite, and the example applications (in both built and source form).
  • clean - Removes all generated build artifacts.
  • cloc - Runs CLOC to count the lines of code on the Source and Specs directories. This requires Perl to execute.
  • sortRequires - Alphabetically sorts the list of required modules in every js file. It also makes sure that the top of every source file uses the same formatting.
  • test - Runs all tests with Karma using the default browser specified in the Karma config file.
  • test-all - Runs all tests with Karma using all browsers installed on the current system.
  • test-non-webgl - Runs only non-WebGL tests with Karma.
  • test-webgl - Runs only WebGL tests with Karma.
  • test-webgl-validation - Runs all tests with Karma and enables low-level WebGL validation.
  • test-release - Runs all tests with Karma on the minified release version of built Cesium.