[Documentation] [TitleIndex] [WordIndex

API review

Proposer: kwc

Present at review:

Proposal

I did a quick survey at dinner to see what was most pressing for ROS 1.2, and roslaunch vars seems up there. I'd like to get a start on this ASAP, so the proposal is below. It's largely based on experience with ant properties.

  1. $(arg foo) substitution arg

    $(arg foo) evaluates to the value specified by an <arg> tag. There must be a corresponding <arg> tag for a $(arg) usage. If an $(arg) fails to resolve, an error is printed the user, similar to the error with unresolved $(env) values.

  2. <arg> tag

    There are three ways an <arg> can be declared:

    • <arg name="foo" />

      • Declares the existence of foo. foo must be passed in either as a command-line argument (if top-level) or via <include> passing (if included).

      <arg name="foo" default="1" />

      • Declares foo with a default value. foo can be overriden by command-line argument (if top-level) or via <include> passing (if included).

      <arg name="foo" value="bar" />

      • Declares foo with constant value. The value for foo cannot be overridden. This usage enables internal parameterization of a launch file without exposing that parameterization at higher levels.

    With the exception of <arg> tags inside of <include> tags (see next), <arg> tag has no effect outside of the file it is declared in.

  3. arg passing in <include>

    An include tag can include <arg> tags, which are passed into the included file. These <args> are evaluated according to the rules specified above. If an included file refers to an arg that has an unset value, this is a fatal error, e.g.: "roslaunch file foo.launch requires the argument 'robot' to be set."

    <include file="blah">
      <!-- all vars that blah requires must be set -->
      <arg name="hoge" value="fuga" />
    </include>
  4. if and unless attributes

    With args in place, a powerful extension is 'if' and 'unless' attributes for all tags. This will include/exclude a tag based on the evaluation of a value. This exercises the power of args more strongly as a single launch file can organize multiple configurations more easily. (already implemented)

    <group if="$(arg foo)">
    </group>
    <param name="foo" value="bar" unless="$(arg foo)" />

Proposal Updates

Removed location attribute option for <arg>

Removed $(arg bar DEFAULT) syntax as this leads to confusion of conflicting default values in use.

Added <arg name="foo" default="value" /> as replacement for $(arg bar DEFAULT). More declarative, more human-readable.

Analysis

This proposal conflates the idea of command-line arguments and roslaunch-declared variables/properties. I originally wrote these up as separate <var> and <arg> tags.

This proposal also takes a more functional approach to the args, i.e. each launch file is viewed as a separate entity that takes in args and spits back a configuration. This is in contrast to a more global dictionary of args, in which each launch file is acting against a global arg space that is being written to by the aggregate files.

It's possible to migrate to a global model by adding namespace rules to the args, e.g. if an include/group tags set a namespace, the arg names are resolved against it. This means that higher-level files can "dig down" and pull out parameter settings from included files. I discussed this with jfaust and we agreed it was powerful, but that it's dangerous and limits the easy composition of the files. In a global model, it's much easier to break the entire file with an accidental arg conflict, aliasing, or any other sort of naming issue on a larger scale. My general experience with feature requests with roslaunch is that people generally doesn't understand the entirety of the larger launch files we deal with, and this would only exacerbate this by increasing the scope of parameterization.

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Bhaskara

Roland

kwc

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Conclusion

Package status change mark change manifest)



2022-05-28 12:35