Source maps are language and technology agnostic. So we are going to
use the following original source, found in mary.txt.

Mary had a little lamb,
his fleece was white as snow.

We will generate code for this text by removing interpunction and take
the starting letter of each word, wrapping lines after four
characters. The result will be written to the file out.txt.

Mhal
lhfw
was

We will create a source map that will relate segments in the
generated code back to the original source. We need to encode the
following information for a given segment of the generated code.

1. Which source file does it refer to?
2. What line is the source element on?
3. In which column does the source element start?
4. Optionally, describe the segment?

The mapping between the generated code and the source files is
described in mappings string. A mappings string is build up from
groups. For each line in the generated code there is a corresponding
group. The groups are seperated by “;”.

Each group is build up from segments. The segments are seperated by
“,”. A segment is a logical unit for which a origin can be
traced. In our example they corrrespond with the characters in the
generated code.

For a segment the following information is recorded

1. Zero-based column index of segment in the generated source
2. Reference to the original source file
3. Zero-based line in the source file the segment originated from
4. Zero-based column in the line the segment originated from
5. Optionally, name the segment. We will not provide this information.

The following table provides all the information to find the original
element.

The source map specification is described in a Google Document. It
offers improvements over older version, both in resulting size of the
source map as ease of using the data provided in a source map.

A source map is a json file. The properties of the file are
described below.

The current version of the specification is 3. To ensure backwards
compatibility the used version needs to be specified in a property version.

"version": 3

The next property is file. It designated the name of the file that
holds the generated code.

"file": "out.txt"

The property sourceRoot informs a client of the source map of the
common root of all the files involved with this source map.

"sourceRoot": ""

Multiple source files can end up in a single generated code. The
property sources is used to name the files that were used in
generating the code.

"sources": ["mary.txt"]

Providers of source maps could use the next property to give the
content of the corresponding source files. This is optional. When no
source content is present for a corresponding file, it should be null.

"sourcesContent": [null]

Sometimes it is usefull to provide information on a certain
segment. The names property is used for this by providing a target
to link back the particular type of segment. We do not use it now.

"names": []

The mapping property gives the actual mapping between the source
files and the generated code.

"mappings": "AAAAAA==,AQAABQ==,AQAABA==,AQAAAg==;AAAABw==,AQABUg==,AQAABA==,AQAABw==;AAAABA==,AQAABg==,AQAAAw=="

When put together this becomes the following json.

{
    "version": 3,
    "file": "out.txt",
    "sourceRoot": "",
    "sources": ["mary.txt"],
    "sourcesContent": [null],
    "names": [],
    "mappings": "AAAAAA==,AQAABQ==,AQAABA==,AQAAAg==;AAAABw==,AQABUg==,AQAABA==,AQAABw==;AAAABA==,AQAABg==,AQAAAw=="
}

One should not make a source map by hand. Instead you should let
tools generate the source. It is not feasible to describe for each
language how to generate a source map. So we will concentrate on
CoffeeScript.

The following CoffeeScript file is used to demonstrate how to
generated a source map.

greet = (name) -> console.log "Hello " + name

greet('InfoSupport')

The following command will generate a JavaScript file with a
corresponding source map.

coffee --compile --map hello.coffee

This will create a hello.js file

// Generated by CoffeeScript 1.8.0
(function() {
  var greet;

  greet = function(name) {
    return console.log("Hello " + name);
  };

  greet('InfoSupport');

}).call(this);

//# sourceMappingURL=hello.js.map

The last line hints at an hello.js.map source map which is

{
  "version": 3,
  "file": "hello.js",
  "sourceRoot": "",
  "sources": [
    "hello.coffee"
  ],
  "names": [],
  "mappings": ";AACA;AAAA,MAAA,KAAA;;AAAA,EAAA,KAAA,GAAQ,SAAC,IAAD,GAAA;WAAU,OAAO,CAAC,GAAR,CAAY,QAAA,GAAW,IAAvB,EAAV;EAAA,CAAR,CAAA;;AAAA,EAEA,KAAA,CAAM,aAAN,CAFA,CAAA;AAAA"
}

Source maps bridges the gap between using languages and tools that
aid development and resource managment and unintelligble files that
gets served to web clients.