Provide better examples for .meta files

[Ryanf55]

I have a bunch of packages that have CMake options exposed. Some are package-specific, but are in upstream repos that don't want to change defaults.

When building in colcon, there is support for changing the behavior of packages from the colcon root, but the docs do not explain how to use it very well.

Can you provide a more complete example in the docs for a use case like this:

src/
   pkgA/
   pkgB/
   pkgC/
.my_example.meta

I want to turn

• BUILD_TESTING=OFF on pkgA because its tests take forever to compile and it's slow, but leave it as default (on) in the others
• PACKAGE_B_CUSTOM1=42 only affecting pkgB

If you try setting CMake args for these for the entire build, there is no fine grained control.

It would be very helpful for the docs to include a sample my_example.meta

Thanks for the consideration!

[leorich]

This may extend the issue a bit, but its related enough I opted to comment here.

There are several ways to affect colcon config:

• colcon.pkg files
• colcon.meta
• defaults.yaml
• cli args

I would love to see the order of precedence (ie what configs override other configs).

It would also be helpful to document if args are appended to existing args, or if existing args are overwritten.