# rules_pkg - 0.4.0

Rules

- pkg_tar
    
- pkg_zip
    
- pkg_deb
    
- pkg_rpm

## Common Attributes

These attributes are used in several rules within this module.

**ATTRIBUTES**

| Name              | Description                                                                                                                                                                     | Type                                                               | Mandatory       | Default                                   |
| :-------------    | :-------------                                                                                                                                                                  | :-------------:                                                    | :-------------: | :-------------                            |
| out               | Name of the output file. This file will always be created and used to access the package content. If `package_file_name` is also specified, `out` will be a symlink.            | String                                                             | required        |                                           |
| package_file_name | The name of the file which will contain the package. The name may contain variables in the form `{var}`. The values for substitution are specified through `package_variables`. | String                                                             | optional        | package type specific                     |
| package_variables | A target that provides `PackageVariablesInfo` to substitute into `package_file_name`.                                                                                           | Label (https://bazel.build/docs/build-ref.html#labels) | optional        | None                                      |
| attributes        | Attributes to set on entities created within packages.  Not to be confused with bazel rule attributes.  See 'Mapping "Attributes"' below                                        | Undefined.                                                         | optional        | Varies.  Consult individual rule documentation for details. |

See
[examples/naming_package_files](https://github.com/bazelbuild/rules_pkg/tree/main/examples/naming_package_files)
for examples of how `out`, `package_file_name`, and `package_variables`
interact.

### Mapping "Attributes"

The "attributes" attribute specifies properties of package contents as used in
rules such as `pkg_files`, and `pkg_mkdirs`.  These allow fine-grained control
of the contents of your package.  For example:

```python
attributes = pkg_attributes(
    mode = "0644",
    user = "root",
    group = "wheel",
    my_custom_attribute = "some custom value",
)
```

`mode`, `user`, and `group` correspond to common UNIX-style filesystem
permissions.  Attributes should always be specified using the `pkg_attributes`
helper macro.

Each mapping rule has some default mapping attributes.  At this time, the only
default is "mode", which will be set if it is not otherwise overridden by the user.

If `user` and `group` are not specified, then defaults for them will be chosen
by the underlying package builder.  Any specific behavior from package builders
should not be relied upon.

Any other attributes should be specified as additional arguments to
`pkg_attributes`.

There are currently no other well-known attributes.

---

## pkg_tar

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

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 srcs attribute.

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

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

       modes
               Dictionary, default to '{}'
        
          A string dictionary to change default mode of specific files from
          srcs. 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 srcs.

       owners
               Dictionary, default to '{}'
        
          A string dictionary to change default owner of specific files from
          srcs. 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 srcs (by default there is no owner names).

       ownernames
               Dictionary, default to '{}'
        
          A string dictionary to change default owner of specific files from
          srcs. 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",
           ...
          },

       package_file_name
       See Common Attributes

       package_variables
       See Common Attributes

## pkg_zip

```python
pkg_zip(name, extension, package_dir, srcs, timestamp, package_file_name,
package_variables)
```

Creates a zip file from a list of inputs.

       Attributes

       name
               Name, required
        
A unique name for this rule.

       extension
               String, default to 'zip'
        
            Deprecated. Use out or package_file_name to specify the output file name.
            The extension for the resulting zipfile. The output
            file will be 'name.extension'.

       package_dir
               String, default to '/'
        
Target directory inside zip.
        
          The prefix of all paths in the zip.

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

       timestamp
               Integer, default to 315532800
        
          The time to use for every file in the zip, expressed as seconds since
          Unix Epoch, RFC 3339.

          Due to limitations in the format of zip files, values before
          Jan 1, 1980 will be rounded up and the precision in the zip file is
          limited to a granularity of 2 seconds.

       package_file_name
       See Common Attributes

       package_variables
       See Common Attributes

### 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, breaks, conflicts,
        predepends, recommends, replaces, package_file_name, package_variables)
```

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.

       triggers
               File, optional
        
          triggers file for configuring installation events exchanged by packages.

          See https://wiki.debian.org/DpkgTriggers.

       conffiles, conffiles_file
               String list or File, optional
        
          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.

          See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files.

       version, version_file
               String or File, required
        
          The package version provided either inline (with version)
          or from a file (with version_file).

       description, description_file
               String or File, required
        
          The package description provided either inline (with description)
          or from a file (with description_file).

       built_using, built_using_file
               String or File
        
          The tool that were used to build this package provided either inline
          (with built_using) or from a file (with built_using_file).

       priority
               String, default to 'optional'
        
The priority of the package.
        
          See http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities.

       section
               String, default to 'contrib/devel'
        
The section of the package.
        
          See http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections.

       homepage
               String, optional
        
The homepage of the project.

               breaks, depends, suggests,
        enhances, conflicts, predepends,
        recommends, replaces and provides.
      
               String list, optional
        
The list of dependencies in the project.
        
          See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps.

       package_file_name
       See Common Attributes
      Default: "%{package}-%{version}-%{architecture}.deb"

       package_variables
       See Common Attributes

### pkg_rpm

```python
pkg_rpm(name, spec_file, architecture, version, version_file, changelog, data)
```

Create an RPM package. See http://rpm.org/documentation.html
for more details on this.

       Attributes

       name
               Name, required
        
A unique name for this rule. Used to name the output package.

       spec_file
               File, required
        
The RPM specification file used to generate the package.
        
          See http://ftp.rpm.org/max-rpm/s1-rpm-build-creating-spec-file.html.

       architecture
               String, default to 'all'
        
The architecture that this package target.

       version, version_file
               String or File, required
        
          The package version provided either inline (with version)
          or from a file (with version_file).

       data
               Files, required
        
          Files to include in the generated package.

