doc: write developer docs for CMake tests. (#31)

Author: 1uc

doc/developer_guide.md

@@ -225,3 +225,135 @@ Anything `H5Easy` related goes in files with the appropriate name.
 What's left goes in `tests/unit/test_high_five_base.cpp`. This covers opening
 files, groups, dataset or attributes; checking certain pathological edge cases;
 etc.
+
+## CMake Integration
+In `tests/cmake_integration` we test that HighFive can be used in downstream projects;
+and that those project can, in turn, be used.
+
+### Overview
+#### Vendoring Strategies
+We'll refer to the process of embedding a copy of HighFive into a consuming
+library as *vendoring*. The *vendoring strategies* will include the strategy to
+not vendor.
+
+There's two broad strategies for integrating HighFive into other code: *finding* or
+*vendoring*. When finding HighFive, the assumption by the consumer is that it's
+been installed somewhere and it can find it. When vendoring, the consumer
+brings their own copy of HighFive and uses it. The different vendoring
+strategies are:
+
+- **find_package**: the standard way for finding dependencies in CMake. Usually
+  the assumption is that HighFive was install properly, either systemwide or in
+  a specific subdirectory. HighFive is then found with `find_package` (or
+  `find_dependency` when called from `*Config.cmake`).
+
+- **add_subdirectory**: the consuming code contains a submodule or subdirectory
+  with the HighFive code; and `add_subdirectory` is used to bring HighFive and
+  all it's targets into the consumer.
+
+- **fetch_content**: the consuming code uses CMake's FetchContent to download
+  and integrate HighFive.
+
+- **external_project**: similar to FetchContent; we don't current test if this
+  works.
+
+#### Integration Strategies
+These refer to downstream projects picking different HighFive targerts to
+"link" with HighFive. There's four: two regular targets, a target that only
+adds `-I <dir>` and one that skips all HighFive CMake code.
+
+#### Location Hints
+There are serveral ways of indicating where to find a package:
+
+- **CMAKE_PREFIX_PATH**: which adds a list of directories to the list of
+  directories that are used as prefixes when searching for `HighFiveConfig.`
+
+- **HighFive_ROOT**: which specifies a guess for where to additionally look
+  (but only when finding HighFive).
+
+There's two types of directories where a dependency can be located:
+
+- **install**: the place it ends up after `cmake --install build`.
+
+- **build**: one can, if one wants to (and we have users that do), specify
+  a build directory (not and install directory) as `HighFive_ROOT`.
+
+
+#### CMake's `export()`
+Furthermore, there's `export(...)`. Documentation describes it as being useful
+for cross-compilation, when one wants to have a set of host tool along with a
+library compiled for the device. It seems we don't need it in HighFive and can
+make it and easily write test consumers work perfectly without.
+
+However, if one of our consumers adds `export(...)` to their `CMakeLists.txt`
+then their build breaks, complaining about missing HighFive targets (and it
+seems they can't "fix it up" on their end because then CMake complains that
+there's duplicate exported HighFive related targets).
+
+The second way ommiting the missing `export()` can break downstream projects is
+if they attempt to use HighFive's build directory (not install directory) as
+`HighFive_ROOT` (or `CMAKE_PREFIX_PATH`).
+
+#### HighFive Visibility
+This is the idea that libraries behave differently depending on whether they
+use HighFive in their distributed headers; or not. If they don't they could
+attempt to hide the fact that they use HighFive from their users.
+
+Currently, we don't check that libraries can hide the use of HighFive.
+
+#### Applications vs Libraries
+In what follows application will refer to code that compiles into an
+executable. While libraries refer to code that compiles into a binary that
+other developers will link to in their library or application.
+
+Libraries and applications that have dependencies that use HighFive must be
+able to agree on a common version of HighFive they want to use. Otherwise,
+during the final linking phase, multiple definitions of the same HighFive
+symbols will exist, and they linker will pick one (arbitrarily); which is only
+safe if all definitions are identical.
+
+### Test "Organization"
+The script to check everything is unwieldy. Here's a summary of what it attemps
+to do.
+
+There's three downstream project in play: `dependent_library` is a library that
+uses HighFive in its public API, `application` is an executable that uses
+HighFive directly, `test_dependent_library` is an application that uses
+`dependent_library` its purpose is to check that our users can write CMake code
+that makes them integrate well with other projects.
+
+The conceptually easy choices are:
+
+- Application that don't have dependencies that use HighFive, can use any
+  strategy to integrate HighFive; because they know they're the only ones using
+  HighFive.
+
+- Libraries and applications that have dependencies that use HighFive should
+  use `find_package` since it's the easiest way of injecting a common version
+  of HighFive everwhere.
+
+Since we can't (and don't want to) force our consumers to use `find_package`
+and ban vendoring, we have to test what happens when libraries vendor
+HighFive. (Many of these are likely sources of headache if you try to figure
+out which code is when using which of the multiple copies of HighFive
+involved; and how they decide to use that version.)
+
+We'll assume that there's some way that all involved projects agree on a single
+version of HighFive (i.e. the exact same source code or git commit).
+
+The `dependent_library` will integrate HighFive using any of the following
+strategies: `external` in two variations one from HighFive's install dir and
+the other from HighFive's build dir; `submodule` in two variations which uses
+`add_subdirectory` once with and once without `EXCLUDE_FROM_ALL`,
+`fetch_content` in one variation.
+
+The `test_dependent_library` itself always incorporates `dependent_library`
+using `find_package` (Config mode). Since that layer might choose any of the
+strategies of integrating HighFive, we again check several. Additionally,
+`test_dependent_library` isn't (and probably shouldn't be) required to
+integrate HighFive directly: option `none`.
+
+Imagine a script that tries all combinations of the above; and attempts to only
+provide hints for the HighFive package location when needed, e.g. for `none`
+there's a `find_dependency` in `Hi5DependentConfig` that needs to be told where
+to look. This is what `test_cmake_integration.sh` attempts to do.