Changes after trying to run the cpp getting started guide (#4049)

### What A few more details around the pixi install and the CMAKE_PREFIX_PATH. Make the example code match minimal/main.cpp ### Checklist * [x] I have read and agree to [Contributor Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md) * [x] I've included a screenshot or gif (if applicable) * [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/4049) (if applicable) * [x] The PR title and labels are set such as to maximize their usefulness for the next release's CHANGELOG - [PR Build Summary](https://build.rerun.io/pr/4049) - [Docs preview](https://rerun.io/preview/74fc40be104594908cfc1d2e2e31da8900401eeb/docs)  - [Examples preview](https://rerun.io/preview/74fc40be104594908cfc1d2e2e31da8900401eeb/examples)  - [Recent benchmark results](https://ref.rerun.io/dev/bench/) - [Wasm size tracking](https://ref.rerun.io/dev/sizes/)
rerun-io · Oct 27, 2023 · 2ec5ce7 · 2ec5ce7
1 parent cc8c9ea
commit 2ec5ce7
Show file tree

Hide file tree

Showing 7 changed files with 103 additions and 25 deletions.
diff --git a/docs/content/getting-started/cpp.md b/docs/content/getting-started/cpp.md
@@ -7,52 +7,63 @@ order: 2
 Before adding Rerun to your application, start by [installing the viewer](installing-viewer.md).
 
 The Rerun C++ SDK depends on an install of the `arrow-cpp` library on your system using.
-If you are using [Pixi](https://prefix.dev/docs/pixi/overview), you can simply type `pixi global install arrow-cpp`.
-Find more information about other package managers at the official Arrow Apache [install guide](https://arrow.apache.org/install/).
-⚠️ On Windows this only downloads release binaries which are **not** compatible with debug builds, causing runtime crashes. For debug builds you have to build Arrow yourself, see [Building Arrow C++](https://arrow.apache.org/docs/developers/cpp/building.html).
+
 🚧 In the future we want to make this part of the setup easier.
 
+### Installing arrow-cpp with pixi
+See our [how-to guide](../howto/arrow-cpp-pixi.md) on using pixi to install `arrow-cpp`.
+
+### Installing arrow-cpp manually
+Find more information about other package managers at the official Arrow Apache [install guide](https://arrow.apache.org/install/).
+
 ## Learning by example
 If you prefer to learn by example, check out our example repository which uses the Rerun C++ SDK to log some data from Eigen and OpenCV: <https://github.com/rerun-io/cpp-example-opencv-eigen>.
 
 ## Using Rerun with CMake
-Add the following to your `CMakeLists.txt`:
 
+Assuming you are starting with a bare-bones `CMakeLists.txt` such as:
+```
+cmake_minimum_required(VERSION 3.16)
+project(example_minimal LANGUAGES CXX)
+
+add_executable(example_minimal main.cpp)
+```
+
+You can add Rerun to your project using `FetchContent`
 ```cmake
 include(FetchContent)
 FetchContent_Declare(rerun_sdk DOWNLOAD_EXTRACT_TIMESTAMP ON URL https://github.com/rerun-io/rerun/releases/download/prerelease/rerun_cpp_sdk.zip) # TODO(#3962): update link
 FetchContent_MakeAvailable(rerun_sdk)
 ```
-
 This will download a bundle with pre-built Rerun C static libraries for most desktop platforms, all Rerun C++ sources and headers, as well as CMake build instructions for them.
 
-Currently, Rerun SDK works with C++17 or newer:
+Currently, Rerun SDK works with C++17 or newer, so you need to add this property to your target:
 ```cmake
-set_property(TARGET example PROPERTY CXX_STANDARD 17)
+set_property(TARGET example_minimal PROPERTY CXX_STANDARD 17)
 ```
 
-Make sure you link with `rerun_sdk`:
+And finally, make sure you link with `rerun_sdk`:
 ```cmake
-target_link_libraries(example PRIVATE rerun_sdk)
+target_link_libraries(example_minimal PRIVATE rerun_sdk)
 ```
 
 Combining the above, a minimal self-contained `CMakeLists.txt` looks like:
 ```cmake
 cmake_minimum_required(VERSION 3.16)
-project(example LANGUAGES CXX)
+project(example_minimal LANGUAGES CXX)
 
-add_executable(example main.cpp)
+add_executable(example_minimal main.cpp)
 
 # Download the rerun_sdk
 include(FetchContent)
 FetchContent_Declare(rerun_sdk DOWNLOAD_EXTRACT_TIMESTAMP ON URL https://github.com/rerun-io/rerun/releases/download/prerelease/rerun_cpp_sdk.zip) # TODO(#3962): update link
 FetchContent_MakeAvailable(rerun_sdk)
 
 # Rerun requires at least C++17, but it should be compatible with newer versions.
-set_property(TARGET example PROPERTY CXX_STANDARD 17)
+set_property(TARGET example_minimal PROPERTY CXX_STANDARD 17)
 
 # Link against rerun_sdk.
-target_link_libraries(example PRIVATE rerun_sdk)
+target_link_libraries(example_minimal PRIVATE rerun_sdk)
 ```
 
 ## Logging some data
@@ -68,7 +79,8 @@ using namespace rerun::demo;
 int main() {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
     auto rec = rerun::RecordingStream("rerun_example_cpp");
-    rec.connect().throw_on_failure();
+    // Try to spawn a new viewer instance.
+    rec.spawn().throw_on_failure();
 
     // Create some data using the `grid` utility function.
     auto points = grid<rerun::Position3D, float>({-10.f, -10.f, -10.f}, {10.f, 10.f, 10.f}, 10);
@@ -79,17 +91,16 @@ int main() {
 }
 ```
 
-Now start the viewer, build your application and run it:
+## Building and running
 
-You can configure cmake and build, for example like so:
+You can configure cmake, build, and run you application like so:
 ```bash
-cmake .
-cmake --build . -j 8
-rerun
-./example
+cmake -B build
+cmake --build build -j
+./build/example_minimal
 ```
 
-Once everything finishes compiling, you will see the points in the Rerun Viewer:
+Once everything finishes compiling, the application will spawn the rerun viewer and send the data to it:
 
 <picture>
   <img src="https://static.rerun.io/intro_cpp_result/398c8fb79766e370a65b051b38eac680671c348a/full.png" alt="">

diff --git a/docs/content/howto/arrow-cpp-pixi.md b/docs/content/howto/arrow-cpp-pixi.md
@@ -0,0 +1,64 @@
+---
+title: Install arrow-cpp with pixi
+order: 6
+---
+[Pixi](https://prefix.dev/docs/pixi/overview) is a convenient tool for managing cross-platform project dependencies. In
+fact, Rerun uses it for our own internal development dependency management, and you will find `pixi.toml` files in most
+of our external examples.
+
+## Installing Pixi
+On Mac or Linux you can just run:
+```
+curl -fsSL https://pixi.sh/install.sh | bash
+```
+Or on Windows:
+```
+iwr -useb https://pixi.sh/install.ps1 | iex
+```
+
+Alternatively if you are already a `cargo` user, you can install `pixi` via:
+```
+cargo install pixi
+```
+
+See the [Pixi installation guide](https://prefix.dev/docs/pixi/overview#installation) for other installation options.
+
+## Adding Pixi to your own project
+
+If you want to use `pixi` to manage dependencies in your own project, you can simply run `pixi init` in the root of your
+project folder. This will create a `pixi.toml` file that manages the project. After that you can run
+`pixi add arrow-cpp==10.0.1` to add arrow-cpp as a dependency to your project.
+
+Now, any pixi tasks added to your project will have access to the `arrow-cpp` library.
+
+Even without tasks, you can run `pixi shell` to create a shell environment where all your project dependencies
+(including `arrow-cpp`) will be available. You can use this `pixi shell` to run you project's build commands.
+
+Check out the [pixi docs](https://prefix.dev/docs/pixi/basic_usage) for more information on what you can do with pixi.
+
+## Using a global install of arrow-cpp
+
+If you're not ready to use pixi for your project, you can still use it to install `arrow-cpp` globally by running
+`pixi global install arrow-cpp`. However, in this case you will need to also tell `cmake` how to find the packages:
+```bash
+export CMAKE_PREFIX_PATH=$HOME/.pixi/envs/arrow-cpp:$CMAKE_PREFIX_PATH
+```
+
+## Pixi in action
+
+The rerun-cpp example: <https://github.com/rerun-io/cpp-example-opencv-eigen> ships with a `pixi.toml` file to manage
+its dependencies, as well as a set of tasks to simplify running it.
+
+If you have pixi installed, all you need to do to run the example is:
+```
+git clone https://github.com/rerun-io/cpp-example-opencv-eigen
+cd cpp-example-opencv-eigen
+pixi run example
+```
+
+## Known Issues
+
+⚠️ [#4050](https://github.com/rerun-io/rerun/issues/4050) `arrow-cpp` needs to be held back to 10.0.1 to avoid conflicts
+with the `rerun-sdk` package when installed in the same pixi environment.
+
+⚠️ On Windows pixi only downloads release binaries which are **not** compatible with debug builds, causing runtime crashes. For debug builds you have to build Arrow yourself, see [Building Arrow C++](https://arrow.apache.org/docs/developers/cpp/building.html).
diff --git a/docs/content/howto/cpp-custom-component-batch-adapter.md b/docs/content/howto/cpp-custom-component-batch-adapter.md
@@ -1,6 +1,6 @@
 ---
 title: C++ Custom Component Batch Adapter
-order: 6
+order: 7
 # TODO(#3962): update link
 redirect: https://github.com/rerun-io/rerun/blob/6b2cf6dbf29124a10f2fc909e02f5fee7cbd0cbe/examples/cpp/custom_component_adapter/README.md
 ---
diff --git a/docs/content/howto/extend.md b/docs/content/howto/extend.md
@@ -1,6 +1,6 @@
 ---
 title: Extend Rerun
-order: 7
+order: 8
 ---
 
 There are currently two major ways of extending Rerun. You can use Rerun with [your own custom data](extend/custom-data.md), or [extend the Rerun Viewer](extend/extend-ui.md) (currently Rust only).

diff --git a/docs/cspell.json b/docs/cspell.json
@@ -6,6 +6,7 @@
     "node_modules/**"
   ],
   "ignoreWords": [
+    "-useb",
     "aarch",
     "abey",
     "adrr",

diff --git a/examples/cpp/minimal/CMakeLists.txt b/examples/cpp/minimal/CMakeLists.txt
@@ -12,7 +12,8 @@ else()
     add_executable(example_minimal main.cpp)
 
     # Set the path to the rerun_c build.
-    set(RERUN_CPP_URL CACHE STRING "URL to the rerun_cpp zip.")
+    #TODO(#3962): Update URL
+    set(RERUN_CPP_URL "https://build.rerun.io/commit/c6c50d2/rerun_cpp_sdk.zip" CACHE STRING "URL to the rerun_cpp zip.")
 
     # Download the rerun_sdk
     include(FetchContent)

diff --git a/examples/cpp/minimal/main.cpp b/examples/cpp/minimal/main.cpp
@@ -5,7 +5,8 @@ using rerun::demo::grid;
 
 int main() {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
-    auto rec = rerun::RecordingStream("rerun_example_minimal");
+    auto rec = rerun::RecordingStream("rerun_example_cpp");
+    // Try to spawn a new viewer instance.
     rec.spawn().throw_on_failure();
 
     // Create some data using the `grid` utility function.