# Meta-attributes

Nix packages can declare meta-attributes that contain information about a package such as a description, its homepage, its license, and so on. For instance, the GNU Hello package has a `meta` declaration like this:

    meta = {
      description = "A program that produces a familiar, friendly greeting";
      longDescription = ''
        GNU Hello is a program that prints "Hello, world!" when you run it.
        It is fully customizable.
      '';
      homepage = http://www.gnu.org/software/hello/manual/;
      license = "GPLv3+";
    };

Meta-attributes are not passed to the builder of the package. Thus, a change to a meta-attribute doesn’t trigger a recompilation of the package. The value of a meta-attribute must a string.

The meta-attributes of a package can be queried from the command-line using `nix-env`:

    $ nix-env -qa hello --meta --xml
    <?xml version='1.0' encoding='utf-8'?>
    <items>
      <item attrPath="hello" name="hello-2.3" system="i686-linux">
        <meta name="description" value="A program that produces a familiar, friendly greeting" />
        <meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
        <meta name="license" value="GPLv3+" />
        <meta name="longDescription" value="GNU Hello is a program that prints &quot;Hello, world!&quot; when you run it.&#xA;It is fully customizable.&#xA;" />
      </item>
    </items>

`nix-env` knows about the `description` field specifically:

    $ nix-env -qa hello --description
    hello-2.3  A program that produces a familiar, friendly greeting

## Standard meta-attributes

The following meta-attributes have a standard interpretation:

`description`

  A short (one-line) description of the package. This is shown by `nix-env -q --description` and also on the Nixpkgs release pages.

  Don’t include a period at the end. Don’t include newline characters. Capitalise the first character. For brevity, don’t repeat the name of package — just describe what it does.

  Wrong: `"libpng is a library that allows you to decode PNG images."`

  Right: `"A library for decoding PNG images"`

`longDescription`

  An arbitrarily long description of the package.

`homepage`

  The package’s homepage. Example: `http://www.gnu.org/software/hello/manual/`

`license`

  The license for the package. See below for the allowed values.

`maintainers`

  A list of names and e-mail addresses of the maintainers of this Nix expression, e.g. `["Alice <alice@example.org>" "Bob <bob@example.com>"]`. If you are the maintainer of multiple packages, you may want to add yourself to `pkgs/lib/maintainers.nix` and write something like `[stdenv.lib.maintainers.alice stdenv.lib.maintainers.bob]`.

`priority`

  The priority of the package, used by `nix-env` to resolve file name conflicts between packages. See the Nix manual page for `nix-env` for details. Example: `"10"` (a low-priority package).

## Licenses

This is just a first attempt at standardising the license attribute.

The `meta.license` attribute must be one of the following:

`GPL`

  GNU General Public License; version not specified.

`GPLv2`

  GNU General Public License, version 2.

`GPLv2+`

  GNU General Public License, version 2 or higher.

`GPLv3`

  GNU General Public License, version 3.

`GPLv3+`

  GNU General Public License, version 3 or higher.

`bsd`

  Catch-all for licenses that are essentially similar to the original BSD license with the advertising clause removed, i.e. permissive non-copyleft free software licenses. This includes the X11 (“MIT”) License.

`free`

  Catch-all for free software licenses not listed above.

`free-copyleft`

  Catch-all for free, copyleft software licenses not listed above.

`free-non-copyleft`

  Catch-all for free, non-copyleft software licenses not listed above.

`unfree-redistributable`

  Unfree package that can be redistributed in binary form. That is, it’s legal to redistribute the output of the derivation. This means that the package can be included in the Nixpkgs channel.

  Sometimes proprietary software can only be redistributed unmodified. Make sure the builder doesn’t actually modify the original binaries; otherwise we’re breaking the license. For instance, the NVIDIA X11 drivers can be redistributed unmodified, but our builder applies `patchelf` to make them work. Thus, its license is `unfree` and it cannot be included in the Nixpkgs channel.

`unfree`

  Unfree package that cannot be redistributed. You can build it yourself, but you cannot redistribute the output of the derivation. Thus it cannot be included in the Nixpkgs channel.

`unfree-redistributable-firmware`

  This package supplies unfree, redistributable firmware. This is a separate value from `unfree-redistributable` because not everybody cares whether firmware is free.