Module::JSAN - Build JavaScript distributions for JSAN


Version 0.03


In Build.PL:

    use inc::Module::JSAN;
    name            'Digest.MD5';
    version         '0.01';
    author          'SamuraiJack <>';
    abstract        'JavaScript implementation of MD5 hashing algorithm';
    license         'perl';
    requires        'Cool.JS.Lib' => '1.1';
    requires        'Another.Cool.JS.Lib' => '1.2';
    docs_markup     'mmd';

or more relaxed DSL syntax:

    use inc::Module::JSAN::DSL;
    name            Digest.MD5
    version         0.01
    author          'SamuraiJack <>'
    abstract        'JavaScript implementation of MD5 hashing algorithm'
    license         perl
    requires        Cool.JS.Lib             1.1
    requires        Another.Cool.JS.Lib     1.2
    docs_markup     mmd

To build, test and install a distribution:

  % perl Build.PL
  % ./Build
  % ./Build test  
  % ./Build install


JSAN is the "JavaScript Archive Network," a JavaScript library akin to CPAN. Visit for details. This module is a developer aid for creating JSAN distributions.

This module works as simple wrapper for Module::Build::JSAN::Installable, please also refer to its documentation for additional details. The difference is that this module provides a less perl-specifiec and more relaxed syntax for builder scripts.


This is a short tutorial on writing a simple JSAN module. Its really not that hard (tm).

The Layout

The basic files in a module look something like this.


See the synopsys above for the sample content of Build.PL. That's all that's strictly necessary. There's additional files you'll need to publish your module on JSAN, most of them can be generated automatically, with the help of this module.

More advanced layout will look like:


Below is the explanation of each item in the layout.


When you run Build.PL, it creates a 'Build' script. That's the whole point of Build.PL.

    perl Build.PL

The 'Build' is a simple, cross-platform perl script, which loads Module::Build::JSAN::Installable and couple of another modules to manage the distribution.

Here's an example of what you need for a very simple module:

    use inc::Module::JSAN;

    name        'Your.Module';
    version     0.01;

'name' directive indentifies the name of your distribution and 'version' - its version. Pretty simple. Name and version is the only metadata which is strictly required to publish your module. For other pieces of metadata which can be specified, please refer to more in-depth tutorial: Module::JSAN::Tutorial.

'Build' script accepts arguments on command line. The 1st argument is called - action. Other arguments are various for different actions. Example of calling 'doc' action:

    ./Build doc

or on Windows

    Build doc    

Manifest is a simple listing of all the files in your distribution.


Filepaths in a MANIFEST always use Unix conventions (ie. /) even if you're not on Unix.

You can write this by hand or generate it with 'manifest' action.

    ./Build manifest

This is the directory where your *.js files you wish to have installed go. They are layed out according to namespace. So Foo.Bar is lib/Foo/Bar.js.


Tests for your modules go here. Each test filename ends with a .t.js.

Automated testing is not yet implemented. Please refer to documentation of various testing tools on JSAN, which allows to run the test suite semi-automatically. Examples: or


A log of changes you've made to this module. The layout is free-form. Here's an example:

    1.01 Fri Apr 11 00:21:25 PDT 2003
        - thing() does some stuff now
        - fixed the wiggy bug in withit()

    1.00 Mon Apr  7 00:57:15 PDT 2003
        - "Rain of Frogs" now supported

A short description of your module, what it does, why someone would use it and its limitations. JSAN automatically pulls your README file out of the archive and makes it available to JSAN users, it is the first thing they will read to decide if your module is right for them.


Instructions on how to install your module along with any dependencies. Suggested information to include here:

    any extra modules required for use
    the required javascript engine
    required operating systems/browser

A file full of regular expressions to exclude when using './Build manifest' to generate the MANIFEST. These regular expressions are checked against each full filepath found in the distribution (so you're matching against "t/foo.t" not "foo.t").

Here's a sample:

    ~$          # ignore emacs and vim backup files
    .bak$       # ignore manual backups
    \b\.svn\b   # ignore all SVN directories
    ^\.git\b    # ignore top-level .git directory

Since # can be used for comments, # must be escaped.

Module::JSAN comes with a default MANIFEST.SKIP to avoid things like version control directories and backup files. You can alter it as necessary.

The Documentation

The work isn't over until the paperwork is done, and you're going to need to put in some time writing some documentation for your module. JSAN module can be documented in several markup languages, notably in


Plain Old Documentation. Authors with perl background may prefere this markup language, as its native to perl


Very convenient markup language, with main focus on documents readability. Markdown documents can be published as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.


Further extension of Markdown with ability to specify some metadata for documents.

if you're not sure about the format, check the links and choose the most appropriate for you. Put the documentation in JavaScript comments, which starts at line begining with double star:

    Your.Module - A new and shining JSAN module
        var instance = new Your.Module({
            foo     : 'bar',
            bar     : 'var'
            var     : 'baz'

    Your.Module is very useful module, which do a single task, and do it good.

parser will found such comments and extract the documentation from them. Pod documentation can be put in the usual comments.

Provide a good synopsis of how your module is used in code, a description, and then notes on the syntax and function of the individual subroutines or methods. Use comments for developer notes and documentation for end-user notes.

The Tarball

Once you have all the preparations done and documentation written, its time to create a release tarball. Execute 'dist' action of the 'Build' script:

    ./Build dist

Perhaps you'll need to specify paths to gzip and tar archivers on your system:

    ./Build dist --gzip=gzip --tar=tar
    % Deleting META.json
    % Creating META.json
    % Creating Task.Joose.Stable-3.04
    % Creating Task.Joose.Stable-3.04.tar.gz
    % tar cf Task.Joose.Stable-3.04.tar Task.Joose.Stable-3.04
    % gzip Task.Joose.Stable-3.04.tar
    % Deleting Task.Joose.Stable-3.04

Thats all, tarball is ready for uploading to JSAN.

The Mantra

JSAN modules can be installed from expanded tarballs using this simple mantra:

    perl Build.PL
    ./Build install

The Magic

For more in-depth explanations please refer to Module::JSAN::Tutorial


Nickolay Platonov, <nplatonov at>


Please report any bugs or feature requests to bug-module-jsan at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Module::JSAN

You can also look for information at:


Many thanks to Curtis Jewell, who's Module::Build::Functions made this module possible.

Many thanks to Jarkko Hietaniemi for his ExtUtils::MakeMaker::Tutorial, from which a lot of content were borrowed.


Copyright 2009 Nickolay Platonov, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 256:

You forgot a '=back' before '=head2'