Reviewed-by: Adam Langley <firstname.lastname@example.org>
diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
@@ -0,0 +1,100 @@
+# Building BoringSSL
+## Build Prerequisites
+ * [CMake]  2.8.8 or later is required.
+ * Perl 5.6.1 or later is required. On Windows, [Strawberry Perl]  and MSYS
+ Perl have both been reported to work. If not found by CMake, it may be
+ configured explicitly by setting `PERL_EXECUTABLE`.
+ * On Windows you currently must use [Ninja]  to build; on other platforms,
+ it is not required, but recommended, because it makes builds faster.
+ * If you need to build Ninja from source, then a recent version of
+ [Python]  is required (Python 2.7.5 works).
+ * On Windows only, [Yasm]  is required. If not found by CMake, it may be
+ configured explicitly by setting `CMAKE_ASM_NASM_COMPILER`.
+ * A C compiler is required. On Windows, MSVC 12 (Visual Studio 2013) or later
+ with Platform SDK 8.1 or later are supported. Recent versions of GCC and
+ Clang should work on non-Windows platforms, and maybe on Windows too.
+ * [Go]  is required. If not found by CMake, the go executable may be
+ configured explicitly by setting `GO_EXECUTABLE`.
+Using Ninja (note the 'N' is capitalized in the cmake invocation):
+ mkdir build
+ cd build
+ cmake -GNinja ..
+Using Make (does not work on Windows):
+ mkdir build
+ cd build
+ cmake ..
+You usually don't need to run `cmake` again after changing `CMakeLists.txt`
+files because the build scripts will detect changes to them and rebuild
+Note that the default build flags in the top-level `CMakeLists.txt` are for
+debugging—optimisation isn't enabled.
+If you want to cross-compile then there is an example toolchain file for 32-bit
+Intel in `util/`. Wipe out the build directory, recreate it and run `cmake` like
+ cmake -DCMAKE_TOOLCHAIN_FILE=../util/32-bit-toolchain.cmake -GNinja ..
+If you want to build as a shared library, pass `-DBUILD_SHARED_LIBS=1`. On
+Windows, where functions need to be tagged with `dllimport` when coming from a
+shared library, define `BORINGSSL_SHARED_LIBRARY` in any code which `#include`s
+the BoringSSL headers.
+### Building for Android
+It's possible to build BoringSSL with the Android NDK using CMake. This has
+been tested with version 10d of the NDK.
+Unpack the Android NDK somewhere and export `ANDROID_NDK` to point to the
+directory. Clone https://github.com/taka-no-me/android-cmake into `util/`. Then
+make a build directory as above and run CMake *twice* like this:
+ cmake -DANDROID_NATIVE_API_LEVEL=android-9 \
+ -DANDROID_ABI=armeabi-v7a \
+ -DCMAKE_TOOLCHAIN_FILE=../util/android-cmake/android.toolchain.cmake \
+ -DANDROID_NATIVE_API_LEVEL=16 \
+ -GNinja ..
+Once you've run that twice, Ninja should produce Android-compatible binaries.
+You can replace `armeabi-v7a` in the above with `arm64-v8a` to build aarch64
+## Known Limitations on Windows
+ * Versions of CMake since 3.0.2 have a bug in its Ninja generator that causes
+ yasm to output warnings
+ yasm: warning: can open only one input file, only the last file will be processed
+ These warnings can be safely ignored. The cmake bug is
+ * CMake can generate Visual Studio projects, but the generated project files
+ don't have steps for assembling the assembly language source files, so they
+ currently cannot be used to build BoringSSL.
+ : http://www.cmake.org/download/
+ : http://strawberryperl.com/
+ : https://martine.github.io/ninja/
+ : https://www.python.org/downloads/
+ : http://yasm.tortall.net/
+ : https://golang.org/dl/