[workspace] Add reusable macro and documentation for vendor_cxx

Update yaml_cpp_internal to follow the new style.

common/yaml/yaml_read_archive.cc

@@ -3,7 +3,7 @@
 #include <algorithm>
 #include <cstring>
 
-#include <drake-yaml-cpp/yaml.h>
+#include <drake_vendor/yaml-cpp/yaml.h>
 #include <fmt/ostream.h>
 
 #include "drake/common/nice_type_name.h"

common/yaml/yaml_write_archive.cc

@@ -4,8 +4,8 @@
 #include <utility>
 #include <vector>
 
-#include <drake-yaml-cpp/emitfromevents.h>
-#include <drake-yaml-cpp/yaml.h>
+#include <drake_vendor/yaml-cpp/emitfromevents.h>
+#include <drake_vendor/yaml-cpp/yaml.h>
 
 #include "drake/common/drake_assert.h"
 #include "drake/common/unused.h"

tools/workspace/vendor_cxx.bzl

@@ -0,0 +1,48 @@
+# -*- python -*-
+
+def cc_library_vendored(
+        name,
+        hdrs = None,
+        hdrs_vendored = None,
+        edit_include = None,
+        srcs = None,
+        srcs_vendored = None,
+        **kwargs):
+    # XXX In the next few stanzas, we'll rewrite the upstream headers and sources to
+    # use a different include paths and a private namespace. This gives Drake a
+    # completely independent build of the upstream library, even when statically
+    # linking other versions of the library into the same DSO.
+    """..."""
+    hdrs = hdrs or []
+    hdrs_vendored = hdrs_vendored or []
+    edit_include = edit_include or {}
+    srcs = srcs or []
+    srcs_vendored = srcs_vendored or []
+    if len(hdrs) != len(hdrs_vendored):
+        fail("The hdrs= and hdrs_vendored= list lengths must match")
+    if len(srcs) != len(srcs_vendored):
+        fail("The srcs= and srcs_vendored= list lengths must match")
+    native.genrule(
+        name = "_{}_vendoring".format(name),
+        srcs = hdrs + srcs,
+        outs = hdrs_vendored + srcs_vendored,
+        cmd = " ".join([
+            "$(execpath @drake//tools/workspace:vendor_cxx)",
+        ] + [
+            "'--edit-include={}:{}'".format(k, v)
+            for k, v in edit_include.items()
+        ] + [
+            "$(execpath {}):$(execpath {})".format(old, new)
+            for old, new in (zip(hdrs, hdrs_vendored) +
+                             zip(srcs, srcs_vendored))
+        ]),
+        tools = ["@drake//tools/workspace:vendor_cxx"],
+        tags = ["manual"],
+        visibility = ["//visibility:private"],
+    )
+    native.cc_library(
+        name = name,
+        hdrs = hdrs_vendored,
+        srcs = srcs_vendored,
+        **kwargs
+    )

tools/workspace/yaml_cpp_internal/package.BUILD.bazel

@@ -4,6 +4,10 @@ load(
     "@drake//tools/install:install.bzl",
     "install",
 )
+load(
+    "@drake//tools/workspace:vendor_cxx.bzl",
+    "cc_library_vendored",
+)
 
 licenses(["notice"])  # MIT
 
@@ -20,39 +24,22 @@ _SRCS = glob([
     "src/*.h",
 ], allow_empty = False)
 
-# In the next few stanzas, we'll rewrite the upstream headers and sources to
-# use a different include paths and a private namespace. This gives Drake a
-# completely independent build of the upstream library, even when statically
-# linking other versions of the library into the same DSO.
-_VENDORED_HDRS = [
-    x.replace("include/yaml-cpp/", "include/drake-yaml-cpp/")
-    for x in _HDRS
-]
-
-_VENDORED_SRCS = [
-    x.replace("src/", "drake-src/")
-    for x in _SRCS
-]
-
-genrule(
-    name = "vendoring",
-    srcs = _HDRS + _SRCS,
-    outs = _VENDORED_HDRS + _VENDORED_SRCS,
-    cmd = " ".join([
-        "$(execpath @drake//tools/workspace:vendor_cxx)",
-        "--edit-include=yaml-cpp/:drake-yaml-cpp/",
-    ] + [
-        "$(execpath {}):$(execpath {})".format(old, new)
-        for old, new in zip(_HDRS, _VENDORED_HDRS) + zip(_SRCS, _VENDORED_SRCS)
-    ]),
-    tools = ["@drake//tools/workspace:vendor_cxx"],
-)
-
-cc_library(
+cc_library_vendored(
     name = "yaml_cpp",
-    hdrs = _VENDORED_HDRS,
-    srcs = _VENDORED_SRCS,
-    includes = ["include"],
+    hdrs = _HDRS,
+    hdrs_vendored = [
+        x.replace("include/yaml-cpp/", "drake_src/drake_vendor/yaml-cpp/")
+        for x in _HDRS
+    ],
+    edit_include = {
+        "yaml-cpp/": "drake_vendor/yaml-cpp/",
+    },
+    includes = ["drake_src"],
+    srcs = _SRCS,
+    srcs_vendored = [
+        x.replace("src/", "drake_src/")
+        for x in _SRCS
+    ],
     linkstatic = 1,
     visibility = ["//visibility:public"],
 )