From 19000d6312d130803ea7bea1c35593eb88c23882 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 10:45:31 +0100 Subject: [PATCH 1/6] Update docs for auto installed arrow --- .vscode/settings.json | 4 +++ .../data/quick_start_guides/cpp_connect.md | 13 ++++------ docs/content/getting-started/cpp.md | 19 +++++--------- ...arrow-cpp-pixi.md => arrow-cpp-install.md} | 25 +++++++++++++++++-- 4 files changed, 38 insertions(+), 23 deletions(-) rename docs/content/howto/{arrow-cpp-pixi.md => arrow-cpp-install.md} (66%) diff --git a/.vscode/settings.json b/.vscode/settings.json index b0e371ce3c46..ed4470dd10cc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -8,6 +8,10 @@ "files.insertFinalNewline": true, "files.trimTrailingWhitespace": true, "files.autoGuessEncoding": true, + "cSpell.ignorePaths": [ + ".vscode", + "pixi.lock" + ], "cSpell.words": [ "andreas", "bbox", diff --git a/crates/re_viewer/data/quick_start_guides/cpp_connect.md b/crates/re_viewer/data/quick_start_guides/cpp_connect.md index 1dc6eeb9a3da..f0e80af96cd0 100644 --- a/crates/re_viewer/data/quick_start_guides/cpp_connect.md +++ b/crates/re_viewer/data/quick_start_guides/cpp_connect.md @@ -15,20 +15,17 @@ Using `pip`: After you have installed it, type `rerun` in your terminal to start the viewer. -#### Using the Rerun C++ SDK -First you need to install the `arrow-cpp` library on your system using your favorite package manager. -If you are using [Pixi](https://prefix.dev/docs/pixi/overview), you can simply type `pixi global install arrow-cpp`. -Find more information at the official Arrow Apache [install guide](https://arrow.apache.org/install/). - -If you're using CMake, you can add the following to your `CMakeLists.txt`: - +#### Using the Rerun C++ SDK with CMake ```cmake include(FetchContent) FetchContent_Declare(rerun_sdk 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. +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. +By default this will in turn download & build [Apache Arrow](https://arrow.apache.org/)'s C++ library which is required to build the Rerun C++. +See [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install?speculative-link) to learn more about this step and how to use an existing install. Make sure you link with `rerun_sdk`: ```cmake diff --git a/docs/content/getting-started/cpp.md b/docs/content/getting-started/cpp.md index 76cb78aa8b68..cd488ac1176b 100644 --- a/docs/content/getting-started/cpp.md +++ b/docs/content/getting-started/cpp.md @@ -6,24 +6,14 @@ order: 2 ## Setup 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. - -🚧 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: . ## Using Rerun with CMake Assuming you are starting with a bare-bones `CMakeLists.txt` such as: -``` -cmake_minimum_required(VERSION 3.16) +```cmake +cmake_minimum_required(VERSION 3.16...3.27) project(example_minimal LANGUAGES CXX) add_executable(example_minimal main.cpp) @@ -35,7 +25,10 @@ include(FetchContent) FetchContent_Declare(rerun_sdk 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. +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. +By default this will in turn download & build [Apache Arrow](https://arrow.apache.org/)'s C++ library which is required to build the Rerun C++. +See [Install arrow-cpp](../howto/arrow-cpp-install) to learn more about this step and how to use an existing install. Currently, Rerun SDK works with C++17 or newer, so you need to add this property to your target: ```cmake diff --git a/docs/content/howto/arrow-cpp-pixi.md b/docs/content/howto/arrow-cpp-install.md similarity index 66% rename from docs/content/howto/arrow-cpp-pixi.md rename to docs/content/howto/arrow-cpp-install.md index 91e029d6c91c..3fbb49a77ae5 100644 --- a/docs/content/howto/arrow-cpp-pixi.md +++ b/docs/content/howto/arrow-cpp-install.md @@ -1,11 +1,30 @@ --- -title: Install arrow-cpp with pixi +title: Install arrow-cpp order: 6 --- + +# Automatically download & build arrow from source (default) + +By default, the Rerun C++ SDK's CMake script (which is part of the SDK's zip artifact that can be fetched via `FetchContent`) +will download a known compatible version of Arrow from Github and add it to the build. +The build configuration is kept to the minimum required by the Rerun C++ SDK. + +To instead use an existing install of Rerun, set the CMake build option `RERUN_DOWNLOAD_AND_BUILD_ARROW` to false. +(by passing `-DRERUN_DOWNLOAD_AND_BUILD_ARROW=OFF` to your CMake configure step). +This will cause Rerun to instead use CMake's `find_package` to look for a ready-to-use install of the Arrow C++ library. + +# Install arrow-cpp with Pixi + [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. +Make sure to use `-DRERUN_DOWNLOAD_AND_BUILD_ARROW=OFF` when building, otherwise Rerun's CMake script +will download & build arrow instead, ignoring your Pixi install. +The advantage of using Pixi is that you can rely on pre-built artifacts rather than adding Arrows build to your own. +Also, Pixi is of course also useful for managing other dependencies like Eigen or OpenCV, +as well as fr pinning the version of your build tooling. + ## Installing Pixi On Mac or Linux you can just run: ``` @@ -61,4 +80,6 @@ pixi run example ⚠️ [#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). +⚠️ 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) +or stick with `RERUN_DOWNLOAD_AND_BUILD_ARROW=ON`. From 51594e68a7aed78caa1c93f0171582f45b1f6594 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 10:45:48 +0100 Subject: [PATCH 2/6] enable git progress on c++ sdk --- rerun_cpp/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/rerun_cpp/CMakeLists.txt b/rerun_cpp/CMakeLists.txt index 47c4f77f83f9..ef4510c400b6 100644 --- a/rerun_cpp/CMakeLists.txt +++ b/rerun_cpp/CMakeLists.txt @@ -163,6 +163,7 @@ if(RERUN_DOWNLOAD_AND_BUILD_ARROW) GIT_REPOSITORY https://github.com/apache/arrow.git GIT_TAG apache-arrow-10.0.1 GIT_SHALLOW true + GIT_PROGRESS true CMAKE_ARGS --preset ninja-debug-minimal -DARROW_IPC=ON From ee78eaedcd3aa9da6209de913cbd413ae3441b90 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 10:48:27 +0100 Subject: [PATCH 3/6] typo fixes --- docs/content/howto/arrow-cpp-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/howto/arrow-cpp-install.md b/docs/content/howto/arrow-cpp-install.md index 3fbb49a77ae5..68a91c55a08e 100644 --- a/docs/content/howto/arrow-cpp-install.md +++ b/docs/content/howto/arrow-cpp-install.md @@ -9,7 +9,7 @@ By default, the Rerun C++ SDK's CMake script (which is part of the SDK's zip art will download a known compatible version of Arrow from Github and add it to the build. The build configuration is kept to the minimum required by the Rerun C++ SDK. -To instead use an existing install of Rerun, set the CMake build option `RERUN_DOWNLOAD_AND_BUILD_ARROW` to false. +To instead use an existing install of Arrow, disable the CMake build option `RERUN_DOWNLOAD_AND_BUILD_ARROW`. (by passing `-DRERUN_DOWNLOAD_AND_BUILD_ARROW=OFF` to your CMake configure step). This will cause Rerun to instead use CMake's `find_package` to look for a ready-to-use install of the Arrow C++ library. From b2c09ddea4b9e9a5ae0823b0362c37392133f613 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 10:50:59 +0100 Subject: [PATCH 4/6] cspell fix --- docs/cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cspell.json b/docs/cspell.json index 98ea43de1fd0..2a7646a2c24a 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -85,6 +85,7 @@ "downscaled", "downscaling", "drawables", + "DRERUN", "dtype", "dtypes", "eframe", From a5282ba8f4c037c2e92650084124d1e988c474d8 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 11:23:39 +0100 Subject: [PATCH 5/6] lint fix --- docs/content/howto/arrow-cpp-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/howto/arrow-cpp-install.md b/docs/content/howto/arrow-cpp-install.md index 68a91c55a08e..54772b884645 100644 --- a/docs/content/howto/arrow-cpp-install.md +++ b/docs/content/howto/arrow-cpp-install.md @@ -6,7 +6,7 @@ order: 6 # Automatically download & build arrow from source (default) By default, the Rerun C++ SDK's CMake script (which is part of the SDK's zip artifact that can be fetched via `FetchContent`) -will download a known compatible version of Arrow from Github and add it to the build. +will download a known compatible version of Arrow from GitHub and add it to the build. The build configuration is kept to the minimum required by the Rerun C++ SDK. To instead use an existing install of Arrow, disable the CMake build option `RERUN_DOWNLOAD_AND_BUILD_ARROW`. From ae3c74d303c64121864d9982c455b5cbd5dfb2ad Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 30 Oct 2023 11:41:08 +0100 Subject: [PATCH 6/6] md link fix --- docs/content/getting-started/cpp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/getting-started/cpp.md b/docs/content/getting-started/cpp.md index cc6c1572a3ab..8b2c9b80893f 100644 --- a/docs/content/getting-started/cpp.md +++ b/docs/content/getting-started/cpp.md @@ -29,7 +29,7 @@ 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. By default this will in turn download & build [Apache Arrow](https://arrow.apache.org/)'s C++ library which is required to build the Rerun C++. -See [Install arrow-cpp](../howto/arrow-cpp-install) to learn more about this step and how to use an existing install. +See [Install arrow-cpp](../howto/arrow-cpp-install.md) to learn more about this step and how to use an existing install. Currently, Rerun SDK works with C++17 or newer, so you need to add this property to your target: ```cmake