(In)stability Notice

‍Warning This is a beta release of the Viam C++ SDK. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.

Resources

Repository Layout

src/viam/sdk The implementation of the C++ sdk library
src/viam/api All the google and viam api autogen files
src/viam/examples A list of examples

Getting Started

Please see BUILDING.md for instructions on how to use CMake-based build system for this project.

NOTE: Windows is not supported. If you are using Windows, build the project in WSL.

Using Docker for Development

A Docker description is included which will install the required packages.

Create a new docker image from one of the provided docker files. From the root directory of this project (where this README is located), run docker build -t cpp . -f etc/docker/Dockerfile.debian.bullseye (other files are provided for Ubuntu Focal and Ubuntu Jammy as well as Debian Sid). Run the new image in a container that has your local project directory mounted to the filesystem. This will ensure that you can continue to develop locally on your machine, and all files will be automatically synced into the docker environment. To create the environment and open a shell to it, run the command docker run --rm -it -v "$PWD":/usr/src/viam-cpp-sdk -w /usr/src/viam-cpp-sdk cpp /bin/bash

Start developing! You can develop as you normally would, using the files on your local filesystem. When it comes time to testing/building/running the program, do so inside the docker environment you opened in the previous step.

Building Documentation Locally for Testing

The C++ sdk uses Doxygen to generate documentation. An automated workflow will generate and update our documentation on each merge, and publish it to cpp.viam.dev.

Generating documentation locally to observe changes while developing with the C++ SDK is simple. First, make sure doxygen is installed, e.g.,

(on mac) brew install doxygen

(on linux) apt-get install -y doxygen

Next, generate the documentation. From the SDK root, run:

./bin/build-docs.sh

That will run doxygen Doxyfile and create the etc/docs/api/current folder. Then simply open the index.html file in your preferred browser to view the documentation.

A Note on Connectivity and webRTC Functionality

The rust webRTC implementation (which C++ relies on via rust's foreign function interface) is still new, and liable to have bugs. At a minimum, we expect that calls to ShellService::shell() have a high likelihood of strange behavior. If you encounter any issues with streaming requests over webRTC, direct dial (by disabling webrtc as above) should resolve them. And please file a bug report! We will endeavor to be as responsive as possible, and resolve issues as quickly as possible.

License

Apache 2.0 - See LICENSE file