The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-JSAN-0.04
River stage zero No dependents
++
/ Module::JSAN

NAME

Module::JSAN - Build JavaScript distributions for JSAN

VERSION

Version 0.03

SYNOPSIS

In Build.PL:

    use inc::Module::JSAN;
    
    
    name            'Digest.MD5';
        
    version         '0.01';
        
    author          'SamuraiJack <root@symbie.org>';
    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';
    
    WriteAll;

or more relaxed DSL syntax:

    use inc::Module::JSAN::DSL;
    
    
    name            Digest.MD5
        
    version         0.01
        
    author          'SamuraiJack <root@symbie.org>'
    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

DESCRIPTION

JSAN is the "JavaScript Archive Network," a JavaScript library akin to CPAN. Visit http://www.openjsan.org/ 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.

WRITING A JSAN MODULE

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.

        Build.PL
        lib/Your/Module.js

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:

        lib/Your/Other/Module.js
        t/01_some_test.t.js
        t/02_some_other_test.t.js
        Changes
        README
        INSTALL
        MANIFEST
        MANIFEST.SKIP

Below is the explanation of each item in the layout.

Build.PL

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

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

        Build.PL
        MANIFEST
        lib/Your/Module.js

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
lib/

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.

t/

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: http://openjsan.org/go?l=Test.Run or http://openjsan.org/go?l=Test.Simple.

Changes

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
README

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.

INSTALL

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
MANIFEST.SKIP

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

POD

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

http://perldoc.perl.org/perlpod.html

Markdown

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.

http://daringfireball.net/projects/markdown/syntax

MultiMarkdown

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

http://fletcherpenney.net/multimarkdown/users_guide/multimarkdown_syntax_guide/

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:

    /**
    
    Name
    ====
    
    Your.Module - A new and shining JSAN module
    
    SYNOPSIS
    ========
    
        var instance = new Your.Module({
            foo     : 'bar',
            bar     : 'var'
            var     : 'baz'
        })
        
        instance.saveMyDay()

    
    DESCRIPTION
    ===========
    
    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
    ./Build install

The Magic

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

AUTHOR

Nickolay Platonov, <nplatonov at cpan.org>

BUGS

Please report any bugs or feature requests to bug-module-jsan at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-JSAN. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

    perldoc Module::JSAN

You can also look for information at:

ACKNOWLEDGEMENTS

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 & LICENSE

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'