diff --git a/doc_build/BUILD b/doc_build/BUILD index 14db111b..44d559cd 100644 --- a/doc_build/BUILD +++ b/doc_build/BUILD @@ -50,6 +50,7 @@ ORDER = [ ("pkg_zip", "//pkg/private/zip:zip.bzl"), ("pkg_zip_impl", "//pkg/private/zip:zip.bzl"), ("mappings", None), + ("pkg_install", None), ("legacy_pkg_rpm", None), ] @@ -114,6 +115,17 @@ bzl_library( visibility = ["//visibility:public"], ) +stardoc( + name = "pkg_install", + out = "pkg_install.md", + input = "//pkg:install.bzl", + deps = [ + ":rules_pkg_lib", + "@bazel_skylib//rules:common_settings", + "@rules_python//python:defs_bzl", + ], +) + py_binary( name = "merge", srcs = ["merge.py"], diff --git a/docs/latest.md b/docs/latest.md index eace4b2f..98d2334a 100755 --- a/docs/latest.md +++ b/docs/latest.md @@ -1,4 +1,4 @@ -# rules_pkg - 1.1.0 +# rules_pkg - 1.2.0

Common Attributes

@@ -347,7 +347,7 @@ pkg_tar(name, deps, allow_duplicates_with_different_content, compression_level, compressor, compressor_args, create_parents, empty_dirs, empty_files, extension, files, include_runfiles, mode, modes, mtime, owner, ownername, ownernames, owners, package_dir, package_dir_file, - package_file_name, package_variables, portable_mtime, preserve_mode, + package_file_name, package_variables, portable_mtime, preserve_mode, preserve_mtime, private_stamp_detect, remap_paths, stamp, strip_prefix, symlinks) @@ -370,9 +370,9 @@ pkg_tar(name, deps, create_parents | - | Boolean | optional | `True` | | empty_dirs | - | List of strings | optional | `[]` | | empty_files | - | List of strings | optional | `[]` | -| extension | - | String | optional | `"tar"` | +| extension | The extension of the generated file. If `"gz"`, `"bz2"`, or `"xz"`, the tarball will also be compressed using that tool, and is mutually exclusive with `compressor`. Note that `xz` may not be supported based on the Python toolchain. | String | optional | `"tar"` | | files | Obsolete. Do not use. | Dictionary: Label -> String | optional | `{}` | -| include_runfiles | Include runfiles for executables. These appear as they would in bazel-bin.For example: 'path/to/myprog.runfiles/path/to/my_data.txt'. | Boolean | optional | `False` | +| include_runfiles | Include runfiles for executables. These appear as they would in bazel-bin. For example: 'path/to/myprog.runfiles/path/to/my_data.txt'. | Boolean | optional | `False` | | mode | - | String | optional | `"0555"` | | modes | - | Dictionary: String -> String | optional | `{}` | | mtime | - | Integer | optional | `-1` | @@ -386,6 +386,7 @@ pkg_tar(name, deps, package_variables | See [Common Attributes](#package_variables) | Label | optional | `None` | | portable_mtime | - | Boolean | optional | `True` | | preserve_mode | If true, will add file to archive with preserved file permissions. | Boolean | optional | `False` | +| preserve_mtime | If true, will add file to archive with preserved file mtime. | Boolean | optional | `False` | | private_stamp_detect | - | Boolean | optional | `False` | | remap_paths | - | Dictionary: String -> String | optional | `{}` | | stamp | Enable file time stamping. Possible values:
  • stamp = 1: Use the time of the build as the modification time of each file in the archive.
  • stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
  • stamp = -1: Control the chosen modification time using the --[no]stamp flag.
    Since 0.5.0
    | Integer | optional | `0` | @@ -756,6 +757,80 @@ strip_prefix.from_root(path) + + +Rules for creating install scripts from pkg_filegroups and friends. + +This module provides an interface (`pkg_install`) for creating a `bazel +run`-able installation script. + + + +## pkg_install + +
    +load("@rules_pkg//pkg:install.bzl", "pkg_install")
+
+pkg_install(name, srcs, destdir, destdir_flag, **kwargs)
+
    + +Create an installer script from pkg_filegroups and friends. + +This macro allows users to create `bazel run`nable installation scripts +using the pkg_filegroup framework. + +For example: + +```python +pkg_install( + name = "install", + srcs = [ + # mapping/grouping targets here + ], + destdir = "out/install", +) +``` + +Installation can be done by invoking: + +``` +bazel run -- //path/to:install +``` + +Additional features can be accessed by invoking the script with the --help +option: + +``` +bazel run -- //path/to:install --help +``` + +WARNING: While this rule does function when being run from within a bazel +rule, such use is not recommended. If you do, **always** use the +`--destdir` argument to specify the desired location for the installation to +occur. Not doing so can lead the outputs going to an unexpected location, +or in some cases, failing. Run the script command with `--help`, as +mentioned above, for more details. + +One such use would be to run the script created by `pkg_install` to produce +a directory output in the build root. This may not function as expected or +may suffer from poorly tested edge cases. A purpose-written rule that would +allow for creation of such directories is discussed in +https://github.com/bazelbuild/rules_pkg/issues/388. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | rule name | none | +| srcs | pkg_filegroup framework mapping or grouping targets | none | +| destdir | The default destination directory.

    If it is specified, this is the default destination to install the files. It is overridable by explicitly specifying `--destdir` in the command line or specifying the `DESTDIR` environment variable.

    If it is not specified, `--destdir` must be set on the command line, or the `DESTDIR` environment variable must be set.

    If this is an absolute path, it is used as-is. If this is a relative path, it is interpreted against `BUILD_WORKSPACE_DIRECTORY`. | `None` | +| destdir_flag | A string_flag target used to obtain the value of destdir. | `None` | +| kwargs | common rule attributes | none | + + + Rules to create RPM archives.