Fix Sample Readme (#838)

* improve readme

* update service sample

* add content table

* fix header layer

* fix readme link

Author: xiazhvera

samples/README.md

@@ -9,7 +9,7 @@ This directory contains sample applications for [aws-iot-device-sdk-cpp-v2](../R
     * [Others](#others)
 * [Instructions](#instructions)
 * [Sample Help](#sample-help)
-* [Enable Logging](#enable-logging)
+* [Enable Logging](#enable-logging-in-samples)
 
 
 ## Samples

samples/mqtt/mqtt5_aws_websocket/README.md

@@ -68,7 +68,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to build
 
-To build the sample, change directory into the samples, and run the cmake commands
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_aws_websocket/build` folder.
 ```sh
 cd samples/mqtt/mqtt5_aws_websocket/
 # If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
@@ -78,10 +78,12 @@ cmake --build build --config "Debug"
 
 ## How to run
 
-To Run this sample from the `samples\mqtt\mqtt5_aws_websocket` folder, use the following command:
+To run this sample, navigate to the build directory where the executable was created:
 
 ```sh
-.mqtt5_aws_websocket \
+# From samples/mqtt/mqtt5_aws_websocket/, go to the build directory
+cd build
+./mqtt5_aws_websocket \
   --endpoint <AWS IoT endpoint> \
   --signing_region <Signing region for websocket connection>
 ```
@@ -111,4 +113,4 @@ optional arguments:
 The sample will not run without the required arguments and will notify you of missing arguments.
 
 ## Additional Information
-Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.
+Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

samples/mqtt/mqtt5_custom_auth_signed/README.md

@@ -70,7 +70,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to build
 
-To build the sample, change directory into the samples, and run the cmake commands
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_custom_auth_signed/build` folder.
 ```sh
 cd samples/mqtt/mqtt5_custom_auth_signed/
 # If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
@@ -80,9 +80,11 @@ cmake --build build --config "Debug"
 
 ## How to run
 
-To Run this sample from the `samples\mqtt\mqtt5_custom_auth_signed` folder, use the following command:
+To run this sample, navigate to the build directory where the executable was created:
 
 ```sh
+# From samples/mqtt/mqtt5_custom_auth_signed/, go to the build directory
+cd build
 # For a signed custom authorizer
 ./mqtt5_custom_auth_signed \
     --endpoint <AWS IoT endpoint> \
@@ -92,7 +94,6 @@ To Run this sample from the `samples\mqtt\mqtt5_custom_auth_signed` folder, use
     --auth_signature <Custom authorizer signature> \
     --auth_username <The name to send when connecting through the custom authorizer> \
     --auth_password <The password to send when connecting through a custom authorizer>
-
 ```
 
 If you would like to see what optional arguments are available, use the `--help` argument:
@@ -122,4 +123,4 @@ optional arguments:
 The sample will not run without the required arguments and will notify you of missing arguments.
 
 ## Additional Information
-Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.
+Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

samples/mqtt/mqtt5_custom_auth_unsigned/README.md

@@ -70,7 +70,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to build
 
-To build the sample, change directory into the samples, and run the cmake commands
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_custom_auth_unsigned/build` folder.
 ```sh
 cd samples/mqtt/mqtt5_custom_auth_unsigned/
 # If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
@@ -80,9 +80,11 @@ cmake --build build --config "Debug"
 
 ## How to run
 
-To Run this sample from the `samples\mqtt\mqtt5_custom_auth_unsigned` folder, use the following command:
+To run this sample, navigate to the build directory where the executable was created:
 
 ```sh
+# From samples/mqtt/mqtt5_custom_auth_unsigned/, go to the build directory
+cd build
 ./mqtt5_custom_auth_unsigned \
   --endpoint <AWS IoT endpoint> \
   --authorizer_name <custom authorizer name> \
@@ -115,4 +117,4 @@ optional arguments:
 The sample will not run without the required arguments and will notify you of missing arguments.
 
 ## Additional Information
-Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.
+Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

samples/mqtt/mqtt5_pkcs11/README.md

@@ -71,7 +71,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to build
 
-To build the sample, change directory into the samples, and run the cmake commands
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_pkcs11/build` folder.
 ```sh
 cd samples/mqtt/mqtt5_pkcs11/
 # If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
@@ -81,9 +81,11 @@ cmake --build build --config "Debug"
 
 ## How to run
 
-To Run this sample from the `samples/mqtt/mqtt5_pkcs11` folder, use the following command:
+To run this sample, navigate to the build directory where the executable was created:
 
 ```sh
+# From samples/mqtt/mqtt5_pkcs11/, go to the build directory
+cd build
 ./mqtt5_pkcs11 \
   --endpoint <AWS IoT endpoint> \
   --cert <path to certificate file> \
@@ -179,4 +181,4 @@ The steps to use [SoftHSM2](https://www.opendnssec.org/softhsm/) as the PKCS#11
     ```
 
 ## Additional Information
-Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.
+Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

samples/mqtt/mqtt5_x509/README.md

@@ -69,7 +69,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to build
 
-To build the sample, change directory into the samples, and run the cmake commands
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/mqtt/mqtt5_x509/build` folder.
 ```sh
 cd samples/mqtt/mqtt5_x509/
 # If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
@@ -79,10 +79,12 @@ cmake --build build --config "Debug"
 
 ## How to run
 
-To Run this sample using a direct MQTT connection with a key and certificate, use the following command:
+To run this sample, navigate to the build directory where the executable was created:
 
-``` sh
-./mqtt5_x509  --endpoint <endpoint> --cert <path to the certificate> --key <path to the private key>
+```sh
+# From samples/mqtt/mqtt5_x509/, go to the build directory
+cd build
+./mqtt5_x509 --endpoint <endpoint> --cert <path to the certificate> --key <path to the private key>
 ```
 
 If you would like to see what optional arguments are available, use the `--help` argument:
@@ -108,4 +110,4 @@ optional arguments:
 The sample will not run without the required arguments and will notify you of missing arguments.
 
 ## Additional Information
-Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.
+Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../../documents/MQTT5_Userguide.md#client-operations), [lifecycle events](../../../documents/MQTT5_Userguide.md#client-lifecycle-management), [connection methods](../../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

samples/others/device_defender/mqtt5_basic_report/README.md

@@ -1,6 +1,6 @@
 # Device Defender
 
-[**Return to main sample list**](../../README.md)
+[**Return to main sample list**](../../../README.md)
 
 This sample uses the AWS IoT [Device Defender](https://aws.amazon.com/iot-device-defender/) Service to send on device metrics to AWS. Device Defender is an AWS IoT Core service that allows you to monitor the health of your IoT device through sending periodic updates containing device data to AWS IoT Core.
 
@@ -63,9 +63,23 @@ This sample expects and requires the following custom metrics:
   * type `ip-list`
   * info: sends a predefined list of documentation IP addresses.
 
-To run the Device Defender sample, use the following command:
+## How to build
 
-``` sh
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/others/device_defender/mqtt5_basic_report/build` folder.
+```sh
+cd samples/others/device_defender/mqtt5_basic_report/
+# If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
+cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-workspace dir>" -DCMAKE_BUILD_TYPE="Debug" .
+cmake --build build --config "Debug"
+```
+
+## How to run
+
+To run this sample, navigate to the build directory where the executable was created:
+
+```sh
+# From samples/others/device_defender/mqtt5_basic_report/, go to the build directory
+cd build
 ./mqtt5-basic-report --endpoint <endpoint> --cert <path to the certificate> --key <path to the private key> --thing_name <thing name>
 ```
 

samples/others/secure_tunneling/secure_tunnel/README.md

@@ -1,18 +1,30 @@
 # Secure Tunnel
 
-[**Return to main sample list**](../../README.md)
+[**Return to main sample list**](../../../README.md)
 
 This sample uses AWS IoT [Secure Tunneling](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html) Service to connect a destination or a source Secure Tunnel Client to an AWS Secure Tunnel endpoint using access tokens using the [V3WebSocketProtocol](https://github.com/aws-samples/aws-iot-securetunneling-localproxy/blob/main/V3WebSocketProtocolGuide.md). For more information, see the [Secure Tunnel Userguide](../../../documents/Secure_Tunnel_Userguide.md)
 
+## How to build
+
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/others/secure_tunneling/secure_tunnel/build` folder.
+```sh
+cd samples/others/secure_tunneling/secure_tunnel/
+# If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
+cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-workspace dir>" -DCMAKE_BUILD_TYPE="Debug" .
+cmake --build build --config "Debug"
+```
+
 ## How to run
 
 Create a new secure tunnel in the AWS IoT console (https://console.aws.amazon.com/iot/) (AWS IoT/Manage/Tunnels/Create tunnel) and retrieve the destination and source access tokens. (https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling-tutorial-open-tunnel.html). Once you have these tokens, you are ready to open a secure tunnel.
 
 ### Destination Mode
 
-To run the sample with a destination access token in destination mode (default), you can use the following command:
+To run the sample with a destination access token in destination mode (default), navigate to the build directory where the executable was created:
 
-``` sh
+```sh
+# From samples/others/secure_tunneling/secure_tunnel/, go to the build directory
+cd build
 ./secure-tunnel --signing_region <signing_region> --access_token_file <path to destination access token>
 ```
 
@@ -22,7 +34,9 @@ The sample will create a Secure Tunnel connection and remain connected in `DESTI
 
 While the focus of the Secure Tunnel Client for the IoT Device SDK is to connect with Secure Tunnels in `DESTINATION MODE` we also support connecting in `SOURCE MODE`. The token file should be the Source Token in this instance and you must add the `--local_proxy_mode_source` flag:
 
-``` sh
+```sh
+# From samples/others/secure_tunneling/secure_tunnel/, go to the build directory
+cd build
 ./secure-tunnel --signing_region <signing_region> --access_token_file <path to source access token> --local_proxy_mode_source
 ```
 

samples/others/secure_tunneling/tunnel_notification/README.md

@@ -1,6 +1,6 @@
 # Secure Tunnel Notification
 
-[**Return to main sample list**](../../README.md)
+[**Return to main sample list**](../../../README.md)
 
 This sample uses an MQTT Client and the AWS IoT [Secure Tunneling](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html) Service to receive a tunnel notification and then connects to the Secure Tunnel using a Secure Tunnel Client.
 
@@ -57,9 +57,23 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 </details>
 
+## How to build
+
+To build the sample, change directory into the sample's folder and run the cmake commands. The sample executable will be built into the `samples/others/secure_tunneling/tunnel_notification/build` folder.
+```sh
+cd samples/others/secure_tunneling/tunnel_notification/
+# If you followed the SDK build instruction, you would use the path to `sdk-workspace` folder for `CMAKE_PREFIX_PATH` here
+cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-workspace dir>" -DCMAKE_BUILD_TYPE="Debug" .
+cmake --build build --config "Debug"
+```
+
 ## How to run
-To Run this sample, use the following command:
-``` sh
+
+To run this sample, navigate to the build directory where the executable was created:
+
+```sh
+# From samples/others/secure_tunneling/tunnel_notification/, go to the build directory
+cd build
 ./tunnel-notification --endpoint <endpoint> --cert <path to the certificate> --key <path to the private key> --thing_name <thing name>
 ```
 Once the MQTT Client is connected, create a new secure tunnel in the AWS IoT console (https://console.aws.amazon.com/iot/) (AWS IoT/Manage/Tunnels/Create tunnel) for the Thing.