Packages/1.1
STATUS: DRAFT
- Implementations
- PINF JS Loader
Packages
This specification 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 specifies the CommonJS package descriptor file and package file format. It does not specify a package catalogue file or format; this is an exercise for future specifications. The package descriptor file is a statement of known fact at the time the package is published and may not be modified without publishing a new release.
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 unique, lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters. It is otherwise opaque.
- version - a version string conforming to the Semantic Versioning requirements (http://semver.org/).
One of the following must also be in the package description file in order for it to be valid.
- main - module that must be loaded when require(name) is called. Definition must be relative to the package description file.
- directories.lib - directory of modules to be loaded under the packages namespace. require(name/subfilename) must return modules from this directory. Definition must be relative to the package description file.
Optional Keywords
- maintainers - Array of maintainers of the package. Each maintainer is a hash which must have a "name" property and may optionally provide "email" and "web" properties. For example:
"maintainers":[ {
"name": "Bill Bloggs",
"email": "billblogs@bblogmedia.com",
" web": "http://www.bblogmedia.com",
}]
- description - a brief description of the package. By convention, the first sentence (up to the first ". ") should be usable as a package title in listings.
- licenses - array of licenses under which the package is provided. This property is not legally binding and does not necessarily mean your package is licensed under the terms you define in this property. Each license is a hash with a "type" property specifying the type of license and a url property linking to the actual text. If the license is one of the official open source licenses the official license name or its abbreviation may be explicated with the "type" property. If an abbreviation is provided (in parentheses), the abbreviation must be used.
"licenses": [
{
"type": "GPLv2",
"url": "http://www.example.com/licenses/gpl.html",
}
]
- "bugs" - URL for submitting bugs. Can be mailto or http.
- "keywords" - an Array of string keywords to assist users searching for the package in catalogs.
- "repositories" - Array of repositories where the package can be located. Each repository is a hash with properties for the "type" and "url" location of the repository to clone/checkout the package. A "path" property may also be specified to locate the package in the repository if it does not reside at the root. For example:
"repositories": [
{
"type": "git",
"url": "http://github.com/example.git",
"path": "packages/mypackage"
}
]
- "contributors" - an Array of hashes each containing the details of a contributor. Format is the same as for maintainer. By convention, the first contributor is the original author of the package.
- "dependencies" - Hash of prerequisite packages on which this package depends in order to install and run. Each dependency defines the lowest compatible MAJOR[.MINOR[.PATCH]] dependency versions (only one per MAJOR version) with which the package has been tested and is assured to work. The version may be a simple version string (see the version property for acceptable forms), or it may be a hash group of dependencies which define a set of options, any one of which satisfies the dependency. The ordering of the group is significant and earlier entries have higher priority. For example:
"dependencies": {
"webkit": "1.2",
"ssl": {
"gnutls": ["1.0", "2.0"],
"openssl": "0.9.8",
},
}
- "homepage" - URL string for the package web site
- "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 engine names includes: ejs, flusspferd, gpsee, jsc, spidermonkey, 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", "jars", "test" and "bin". Package manager tools must use these directory definitions to find various package components.
- implements - Array of relevant CommonJS specifications this package supports. A specification identifier is the WikiName of the specification prefixed by "CommonJS/". Arbitrary URLs may also be specified to indicate support for externally published specifications.
"implements": [ "CommonJS/Modules/1.0", "CommonJS/JSGI/1.0"]
- 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",
"doc": "make-doc.js",
"test": "test.js",
}
- overlay - Object hash of identifiers for conditional replacements of top level properties. For example:
"overlay": {
"node" : {"dependencies":[...]},
"npm" : {"scripts":{"install":"./npm-install.sh"}
}
Package managers and loaders should ignore unknown fields in the package descriptor file.
Reserved Properties
The following fields are reserved for future expansion: build, default, email, external, files, imports, maintainer, paths, platform, require, summary, test, using, downloads, uid. Extensions to the package descriptor specification should strive to avoid collisions for future standard names by name spacing their properties with innocuous names that do not have meanings relevant to general package management.
The following fields are reserved for package registries to use at their discretion: id, type.
All properties beginning with _ or $ are also reserved for package registries to use that their discretion.
Catalog Properties
When a package.json is included in a catalog of packages, the following fields should be present for each package.
- checksums - Hash of package checksums. This checksum is used by package manager tools to verify the integrity of a package. For example:
checksums: {"md5": "841959b03e98c92d938cdeade9e0784d"}
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 (Though this format may change in future revisions of this specification). The archive must have a single top level directory.
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
- All modules contained in packages must conform to the CommonJS Securable Modules specification.
Minimal Example Package Descriptor File
{
"name" : "mypackage",
"version" : "0.7.0",
"main" : "./lib/main",
}
Large Example Package Descriptor File
{
"name": "mypackage",
"version": "0.7.0",
"description": "Sample package for CommonJS. This package demonstrates the required elements of a CommonJS package.",
"keywords": [
"package",
"example"
],
"maintainers": [
{
"name": "Bill Smith",
"email": "bills@example.com",
"web": "http://www.example.com"
}
],
"contributors": [
{
"name": "Mary Brown",
"email": "maryb@embedthis.com",
"web": "http://www.embedthis.com"
}
],
"bugs": {
"mail": "dev@example.com",
"web": "http://www.example.com/bugs"
},
"licenses": [
{
"type": "GPLv2",
"url": "http://www.example.org/licenses/gpl.html"
}
],
"repositories": [
{
"type": "git",
"url": "http://hg.example.com/mypackage.git"
}
],
"dependencies": {
"webkit": "1.2",
"ssl": {
"gnutls": ["1.0", "2.0"],
"openssl": "0.9.8"
}
},
"implements": ["cjs-module-0.3", "cjs-jsgi-0.1"],
"os": ["linux", "macos", "win"],
"cpu": ["x86", "ppc", "x86_64"],
"engines": ["v8", "ejs", "node", "rhino"],
"scripts": {
"install": "install.js",
"uninstall": "uninstall.js",
"build": "build.js",
"test": "test.js"
},
"directories": {
"lib": "src/lib",
"bin": "local/binaries",
"jars": "java"
}
}
Editor Macros/Scripts
Remembering the format and typing the common bits can be boring. So listed below are know editor scripts to make this easier:
- commonjs-package-json.vim written by Ashb.
Background
- Packages-Background (discussion)
- modules packaging
- Semantic Versioning
- How to make packages in Narwhal
