update docs and add example conanfile.txt

BUILDING.md

@@ -74,44 +74,6 @@ manually rather than via your package manager, though this is likely
 to make it more difficult to correctly configure the build of the Viam
 C++ SDK.
 
-### Dependencies with `conan`
-
-As of version 0.0.11 there is experimental support for building with
- `conan` using the `conanfile.py`. Currently, the only supported configuration
- is that specified in the `default_options` of the `conanfile.py`. 
-
-  From the root of this repo, you can do
-``` shell
-conan install . --output-folder=build-conan --build=missing
-```
-to install dependencies with `conan`. And then
-``` shell
-cmake . --preset conan-release
-cmake --build --preset=conan-release -j
-```
-The `conan install` sets up some [cmake-presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)
-which are used to resolve `--preset conan-release` above. Among other things,
-this tells CMake about the `conan_toolchain.cmake` generated by `conan`, and
-runs CMake with certain environment variables set. 
-
-If you do not want to use cmake-presets, you can do
-``` shell
-cd build-conan
-source conanbuild.sh
-cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
-```
-and later call `source deactivate_conanbuild.sh`. The `conanbuild.sh`
-script does the same environment variable setting as the cmake-presets,
-but it may be preferable if you would rather invoke your build system directly.
-
-PLEASE NOTE: Whether by cmake-presets or `conanbuild.sh`, you MUST, one way or
-another, make the `PATH` entries set by `conan` available to CMake, because
-`buf` requires that `protoc` is available on `PATH`. If you do not do this
-then `buf generate` will fail outright, or, if you have a different version of
-`protoc` available in your `PATH`, it will silently fail and later cause 
-compilation failures due to protobuf version mismatches.
-
-
 ## Obtaining the `viam-cpp-sdk` Source
 
 Just clone https://github.com/viamrobotics/viam-cpp-sdk into a
@@ -186,6 +148,99 @@ an installation tree under `build/install`.
 
 If the build did not succeed, please see the next section.
 
+## Building with `conan`
+
+As of version 0.0.11 there is experimental support for building with
+`conan` using the `conanfile.py`. Currently, the only supported
+configuration is that specified in the `default_options` of the
+`conanfile.py`.
+
+Note that there are two possible approaches here, which complement or
+supersede some of the other sections in this document. Namely, it is
+possible to
+
+1. use `conan` to obtain the [software
+   prerequisites](#software-prerequisites) for the SDK; OR
+2. use `conan` to build and package the SDK.
+
+Option 1. makes more sense for doing locally development on the SDK
+while using `conan` to get dependencies instead of your system package
+manager.
+
+Option 2. makes more sense for [building against the
+SDK](#building-against-the-sdk) as you would in module development.
+There we use `conan` to build, install, and package the SDK, which also
+implicitly performs the dependency management of Option 1. We now treat
+each in more detail.
+
+### Using `conan` to manage the SDK dependencies
+
+Here we use `conan` to grab the SDK dependencies, setting ourselves up
+for local SDK development.
+
+From the root of this repo, you can do
+``` shell
+conan install . --output-folder=build-conan --build=missing
+```
+to install dependencies with `conan`. And then
+``` shell
+cmake . --preset conan-release
+cmake --build --preset=conan-release -j
+```
+The `conan install` sets up some
+[cmake-presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)
+which are used to resolve `--preset conan-release` above. Among other
+things, this tells CMake about the `conan_toolchain.cmake` generated by
+`conan`, and runs CMake with certain environment variables set.
+
+If you do not want to use cmake-presets, you can do
+``` shell
+cd build-conan
+source conanbuild.sh
+cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
+```
+and later call `source deactivate_conanbuild.sh`. The `conanbuild.sh`
+script does the same environment variable setting as the cmake-presets,
+but it may be preferable if you would rather invoke your build system
+directly.
+
+PLEASE NOTE: Whether by cmake-presets or `conanbuild.sh`, you MUST, one
+way or another, make the `PATH` entries set by `conan` available to
+CMake, because `buf` requires that `protoc` is available on `PATH`. If
+you do not do this then `buf generate` will fail outright, or, if you
+have a different version of `protoc` available in your `PATH`, it will
+silently fail and later cause compilation failures due to protobuf
+version mismatches.
+
+## Creating and consuming the SDK `conan` package.
+
+Here we use `conan` to package and install the SDK so that we can build
+against it by declaring it as a dependency in a
+`conanfile.txt` or a `conanfile.py`.
+
+To do this, call `conan create .` from the project root. This will build
+and test the `viam-cpp-sdk` recipe, adding it into your local cache. See
+the [conan docs](https://docs.conan.io/2/reference/commands/create.html)
+for more info on `conan create`, as we will omit any details about using
+profiles, options, or settings to customize the build.
+
+Once this is done, the `viam-cpp-sdk` package is ready to be consumed.
+The example projects show a [minimal
+`conanfile.txt`](src/viam/examples/project/cmake/conanfile.txt). With
+this `conanfile.txt` in the same directory as your project's
+`CMakeLists.txt`, you can then do, for example,
+
+```shell
+conan install . --output-folder=build-conan --build=missing
+cmake . --preset=conan-release
+cmake --build --preset=conan-release -j 8
+```
+
+It is also possible to build using a `conanfile.py` rather than a
+`conanfile.txt`, see again the [conan
+docs](https://docs.conan.io/2/tutorial/consuming_packages/the_flexibility_of_conanfile_py.html#consuming-packages-flexibility-of-conanfile-py),
+or look at the [`test_package/conanfile.py`](test_package/conanfile.py)
+which is the test package recipe.
 
 ## Options to Configure or Customize the Build
 

src/viam/examples/project/README.md

@@ -4,8 +4,12 @@ tree and read the build instructions, then install the SDK.
 
 - For an example project showing how to consume an installed
   `viam-cpp-sdk` with CMake's `find_package`, see
-  `cmake/CMakeLists.txt`.
+  [`cmake/CMakeLists.txt`](cmake/CMakeLists.txt). Note that
+  this sample `CMakeLists.txt` can be used with no modifications
+  to build against the SDK as installed directly from CMake,
+  or to build against the `viam-cpp-sdk` `conan` package. For
+  instructions building with `conan`, see [here](/../../../../BUILDING.md#creating-and-consuming-the-sdk-conan-package).
 
 - For an example project showing how to consume an installed
   `viam-cpp-sdk` via its `pkg-config` setup, see
-  `pkg-config/Makefile`.
+  [`pkg-config/Makefile`](pkg-config/Makefile).

src/viam/examples/project/cmake/conanfile.txt

@@ -0,0 +1,6 @@
+[requires]
+viam-cpp-sdk/0.0.11
+
+[generators]
+CMakeDeps
+CMakeToolchain