feat!: Provide cargo suited examples

.github/workflows/main.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Provision toolchain
         run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
       - name: Build
-        run: cargo build --features test-vendored-openssl
+        run: cargo build --features test-vendored-openssl --examples
       - name: Run tests
         run: cargo test --features test-vendored-openssl --verbose
       - name: Run integration tests
@@ -44,7 +44,7 @@ jobs:
       - name: Provision toolchain
         run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
       - name: Build
-        run: cargo build --features test-vendored-openssl
+        run: cargo build --features test-vendored-openssl --examples
       - name: Run tests
         run: cargo test --features test-vendored-openssl --verbose
 

Cargo.toml

@@ -10,12 +10,5 @@ resolver = "2"
 members = [
     "lib",
     "integration",
-    "samples/demo-server",
-    "samples/simple-client",
-    "samples/mqtt-client",
-    "samples/simple-server",
-    "samples/chess-server",
-    "samples/discovery-client",
-    "samples/event-client",
     "tools/certificate-creator"
 ]

README.md

@@ -46,26 +46,24 @@ The API documentation is generated from the latest published crates. This may be
 
 <a href="https://docs.rs/opcua"><img src="https://docs.rs/opcua/badge.svg"></img></a>
 
-# Samples
+# Examples
 
-If you want to get stuck in, there are a number of samples in the samples/ folder. The `simple-client` and the `simple-server` projects are
+If you want to get stuck in, there are a number of examples in the examples/ folder. The `simple-client` and the `simple-server` projects are
 minimal client and server programs respectively.
 
 ```bash
 # In one bash
-cd opcua/samples/simple-server
-cargo run
+cargo run --example simple-server
 # In another bash
-cd opcua/samples/simple-client
-cargo run
+cargo run --example simple-client
 ```
 
-The full list of samples:
+The full list of examples:
 
-1. [`simple-server`](samples/simple-server) - an OPC UA server that adds 4 variables v1, v2, v3 and v4 and updates them from a timer via push and pull mechanisms.
-2. [`simple-client`](samples/simple-client) - an OPC UA client that connects to a server and subscribes to the values of v1, v2, v3 and v4.
-3. [`discovery-client`](samples/discovery-client) - an OPC UA client that connects to a discovery server and lists the servers registered on it.
-4. [`chess-server`](samples/chess-server) - an OPC UA server that connects to a chess engine as its back end and updates variables representing the state of the game.
-5. [`demo-server`](samples/demo-server) - an OPC UA server that is more complex than the simple server and can be used for compliance testing.
-6. [`mqtt-client`](samples/mqtt-client) - an OPC UA client that subscribes to some values and publishes them to an MQTT broker.
-7. [`event-client`](samples/event-client) - an OPC UA client that will connect to a server and subscribe to alarms / events.
+1. [`simple-server`](lib/examples/simple-server) - an OPC UA server that adds 4 variables v1, v2, v3 and v4 and updates them from a timer via push and pull mechanisms.
+2. [`simple-client`](lib/examples/simple-client) - an OPC UA client that connects to a server and subscribes to the values of v1, v2, v3 and v4.
+3. [`discovery-client`](lib/examples/discovery-client) - an OPC UA client that connects to a discovery server and lists the servers registered on it.
+4. [`chess-server`](lib/examples/chess-server) - an OPC UA server that connects to a chess engine as its back end and updates variables representing the state of the game.
+5. [`demo-server`](lib/examples/demo-server) - an OPC UA server that is more complex than the simple server and can be used for compliance testing.
+6. [`mqtt-client`](lib/examples/mqtt-client) - an OPC UA client that subscribes to some values and publishes them to an MQTT broker.
+7. [`event-client`](lib/examples/event-client) - an OPC UA client that will connect to a server and subscribe to alarms / events.

docs/design.md

@@ -59,7 +59,7 @@ fn main() {
 
 This server will accept connections, allow you to browse the address space and subscribe to variables.
 
-Refer to the [`samples/simple-server/`](../samples/simple-server) and [`samples/simple-client/`](../samples/simple-client) examples
+Refer to the [`samples/simple-server/`](../samples/simple-server) and [`lib/examples/simple-client/`](../lib/examples/simple-client) examples
 for something that adds variables to the address space and changes their values.
 
 ## Types

lib/Cargo.toml

@@ -68,7 +68,6 @@ gethostname = "0.4"
 libc = "0.2"
 foreign-types = "0.3"
 # dependencies below are only required when certain features are enabled
-rumqttc = { version = "0.23", optional = true }
 env_logger = { version = "0.10", optional = true }
 actix-web = { version = "4.4", optional = true }
 actix-files = { version = "0.6", optional = true }
@@ -80,4 +79,16 @@ tempdir = "0.3"
 serde_json = "1.0"
 
 # Include console-logging when building tests
-opcua = { path = ".", features = ["console-logging"] }
+opcua = { path = ".", features = ["console-logging", "http"] }
+
+# Examples
+## chess-server, demo-server, discovery-client, event-client, mqtt-client, simple-client
+chrono = "0.4"
+lazy_static = "1.4.0"
+log = "0.4"
+log4rs = "1.2"
+pico-args = "0.5"
+rand = "0.7"
+rumqttc = "0.23"
+tokio = { version = "1", features = ["full"] }
+uci = "0.1.1"

samples/chess-server/README.md → lib/examples/chess-server/README.md

@@ -5,7 +5,7 @@ Chess is played to standard rules with castling and en passant. If the game play
 a piece being taken or a pawn advanced, the game is reset.
 
 ```
-cargo run
+cargo run --example chess-server
 ```
 
 Connect to the server with this url `opc.tcp://localhost:1234`.

samples/chess-server/src/main.rs → lib/examples/chess-server/main.rs

@@ -42,7 +42,7 @@ fn main() {
     let game = Arc::new(Mutex::new(game::Game::new(&engine_path)));
 
     // Create an OPC UA server with sample configuration and default node set
-    let server = Server::new(ServerConfig::load(&PathBuf::from("../server.conf")).unwrap());
+    let server = Server::new(ServerConfig::load(&PathBuf::from("samples/server.conf")).unwrap());
 
     let address_space = server.address_space();
 

samples/demo-server/README.md → lib/examples/demo-server/README.md

@@ -14,8 +14,7 @@ from `http://localhost:8585`, however you must start it from the `demo-server` d
 and other resources.
 
 ```
-cd opcua/samples/demo-server
-cargo run
+cargo run --example demo-server
 ```
 
 ## Testing configuration

samples/demo-server/src/main.rs → lib/examples/demo-server/main.rs

@@ -47,7 +47,7 @@ impl Default for Args {
             raise_events = true;
             config_path = PathBuf::from("server.conf");
             if !config_path.exists() {
-                config_path = PathBuf::from("../server.conf");
+                config_path = PathBuf::from("samples/server.conf");
             }
         }
 
@@ -111,7 +111,7 @@ fn main() {
         Args::usage();
     } else {
         // More powerful logging than a console logger
-        log4rs::init_file("log4rs.yaml", Default::default()).unwrap();
+        log4rs::init_file("lib/examples/demo-server/log4rs.yaml", Default::default()).unwrap();
 
         // Create an OPC UA server with sample configuration and default node set
         let mut server = Server::new(ServerConfig::load(&args.config_path).unwrap());

lib/examples/discovery-client/README.md

@@ -0,0 +1,7 @@
+This sample attempts to connect to a discovery server url and find servers from it.
+
+Run the sample via `cargo run --example discovery-client` and it will attempt to connect to `opc.tcp://localhost:4840/`
+and query the endpoints it finds.
+
+If you want to query another discovery server, then pass the url on the command line like so
+`cargo run --example discovery-client  -- --url opc.tcp://foo:4840/`.

lib/examples/event-client/README.md

@@ -0,0 +1,7 @@
+This is a simple client that will connect to a server and subscribe to alarms / events.
+
+Example usage
+
+```sh
+cargo run --example event-client -- --url opc.tcp://opcua.demo-this.com:62544/Quickstarts/AlarmConditionServer --event-source i=2253
+```

samples/mqtt-client/src/main.rs → lib/examples/mqtt-client/main.rs

@@ -58,7 +58,7 @@ Usage:
     }
 }
 
-const DEFAULT_CONFIG_FILE: &str = "../client.conf";
+const DEFAULT_CONFIG_FILE: &str = "samples/client.conf";
 const DEFAULT_MQTT_HOST: &str = "broker.hivemq.com";
 const DEFAULT_MQTT_PORT: u16 = 1883;
 

samples/simple-client/README.md → lib/examples/simple-client/README.md

@@ -1,7 +1,7 @@
 To run this sample:
 
-1. Launch either the `samples/simple-server`, or `3rd-party/node-opcua-server`. Both servers expose the same variables. 
-2. Run as `cargo run`
+1. Launch either the `lib/examples/simple-server`, or `3rd-party/node-opcua-server`. Both servers expose the same variables. 
+2. Run as `cargo run --examples simple-client`
 
 The client connects to the server, creates a subscription to variables v1, 
 v2, v3, v4 and continues to print out changes to those values without terminating.

samples/simple-server/README.md → lib/examples/simple-server/README.md

@@ -25,7 +25,7 @@ will trust the client and allow it to establish a connection.
 Build and run like this:
 
 ```
-cargo run
+cargo run --example simple-server
 ```
 
 # Connecting

samples/simple-server/src/main.rs → lib/examples/simple-server/main.rs

@@ -17,7 +17,8 @@ fn main() {
     opcua::console_logging::init();
 
     // Create an OPC UA server with sample configuration and default node set
-    let mut server = Server::new(ServerConfig::load(&PathBuf::from("../server.conf")).unwrap());
+    let mut server =
+        Server::new(ServerConfig::load(&PathBuf::from("samples/server.conf")).unwrap());
 
     let ns = {
         let address_space = server.address_space();