Learn By Example

We have created an example distribution that you can use as a starting point for developing and packaging JSAN libraries.

Download and Get Started.

Distribution Format

We currently accept tarballs. That is, a directory structure that has been passed through tar and gzip. Here is how you could do that on the command line. 

tar czvf JSAN-0.01.tar.gz JSAN-0.01

Distribution Name

You must name your distribution. The name must consist of your primary class. This should be followed by the distribution version number, such as '0.10', and these two pieces of information should be split by a dash ('-'). This make the full name 'Test.Simple-0.10'. That should be the name of the distribution directory when the tarball is unpacked. The name of the tarball just adds a '.tar.gz' onto the end making it 'Test.Simple-0.10.tar.gz'.

Distribution Layout

Here is an example of the structure of a JSAN distribution. I am using the JSAN library itself. 

JSAN
|-- META.yml
|-- README
|-- lib
|   `-- JSAN.js
`-- tests
    |-- importfunctions.t.html
    |-- importmore.t.html
    |-- importonly.t.html
    |-- includepath.t.html
    |-- index.html
    |-- testerror.t.html
    |-- useclass.t.html
    `-- lib
        `-- Test
            |-- Builder.js
            |-- Harness.js
            |-- More.js
            |-- Simple.js
            `-- Harness
                `-- Browser.js

META.yml

This file contains all the metadata for this distribution. It should have entries for the distribution name, version, dependences, and license information. The format for the '/src/i/in/ingy/META.yml' file is YAML, which is outlined in detail at yaml.org's current specification page.

Detailed descriptions of the META.yml file are found in the Module::Build specification.

name:         JSAN
version:      0.01
author:
  - Casey West <casey@geeknest.com>
abstract: JavaScript Archive Network
license: perl
build_requires:
    Test.Simple:    0.10

Here is an overview of what we want in a '/src/i/in/ingy/META.yml' file.

name

This is a scalar value, the name of the distribution. Examples include 'Test.Simple', 'Digest.MD5', and 'JSAN'.

version

This is the version number of the distribution. Each version you upload through JAUSE will contain a high version number than the last one.

author

A list of authors for this distribution. The value of each line should be an email address for each author. Here is a complex example. 

author:
  - Casey West <casey@geeknest.com>
  - user@example.com
  - Someone Else <mystery@openjsan.org> (Who Knows)
abstract

An abstract is a short description of what this distribution does. For example, JSAN is "JavaScript Archive Network". DOM.Display is "A Controller for Block Display Toggles."

license

This section describes the license this destribution is destributed under. You should choose an OSI Approved License. The most common option in Open Source today is the GNU GPL, however, one of the most flexible is the Artistic License. The Perl programming language is distributed under both licenses, which is perfectly optional.

A list of valid options are listed in the Module::Build documentation.

requires

This is a hash of required distributions for this one to work. If your distribution requires at least version 0.05 of Digest.MD5, you would use this. 

requires:
  Digest.MD5: 0.05

If you're less concerned about the version of a distribution you can just use zero (0) for the distribution version. 

requires:
  Digest.MD5: 0.05
  DOM.Display: 0
  JSAN: 0.01
build_requires

This is a hash of distributions required to run the tests for this distribution. The most common example available today is Test.Simple. 

build_requires:
  Test.Simple: 0.10

README

This file should contain plain text and give a description of the package. Optionally it could also contain an example of how to install the libraries. Since the libraries can be copied into place this may be less useful than it would be for programming languages that require a build system.

JavaScript Libraries under lib/

These files contain your code. For every namespace that you have, a library should be created. The Test.Simple distribution has an excellent example of the expected structure of the lib/ directory. 

lib/Test/Builder.js
lib/Test/Harness.js
lib/Test/Harness/Browser.js
lib/Test/More.js
lib/Test/Simple.js

It should be obvious that each of those libraries maps to a namespace. In order those namespaces are Test.Builder, Test.Harness, Test.Harness.Browser, Test.More, and Test.Simple.

Currently only inline documentation will be extracted by the JAUSE Incoming System. Inline documentation is required to be in Plain Old Documentation Format.

Please see lib/JSAN.js in the JSAN source code for an example.

tests/

Test files live in the tests/ directory. Each file should be using Test.Simple or Test.More for running their tests and reporting in Standard TAP output.

For convenience, you can create an index.html file that runs the Test.Harness.Browser to run all your tests at once.