Improved control of symbol visibility

[rpoyner-tri]

Description of Issue

Drake has begun incorporating portions of OpenUSD, via building from source code. One Drake-specific requirement (that other downstream library developers may have) is to minimize the symbols that are visible from its shared libraries.

Drake uses two techniques to control symbols:

1. compiler symbol visibility attributes (https://gcc.gnu.org/wiki/Visibility)
2. rewriting namespace names to contain the string 'drake_vendor'

Technique 1 has the limitation that it sometimes interferes with c++ in surprising ways (e.g https://github.com/PixarAnimationStudios/OpenUSD/issues/1475). It can work well for plain C code.

Happily, OpenUSD has a very nice system to let downstream builders rewrite its namespaces. However, the Drake integration experience so far has uncovered a few holes in the namespace scheme. I hope to help address this by offering a few small PRs, with reference back to this issue.

Steps to Reproduce

It's easiest to give an example from OpenUSD's own shared library output. These instructions are for Ubuntu Jammy.

1. $cd path-to/OpenUSD
2. $ git checkout dev
3. $ python3 ./build_scripts/build_usd.py --no-python ~/tmp/usd/dist
4. $ cd ~/tmp/usd/dist
5. $ readelf --wide --symbols --demangle ./lib/libusd_work.so | grep 'GLOBAL *DEFAULT' |egrep -v 'pxrInternal|GLIBC|GCC|CXXABI|tbb::'
6. In the output from above, the data section symbol PXR_WORK_THREAD_LIMIT is GLOBAL and not namespaced.
7. Repeat the above on libusd_gf.so, libusd_pegtl.so, etc., to see other cases.

System Information (OS, Hardware)

Ubuntu LTS versions for x84_64, macOS recent versions for arm64. See the Supported Configurations table at https://drake.mit.edu/installation.html .

Package Versions

The problems vary over time, but several were seen as of v24.08. Current dev has fewer problems already.

Build Flags

[jesschimein]

Filed as internal issue #USD-10094