Rename pkg_mklink.src to target (#496)

* rename mklinks src to target
* allow src as an alternate
* rename dest to link_name
* do docs

Author: aiuto

docs/latest.md

@@ -562,12 +562,12 @@ Defines creation and ownership of directories in packages
 | <a id="pkg_mkdirs-dirs"></a>dirs |  Directory names to make within the package<br><br>            If any part of the requested directory structure does not already             exist within a package, the package builder will create it for you             with a reasonable set of default permissions (typically <code>0755             root.root</code>).   | List of strings | required |  |
 
 
-<a id="#pkg_mklink"></a>
+<a id="#pkg_mklink_impl"></a>
 
-## pkg_mklink
+## pkg_mklink_impl
 
 <pre>
-pkg_mklink(<a href="#pkg_mklink-name">name</a>, <a href="#pkg_mklink-attributes">attributes</a>, <a href="#pkg_mklink-dest">dest</a>, <a href="#pkg_mklink-src">src</a>)
+pkg_mklink_impl(<a href="#pkg_mklink_impl-name">name</a>, <a href="#pkg_mklink_impl-attributes">attributes</a>, <a href="#pkg_mklink_impl-link_name">link_name</a>, <a href="#pkg_mklink_impl-target">target</a>)
 </pre>
 
 Define a symlink  within packages
@@ -584,10 +584,10 @@ Define a symlink  within packages
 
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="pkg_mklink-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="pkg_mklink-attributes"></a>attributes |  Attributes to set on packaged symbolic links.<br><br>            Always use <code>pkg_attributes()</code> to set this rule attribute.<br><br>            Symlink permissions may have different meanings depending on your             host operating system; consult its documentation for more details.<br><br>            If not otherwise overridden, the link's mode will be set to UNIX             "0777", or the target platform's equivalent.<br><br>            Consult the "Mapping Attributes" documentation in the rules_pkg             reference for more details.   | String | optional | "{}" |
-| <a id="pkg_mklink-dest"></a>dest |  Link "target", a path within the package.<br><br>            This is the actual created symbolic link.<br><br>            If the directory structure provided by this attribute is not             otherwise created when exist within the package when it is built, it             will be created implicitly, much like with <code>pkg_files</code>.<br><br>            This path may be prefixed or rooted by grouping or packaging rules.   | String | required |  |
-| <a id="pkg_mklink-src"></a>src |  Link "source", a path on the filesystem.<br><br>            This is what the link "points" to, and may point to an arbitrary             filesystem path, even relative paths.   | String | required |  |
+| <a id="pkg_mklink_impl-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="pkg_mklink_impl-attributes"></a>attributes |  Attributes to set on packaged symbolic links.<br><br>            Always use <code>pkg_attributes()</code> to set this rule attribute.<br><br>            Symlink permissions may have different meanings depending on your             host operating system; consult its documentation for more details.<br><br>            If not otherwise overridden, the link's mode will be set to UNIX             "0777", or the target platform's equivalent.<br><br>            Consult the "Mapping Attributes" documentation in the rules_pkg             reference for more details.   | String | optional | "{}" |
+| <a id="pkg_mklink_impl-link_name"></a>link_name |  Link "destination", a path within the package.<br><br>            This is the actual created symbolic link.<br><br>            If the directory structure provided by this attribute is not             otherwise created when exist within the package when it is built, it             will be created implicitly, much like with <code>pkg_files</code>.<br><br>            This path may be prefixed or rooted by grouping or packaging rules.   | String | required |  |
+| <a id="pkg_mklink_impl-target"></a>target |  Link "target", a path on the filesystem.<br><br>            This is what the link "points" to, and may point to an arbitrary             filesystem path, even relative paths.   | String | required |  |
 
 
 <a id="#pkg_attributes"></a>
@@ -629,6 +629,29 @@ rules (e.g. `pkg_files`).
 A value usable in the "attributes" attribute in package mapping rules.
 
 
+<a id="#pkg_mklink"></a>
+
+## pkg_mklink
+
+<pre>
+pkg_mklink(<a href="#pkg_mklink-name">name</a>, <a href="#pkg_mklink-link_name">link_name</a>, <a href="#pkg_mklink-target">target</a>, <a href="#pkg_mklink-attributes">attributes</a>, <a href="#pkg_mklink-src">src</a>, <a href="#pkg_mklink-kwargs">kwargs</a>)
+</pre>
+
+Create a symlink.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="pkg_mklink-name"></a>name |  target name   |  none |
+| <a id="pkg_mklink-link_name"></a>link_name |  the path in the package that should point to the target.   |  none |
+| <a id="pkg_mklink-target"></a>target |  target path that the link should point to.   |  none |
+| <a id="pkg_mklink-attributes"></a>attributes |  file attributes.   |  <code>None</code> |
+| <a id="pkg_mklink-src"></a>src |  <p align="center"> - </p>   |  <code>None</code> |
+| <a id="pkg_mklink-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+
+
 <a id="#strip_prefix.files_only"></a>
 
 ## strip_prefix.files_only

examples/rich_structure/src/client/BUILD

@@ -94,8 +94,8 @@ pkg_files(
 
 pkg_mklink(
     name = "usr_bin",
-    src = select(shared_object_path_selector) + "/bin/foo",
-    dest = "usr/bin/foo",
+    link_name = "usr/bin/foo",
+    target = select(shared_object_path_selector) + "/bin/foo",
 )
 
 pkg_filegroup(

pkg/mappings.bzl

@@ -476,13 +476,13 @@ def _pkg_mklink_impl(ctx):
     out_attributes.setdefault("mode", "0777")
     return [
         PackageSymlinkInfo(
-            destination = ctx.attr.dest,
-            source = ctx.attr.src,
+            destination = ctx.attr.link_name,
+            target = ctx.attr.target,
             attributes = out_attributes,
         ),
     ]
 
-pkg_mklink = rule(
+pkg_mklink_impl = rule(
     doc = """Define a symlink  within packages
 
     This rule results in the creation of a single link within a package.
@@ -494,8 +494,17 @@ pkg_mklink = rule(
     implementation = _pkg_mklink_impl,
     # @unsorted-dict-items
     attrs = {
-        "dest": attr.string(
-            doc = """Link "target", a path within the package.
+        "target": attr.string(
+            doc = """Link "target", a path on the filesystem.
+
+            This is what the link "points" to, and may point to an arbitrary
+            filesystem path, even relative paths.
+
+            """,
+            mandatory = True,
+        ),
+        "link_name": attr.string(
+            doc = """Link "destination", a path within the package.
 
             This is the actual created symbolic link.
 
@@ -508,15 +517,6 @@ pkg_mklink = rule(
             """,
             mandatory = True,
         ),
-        "src": attr.string(
-            doc = """Link "source", a path on the filesystem.
-
-            This is what the link "points" to, and may point to an arbitrary
-            filesystem path, even relative paths.
-
-            """,
-            mandatory = True,
-        ),
         "attributes": attr.string(
             doc = """Attributes to set on packaged symbolic links.
 
@@ -537,6 +537,31 @@ pkg_mklink = rule(
     provides = [PackageSymlinkInfo],
 )
 
+def pkg_mklink(name, link_name, target, attributes=None, src=None, **kwargs):
+  """Create a symlink.
+
+  Args:
+    name: target name
+    target: target path that the link should point to.
+    link_name: the path in the package that should point to the target.
+    attributes: file attributes.
+  """
+  if src:
+    if target:
+      fail("You can not specify both target and src.")
+    # buildifier: disable=print
+    print("Warning: pkg_mklink.src is deprecated. Use target.")
+    target = src
+  pkg_mklink_impl(
+      name = name,
+      target = target,
+      link_name = link_name,
+      attributes = attributes,
+      **kwargs,
+  )
+
+
+
 def _pkg_filegroup_impl(ctx):
     files = []
     dirs = []
@@ -575,7 +600,7 @@ def _pkg_filegroup_impl(ctx):
                 links += [
                     (
                         PackageSymlinkInfo(
-                            source = psi.source,
+                            target = psi.target,
                             destination = paths.join(ctx.attr.prefix, psi.destination),
                             attributes = psi.attributes,
                         ),
@@ -608,7 +633,7 @@ def _pkg_filegroup_impl(ctx):
 
             if PackageSymlinkInfo in s:
                 new_psi = PackageSymlinkInfo(
-                    source = s[PackageSymlinkInfo].source,
+                    target = s[PackageSymlinkInfo].target,
                     destination = paths.join(ctx.attr.prefix, s[PackageSymlinkInfo].destination),
                     attributes = s[PackageSymlinkInfo].attributes,
                 )

pkg/private/pkg_files.bzl

@@ -122,7 +122,7 @@ def _process_pkg_symlink(content_map, pkg_symlink_info, origin, default_mode, de
         user = attrs[1],
         group = attrs[2],
         origin = origin,
-        link_to = pkg_symlink_info.source,
+        link_to = pkg_symlink_info.target,
     )
 
 def _process_pkg_filegroup(content_map, pkg_filegroup_info, origin, default_mode, default_user, default_group):

pkg/providers.bzl

@@ -65,7 +65,7 @@ PackageSymlinkInfo = provider(
     fields = {
         "attributes": """See `attributes` in PackageFilesInfo.""",
         "destination": """string: Filesystem link 'name'""",
-        "source": """string or Label: Filesystem link 'target'.
+        "target": """string or Label: Filesystem link 'target'.
 
         TODO(nacl): Label sources not yet supported.
         """,

pkg/rpm_pfg.bzl

@@ -202,7 +202,7 @@ def _process_symlink(psi, origin_label, grouping_label, file_base, dest_check_ma
     rpm_files_list.append(file_base + " " + abs_dest)
     install_script_pieces.append(_INSTALL_SYMLINK_STANZA_FMT.format(
         abs_dest,
-        psi.source,
+        psi.target,
         psi.attributes["mode"],
     ))
 

tests/BUILD

@@ -18,7 +18,7 @@ load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
 load(":my_package_name.bzl", "my_package_naming")
 load(":path_test.bzl", "path_tests")
 load("//pkg:deb.bzl", "pkg_deb")
-load("//pkg:mappings.bzl", "pkg_attributes", "pkg_mkdirs", "pkg_mklink")
+load("//pkg:mappings.bzl", "pkg_attributes", "pkg_mkdirs")
 load("//pkg:pkg.bzl", "pkg_tar")
 load("//pkg:zip.bzl", "pkg_zip")
 

tests/deb/BUILD

@@ -38,8 +38,8 @@ my_package_naming(
 
 pkg_mklink(
     name = "java_link",
-    src = "/path/to/bin/java",
-    dest = "usr/bin/java",
+    link_name = "usr/bin/java",
+    target = "/path/to/bin/java",
 )
 
 pkg_tar(

tests/mappings/BUILD

@@ -25,7 +25,6 @@ load(
     "pkg_filegroup",
     "pkg_files",
     "pkg_mkdirs",
-    "pkg_mklink",
     "strip_prefix",
 )
 load("//tests/util:defs.bzl", "directory", "write_content_manifest")

tests/mappings/mappings_test.bzl

@@ -213,7 +213,7 @@ def _test_pkg_files_contents():
         ),
     )
 
-    # Test that pkg_files rejects cases where two sources resolve to the same
+    # Test that pkg_files rejects cases where two targets resolve to the same
     # destination.
     pkg_files(
         name = "pf_destination_collision_invalid_g",
@@ -557,14 +557,14 @@ def _pkg_mklink_contents_test_impl(ctx):
 
     asserts.equals(
         env,
-        ctx.attr.expected_src,
-        target_under_test[PackageSymlinkInfo].source,
-        "pkg_mklink source does not match expectations",
+        ctx.attr.expected_target,
+        target_under_test[PackageSymlinkInfo].target,
+        "pkg_mklink target does not match expectations",
     )
 
     asserts.equals(
         env,
-        ctx.attr.expected_dest,
+        ctx.attr.expected_link_name,
         target_under_test[PackageSymlinkInfo].destination,
         "pkg_mklink destination does not match expectations",
     )
@@ -583,35 +583,35 @@ def _pkg_mklink_contents_test_impl(ctx):
 pkg_mklink_contents_test = analysistest.make(
     _pkg_mklink_contents_test_impl,
     attrs = {
-        "expected_src": attr.string(mandatory = True),
-        "expected_dest": attr.string(mandatory = True),
         "expected_attributes": attr.string(),
+        "expected_link_name": attr.string(mandatory = True),
+        "expected_target": attr.string(mandatory = True),
     },
 )
 
 def _test_pkg_mklink():
     pkg_mklink(
         name = "pkg_mklink_base_g",
-        dest = "foo",
-        src = "bar",
+        link_name = "foo",
+        target = "bar",
         tags = ["manual"],
         attributes = pkg_attributes(mode = "0111"),
     )
 
     pkg_mklink_contents_test(
         name = "pkg_mklink_base",
         target_under_test = ":pkg_mklink_base_g",
-        expected_dest = "foo",
-        expected_src = "bar",
+        expected_link_name = "foo",
+        expected_target = "bar",
         expected_attributes = pkg_attributes(mode = "0111"),
     )
 
     # Test that the default mode (0755) is always set regardless of the other
     # values in "attributes".
     pkg_mklink(
         name = "pkg_mklink_mode_overlay_if_not_provided_g",
-        dest = "foo",
-        src = "bar",
+        link_name = "foo",
+        target = "bar",
         attributes = pkg_attributes(
             user = "root",
             group = "sudo",
@@ -621,8 +621,8 @@ def _test_pkg_mklink():
     pkg_mklink_contents_test(
         name = "pkg_mklink_mode_overlay_if_not_provided",
         target_under_test = ":pkg_mklink_mode_overlay_if_not_provided_g",
-        expected_dest = "foo",
-        expected_src = "bar",
+        expected_link_name = "foo",
+        expected_target = "bar",
         expected_attributes = pkg_attributes(
             mode = "0777",
             user = "root",
@@ -734,8 +734,8 @@ def _test_pkg_filegroup(name):
 
     pkg_mklink(
         name = "{}_pkg_symlink".format(name),
-        src = "src",
-        dest = "dest",
+        link_name = "dest",
+        target = "src",
         tags = ["manual"],
     )
 
@@ -788,8 +788,8 @@ def _test_pkg_filegroup(name):
 
     pkg_mklink(
         name = "{}_pkg_symlink_prefixed".format(name),
-        src = "src",
-        dest = "prefix/dest",
+        link_name = "prefix/dest",
+        target = "src",
         tags = ["manual"],
     )
 
@@ -833,8 +833,8 @@ def _test_pkg_filegroup(name):
 
     pkg_mklink(
         name = "{}_pkg_symlink_nested_prefixed".format(name),
-        src = "src",
-        dest = "nest/prefix/dest",
+        link_name = "nest/prefix/dest",
+        target = "src",
         tags = ["manual"],
     )