[docs-integration] Add more documentation about using the CMake toolchain file

1 files changed, 23 insertions, 1 deletions

diff --git a/docs/users/integration.md b/docs/users/integration.md
index f1b5014bf..ce52abe23 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -40,10 +40,32 @@ See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked exam
 Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms:
 ```cmake
 # To find and use catch
-find_path(CATCH_INCLUDE_DIR catch.hpp)
+find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
 include_directories(${CATCH_INCLUDE_DIR})
 ```
 
+##### Using an environment variable instead of a command line option
+
+The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line:
+
+```cmake
+if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
+  set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+      CACHE STRING "")
+endif()
+
+project(myproject CXX)
+```
+
+##### Using multiple toolchain files
+
+To use an external toolchain file with a project using vcpkg, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` on the configure line:
+```no-highlight
+cmake ../my/project \
+   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
+   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-toolchain.cmake
+```
+
 #### Linking NuGet file
 
 We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.