This page describes how to keep your code compatible with a Single File Library (SFL) release of the OpenLayers library.

Some background information about the process is found on the SingleFileJsLibrary page, but some of it is outdated. This page simply covers what you need to know in order to make your code compatible and generate the single file version. The long-term motivation is to be somewhat compatible with how OpenJSAN does it.

Writing Code Compatible with a Single File Library release

The only step you need to take to be compatible with a SFL release is to include a special comment in your source file for each source file dependency in your code.

A dependency is (currently) specified by including a single-line comment like this near the top of the file:

// @require: foo/bar.js

Example

Assume we have a directory structure like this:

js/foo/sound.js
js/quux/oink.js
js/quux/ham.js

The content of oink.js looks like this:

/*
  oink.js -- Do something oinky.

  Licensed under the PIG license.
 */

var allSounds = new SoundStore();

function render() {
  // Renders an oinker as food.
  allSounds["squeal"].play();
  return new Ham();
}

The class SoundStore is defined in sound.js while Ham is defined in ham.js.

How do we make this file compatible with a SFL release of the code?

This is a compatible version with the change in bold:

/*
  oink.js -- Do something oinky.

  Licensed under the PIG license.
 */

// @require: foo/sound.js

var allSounds = new SoundStore();

function render() {
  // Renders an oinker as food.
  allSounds["squeal"].play();
  return new Ham();
}

Some questions you might want answered:

• What determines whether a file is considered a dependency?
  If the code is normally executed when the Javascript source code file is imported then it should be considered a dependency.
  This is the reason why the file foo/sound.js is counted as a dependency while the quux/ham.js is not. [Note: This actually makes it incompatible with the OpenJSAN approach, but makes it easier for us initially.] If it was expected that render() was to be called by a subsequent file when it was imported then quux/ham.js would also need to be counted as a dependency.
  There is nothing to stop you from specifiying all dependencies but it's not currently essential.
  The reason for the current policy is that very few source code files in our code base actually do much in the way of complicated setup. (The only situation where this currently happens is when classes are subclassed.)

• Do I really have to specify a dependency for prototype.js (or some other frequently occurring dependency) in every file?
  Possibly not. :-) If we followed Python's edict of "Explicit is better than Implicit" then the answer would be "yes". If we wanted to be more compatible with OpenJSAN then the answer would be "yes". But because I want to make life easy for you the answer is currently "no, you don't have to". For details, see the explanation of the [first] section of the configuration file below.

• How do I specify that a particular file depends on all the other files in the library? Do I have to list all the files in the library as dependencies?
  Possibly not. (Again.) See the answer above for a longer explanation of why, and for details of how, see the explanation of the [last] section of the configuration file below.

• Can I specify that I don't want a particular source file in the directory to be included at all?
  Yes. See the explanation of the [exclude] section of the configuration file below.

• Wait, how do I know what file path to specify as the dependency?
  The short answer, for OpenLayers, is to strip off every directory up to and including the js/ directory and include the remainder as a relative path.
  e.g. If the full path of the dependency source file is:

     .../openlayers/js/core/application.js
  

  then the dependency will be written as:

     // @require: core/application.js
  

  This is the case even if the dependency is in the same directory as the source file. Essentially, dependencies are always specified as relative paths below the root directory specified when the SFL file is generated. (See the Generation section below for how the root directory is specified at the time the file is generated.)

• I use Windows, should I still use / as the path separator?
  Yes.

• If my file depends on X.js and X.js depends on Y.js, does my file have to declare the dependency on Y.js as well?
  No. You can treat the dependencies as a "black box". If you require a file, you do not need to specify the dependencies that that file has.
  

• I have a question not answered here, what should I do?
  First of all, don't panic--this isn't a major cause for alarm. Secondly, you can add your question here and then send an email to the dev list requesting an answer. See, that wasn't too difficult, was it?

Configuration

cat js/myversion.cfg 
[first]
3rd/prototype.js
core/application.js
core/params.js

[last]
core/api.js

[exclude]
3rd/logger.js

Generation

Some questions you might want answered:

• Can I generate a SFL release using Windows?
  Christian López (penyaskito) has reported that this *is* doable. He was running Windows XP with python installed.