Packages/1.0

This Packages 0.1 proposal describes the CommonJS package format for distributing CommonJS programs and libraries. A CommonJS package is a cohesive wrapping of a collection of modules, code and other assets into a single form. It provides the basis for convenient delivery, installation and management of CommonJS components.

This proposal specifies the CommonJS package descriptor file and package file format. It does not (yet) specify a package catalogue file or format.

Package Descriptor File

Each package MUST provide a top-level package descriptor file called "package.json". This file is a json format file. Each package MUST provide all the following fields in its package descriptor file.

• name - the name of the package. This must be a lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters.
• description - a brief description of the package. By convention, the first sentence should be usable as a package title in listings.
• version - a version string conforming to the Semantic Versioning requirements (http://semver.org/)
• keywords - an Array of string keywords to assist users searching for the package in catalogs.
• author - Hash describing the original or primary author of the package. This field MUST have a "name" property and may optionally provide "email" and "web" properties. For example:

author: {
   name: "Bill Bloggs",
   email: "[email protected]",
   web: "http://www.bblogmedia.com",
}

• contributors - an Array of hashes each containing the details of a contributor. Format is the same as for author.
• bugs - URL for submitting bugs. Can be mailto or http.
• license - array of licenses under which the package is provided. Each license is a hash with a "kind" property specifying the type of license and a url property linking to the actual text. For example

license: [
   {
       kind: "GPLv2",
       url: "http://www.ejscript.org/products/ejs/doc/licenses/gpl.html",
   }
]

• location - Array of repositories where the package can be located. Each repository is a tuple where the first element is the kind of repository and the second element is a URL path to clone/checkout the package. For example:

location: [
       {
            kind: "mercurial", 
            url: "http://hg.embedthis.com/ejs"
       }
]

• dependencies - Array of prerequisite packages on which this package depends in order to install and run. Each dependency is an array with one to three elements. The first element is the dependent package name and is mandatory. The second is an optional version defining the lowest qualifying version. The third element is a version defining the highest qualifying version. For example:

   dependencies: [ "ejs", "1.0.0", "2.0"]. 

This specifies a dependency on the "ejs" package with versions between 1.0 and 2.0. If the version are omitted, the latest available version of the dependency is acceptable. If only one version is supplied, any version including and after that is acceptable.

• implements - Array of relevant CommonJS specifications this package supports. TBD: define these specifiers. For example:

  implements: [ "CommonJS-Modules-1.0", "CommonJS-JSGI-1.0"]

Optional Keywords

• homepage - URL string for the package web site
• signature - Hash of package checksums. For example:

   signature: {"md5", "841959b03e98c92d938cdeade9e0784d"}

• os - Array of supported operating systems. If absent or set to the empty set, the package makes no platform assumptions. The set of valid os names includes: aix, freebsd, linux, macos, solaris, vxworks, windows.
• cpu - Array of supported CPU architectures. If absent or set to the empty set, the package makes no platform assumptions. The set of valid cpu names includes: arm, mips, ppc, sparc, x86, x86_64.
• engine - Array of supported JavaScript engines. If absent or set to the empty set, the package makes no platform assumptions. The set of valid cpu names includes: ejs, flusspferd, gpsee, jsc, mozilla, narwhal, node, rhino, v8.
• builtin- Boolean value indicating the package is built in as a standard component of the underlying platform
• directories - Object hash of package directories. Typical directories include "lib", "src", "doc", "test" and "bin". Package manager tools SHOULD use these directory definitions to find various package components.
• scripts - Object hash of scripts used in managing the package. A package manager tool may use these scripts to install, build, test or uninstall the package. For example:

   scripts: {
       install: "install.js",
       uninstall: "uninstall.js",
       build: "build.js,
   }

Package managers and loaders should ignore unknown fields in the package descriptor file.

Package File Format

The package files shall be a simple archive of the package directory including the package.json file in a relative, ZIP archive format.

Package Directory Layout

A CommonJS package will observe the following:

• A package.json file must be in the top level directory
• Binary files SHOULD be in the "bin" directory,
• Javascript code SHOULD be under the "lib" directory
• Documentation SHOULD be under the "doc" directory
• Unit tests SHOULD be under the "test" directory

Package Files

To install and uninstall a CommonJS package some local installation steps may be required. A package MAY specify various scripts to run via the "scripts" package.json field.

Other Requirements

• Packages MUST conform to the CommonJS Securable Modules specification.

Example Package Descriptor File

{
   name: "mypackage",
   version: "0.7.0",
   description: "Sample package for CommonJS. This package demonstrats the required elements of a CommonJS package.",
   keywords: [
       "package",
       "example",
   ],
   author: {
       name: "Bill Smith",
       email: "[email protected]",
       web: "http://www.example.com",
   ],
   contributors: [
       {
           name: "Mary Brown",
           email: "[email protected]",
           web: "http://www.embedthis.com",
       },
   ],
   bugs: {
       mail: "[email protected]",
       web: "http://www.example.com/bugs",
   }
   license: {
       kind: "GPLv2", 
       url: "http://www.example.org/licenses/gpl.html"
   },
   location: [
       {
           kind: "git",
           url: "http://hg.example.com/mypackage.git"
       },
   ]
   signature: {
       md5: "719ea61444a0bd34c9cf7454227a2e5c",
   },
   dependencies: [
       [ "ejs", "1.0.0", "2.0" ],
   ],
   implements: ["cjs-module-0.3", "cjs-jsgi-0.1"],
   os: ["linux", "macos", "win"]
   cpu: "*",
   engines: ["v8", "ejs", "node", "rhino"],
   scripts: {
       install: "install.es",
       uninstall: "uninstall.es",
       build: "build.es",
   },
   directories: {
       lib: "src/lib",
       bin: "local/binaries",
   },
}

Background

• Packages-Background (discussion)
• modules packaging
• Semantic Versioning
• How to make packages in Narwhal

Changes

These are the changes in the first round feedback (12/16/2009)

• Removed stability
• Renamed conforms to implements
• Convert author/contributors to hashes
• Convert license to array of hashes
• Removed builtin
• Changed checksums to signature and converted to a hash.