Improve message generation tutorial and example

CMakeLists.txt

@@ -173,6 +173,7 @@ configure_file(${CMAKE_SOURCE_DIR}/tutorials.md.in ${CMAKE_BINARY_DIR}/tutorials
 gz_create_docs(
   API_MAINPAGE_MD "${CMAKE_BINARY_DIR}/api.md"
   TUTORIALS_MAINPAGE_MD "${CMAKE_BINARY_DIR}/tutorials.md"
+  IMAGE_PATH_DIRS "${CMAKE_SOURCE_DIR}/tutorials/files"
   TAGFILES
     "${GZ-MATH_DOXYGEN_TAGFILE} = ${GZ-MATH_API_URL}"
 )

examples/generating_custom_msgs/CMakeLists.txt

@@ -15,7 +15,10 @@ set(GZ_MSGS_VER ${gz-msgs10_VERSION_MAJOR})
 
 # Example of custom messages that depend on gz.msgs
 set(MSGS_PROTOS
-   ${CMAKE_CURRENT_SOURCE_DIR}/proto/gz/custom_msgs/vector3d.proto)
+   ${CMAKE_CURRENT_SOURCE_DIR}/proto/gz/custom_msgs/foo.proto
+   ${CMAKE_CURRENT_SOURCE_DIR}/proto/gz/custom_msgs/bar.proto
+   ${CMAKE_CURRENT_SOURCE_DIR}/proto/gz/custom_msgs/baz.proto
+)
 
 gz_msgs_generate_messages(
   # The cmake target to be generated for libraries/executables to link
@@ -32,7 +35,6 @@ gz_msgs_generate_messages(
 
 add_executable(${PROJECT_NAME} main.cc)
 
-# Automatically uses whole-archive linking to get all the messages available
 target_link_libraries(${PROJECT_NAME} PUBLIC ${PROJECT_NAME}-msgs)
 
 install(TARGETS ${PROJECT_NAME}

examples/generating_custom_msgs/README.md

@@ -57,10 +57,3 @@ gz_msgs_generate_messages(
   # List of message targets this library imports from
   DEPENDENCIES gz_msgs_gen)
 ```
-
-Be sure to link all dependent message targets:
-
-```
-# Automatically uses whole-archive linking to get all the messages available
-target_link_messages(TARGET ${PROJECT_NAME} PUBLIC MSG_TARGETS custom_msgs_gen gz_msgs_gen)
-```

examples/generating_custom_msgs/main.cc

@@ -1,34 +1,68 @@
-#include <gz/msgs/vector3d.pb.h>
-#include <gz/custom_msgs/vector3d.pb.h>
+#include <gz/custom_msgs/foo.pb.h>
+#include <gz/custom_msgs/bar.pb.h>
+#include <gz/custom_msgs/baz.pb.h>
 
 #include <google/protobuf/text_format.h>
 
 // A simple example that demonstrates the use of the message factory
 //
-// Usage:
-// Print text description of original and custom Vector3d msgs.
 //   ./generating_custom_messages
 int main(int argc, char** argv)
 {
   (void) argc;
   (void) argv;
-  // Print the text description of the original message
-  gz::msgs::Vector3d original;
+
+  gz::custom_msgs::BazStamped msg;
+
+  // msg has header and baz field
+  auto *header = msg.mutable_header();
+  auto *baz = msg.mutable_baz();
+
   {
-    auto descriptor = original.GetDescriptor();
-    auto fileDescriptor = descriptor->file();
-    std::cout << "Name: " << descriptor->full_name() << std::endl;
-    std::cout << "File: " << fileDescriptor->name() << std::endl << std::endl;
-    std::cout << descriptor->DebugString() << std::endl;
+    // Populate the header with something
+    header->mutable_stamp()->set_sec(100);
+    header->mutable_stamp()->set_nsec(100);
+  }
+
+  {
+    // Add a frame_id to the header
+    auto map_entry = header->add_data();
+    map_entry->set_key("frame_id");
+    map_entry->add_value("gz_custom_msgs");
   }
 
-  // Print the text description of the custom message
-  gz::custom_msgs::Vector3d custom;
   {
-    auto descriptor = custom.GetDescriptor();
+    // Add an arbitrary array value to the header
+    auto map_entry = header->add_data();
+    map_entry->set_key("array");
+    map_entry->add_value("a");
+    map_entry->add_value("b");
+    map_entry->add_value("c");
+  }
+
+  // baz has foo and bar field;
+  auto *foo = baz->mutable_foo();
+  auto *bar = baz->mutable_bar();
+
+  {
+    // Set the values of our custom sub-messges
+    foo->set_value(1.0);
+    bar->set_value(1.0);
+  }
+
+  {
+    // Print the text descriptor of a message
+    auto descriptor = msg.GetDescriptor();
     auto fileDescriptor = descriptor->file();
+    std::cout << "Message definition: " << std::endl;
     std::cout << "Name: " << descriptor->full_name() << std::endl;
     std::cout << "File: " << fileDescriptor->name() << std::endl << std::endl;
     std::cout << descriptor->DebugString() << std::endl;
   }
+
+  {
+    // Print the populated values of a message
+    std::cout << "===============================" << std::endl;
+    std::cout << "Pouplated Message: \n" << msg.DebugString() << std::endl;
+  }
 }

examples/generating_custom_msgs/proto/gz/custom_msgs/bar.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+package gz.custom_msgs;
+
+import "gz/msgs/header.proto";
+
+message Bar
+{
+  double value = 1;
+}
+
+message BarStamped
+{
+  gz.msgs.Header header = 1;
+  gz.custom_msgs.Bar bar = 2;
+}

examples/generating_custom_msgs/proto/gz/custom_msgs/baz.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+package gz.custom_msgs;
+
+import "gz/msgs/header.proto";
+
+import "gz/custom_msgs/foo.proto";
+import "gz/custom_msgs/bar.proto";
+
+message Baz
+{
+  gz.custom_msgs.Foo foo = 1;
+  gz.custom_msgs.Bar bar = 2;
+}
+
+message BazStamped
+{
+  gz.msgs.Header header = 1;
+  gz.custom_msgs.Baz baz = 2;
+}

examples/generating_custom_msgs/proto/gz/custom_msgs/foo.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+package gz.custom_msgs;
+
+import "gz/msgs/header.proto";
+
+message Foo
+{
+  double value = 1;
+}
+
+message FooStamped
+{
+  gz.msgs.Header header = 1;
+  gz.custom_msgs.Foo foo = 2;
+}

tutorials.md.in

@@ -8,6 +8,7 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 
 1. \subpage install "Installation"
 2. \subpage cppgetstarted "C++ Get Started"
+3. \subpage messagegeneration "Message Generation"
 
 ## License