[RSDK-1929] Add notes on fixing protobuf linking errors (#56)

README.md

@@ -136,8 +136,60 @@ git pull
 git submodule update --init --recursive
 ```
 
+### Troubleshooting Build Failures
+When building on `MacOS` and seeing errors related to `protobuf` such as
+
+```
+Undefined symbols for architecture arm64:
+  "google::protobuf::internal::InternalMetadata::~InternalMetadata()", referenced from:
+      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(common.pb.cc.o)
+      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(slam.pb.cc.o)
+      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(http.pb.cc.o)
+```
+
+or
+
+```
+/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:12:2: error: This file was generated by a newer version of protoc which is
+/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:13:2: error: incompatible with your Protocol Buffer headers. Please update
+/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:14:2: error: your headers.
+```
+
+Then it possible your `brew` installation is using the incorrect version of `protobuf`. To check if you are seeing this issue run
+
+```
+protoc --version
+```
+
+If your version is `3.20.3` then you may be having this error. To fix take the following steps
+
+1. unlink protobuf@3
+
+```
+brew unlink protobuf@3
+```
+
+2. link normal protobuf
+
+```
+brew unlink protobuf && brew link protobuf
+```
+
+3. echo your path & confirm you are not manually pathing to protobuf@3. If you see protobuf@3 in your path, track down where that is being added to your path & remove it (try .zshrc / .bashrc)
+
+```
+echo $PATH
+```
+
+4. Create a new terminal window to get a clean shell state
+
+5. Confirm you have a new version installed. The minimum version you should see on your Mac is `3.21.12`
+
+```
+protoc --version
+```
+
 ## License
 Copyright 2023 Viam Inc.
 
 Apache 2.0 - See [LICENSE](https://github.com/viamrobotics/slam/blob/main/LICENSE) file
-