Add READMEs, basic veilid-core example

Cargo.lock

@@ -6530,6 +6530,14 @@ dependencies = [
  "x25519-dalek",
 ]
 
+[[package]]
+name = "veilid-core-examples-basic"
+version = "0.1.0"
+dependencies = [
+ "tokio",
+ "veilid-core",
+]
+
 [[package]]
 name = "veilid-flutter"
 version = "0.4.6"

Cargo.toml

@@ -2,6 +2,7 @@
 members = [
     "veilid-tools",
     "veilid-core",
+    "veilid-core/examples/basic",
     "veilid-server",
     "veilid-cli",
     "veilid-flutter/rust",

README.md

@@ -18,61 +18,9 @@ The easiest way to help grow the Veilid network is to run your own node. Every u
 
 To run such a node, establish a Debian or Fedora based VPS and install the veilid-server service. To make this process simple we are hosting package manager repositories for .deb and .rpm packages. See the [installing](./INSTALL.md) guide for more information.
 
-## Building on Veilid
+## Building with Veilid
 
-If you want to start using Veilid for your own app, take a look at the [Developer Book](https://veilid.gitlab.io/developer-book/).
+See the [README for veilid-core](./veilid-core/README.md)
-
-A basic example using `veilid-core` and `tokio` might look like this.
-
-```rust
-use std::sync::Arc;
-use veilid_core::VeilidUpdate::{AppMessage, Network};
-use veilid_core::{VeilidConfigBlockStore, VeilidConfig, VeilidConfigProtectedStore, VeilidConfigTableStore, VeilidUpdate};
-
-#[tokio::main]
-async fn main() {
-    let update_callback = Arc::new(move |update: VeilidUpdate| {
-        match update {
-            AppMessage(msg) => {
-                println!("Message: {}", String::from_utf8_lossy(msg.message().into()));
-            }
-            Network(msg) => {
-                println!("Network: Peers {:}, bytes/sec [{} up] [{} down]", msg.peers.iter().count(), msg.bps_up, msg.bps_down)
-            }
-            _ => {
-                println!("{:?}", update)
-            }
-        };
-    });
-
-    let config = VeilidConfig {
-        program_name: "Example Veilid".into(),
-        namespace: "veilid-example".into(),
-        protected_store: VeilidConfigProtectedStore {
-            // avoid prompting for password, don't do this in production
-            always_use_insecure_storage: true,
-            directory: "./.veilid/block_store".into(),
-            ..Default::default()
-        },
-        block_store: VeilidConfigBlockStore {
-            directory: "./.veilid/block_store".into(),
-            ..Default::default()
-        },
-        table_store: VeilidConfigTableStore {
-            directory: "./.veilid/table_store".into(),
-            ..Default::default()
-        },
-        ..Default::default()
-    };
-
-    let veilid = veilid_core::api_startup_config(update_callback, config).await.unwrap();
-    println!("Node ID: {}", veilid.config().unwrap().get().network.routing_table.node_id);
-    veilid.attach().await.unwrap();
-    // Until CTRL+C is pressed, keep running
-    tokio::signal::ctrl_c().await.unwrap();
-    veilid.shutdown().await;
-}
-```
 
 ## Development
 

veilid-cli/Cargo.toml

@@ -10,6 +10,7 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+publish = false
 
 [[bin]]
 name = "veilid-cli"

veilid-core/Cargo.toml

@@ -11,6 +11,8 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+documentation = "https://docs.rs/veilid-core"
+homepage = "https://veilid.gitlab.io/developer-book/"
 
 [lib]
 crate-type = ["cdylib", "staticlib", "rlib"]

veilid-core/README.md

@@ -0,0 +1,34 @@
+<!-- DO NOT EDIT BELOW - content within cargo-sync-readme blocks is generated -->
+<!-- cargo-sync-readme start -->
+
+# The Veilid Framework
+
+This is the core library used to create a Veilid node and operate it as part of an application.
+
+`veilid-core` contains all of the core logic for Veilid and can be used in mobile applications as well as desktop
+and in-browser WebAssembly apps.
+
+## Getting started
+
+- [Developer Book](https://veilid.gitlab.io/developer-book/)
+- [Examples](https://gitlab.com/veilid/veilid/-/tree/main/veilid-core/examples/)
+- [API Documentation](https://docs.rs/veilid-core)
+
+The public API is accessed by getting a [VeilidAPI] object via a call to [api_startup], [api_startup_json], or
+[api_startup_config].
+
+From there, a [RoutingContext] object can get you access to public and private routed operations.
+
+## Cargo features
+
+The default `veilid-core` configurations are:
+
+* `default` - Uses `tokio` as the async runtime.
+
+If you use `--no-default-features`, you can switch to other runtimes:
+
+* `default-async-std` - Uses `async-std` as the async runtime.
+* `default-wasm` - When building for the `wasm32` architecture, use this to enable `wasm-bindgen-futures` as the async runtime.
+
+
+<!-- cargo-sync-readme end -->

veilid-core/examples/basic/.gitignore

@@ -0,0 +1 @@
+.veilid

veilid-core/examples/basic/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "veilid-core-examples-basic"
+version = "0.1.0"
+repository.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+publish = false
+
+[dependencies]
+tokio = { version = "^1.43.0" }
+veilid-core = { version = "0.4.6", path = "../../../veilid-core" }
+
+[lints]
+workspace = true

veilid-core/examples/basic/src/main.rs

@@ -0,0 +1,55 @@
+use std::sync::Arc;
+use veilid_core::VeilidUpdate::{AppMessage, Network};
+use veilid_core::{VeilidConfig, VeilidConfigProtectedStore, VeilidConfigTableStore, VeilidUpdate};
+
+#[tokio::main]
+async fn main() {
+    let update_callback = Arc::new(move |update: VeilidUpdate| {
+        match update {
+            AppMessage(msg) => {
+                println!("Message: {}", String::from_utf8_lossy(msg.message()));
+            }
+            Network(msg) => {
+                println!(
+                    "Network: Peers {:}, bytes/sec [{} up] [{} down]",
+                    msg.peers.len(),
+                    msg.bps_up,
+                    msg.bps_down
+                )
+            }
+            _ => {
+                println!("{:#?}", update)
+            }
+        };
+    });
+
+    let config = VeilidConfig {
+        program_name: "Example Veilid".into(),
+        namespace: "veilid-example".into(),
+
+        protected_store: VeilidConfigProtectedStore {
+            // IMPORTANT: don't do this in production
+            // This avoids prompting for a password and is insecure
+            always_use_insecure_storage: true,
+            directory: "./.veilid/protected_store".into(),
+            ..Default::default()
+        },
+        table_store: VeilidConfigTableStore {
+            directory: "./.veilid/table_store".into(),
+            ..Default::default()
+        },
+        ..Default::default()
+    };
+
+    let veilid = veilid_core::api_startup_config(update_callback, config)
+        .await
+        .unwrap();
+    println!(
+        "Node ID: {}",
+        veilid.config().unwrap().get().network.routing_table.node_id
+    );
+    veilid.attach().await.unwrap();
+    // Until CTRL+C is pressed, keep running
+    tokio::signal::ctrl_c().await.unwrap();
+    veilid.shutdown().await;
+}

veilid-core/src/lib.rs

@@ -1,16 +1,22 @@
 //! # The Veilid Framework
 //!
-//! Core library used to create a Veilid node and operate it as part of an application.
+//! This is the core library used to create a Veilid node and operate it as part of an application.
 //!
 //! `veilid-core` contains all of the core logic for Veilid and can be used in mobile applications as well as desktop
 //! and in-browser WebAssembly apps.
 //!
+//! ## Getting started
+//!
+//! - [Developer Book](https://veilid.gitlab.io/developer-book/)
+//! - [Examples](https://gitlab.com/veilid/veilid/-/tree/main/veilid-core/examples/)
+//! - [API Documentation](https://docs.rs/veilid-core)
+//!
 //! The public API is accessed by getting a [VeilidAPI] object via a call to [api_startup], [api_startup_json], or
 //! [api_startup_config].
 //!
 //! From there, a [RoutingContext] object can get you access to public and private routed operations.
 //!
-//! ## Features
+//! ## Cargo features
 //!
 //! The default `veilid-core` configurations are:
 //!

veilid-flutter/rust/Cargo.toml

@@ -10,6 +10,7 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+publish = false
 
 [lib]
 crate-type = ["cdylib", "staticlib", "rlib"]

veilid-server/Cargo.toml

@@ -10,6 +10,7 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+publish = false
 
 [[bin]]
 name = "veilid-server"

veilid-tools/Cargo.toml

@@ -10,6 +10,8 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+documentation = "https://docs.rs/veilid-tools"
+homepage = "https://veilid.gitlab.io/developer-book/"
 
 [lib]
 # staticlib for iOS tests, cydlib for android tests, rlib for everything else

veilid-tools/README.md

@@ -0,0 +1,26 @@
+<!-- DO NOT EDIT BELOW - content within cargo-sync-readme blocks is generated -->
+<!-- cargo-sync-readme start -->
+
+# veilid-tools
+
+A collection of baseline tools for Rust development use by Veilid and Veilid-enabled Rust applications
+
+These are used by `veilid-core`, `veilid-server`, `veilid-cli` and may be used by any other applications
+that link in `veilid-core` if a common baseline of functionality is desired. Extending this crate with new
+utility functions is encouraged rather than adding 'common' functionality to `veilid-core`, allowing it to
+remain free of boilerplate and utility classes that could be reused elsewhere.
+
+Everything added to this crate must be extensively unit-tested.
+
+## Cargo features
+
+The default `veilid-tools` configurations are:
+
+- `default` - Uses `tokio` as the async runtime
+
+If you use `--no-default-features`, you can switch to other runtimes:
+
+- `rt-async-std` - Uses `async-std` as the async runtime
+- `rt-wasm-bindgen` - When building for the `wasm32` architecture, use this to enable `wasm-bindgen-futures` as the async runtime
+
+<!-- cargo-sync-readme end -->

veilid-tools/src/lib.rs

@@ -1,4 +1,4 @@
-//! # Veilid Tools
+//! # veilid-tools
 //!
 //! A collection of baseline tools for Rust development use by Veilid and Veilid-enabled Rust applications
 //!
@@ -9,7 +9,7 @@
 //!
 //! Everything added to this crate must be extensively unit-tested.
 //!
-//! ## Features
+//! ## Cargo features
 //!
 //! The default `veilid-tools` configurations are:
 //!

veilid-wasm/Cargo.toml

@@ -10,6 +10,7 @@ authors.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+publish = false
 
 [lib]
 crate-type = ["cdylib", "rlib"]