pydrake: Modules should be compiled with hidden symbols

[jamiesnape]

INFO: From Compiling bindings/pydrake/symbolic_py.cc:
In file included from bindings/pydrake/symbolic_py.cc:13:0:
bazel-out/k8-opt/bin/bindings/pydrake/util/_virtual_includes/wrap_pybind/drake/bindings/pydrake/util/wrap_pybind.h
:17:7: warning: 'drake::pydrake::MirrorDef' declared with greater visibility than the type of its field
'drake::pydrake::MirrorDef::m_' [-Wattributes]
 class MirrorDef {
       ^
bazel-out/k8-opt/bin/bindings/pydrake/util/_virtual_includes/wrap_pybind/drake/bindings/pydrake/util/wrap_pybind.h
:17:7: warning: 'drake::pydrake::MirrorDef' declared with greater visibility than the type of its field
'drake::pydrake::MirrorDef::mirror_' [-Wattributes]

[jwnimmer-tri]

I suspect that we should also promote Wattributes to Werror=attributes. @EricCousineau-TRI if you do that as part of the fix then great; otherwise I can open it as a new issue later on.

[EricCousineau-TRI]

Gotcha. Seems that I need to inline / hide this class:
http://pybind11.readthedocs.io/en/stable/faq.html#someclass-declared-with-greater-visibility-than-the-type-of-its-field-someclass-member-wattributes

Will see if I can update those flags.

[EricCousineau-TRI]

Relates #8540 on the level of RTTI and all that.
If we are able to resolve this, we should ensure CPS-generated CMake interface propagates visibility as well via its interface (#8644).

[jwnimmer-tri]

Refer to #16756 for a nice trick. We can set hidden visibility on an entire Drake namespace, instead of fighting with -fvisibility=hidden vs the linker.

With the attribute, symbols used within the file but not in the pydrake namespace can still be hidden (or not) per their original declarations. With the -fvisibility build flag all symbols are hidden, which leads to mismatched visibility vs other TUs.

namespace pydrake __attribute__ ((visibility ("hidden"))) {
...
}  // namespace pydrake

[jwnimmer-tri]

I think this is probably still worth doing, but in terms of scheduling my plan is to do the module flattening first (so that we have fewer python shared libraries -- most likely just one), at which point it should be less of a hassle to get this right.

[jwnimmer-tri]

See also #18677. It adds the warning flag, and provides a nice macro for the namespace-level visibility control.