Build Profiles

OpenLayers Build Profiles are a way to control which code classes are included in a single file build of OpenLayers.

Development Version

When developing with OpenLayers, typically users will use the lib/OpenLayers.js file, which will append script tags to the DOM for each OpenLayers class. This method works fine for development, but due to network latency, is slow. Additionally, the content of these files is not compressed, so network transfer time is slower than it might be otherwise.

Creating a Single File

In order to optimize the end-user's experience, the OpenLayers distribution includes tools which allow you to build your own single file version of the code. This code uses a configuration file to choose which files should be included in the build: In this way, for production use, you can remove classes from your OpenLayers JavaScript library file which are not used in your application.

In addition, the OpenLayers build scripts strip unneccesary comments and whitespace to save space, using the jsmin library.

To build a single file version of OpenLayers, cd into the build directory of the OpenLayers release under a UNIX-like shell with access to Python. Type python build.py profilename.

OpenLayers ships with three configurations to create a single file version:

  • library: This file includes the OpenLayers code to create a build for everything that does not require vector support. build.py uses this profile if no other one is specified.
  • full: This is the full build with all files: this includes the vector-related files like Renderers and Formats.
  • lite: This file includes a small subset of OpenLayers code, designed to be integrated into another application. It includes only the Layer types neccesary to create tiled or untiled WMS, and does not include any Controls. This is the result of what was at the time called "Webmap.js" at the FOSS4G Web Mapping BOF.

Creating your own Profile

Profiles are simple to create. You can start by copying lite.cfg to something else, e.g. myversion.cfg in the build directory, and then build it with the following command:

  $ python build.py myversion

In Windows, from the Start Menu, select Run. Copy the path to build.py from the address bar of the Explorer Window into the text box and then add the name of the configuration file:

  Open:   C:\Downloads\OpenLayers-2.6\build\build.py myversion.cfg

The beginning of the file should include pieces which need to be included before anything else. In the case of the default OpenLayers build, this is:

 OpenLayers/SingleFile.js
 OpenLayers.js
 OpenLayers/BaseTypes.js
 OpenLayers/Util.js

If you wish to create a build where you must specify each file you wish to include, you should then add files to an '[include]' stanza, as lite.cfg does. If you wish to create a build where all files in the lib/ directory are included by default, and you wish to *exclude* certain files, you can do this by putting filenames under the [exclude] header. Look at the files full.cfg and lite.cfg in the build/ directory for examples of this behavior.

For example, if you wished to remove the OverviewMap control from the default OpenLayers build, you would create a copy of full.cfg, and add the lines:

    [exclude] 
    OpenLayers/Control/OverviewMap.js

If, instead, you wished to add the MouseDefaults and PanZoom controls to the lite configuration, you could add the following to the lite.cfg:

    [include]
    OpenLayers/Control/MouseDefaults.js
    OpenLayers/Control/PanZoom.js

As of version 2.4, simply adding these two modules *should* ensure that any prerequisites for these modules will be added to the build as well.

build.py will also take an alternate output filename as an additional argument:

  $ python build.py lite webmap.js

This would store a compressed version of the library using the lite.cfg profile in a file called webmap.js.