Add document about incorporating BoringSSL into a project.

Change-Id: Ia825300bae236e3133dd9a19313b7f5450f0c8e2
Reviewed-on: https://boringssl-review.googlesource.com/7781
Reviewed-by: David Benjamin <davidben@google.com>

2 files changed, 86 insertions, 0 deletions

diff --git a/INCORPORATING.md b/INCORPORATING.md
new file mode 100644
index 0000000..ef36aa3
--- /dev/null
+++ b/INCORPORATING.md
@@ -0,0 +1,85 @@
+# Incorporating BoringSSL into a project
+
+**Note**: if your target project is not a Google project then first read the
+[main README](/README.md) about the purpose of BoringSSL.
+
+## Directory layout
+
+Typically projects create a `third_party/boringssl` directory to put
+BoringSSL-specific files into. The source code of BoringSSL itself goes into
+`third_party/boringssl/src`, either by copying or as a
+[submodule](https://git-scm.com/docs/git-submodule).
+
+It's generally a mistake to put BoringSSL's source code into
+`third_party/boringssl` directly because pre-built files and custom build files
+need to go somewhere and merging these with the BoringSSL source code makes
+updating things more complex.
+
+## Build support
+
+BoringSSL is designed to work with many different build systems. Currently,
+different projects use [GYP](https://gyp.gsrc.io/),
+[GN](https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/quick_start.md),
+[Bazel](http://bazel.io/) and [Make](https://www.gnu.org/software/make/)  to
+build BoringSSL, without too much pain.
+
+The development build system is CMake and the CMake build knows how to
+automatically generate the intermediate files that BoringSSL needs. However,
+outside of the CMake environment, these intermediates are generated once and
+checked into the incorporating project's source repository. This avoids
+incorporating projects needing to support Perl and Go in their build systems.
+
+The script [`util/generate_build_files.py`](/util/generate_build_files.py)
+expects to be run from the `third_party/boringssl` directory and to find the
+BoringSSL source code in `src/`. You should pass it a single argument: the name
+of the build system that you're using. If you don't use any of the supported
+build systems then you should augment `generate_build_files.py` with support
+for it.
+
+The script will pregenerate the intermediate files (see
+[BUILDING.md](/BUILDING.md) for details about which tools will need to be
+installed) and output helper files for that build system. It doesn't generate a
+complete build script, just file and test lists, which change often. For
+example, see the
+[file](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated.gni)
+and
+[test](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated_tests.gni)
+lists generated for GN in Chromium.
+
+## Defines
+
+BoringSSL does not present a lot of configurability in order to reduce the
+number of configurations that need to be tested. But there are a couple of
+#defines that you may wish to set:
+
+`OPENSSL_NO_ASM` prevents the use of assembly code (although it's up to you to
+ensure that the build system doesn't link it in if you wish to reduce binary
+size). This will have a significant performance impact but can be useful if you
+wish to use tools like
+[AddressSanitizer](http://clang.llvm.org/docs/AddressSanitizer.html) that
+interact poorly with assembly code.
+
+`OPENSSL_SMALL` removes some code that is especially large at some performance
+cost.
+
+## Symbols
+
+You cannot link multiple versions of BoringSSL or OpenSSL into a single binary
+without dealing with symbol conflicts. If you are statically linking multiple
+versions together, there's not a lot that can be done because C doesn't have a
+module system.
+
+If you are using multiple versions in a single binary, in different shared
+objects, ensure you build BoringSSL with `-fvisibility=hidden` and do not
+export any of BoringSSL's symbols. This will prevent any collisions with other
+verisons that may be included in other shared objects. Note that this requires
+that all callers of BoringSSL APIs live in the same shared object as BoringSSL.
+
+If you require that BoringSSL APIs be used across shared object boundaries,
+continue to build with `-fvisibility=hidden` but define
+`BORINGSSL_SHARED_LIBRARY` in both BoringSSL and consumers. BoringSSL's own
+source files (but *not* consumers' source files) must also build with
+`BORINGSSL_IMPLEMENTATION` defined. This will export BoringSSL's public symbols
+in the resulting shared object while hiding private symbols. However note that,
+as with a static link, this precludes dynamically linking with another version
+of BoringSSL or OpenSSL.
diff --git a/README.md b/README.md
index e306da9..4caedb7 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ There are other files in this directory which might be helpful:
 
   * [PORTING.md](/PORTING.md): how to port OpenSSL-using code to BoringSSL.
   * [BUILDING.md](/BUILDING.md): how to build BoringSSL
+  * [INCORPORATING.md](/INCORPORATING.md): how to incorporate BoringSSL into a project.
   * [STYLE.md](/STYLE.md): rules and guidelines for coding style.
   * include/openssl: public headers with API documentation in comments. Also [available online](https://commondatastorage.googleapis.com/chromium-boringssl-docs/headers.html).
   * [FUZZING.md](/FUZZING.md): information about fuzzing BoringSSL.