resource_index.md does not explain what a resource is about ament_cmake HOT 5 CLOSED

Please link to documents when you refer to them: https://github.com/ament/ament_cmake/blob/master/ament_cmake_core/doc/resource_index.md

I thought that the purpose was fairly clearly stated:

The queries might be anything from "Which packages are installed?" to "Which packages provide plugins of a certain type?". This project does not aim to catalog and explicitly reference all individual resources, but rather to provide meta information about what resources are provided by what packages and then providing absolute paths to the prefix containing the package.

So the idea is that packages provide resources, where a resource is something like a package.xml or a launch file or message definitions or a plugin for a particular part of the system. It doesn't catalog the resources, but merely is used to narrow down the scope when looking for packages which provide certain resources. What ever definition you have for resource has no bearing on that document, and you should interpret it as such.

You also mention the capitalized Process as if it means something in general. I don't know what you're referring to by "Process". Our use of the word resource is not related to any CMMI or formal design process, but rather the general term defined as "a stock or supply of money, materials, staff, and other assets that can be drawn on by a person or organization in order to function effectively." where we probably fit in the term "asset". I'd define it in our scope as a "any asset or functionality provided by a single package which should be advertised to other packages and tools", or something along those lines.

If you have a concrete idea how this could be clarified, please open a pull request.

from ament_cmake.

Hi William,

By Process i meant a CMMI approved process for software development. The resources being indexed are related to software development process, and the ament articles are defining a software development process. They place requirements and restrictions on the structure of the source code.

While the article lists requirements for how the indexer should work, but it does not list requirements for why the indexer is necessary. It may be that to you all it is clearer because you have "tribal knowledge" of the build system which I do not. I am not as experienced in ros as you all are, and there is an increasing interest from other 3rd parties who also lack that experience. I run into the same problem all the time when I write documentation, which I think is perfectly clear but others disagree.

At this point in the post I had a very long explanation of CMMI Things and Stuff. After re-reading the articles a dozen times, Things and Stuff has been cut. Let me know if the following are valid (in which case I might have enough context to do a pull request):

• "we want to have well defined file system locations for installing files, because the FHS is a good idea and we now require everything to be installed before it can be run (link to ament main article)"
• "these well defined locations in turn simplify other tools. for example. rostopic will always be able to find .msg definitions (and perhaps autogenerate them so Bob can stop sending nasty emails to grad students who only send binaries)"
• "we want this because we want you, the developer, to know what's going on with an 'ls' command"
• "we, OSRF + community, will define a default set of these locations for core resources through the REP process. Examples of potential locations are:"
  • i.e. all messages go to /opt/ros2/alpha/msgs/<package_name>/*.msg
  • all rviz plugin files go to /opt/ros2/alpha/share/rviz/plugins/lib and plugins/xml
  • alternatively rviz plugin.xml files to to /opt/ros2/alpha/share/rviz and rviz plugins will use the naming convention lib<plugin_name>_rviz_plugin.so. (ls /opt/ros2/alpha/lib | grep "*rviz_plugin")

Also, why is there the additional requirement of ament_index/resource_index in the path? why not just /share/msgs, or to keep it separate /resource_share/msgs instead of /share/ament_index/resource_index/msgs? ament_index implies that only ament can be used to build the system. For example, if a company has an established build system may be easier/cheaper to update it to install to the common locations versus switching to use ament for internal development.

from ament_cmake.

Yes we follow FHS, but that is unrelated to the ament resource index.

A known layout (e.g. for message definitions) allows tools to find them. But even with a known layout a tool would need to crawl all subfolders of share and look for subfolders like msg to find .msg files in there. The ament resource index provides a way to "register" a resource (e.g. the existance of a .msg file) at install time. At runtime tools can query information like "what messages does package foo have?" without requiring to crawl the file system.

The user could use ls but there is also a C++ and Python API to query the index: https://github.com/ament/ament_index

A few resources will very likely be "official". But basically every package can define such a resource type and document it accordingly. E.g. rviz can decide that without requiring a global REP.

Currently the index is created in a known (not changeable) location. While we could allow a custom location that would also imply that every lookup needs to be aware of that custom location.

from ament_cmake.

"we want to have well defined file system locations for installing files, because the FHS is a good idea and we now require everything to be installed before it can be run (link to ament main article)"

I would consider having an installation step and installing to an FHS layout to be prerequisites of this pattern.

"these well defined locations in turn simplify other tools. for example. rostopic will always be able to find .msg definitions (and perhaps autogenerate them so Bob can stop sending nasty emails to grad students who only send binaries)"

This pattern of indexing doesn't tell rostopic where the message files are, just which packages have them. It is out of the scope of this index and this pattern to describe exact locations of things. As the document points out these files are usually in a relative location from the index files themselves since it is in an FHS layout. This document has no bearing on distribution or or generation of msg files. I'm not sure what you expect this pattern or document to cover with respect to that topic.

"we want this because we want you, the developer, to know what's going on with an 'ls' command"

I don't think that's the point, I think the point is that the "look up" mechanism is so simple that it could be accomplished with a single ls command per prefix. Not to imply that users will be manually ls's directories to learn about the installed packages. Being simple to add to the index and simple (and efficient) to query the index was a design goal.

"we, OSRF + community, will define a default set of these locations for core resources through the REP process. Examples of potential locations are:"

Those are out of the scope of this document and pattern. This pattern is just a tool which can be used in conjunction with conventions about where to put files and what is in them. Things like where .msg files are installed and what is in them or how you indicate to rviz that your package provides a plugin for it is to be defined elsewhere. They are merely mentioned to give context and examples to this document.

from ament_cmake.

With the recent changes in #100 I will close this. If you think more information would be helpful please feel free to contribute a PR.

from ament_cmake.