cargo install rerun-cli (#2183)

* Remove `native_viewer` from the default features of `rerun` crate Closes #1997 Most of our users only use the `rerun` library as a logging library but are still paying the cost of compiling the native viewer. With this PR, the `rerun` crate will not have the `native_viewer` (not `web_viewer`) feature on by default. This halves the compilation time on my computer. The `native_viewer` feature is only for users using the `show` or `spawn` features, which will hopefully be removed soon anyay: * #2109 To install the `rerun` binary with `native_viewer` and `web_viewer`, you now have to run `cargo install rerun --features binary`. This will be improved by: * #2108 To make things nicer for us developers, I've added `cargo rerun` as a shorthand for compiling and running `rerun` with the `native_viewer` feature, but NOT the `web_viewer` feature. * Add rerun-cli Users will now install the `rerun` binary with `cargo install rerun-cli` * Add a README.md * better text about how to run examples Co-authored-by: Andreas Reich <[email protected]> * Improve docs * Update RELEASES.md * Add checking of the docs to the release process --------- Co-authored-by: Andreas Reich <[email protected]>
rerun-io · May 23, 2023 · 9cb1685 · 9cb1685 · github-actions · May 23, 2023
1 parent aee4d1f
commit 9cb1685
Show file tree

Hide file tree

Showing 22 changed files with 183 additions and 40 deletions.
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -1,4 +1,7 @@
 [alias]
+# `cargo rerun` is short a convenient shorthand, skipping the web viewer.
+rerun = "run --package rerun-cli --no-default-features --features native_viewer --"
+
 # To easily run examples on the web, see https://github.com/rukai/cargo-run-wasm.
 # Temporary solution while we wait for our own xtasks!
 run-wasm = "run --release --package run_wasm --"

diff --git a/BUILD.md b/BUILD.md
@@ -17,6 +17,9 @@ This is a guide to how to build Rerun.
 * Run `./scripts/setup_dev.sh`.
 * Make sure `cargo --version` prints `1.69.0` once you are done
 
+All Rust examples are separate executable projections. Meaning to run them you specify the package, e.g. `cargo run -p dna`.
+
+You can type `cargo rerun` to compile and run the `rerun` binary with most features enabled, thanks to a shortcut in `.cargo/config.toml`.
 
 ### Apple-silicon Macs
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ rr.log_rect("car", bbox)
 ### Rerun Viewer binary
 Both the Python and Rust library can start the Rerun Viewer, but to stream log data over the network or load our `.rrd` data files you also need the `rerun` binary.
 
-It can be installed with `pip install rerun-sdk` or with `cargo install rerun`.
+It can be installed with `pip install rerun-sdk` or with `cargo install rerun-cli`.
 
 You should now be able to run `rerun --help` in any terminal.
 

diff --git a/RELEASES.md b/RELEASES.md
@@ -55,6 +55,11 @@ This is a living document. Strive to improve it on each new release.
     * [ ] Editorialize the changelog if necessary
     * [ ] Make sure the changelog includes instructions for handling any breaking changes
     * [ ] Commit and push the changelog
+* [ ] Check that the [`rerun-docs`](https://github.com/rerun-io/rerun-docs) are up to date:
+  * [ ] Python quick start
+  * [ ] Logging Data in Python
+  * [ ] Rust quick start
+  * [ ] Logging Data in Rust
 * [ ] Create a draft PR containing:
     * [ ] One-line summary of the release
     * [ ] A multi-line summary of the release
@@ -96,7 +101,7 @@ Before pushing the release tag:
 
 After tagging and the CI has published:
   * [ ] Test the Python packages from PyPI: `pip install rerun_sdk==0.x.0a1`
-  * [ ] Test rust install version: `cargo install -f [email protected] -F web_viewer && rerun --web-viewer api.rrd`
+  * [ ] Test rust install version: `cargo install --force rerun-cli@0.x.0-alpha.1 && rerun --web-viewer api.rrd`
   * [ ] Test rust crate: Modify Cargo.toml of any example to not point to the workspace
     * [ ] run with `--serve` to test web player
 

diff --git a/crates/rerun-cli/Cargo.toml b/crates/rerun-cli/Cargo.toml
@@ -0,0 +1,62 @@
+[package]
+name = "rerun-cli"
+authors.workspace = true
+categories = ["visualization", "computer-vision"]
+default-run = "rerun"
+description = "Log images, point clouds, etc, and visualize them effortlessly"
+edition.workspace = true
+homepage.workspace = true
+include.workspace = true
+keywords = ["mesh", "plotting", "point-cloud", "robotics", "visualization"]
+license.workspace = true
+publish = true
+readme = "README.md"
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+
+[package.metadata.docs.rs]
+all-features = true
+targets = ["x86_64-unknown-linux-gnu", "wasm32-unknown-unknown"]
+
+
+[features]
+# The default is what the user gets when they call `cargo install rerun-cli`,
+# so wer have all the bells and wistles here
+default = ["native_viewer", "web_viewer"]
+
+## Support spawning a native viewer.
+## This adds a lot of extra dependencies, so only enable this feature if you need it!
+native_viewer = ["rerun/native_viewer"]
+
+## Support serving a web viewer over HTTP.
+##
+## Enabling this inflates the binary size quite a bit, since it embeds the viewer wasm.
+# When building from source (in the repository), this feature adds quite a bit
+# to the compile time since it requires compiling and bundling the viewer as wasm.
+#
+# You also need to install some additional tools, which you can do by running
+# [`scripts/setup_web.sh`](https://github.com/rerun-io/rerun/blob/main/scripts/setup_web.sh).
+web_viewer = ["rerun/web_viewer"]
+
+[dependencies]
+re_build_info.workspace = true
+re_log.workspace = true
+re_memory.workspace = true
+rerun = { workspace = true, features = [
+  "analytics",
+  "demo",
+  "glam",
+  "image",
+  "sdk",
+  "server",
+] }
+
+anyhow.workspace = true
+document-features = "0.2"
+mimalloc.workspace = true
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+
+
+[build-dependencies]
+re_build_build_info.workspace = true
diff --git a/crates/rerun-cli/README.md b/crates/rerun-cli/README.md
@@ -0,0 +1,35 @@
+<h1 align="center">
+  <a href="https://www.rerun.io/">
+    <img alt="banner" src="https://user-images.githubusercontent.com/1148717/218142418-1d320929-6b7a-486e-8277-fbeef2432529.png">
+  </a>
+</h1>
+
+<h1 align="center">
+  <a href="https://crates.io/crates/rerun-cli">                           <img alt="Latest version" src="https://img.shields.io/crates/v/rerun-cli.svg">                            </a>
+  <a href="https://docs.rs/rerun-cli">                                    <img alt="Documentation"  src="https://docs.rs/rerun-cli/badge.svg">                                      </a>
+  <a href="https://github.com/rerun-io/rerun/blob/master/LICENSE-MIT">    <img alt="MIT"            src="https://img.shields.io/badge/license-MIT-blue.svg">                        </a>
+  <a href="https://github.com/rerun-io/rerun/blob/master/LICENSE-APACHE"> <img alt="Apache"         src="https://img.shields.io/badge/license-Apache-blue.svg">                     </a>
+  <a href="https://discord.gg/Gcm8BbTaAj">                                <img alt="Rerun Discord"  src="https://img.shields.io/discord/1062300748202921994?label=Rerun%20Discord"> </a>
+</h1>
+
+## Rerun command-line tool
+You can install the binary with `cargo install rerun-cli`
+
+This can act either as a server, a viewer, or both, depending on which options you use when you start it.
+
+Running `rerun` with no arguments will start the viewer, waiting for an SDK to connect to it over TCP.
+
+Run `rerun --help` for more.
+
+
+## What is Rerun?
+- [Examples](https://github.com/rerun-io/rerun/tree/latest/examples/rust)
+- [High-level docs](http://rerun.io/docs)
+- [Rust API docs](https://docs.rs/rerun/)
+- [Troubleshooting](https://www.rerun.io/docs/getting-started/troubleshooting)
+
+
+### Running a web viewer
+```sh
+rerun --web-viewer ../nyud.rrd
+```
diff --git a/crates/rerun-cli/build.rs b/crates/rerun-cli/build.rs
@@ -0,0 +1,4 @@
+fn main() {
+    re_build_build_info::rebuild_if_crate_changed("rerun-cli");
+    re_build_build_info::export_env_vars();
+}
diff --git a/crates/rerun-cli/src/bin/rerun.rs b/crates/rerun-cli/src/bin/rerun.rs
@@ -0,0 +1,26 @@
+//! The `rerun` binary, part of the [`rerun`](https://github.com/rerun-io/rerun) family of crates.
+//!
+//! Run `rerun --help` for more information.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
+//! ## Links
+//! - [Examples](https://github.com/rerun-io/rerun/tree/latest/examples/rust)
+//! - [High-level docs](http://rerun.io/docs)
+//! - [Rust API docs](https://docs.rs/rerun/)
+//! - [Troubleshooting](https://www.rerun.io/docs/getting-started/troubleshooting)
+use re_memory::AccountingAllocator;
+
+#[global_allocator]
+static GLOBAL: AccountingAllocator<mimalloc::MiMalloc> =
+    AccountingAllocator::new(mimalloc::MiMalloc);
+
+#[tokio::main]
+async fn main() -> anyhow::Result<std::process::ExitCode> {
+    re_log::setup_native_logging();
+    let build_info = re_build_info::build_info!();
+    rerun::run(build_info, rerun::CallSource::Cli, std::env::args())
+        .await
+        .map(std::process::ExitCode::from)
+}
diff --git a/crates/rerun/Cargo.toml b/crates/rerun/Cargo.toml
@@ -2,7 +2,6 @@
 name = "rerun"
 authors.workspace = true
 categories = ["visualization", "computer-vision"]
-default-run = "rerun"
 description = "Log images, point clouds, etc, and visualize them effortlessly"
 edition.workspace = true
 homepage.workspace = true
@@ -21,15 +20,7 @@ targets = ["x86_64-unknown-linux-gnu", "wasm32-unknown-unknown"]
 
 
 [features]
-default = [
-  "analytics",
-  "demo",
-  "glam",
-  "image",
-  "native_viewer",
-  "server",
-  "sdk",
-]
+default = ["analytics", "demo", "glam", "image", "sdk", "server"]
 
 ## Enable telemetry using our analytics SDK.
 analytics = [
@@ -52,7 +43,7 @@ image = ["re_log_types/image", "re_sdk?/image"]
 ## This adds a lot of extra dependencies, so only enable this feature if you need it!
 native_viewer = ["dep:re_viewer"]
 
-## Support for running a HTTP server that listens to incoming log messages from a Rerun SDK.
+## Support for running a TCP server that listens to incoming log messages from a Rerun SDK.
 server = ["re_sdk_comms/server"]
 
 ## Embed the Rerun SDK and re-export all of its public symbols.
@@ -102,7 +93,6 @@ webbrowser = { version = "0.8", optional = true }
 backtrace = "0.3"
 clap = { workspace = true, features = ["derive"] }
 ctrlc.workspace = true
-mimalloc.workspace = true
 puffin.workspace = true
 rayon.workspace = true
 tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }

diff --git a/crates/rerun/README.md b/crates/rerun/README.md
@@ -46,7 +46,7 @@ You can add the `rerun` crate to your project with `cargo add rerun`.
 To get started, see [the examples](https://github.com/rerun-io/rerun/tree/latest/examples/rust).
 
 ## Binary
-You can install the binary with `cargo install rerun`
+You can install the binary with `cargo install rerun-cli`
 
 This can act either as a server, a viewer, or both, depending on which options you use when you start it.
 
@@ -59,6 +59,5 @@ Run `rerun --help` for more.
 The web viewer is an experimental feature, but you can try it out with:
 
 ```sh
-cargo install --features web rerun
 rerun --web-viewer ../nyud.rrd
 ```
diff --git a/crates/rerun/src/lib.rs b/crates/rerun/src/lib.rs
@@ -5,7 +5,7 @@
 //! There is also a `rerun` binary.
 //! The binary is required in order to stream log data
 //! over the networks, and to open our `.rrd` data files.
-//! If you need it, install the `rerun` binary with `cargo install rerun`.
+//! If you need it, install the `rerun` binary with `cargo install rerun-cli`.
 //!
 //! ## Feature flags
 #![doc = document_features::document_features!()]

diff --git a/crates/rerun/src/main.rs b/crates/rerun/src/main.rs
diff --git a/crates/rerun/src/web_viewer.rs b/crates/rerun/src/web_viewer.rs
@@ -98,7 +98,7 @@ impl crate::sink::LogSink for WebViewerSink {
 /// If the `open_browser` argument is `true`, your default browser
 /// will be opened with a connected web-viewer.
 ///
-/// If not, you can connect to this server using the `rerun` binary (`cargo install rerun`).
+/// If not, you can connect to this server using the `rerun` binary (`cargo install rerun-cli`).
 ///
 /// NOTE: you can not connect one `Session` to another.
 ///

diff --git a/examples/rust/api_demo/Cargo.toml b/examples/rust/api_demo/Cargo.toml
@@ -7,7 +7,10 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = [
+  "native_viewer",
+  "web_viewer",
+] }
 
 anyhow = "1.0"
 clap = { version = "4.0", features = ["derive"] }

diff --git a/examples/rust/clock/Cargo.toml b/examples/rust/clock/Cargo.toml
@@ -7,7 +7,10 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = [
+  "native_viewer",
+  "web_viewer",
+] }
 
 anyhow = "1.0"
 clap = { version = "4.0", features = ["derive"] }

diff --git a/examples/rust/dna/Cargo.toml b/examples/rust/dna/Cargo.toml
@@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = ["native_viewer"] }
 
 itertools = "0.10"
 rand = "0.8"
diff --git a/examples/rust/minimal/Cargo.toml b/examples/rust/minimal/Cargo.toml
@@ -7,4 +7,4 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun" }
+rerun = { path = "../../../crates/rerun", features = ["native_viewer"] }
diff --git a/examples/rust/minimal_options/Cargo.toml b/examples/rust/minimal_options/Cargo.toml
@@ -7,7 +7,10 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = [
+  "native_viewer",
+  "web_viewer",
+] }
 
 anyhow = "1.0"
 clap = { version = "4.0", features = ["derive"] }

diff --git a/examples/rust/objectron/Cargo.toml b/examples/rust/objectron/Cargo.toml
@@ -8,7 +8,10 @@ publish = false
 
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = [
+  "native_viewer",
+  "web_viewer",
+] }
 
 anyhow = "1.0"
 clap = { version = "4.0", features = ["derive"] }

diff --git a/examples/rust/raw_mesh/Cargo.toml b/examples/rust/raw_mesh/Cargo.toml
@@ -7,7 +7,10 @@ license = "MIT OR Apache-2.0"
 publish = false
 
 [dependencies]
-rerun = { path = "../../../crates/rerun", features = ["web_viewer"] }
+rerun = { path = "../../../crates/rerun", features = [
+  "native_viewer",
+  "web_viewer",
+] }
 
 anyhow = "1.0"
 bytes = "1.3"

diff --git a/scripts/publish_crates.sh b/scripts/publish_crates.sh
@@ -118,5 +118,6 @@ cargo publish $FLAGS -p re_data_ui
 cargo publish $FLAGS -p re_viewer
 cargo publish $FLAGS -p re_sdk
 cargo publish $FLAGS -p rerun
+cargo publish $FLAGS -p rerun-cli
 
 echo "All crates successfully published!"
Benchmark suite	Current: `9cb1685`	Previous: `aee4d1f`	Ratio
`datastore/num_rows=1000/num_instances=1000/packed=false/latest_at_missing/primary/default`	`261` ns/iter (`± 0`)	`204` ns/iter (`± 3`)	`1.28`
`datastore/num_rows=1000/num_instances=1000/gc/default`	`2486969` ns/iter (`± 5739`)	`1647603` ns/iter (`± 6333`)	`1.51`
`mono_points_arrow/generate_message_bundles`	`29533912` ns/iter (`± 666551`)	`21724542` ns/iter (`± 372096`)	`1.36`
`mono_points_arrow_batched/generate_message_bundles`	`23167771` ns/iter (`± 956185`)	`15524874` ns/iter (`± 84799`)	`1.49`
`mono_points_arrow_batched/generate_messages`	`4686297` ns/iter (`± 260667`)	`2942496` ns/iter (`± 25790`)	`1.59`
`mono_points_arrow_batched/encode_total`	`29927125` ns/iter (`± 1356787`)	`20060708` ns/iter (`± 58413`)	`1.49`
`mono_points_arrow_batched/decode_log_msg`	`764952` ns/iter (`± 11215`)	`484965` ns/iter (`± 1734`)	`1.58`
`mono_points_arrow_batched/decode_message_bundles`	`7999537` ns/iter (`± 274642`)	`6093899` ns/iter (`± 7012`)	`1.31`
`mono_points_arrow_batched/decode_total`	`9027932` ns/iter (`± 256972`)	`6608132` ns/iter (`± 19336`)	`1.37`
`batch_points_arrow/encode_log_msg`	`318763` ns/iter (`± 1921`)	`225722` ns/iter (`± 478`)	`1.41`
`batch_points_arrow/encode_total`	`602360` ns/iter (`± 2480`)	`448752` ns/iter (`± 918`)	`1.34`
`arrow_mono_points/insert`	`2308415666` ns/iter (`± 6673732`)	`1523410734` ns/iter (`± 10697765`)	`1.52`
`arrow_mono_points/query`	`1282751` ns/iter (`± 12410`)	`863227` ns/iter (`± 1198`)	`1.49`
`arrow_batch_points/query`	`16871` ns/iter (`± 63`)	`12254` ns/iter (`± 4`)	`1.38`
`arrow_batch_vecs/query`	`389776` ns/iter (`± 688`)	`296250` ns/iter (`± 785`)	`1.32`