[docs] Document LLVM_{BUILD,LINK}_LLVM_DYLIB

[axw]

Summary

Document the LLVM_BUILD_LLVM_DYLIB and LLVM_LINK_LLVM_DYLIB
CMake options, move BUILD_SHARED_LIBS out of frequently-used,
and add a note/warning to BUILD_SHARED_LIBS.

[mjacob]

LGTM.

[delcypher]

Looks like this got merged before I was able to comment on this.

docs/CMake.rst

443

I would consider expanding a little

If enabled, the target for building the libLLVM shared library is added.
This library contains all of LLVM's components in a single shared library. 
Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS=ON.
Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB is also ON.
The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS
to a list of the desired components.

454

I would consider rewording to

Flag indicating if each LLVM component (e.g. Support) is built as a shared library (ON) or as a static
library (OFF). Its default value is OFF. On Windows, shared libraries may
be used when building with MinGW, including mingw-w64, but not when
building with the Microsoft toolchain.

[axw]

In D16208#327770, @delcypher wrote:

Looks like this got merged before I was able to comment on this.

Sorry, I probably should have left it open a bit longer. Your suggestions read well, I'll commit them early next week.

[axw]

In D16208#328470, @axw wrote:

In D16208#327770, @delcypher wrote:

Looks like this got merged before I was able to comment on this.

Sorry, I probably should have left it open a bit longer. Your suggestions read well, I'll commit them early next week.

Done in r258112

docs/CMake.rst

**LLVM_LIBDIR_SUFFIX**:STRING
   to install libraries to ``/usr/lib64``.
 
 **CMAKE_C_FLAGS**:STRING
   Extra flags to use when compiling C source files.
 
 **CMAKE_CXX_FLAGS**:STRING
   Extra flags to use when compiling C++ source files.
 
-**BUILD_SHARED_LIBS**:BOOL
-  Flag indicating if shared libraries will be built. Its default value is
-  OFF. This option is only recommended for use by LLVM developers.
-  On Windows, shared libraries may be used when building with MinGW, including
-  mingw-w64, but not when building with the Microsoft toolchain.
-
 .. _LLVM-specific variables:
 
 LLVM-specific variables
 -----------------------
 
 **LLVM_TARGETS_TO_BUILD**:STRING
   Semicolon-separated list of targets to build, or *all* for building all
   targets. Case-sensitive. Defaults to *all*. Example:
**SPHINX_WARNINGS_AS_ERRORS**:BOOL
   errors. Defaults to ON.
 
 **LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
   OS X Only: If enabled CMake will generate a target named
   'install-xcode-toolchain'. This target will create a directory at
   $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
   be used to override the default system tools. 
 
+**LLVM_BUILD_LLVM_DYLIB**:BOOL
+  If enabled, the target for building the libLLVM shared library is added.
+  Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS.
+  Tools will only be linked to the libLLVM shared library if
+  LLVM_LINK_LLVM_DYLIB is also ON.
+
+**LLVM_LINK_LLVM_DYLIB**:BOOL
+  If enabled, tools will be linked with the libLLVM shared library. Defaults
+  to OFF. Setting LLVM_LINK_LLVM_DYLIB to ON also sets LLVM_BUILD_LLVM_DYLIB
+  to ON.
+
+**BUILD_SHARED_LIBS**:BOOL
+  Flag indicating if shared libraries will be built instead of static
+  libraries. Its default value is OFF. On Windows, shared libraries may
+  be used when building with MinGW, including mingw-w64, but not when
+  building with the Microsoft toolchain.
+ 
+  .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
+            If you want to build LLVM as a shared library, you should use the
+            ``LLVM_BUILD_LLVM_DYLIB`` option.
+
 Executing the test suite
 ========================
 
 Testing is performed when the *check-all* target is built. For instance, if you are
 using Makefiles, execute this command in the root of your build directory:
 
 .. code-block:: console