Skip to content

Package Description Formats

Jump to bottom Edit New page
Alf Eaton edited this page Mar 6, 2014 · 2 revisions

Wikipedia: List of software package management systems: Application-level package managers

Key: ** = required, * = recommended, everything else = optional

NPM (Node)

package.json

Specification

  • **name: what your package is called.
  • **version: must be parseable by node-semver
  • description: helps people discover your package, as it's listed in npm search.
  • keywords: an array of strings. This helps people discover your package as it's listed in npm search.
  • homepage: url to the project homepage.
  • bugs: url to your project's issue tracker and/or the email address to which issues should be reported. These are helpful for people who encounter issues with your package. key/value; url, email.
  • license: specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it. The simplest way, assuming you're using a common license such as BSD-3-Clause or MIT, is to just specify the standard SPDX ID of the license you're using. Ideally you should pick one that is OSI approved. It's also a good idea to include a LICENSE file at the top level in your package.
  • author: an object with a "name" field and optionally "url" and "email”.
  • contributors: an array of objects with a "name" field and optionally "url" and "email”.
  • files: an array of files to include in your project. If you name a folder in the array, then it will also include the files inside that folder. (Unless they would be ignored by another rule.) You can also provide a ".npmignore" file in the root of your package, which will keep files from being included, even if they would be picked up by the files array. The ".npmignore" file works just like a ".gitignore".
  • main: The main field is a module ID that is the primary entry point to your program. That is, if your package is named foo, and a user installs it, and then does require("foo"), then your main module's exports object will be returned.
  • bin: One or more executable files to install into the PATH. A map of command name to local file name. On install, npm will symlink that file into prefix/bin for global installs, or ./node_modules/.bin/ for local installs.
  • man: Specify either a single file or an array of filenames to put in place for the manprogram to find.
  • directories: The CommonJS Packages spec details a few ways that you can indicate the structure of your package using a directories hash. e.g. doc, lib, man.
  • directories.lib: Tell people where the bulk of your library is. Nothing special is done with the lib folder in any way, but it's useful meta info.
  • directories.bin: If you specify a "bin" directory, then all the files in that folder will be used as the "bin" hash.
  • directories.man: A folder that is full of man pages. Sugar to generate a "man" array by walking the folder.
  • directories.doc: Put markdown files in here. Eventually, these will be displayed nicely, maybe, someday.
  • directories.example: Put example scripts in here. Someday, it might be exposed in some clever way.
  • repository: Specify the place where your code lives. This is helpful for people who want to contribute. If the git repo is on github, then the npm docs command will be able to find you. type, url. The URL should be a publicly available (perhaps read-only) url that can be handed directly to a VCS program without any modification. It should not be a url to an html project page that you put in your browser. It's for computers.
  • scripts: The "scripts" member is an object hash of script commands that are run at various times in the lifecycle of your package. The key is the lifecycle event, and the value is the command to run at that point.
  • config: A "config" hash can be used to set configuration parameters used in package scripts that persist across upgrades.
  • dependencies: Dependencies are specified with a simple hash of package name to version range. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or git URL.
  • devDependencies: If someone is planning on downloading and using your module in their program, then they probably don't want or need to download and build the external test or documentation framework that you use.
  • bundledDependencies: Array of package names that will be bundled when publishing the package.
  • optionalDependencies: If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the optionalDependencieshash. This is a map of package name to version or url, just like thedependencies hash. The difference is that failure is tolerated.
  • engines: You can specify the version of node that your stuff works on. You can also use the "engines" field to specify which versions of npm are capable of properly installing your program.
  • engineStrict: If you are sure that your module will definitely not run properly on versions of Node/npm other than those specified in the engines hash, then you can set"engineStrict": true in your package.json file. This will override the user'sengine-strict config setting.
  • os: You can specify which operating systems your module will run on.
  • cpu: If your code only runs on certain cpu architectures, you can specify which ones.
  • preferGlobal: If your package is primarily a command-line application that should be installed globally, then set this value to true to provide a warning if it is installed locally.
  • private: If you set "private": true in your package.json, then npm will refuse to publish it. This is a way to prevent accidental publication of private repositories.
  • publishConfig: This is a set of config values that will be used at publish-time. It's especially handy if you want to set the tag or registry, so that you can ensure that a given package is not tagged with "latest" or published to the global public registry by default.

Bower (web)

bower.json

Specification

  • **name: The name of the package as stored in the registry. Must be unique. Should be slug style for simplicity, consistency and compatibility. Example: unicorn-cake Lowercase, a-z, can contain dash or dot but not start/end with them. Consecutive dashes or dots not allowed. 50 characters or less.
  • *description: Any character. Max 140. Help users identify and search for your package with a brief description. Describe what your package does, rather than what it's made of. Will be displayed in search/lookup results on the CLI and the website that can be used to search for packages.
  • version: The package's semantic version number. Must be a semantic version parseable by node-semver. If publishing a folder, the version must be higher than the version stored in the registry, when republishing. Version should only be required if you are not using git tags.
  • *main: string or array. The primary acting files necessary to use your package. While Bower does not directly use these files, they are listed with the commands bower list --json and bower list --paths, so they can be used by build tools.
  • *license: string or array. SPDX license identifier or path/url to a license.
  • *ignore: array. A list of files for Bower to ignore when installing your package.
  • *keywords: array. Used for search by keyword. Helps make your package easier to discover without people needing to know its name.
  • authors: array of strings or objects. A list of people that authored the contents of the package. name, email, homepage or parsed from string.
  • homepage: URL to learn more about the package. Falls back to GitHub project if not specified and it’s a GitHub endpoint.
  • repository: The repository in which the source code can be found. type, url.
  • dependencies: Dependencies are specified with a simple hash of package name to a semver compatible identifier or URL.
  • devDependencies: Dependencies that are only needed for development of the package, e.g., test framework or building documentation.
  • resolutions: Dependency versions to automatically resolve with if conflicts occur between packages.
  • private: If you set it to true it will refuse to publish it. This is a way to prevent accidental publication of private repositories.

##Composer (PHP)

composer.json

Specification

  • **name: The name of the package. It consists of vendor name and project name, separated by "/"
  • description: A short description of the package. Usually this is just one line long.
  • **version: The version of the package. Optional if the package repository can infer the version from somewhere, such as the VCS tag name in the VCS repository. In that case it is also recommended to omit it.
  • type: library (default), project, metapackage, composer-plugin.
  • keywords: An array of keywords that the package is related to. These can be used for searching and filtering.
  • homepage: A URL to the website of the project.
  • time: Release date of the version. Must be in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format.
  • *license: The license of the package. SPDX identifier. This can be either a string or an array of strings (there are rules for combining them).
  • *authors: The authors of the package. This is an array of objects: name, email, homepage, role
  • support: key/value hash: email address, issues URL, forum URL, wiki URL, IRC channel, source URLs
  • require: Lists packages required by this package. key/value hash (identifier + version)
  • require-dev: Lists packages required for developing this package, or running tests, etc. key/value hash (identifier + version)
  • conflict: Lists packages that conflict with this version of this package.
  • replace: Lists packages that are replaced by this package.
  • provide: List of other packages that are provided by this package (for filling a virtual package requirement).
  • autoload: Autoload mapping for a PHP autoloader. psr-4, psr-0, classmap or files.
  • autoload-dev: This section allows to define autoload rules for development purposes.
  • minimum-stability: This defines the default behavior for filtering packages by stability. This defaults to stable, so if you rely on a dev package, you should specify it in your file to avoid surprises.
  • prefer-stable: When this is enabled, Composer will prefer more stable packages over unstable ones, when finding compatible stable packages is possible.
  • repositories: Custom package repositories to use (by default composer just uses the packagist repository). type, url, options.
  • config: options for Composer to use when installing.
  • scripts: Composer allows you to hook into various parts of the installation process through the use of scripts.
  • extra: Arbitrary extra data for consumption by scripts.
  • bin: A set of files that should be treated as binaries and symlinked into the bin-dir (from config).
  • archive: A set of options for creating package archives.

##CPAN (Perl)

META.json (previously META.yml)

Specification

  • **abstract: This is a short description of the purpose of the distribution.
  • **author: one or more author name + email strings
  • **dynamic_config: A boolean flag indicating whether a Build.PL or Makefile.PL (or similar) must be executed to determine prerequisites.
  • **generated_by: This field indicates the tool that was used to create this metadata.
  • **license: One or more licenses (strings, ids) that apply to some or all of the files in the distribution. If multiple licenses are listed, the distribution documentation should be consulted to clarify the interpretation of multiple licenses.
  • **meta-spec: version of the CPAN Meta Spec that should be used to interpret the metadata. version, url
  • **name: the name of the distribution. This is often created by taking the "main package" in the distribution and changing :: to -, but the name may be completely unrelated to the packages within the distribution
  • **release_status: unstable, testing, stable
  • **version
  • description: A longer, more complete description of the purpose or intended use of the distribution than the one provided by the abstract key.
  • keywords: A List of keywords that describe this distribution. Keywords must not include whitespace.
  • no_index: This Map describes any files, directories, packages, and namespaces that are private to the packaging or implementation of the distribution and should be ignored by indexing or search tools.
  • optional_features: key/value. describes optional features with incremental prerequisites.
  • prereqs: all the prerequisites of the distribution. The keys are phases of activity, such as configure, build, test or runtime. Values are Maps in which the keys name the type of prerequisite relationship such as requires, recommends, or suggests and the value provides a set of prerequisite relations. The set of relations must be specified as a Map of package names to version ranges.
  • provides: This describes all packages provided by this distribution. This information is used by distribution and automation mechanisms like PAUSE, CPAN, and search.cpan.org to build indexes saying in which distribution various packages can be found.
  • resources: This field describes resources (URLs) related to this distribution. homepage, license, bugtracker, repository

CRAN (R)

DESCRIPTION

Specification

  • **Package: the name of the package
  • **Version: the version of the package
  • **License: specify the license of the package in a standardized form
  • **Description: a comprehensive description of what the package does. One can use several (complete) sentences, but only one paragraph.
  • **Title: should give a short description of the package. Some package listings may truncate the title to 65 characters. It should be capitalized, not use any markup, not have any continuation lines, and not end in a period.
  • **Author: who wrote the package. It is a plain text field intended for human readers, but not for automatic processing. Note that all significant contributors must be included.
  • **Maintainer: a single name, followed a valid (RFC 2822) email address in angle brackets.
  • Both ‘Author’ and ‘Maintainer’ fields can be omitted if a suitable ‘Authors@R’ field is given. This field can be used to provide a refined and machine-readable description of the package “authors” (in particular specifying their precise roles), via suitable R code. The roles can include ‘"aut"’ (author) for full authors, ‘"cre"’ (creator) for the package maintainer, and ‘"ctb"’ (contributor) for other contributors, ‘"cph"’ (copyright holder), among others.
  • Copyright: used where the copyright holder(s) are not the authors. If necessary, this can refer to an installed file: the convention is to use file inst/COPYRIGHTS.
  • Date: the release date of the current version of the package
  • Depends
  • Imports
  • Suggests
  • Enhances
  • LinkingTo
  • SystemRequirements: Dependencies external to the R system.
  • URL: a list of URLs separated by commas or whitespace, for example the homepage of the author or a page where additional material describing the software can be found.
  • BugReports: a single URL to which bug reports about the package should be submitted.
  • Priority: ‘base’ or ‘recommended’.
  • Collate: for controlling the collation order for the R code files in a package when these are processed for package installation.
  • LazyData: whether the R datasets use lazy-loading.
  • KeepSource: controls if the package code is sourced using keep.source
  • ByteCompile: controls if the package code is to be byte-compiled on installation
  • Biarch: used on Windows to select the INSTALL option --force-biarch for this package
  • BuildVignettes: logical field can be set to a false value to stop R CMD build from attempting to build the vignettes
  • Encoding: If the DESCRIPTION file is not entirely in ASCII it should contain an ‘Encoding’ field specifying an encoding.
  • NeedsCompilation: set to "yes" if the package contains code which to be compiled
  • OS_type: specifies the OS(es) for which the package is intended (unix, windows)
  • Type: specifies the type of the package. Package, Translation
  • Classification/ACM or Classification/JEL or Classification/MSC: subject classifications for the content of the package
  • Language: if the package documentation is not in English
  • There is no restriction on the use of other fields not mentioned here (but using other capitalizations of these field names would cause confusion). Fields Note, Contact (for contacting the authors/developers) and MailingList are in common use.

Gem (Ruby)

Gem::Specification

Specification

  • **author/authors: name(s)
  • **files: Files included in this gem
  • **name: This gem's name.
  • **platform: The platform this gem runs on. This is usually Gem::Platform::RUBY or Gem::Platform::CURRENT.
  • **require_paths: Paths in the gem to add to $LOAD_PATH when this gem is activated.
  • **rubygems_version: The version of RubyGems used to create this gem.
  • **summary: A short summary of this gem's description.
  • **version: This gem's version.
  • *license/licenses: The license must be a short name, no more than 64 characters.
  • add_development_dependency: Adds a development dependency named gem with requirements to this gem.
  • add_runtime_dependency: Adds a runtime dependency named gem with requirements to this gem.
  • bindir: The path in the gem for executable scripts. Usually 'bin'
  • cert_chain: The certificate chain used to sign this gem. See Gem::Security for details.
  • description: A long description of this gem
  • email: A contact email address (or addresses) for this gem
  • executables: Executables included in the gem.
  • extensions: Extensions to build when installing the gem, specifically the paths to extconf.rb-style files used to compile extensions.
  • extra_rdoc_files: Extra files to add to RDoc such as README or doc/examples.txt
  • homepage: The URL of this gem's home page
  • metadata: The metadata holds extra data for this gem that may be useful to other consumers and is settable by gem authors without requiring an update to the rubygems software.
  • post_install_message: A message that gets displayed after the gem is installed.
  • rdoc_options: Specifies the rdoc options to be used when generating API documentation.
  • required_ruby_version: The version of Ruby required by this gem
  • required_rubygems_version: The RubyGems version required by this gem.
  • requirements: Lists the external (to RubyGems) requirements that must be met for this gem to work. It's simply information for the user.
  • signing_key: The key used to sign this gem.
  • test_files: A collection of unit test files. They will be loaded as unit tests when the user requests a gem to be unit tested.

Python

http://guide.python-distribute.org/index.html

requirements.txt (a list of requirements)

LICENSE

Module docstring

  • author: comma-separated list of names, as a string
  • copyright = copyright statement
  • credits = array of contributor names. includes people who reported bug fixes, made suggestions, etc. but did not actually write the code.
  • license = license ID
  • version = version number
  • maintainer = maintainer name. The person who will fix bugs and make improvements.
  • email = maintainer email
  • status = "Prototype", "Development", "Production"

setup.py

  • **name: must be unique if you wish to publish your package on the Python Package Index (PyPI)
  • **version: keeps track of different releases of the project
  • **packages: describes where you’ve put the Python source code within your project.
  • license: string

PKG-INFO (distutils)

package metadata

Metadata-Version: version of the metadata file format

  • **Name
  • **Version
  • **Platform
  • **Supported-Platform: the OS and CPU for which the binary package was compiled
  • **Summary: one-line description
  • Description: A longer description of the package that can run to several paragraphs.
  • Keywords
  • Home-page
  • **Download-URL: A string containing the URL from which this version of the package can be downloaded.
  • Author: string
  • **Author-email: string
  • License: Text indicating the license covering the package
  • Classifier: Each entry is a string giving a single classification value for the package. Classifiers are described in PEP 301.
  • Requires: Each entry contains a string describing some other module or package required by this package. The format of a requirement string is identical to that of a module or package name usable with the 'import' statement, optionally followed by a version declaration within parentheses.
  • Provides
  • Obsoletes

##DEB (Debian)

Add a custom footer
Add a custom sidebar
Clone this wiki locally