Imported Upstream version 1.36.0

[platform/upstream/grpc.git] / BUILDING.md

diff --git a/BUILDING.md b/BUILDING.md
index 531e3dc..01ffd2a 100644 (file)
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -144,7 +144,7 @@ you will be able to browse and build the code.
 > cmake --build . --config Release
 ```
 
-If you want to build DLLs, run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
+Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`. 
 
 ### Windows, Using Ninja (faster build).
 
@@ -160,7 +160,16 @@ installed to be able to compile the C/C++ sources.
 > cmake --build .
 ```
 
-If you want to build DLLs, run `cmake` with `-DBUILD_SHARED_LIBS=ON`.
+Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.
+
+### Windows: A note on building shared libs (DLLs)
+
+Windows DLL build is supported at a "best effort" basis and we don't recommend using gRPC C++ as a DLL as there are some known drawbacks around how C++ DLLs work on Windows. For example, there is no stable C++ ABI and you can't safely allocate memory in one DLL, and free it in another etc.
+
+That said, we don't actively prohibit building DLLs on windows (it can be enabled in cmake with `-DBUILD_SHARED_LIBS=ON`), and are free to use the DLL builds
+at your own risk.
+- you've been warned that there are some important drawbacks and some things might not work at all or will be broken in interesting ways.
+- we don't have extensive testing for DLL builds in place (to avoid maintenance costs, increased test duration etc.) so regressions / build breakages might occur
 
 ### Dependency management