Support symbol prefixes
- In base.h, if BORINGSSL_PREFIX is defined, include
boringssl_prefix_symbols.h
- In all .S files, if BORINGSSL_PREFIX is defined, include
boringssl_prefix_symbols_asm.h
- In base.h, BSSL_NAMESPACE_BEGIN and BSSL_NAMESPACE_END are
defined with appropriate values depending on whether
BORINGSSL_PREFIX is defined; these macros are used in place
of 'namespace bssl {' and '}'
- Add util/make_prefix_headers.go, which takes a list of symbols
and auto-generates the header files mentioned above
- In CMakeLists.txt, if BORINGSSL_PREFIX and BORINGSSL_PREFIX_SYMBOLS
are defined, run util/make_prefix_headers.go to generate header
files
- In various CMakeLists.txt files, add "global_target" that all
targets depend on to give us a place to hook logic that must run
before all other targets (in particular, the header file generation
logic)
- Document this in BUILDING.md, including the fact that it is
the caller's responsibility to provide the symbol list and keep it
up to date
- Note that this scheme has not been tested on Windows, and likely
does not work on it; Windows support will need to be added in a
future commit
Change-Id: If66a7157f46b5b66230ef91e15826b910cf979a2
Reviewed-on: https://boringssl-review.googlesource.com/31364
Commit-Queue: David Benjamin <davidben@google.com>
CQ-Verified: CQ bot account: commit-bot@chromium.org <commit-bot@chromium.org>
Reviewed-by: David Benjamin <davidben@google.com>
diff --git a/BUILDING.md b/BUILDING.md
index 19dbe01..9bf9cb2 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -110,6 +110,28 @@
Passing multiple architectures for a multiple-architecture build is not
supported.
+### Building with Prefixed Symbols
+
+BoringSSL's build system has experimental support for adding a custom prefix to
+all symbols. This can be useful when linking multiple versions of BoringSSL in
+the same project to avoid symbol conflicts.
+
+In order to build with prefixed symbols, the `BORINGSSL_PREFIX` CMake variable
+should specify the prefix to add to all symbols, and the
+`BORINGSSL_PREFIX_SYMBOLS` CMake variable should specify the path to a file
+which contains a list of symbols which should be prefixed (one per line;
+comments are supported with `#`). In other words, `cmake ..
+-DBORINGSSL_PREFIX=MY_CUSTOM_PREFIX
+-DBORINGSSL_PREFIX_SYMBOLS=/path/to/symbols.txt` will configure the build to add
+the prefix `MY_CUSTOM_PREFIX` to all of the symbols listed in
+`/path/to/symbols.txt`.
+
+It is currently the caller's responsibility to create and maintain the list of
+symbols to be prefixed.
+
+This mechanism is under development and may change over time. Please contact the
+BoringSSL maintainers if making use of it.
+
## Known Limitations on Windows
* Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
