# Packaging for Bazel

## Deprecated

These rules have been extracted from the Bazel sources and are now available at
[bazelbuild/rules_pkg](https://github.com/bazelbuild/rules_pkg/releases)
 [(docs)](https://github.com/bazelbuild/rules_pkg/tree/master/pkg).

Issues and PRs against the built-in versions of these rules will no longer be
addressed. This page will exist for reference until the code is removed from
Bazel. You can test the removal of these rules with Bazel at version >= 0.28.0.

```
bazel build --//tools/build_defs/pkg:incompatible_no_build_defs_pkg  target...
```

For more information, follow [issue 8857](https://github.com/bazelbuild/bazel/issues/8857)

## rules_pkg

Rules

- pkg_tar
    
- pkg_deb

## Overview

These build rules are used for building various packaging such as tarball
and debian package.

## Basic Example

This example is a simplification of the debian packaging of Bazel:

```python
load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar", "pkg_deb")

pkg_tar(
    name = "bazel-bin",
    strip_prefix = "/src",
    package_dir = "/usr/bin",
    srcs = ["//src:bazel"],
    mode = "0755",
)

pkg_tar(
    name = "bazel-tools",
    strip_prefix = "/",
    package_dir = "/usr/share/lib/bazel/tools",
    srcs = ["//tools:package-srcs"],
    mode = "0644",
)

pkg_tar(
    name = "debian-data",
    extension = "tar.gz",
    deps = [
        ":bazel-bin",
        ":bazel-tools",
    ],
)

pkg_deb(
    name = "bazel-debian",
    architecture = "amd64",
    built_using = "unzip (6.0.1)",
    data = ":debian-data",
    depends = [
        "zlib1g-dev",
        "unzip",
    ],
    description_file = "debian/description",
    homepage = "http://bazel.build",
    maintainer = "The Bazel Authors <bazel-dev@googlegroups.com>",
    package = "bazel",
    version = "0.1.1",
)
```

Here, the Debian package is built from three `pkg_tar` targets:

 - `bazel-bin` creates a tarball with the main binary (mode `0755`) in
   `/usr/bin`,
 - `bazel-tools` create a tarball with the base workspace (mode `0644`) to
   `/usr/share/bazel/tools` ; the `modes` attribute let us specifies executable
   files,
 - `debian-data` creates a gzip-compressed tarball that merge the three previous
   tarballs.

`debian-data` is then used for the data content of the debian archive created by
`pkg_deb`.

## Future work

 - Support more format, especially `pkg_zip`.
 - Maybe a bit more integration with the `docker_build` rule.

## pkg_tar

```python
pkg_tar(name, extension, strip_prefix, package_dir, srcs,
mode, modes, deps, symlinks)
```

Creates a tar file from a list of inputs.

       Attributes

       name
               Name, required
        
A unique name for this rule.

       extension
               String, default to 'tar'
        
            The extension for the resulting tarball. The output
            file will be 'name.extension'. This extension
            also decide on the compression: if set to tar.gz
            or tgz then gzip compression will be used and
            if set to tar.bz2 or tar.bzip2 then
            bzip2 compression will be used.

       strip_prefix
               String, optional
        
Root path of the files.
        
          The directory structure from the files is preserved inside the
          tarball but a prefix path determined by strip_prefix
          is removed from the directory structure. This path can
          be absolute from the workspace root if starting with a / or
          relative to the rule's directory. A relative path may start with "./"
          (or be ".") but cannot use ".." to go up level(s). By default, the
          strip_prefix attribute is unused and all files are supposed to have no
          prefix. A strip_prefix of "" (the empty string) means the
          same as the default.

       package_dir
               String, optional
        
Target directory.
        
          The directory in which to expand the specified files, defaulting to '/'.
          Only makes sense accompanying files.

       srcs
               List of files, optional
        
File to add to the layer.
        
          A list of files that should be included in the archive.

       mode
               String, default to 0555
        
          Set the mode of files added by the files attribute.

       mtime
               int, seconds since Jan 1, 1970, default to -1 (ignored)
        
          Set the mod time of files added by the files attribute.

       portable_mtime
               bool, default True
        
          Set the mod time of files added by the files attribute
          to a 2000-01-01.

       modes
               Dictionary, default to '{}'
        
          A string dictionary to change default mode of specific files from
          files. Each key should be a path to a file before
          appending the prefix package_dir and the corresponding
          value the octal permission of to apply to the file.

          modes = {
           "tools/py/2to3.sh": "0755",
           ...
          },

       owner
               String, default to '0.0'
        
          UID.GID to set the default numeric owner for all files
          provided in files.

       owners
               Dictionary, default to '{}'
        
          A string dictionary to change default owner of specific files from
          files. Each key should be a path to a file before
          appending the prefix package_dir and the corresponding
          value the UID.GID numeric string for the owner of the
          file. When determining owner ids, this attribute is looked first then
          owner.

          owners = {
           "tools/py/2to3.sh": "42.24",
           ...
          },

       ownername
               String, optional
        
          username.groupname to set the default owner for all files
          provided in files (by default there is no owner names).

       ownernames
               Dictionary, default to '{}'
        
          A string dictionary to change default owner of specific files from
          files. Each key should be a path to a file before
          appending the prefix package_dir and the corresponding
          value the username.groupname string for the owner of the
          file. When determining ownernames, this attribute is looked first then
          ownername.

          owners = {
           "tools/py/2to3.sh": "leeroy.jenkins",
           ...
          },

       deps
               List of labels, optional
        
Tar files to extract and include in this tar package.
        
          A list of tarball labels to merge into the output tarball.

       symlinks
               Dictionary, optional
        
Symlinks to create in the output tarball.

          symlinks = {
           "/path/to/link": "/path/to/target",
           ...
          },

       remap_paths
               Dictionary, optional
        
Source path prefixes to remap in the tarfile.

          remap_paths = {
           "original/path/prefix": "replaced/path",
           ...
          },

### pkg_deb

```python
pkg_deb(name, data, package, architecture, maintainer, preinst, postinst, prerm, postrm, version, version_file, description, description_file, built_using, built_using_file, priority, section, homepage, depends, suggests, enhances, conflicts, predepends, recommends)
```

Create a debian package. See http://www.debian.org/doc/debian-policy/ch-controlfields.html
for more details on this.

       Attributes

       name
               Name, required
        
A unique name for this rule.

       data
               File, required
        
          A tar file that contains the data for the debian package (basically
          the list of files that will be installed by this package).

       package
               String, required
        
The name of the package.

       architecture
               String, default to 'all'
        
The architecture that this package target.
        
          See http://www.debian.org/ports/.

       maintainer
               String, required
        
The maintainer of the package.

       preinst, postinst, prerm and postrm
               Files, optional
        
          Respectively, the pre-install, post-install, pre-remove and
          post-remove scripts for the package.

          See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html.

       config
               File, optional
        
          config file used for debconf integration.

          See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts.

       templates
               File, optional
        
          templates file used for debconf integration.

          See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts.

    <tr>
      <td><code>conffiles</code>, <code>conffiles_file</code></td>
      <td>
        <code>String list or File, optional</code>
        <p>
          The list of conffiles or a file containing one conffile per
          line. Each item is an absolute path on the target system
          where the deb is installed.
        </p>
        <p>
          See <a href="https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html#s-conffile">https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html#s-conffile</a>.
        </p>
      </td>
    </tr>
    <tr>
      <td><code>version</code>, <code>version_file</code></td>
      <td>
        <code>String or File, required</code>
        <p>
          The package version provided either inline (with <code>version</code>)
          or from a file (with <code>version_file</code>).
        </p>
      </td>
    </tr>
    <tr>
      <td><code>description</code>, <code>description_file</code></td>
      <td>
        <code>String or File, required</code>
        <p>
          The package description provided either inline (with <code>description</code>)
          or from a file (with <code>description_file</code>).
        </p>
      </td>
    </tr>
    <tr>
      <td><code>built_using</code>, <code>built_using_file</code></td>
      <td>
        <code>String or File</code>
        <p>
          The tool that were used to build this package provided either inline
          (with <code>built_using</code>) or from a file (with <code>built_using_file</code>).
        </p>
      </td>
    </tr>
    <tr>
      <td><code>priority</code></td>
      <td>
        <code>String, default to 'optional'</code>
        <p>The priority of the package.</p>
        <p>
          See <a href="http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities">http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities</a>.
        </p>
      </td>
    </tr>
    <tr>
      <td><code>section</code></td>
      <td>
        <code>String, default to 'contrib/devel'</code>
        <p>The section of the package.</p>
        <p>
          See <a href="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections">http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections</a>.
        </p>
      </td>
    </tr>
    <tr>
      <td><code>homepage</code></td>
      <td>
        <code>String, optional</code>
        <p>The homepage of the project.</p>
      </td>
    </tr>
    <tr>
      <td>
        <code>depends</code>, <code>suggests</code>, <code>enhances</code>,
        <code>conflicts</code>, <code>predepends</code> and <code>recommends</code>.
      </td>
      <td>
        <code>String list, optional</code>
        <p>The list of dependencies in the project.</p>
        <p>
          See <a href="http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps">http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps</a>.
        </p>
      </td>
    </tr>
  

