Offer a supported interface to import Drake into other Bazel workspaces

[jwnimmer-tri]

Drake should offer a supported interface to load Drake into other Bazel workspaces. In other words, if a different project is using Bazel as its native build system, it should be able easily link against Drake in a way that will be robust as Drake evolves.

Right now, there is friction because (1) entries from Drake's //:WORKSPACE have to be repeated (at least until bazelbuild/bazel#1943 is resolved), and (2) some convenience macros such as lcm_cc_library would be useful to downstreams, and should be declared as part of our stable build API (with, e.g., a known deprecation policy).

This fix should probably wait until #6996 concludes, because all of Drake's package names are going to change.

After that, my intent for (1) would be to have for every third-party @thing in Drake's //:WORKSPACE come from a //tools/workspace/thing:repo.bzl file that can be load()ed by other workspace's WORKSPACE file(s) like load("@drake//tools/workspace/thing:repo.bzl", "thing_repository") and then invoked simply like thing_repository(); this part is related to #7226. Furthermore, we should consider offering a "one stop shopping" repository rule that can be loaded to declare all workspace items that Drake needs.

My intent for (2) would be some kind of documentation and/or CI tests, as part of the general stable API push. We would also want to examine any supported *.bzl files to make sure there dependencies were well-factored (i.e., they could be used without loading extra gunk) -- for some, we might want to prune off the install.bzl usage into a separate rules file, for example.

[jwnimmer-tri]

See #6193 for prior related discussion.

[jwnimmer-tri]

Feature branches will be:

• https://github.com/jwnimmer-tri/drake/tree/bazel-reuse-workspace
• https://github.com/jwnimmer-tri/drake-shambhala/tree/bazel

[jwnimmer-tri]

Before closing this, we should be sure to settle on the final name for package.bzl ala //tools/workspace/foo:package.bzl. In #7743 a discussion proposed that "package.bzl" might be confusing, because it's not (primarily) a Bazel package.

Edit: Done in #7837.

[jwnimmer-tri]

In terms of capability, I believe this is reasonably well done. There is an example in Shambhala, and the workspace code is factored for reuse. We are reusing the Drake workspace in TRI's Anzu repository successfully. There will undoubtedly be some sharp edges that still need polish, but we'll look at those individually as they come up -- please file issues for any remaining challenges.

The original post proposed capturing the workspace interface as part of the stable API set. That's still a good idea, but I feel best addressed in the context of the stable release proposal, without front-running it here. The same documentation, deprecation, non-regression, and cadence policies should apply to the build system APIs as well as the C++ and Python APIs.