API review

Proposer: Tully Foote

Present at review:

• Jack O’Quin
• Shawn Edwards
• Jonathan Bohren
• Thibault Kruse
• Daniel Stonier
• Lorenz Mösenlechner
• Andy Somerville
• Tully Foote
• Dirk Thomas

This page lists the notes taken during a teleconference on 14.08.2012

Notes from Google Doc

Packages and Packaging

1. ROS packages are packaged individually in Linux packages, no more ROS stacks
   1. General decision
      1. Consensus is to package packages.
   2. Joined/separate versioning of multiple packages per repository
      1. In DVCS packages in the same repository are expected to level together, will write a tool to help with this
      2. Add a tool which levels multiple packages, (possibly in different repositories), together from a dependency list or meta-package dependency.
   3. Meta-data per package?
      1. Bugtracker URL
         1. Need a machine readable location.
         2. Might want more than just a url, component, version
         3. tool ros-report-bug package_name (introspect current version) opens url, email maintainer if tracker is not declared.
         4. put it into the manifest to support private repos
      2. Status (like maintained or orphaned) must be editable even without write access to the repo.
      3. bloom warn on missing maintainer field
      4. deprecate review field in manifest
   4. Release process
      1. Version number in distro.yaml requires pull request for leveling it, but it allows rollback without repo access and defines exact set of ROS packages
         1. Bloom should generate pull requests for leveling the version number in the distro.yaml
         2. Look at a tool for adding the urls for first release.
2. Meta packages (vs.) variants
   1. What aspect should they cover / what not?
   2. One generalized concept or different things necessary?
   3. What information is stored and where?
   4. How can we maintain the utility of current ROS Stacks?
      1. Issues discussed:
         1. duplication of effort of maintaining metadata in standalone packages
         2. possibly collect information at the repository level
         3. Location for package-group related files, like xyz.rosinstall, roslaunch files, tutorials, install instructions
         4. Nobody is responsible for maintaining meta-package data (e.g. when a package is split up into two, or renamed)
         5. If package-group related resources exist, it is difficult to find them from a package wiki site, if the package links to several meta-packages. Adding the same information to all package wiki pages is cumbersome (and no solution for packages without wiki page)
         6. possibly a tool to propagate meta information to a set of packages
      2. Possibly just a package with a simple flag?
         1. Renders differently on the wiki
         2. bloom has an option to processes dependencies automatically, with prompt for each subpackage that is not another stack
         3. Try implementing it with stacks as empty packages, prove if flag is necessary.
      3. Variants are too ephemeral probably should be deprecated.
   5. Effects on the ROS wiki
      1. Package/Stack/Variant header
         1. Maintain a flat namespace
            1. could use prepended strings conventions if necessary in the future but not now
            2. possibly a guideline/convention for using a ros prefix on library names
      2. How does the new concept map to the current content? Pending meta-package decision
         1. We will need a stack like entity to maintain consistency with wiki pages.
         2. Keeping the stack name for whatever meta-package we choose would be good for continuity
      3. Standard Changelist location/format in repo
         1. it would be good to have an automatic way to collect package changelogs into a meta-package changelog entry
         2. General support
3. Separation of src, dev, runtime, dbg and doc packages
   1. Does not require any additional information, just tools to do it
      1. For doc, use doc subdirectory.
      2. There are more complications, but they are usually handled at packaging time. (Feature request for bloom)
4. External private debian build infrastructure.
   1. Partially tested, definitely a requirement. Need better documentation.

Building

1. Catkin
   1. more standard conformant: find_package(), pkg-config, etc.
   2. Differences between catkin in Fuerte and Groovy
      1. better FHS compliance
      2. buildspace supported the same as a installspace
   3. Need very good documentation of how to migrate!
2. Global vs. local buildfolder (vs. multiple workspaces) (1 vs n CMake instantiations)
   1. keep binaries in package-separate folder

      1. FHS 3.0 draft 1 http://www.linuxbase.org/betaspecs/fhs/fhs.html#usrlibexec gives two options for “internal” binaries:

         1. lib/PKGNAME
         2. libexec/PKGNAME (not used on i.e. Ubuntu)
   2. if binary names collide the target name needs to be prefixed (while keeping the binary name)
   3. Support single workspace
      1. Document guidelines for good practices how to avoid conflicts
         1. CACHED variables- prefix with package name
         2. no usages of globals
         3. Make sure examples follow all good practices
         4. Add a build target for each package. (Probably need a macro at the end of a CMakeLists.txt)
         5. Look at adding a custom target generator to de-conflict executables
         6. Concerns about confusion of side effects of shared build space for non expert users.
            1. We can mitigate this by making sure that roscreate-pkg provides a comprehensive template.
            2. Users creating just one node will likely not be a problem.

3. Uninstall target : http://www.cmake.org/Wiki/CMake_FAQ#Can_I_do_.22make_uninstall.22_with_CMake.3F

   1. Do a best effort, and document the shortcomings clearly.
      1. would need an install target to uninstall based on an installed file manifest first to be robust to updates.
4. Effects for the user and necessary tools
   1. All toolchain need to be upgraded
      1. rospkg, rosinstall, resource manager, bloom, buildfarm, indexer. ...
5. Workspace assistants
   1. Such as roscreate, rosmake etc.

   2. Add a utility for calling mkdir build && cd build && cmake .. && make

      1. Some simple options as args, e.g. debug/release
   3. roscd allow options for alternate directories --bin --lib --share, with --share default
   4. rosfind (given target and package) return folder containing
   5. rosdep will walk source tree, confirm working with new packaging
6. Building 3rd party dependencies integration as packages. Things not available as system installations.
   1. Issue is how to support build and install space
   2. Integration with CMake external project module?
   3. standard procedure for a custom installation path in source directory, support only build space
   4. leverage rosdep sourcerosdep for non supported platforms if required to install
   5. support installation via custom debians

Milestones, Outlook

1. What needs to be done in which order?
   1. How does it affect the roadmap of Groovy?
      1. land workspace changes this week
      2. convert wet next week
2. Decide which functionality/changes go into Groovy, Hydro (and optionally Groovy when implemented in time)
   1. ABI version?
   2. Versioned dependencies?
      1. Target simple version of versioned dependencies (only minimum versions)
      2. Make tool for synchronized releases have an argument to require the latest version of the other packages.
      3. Future discussion, when we have a clear picture we can approach the implementation of that
3. What is planned to be catkin-ized for Groovy?

   1. Currently 55 of 282 released stacks http://jenkins.willowgarage.com:8080/job/fuerte-status/11853/console

   2. how do we remove them from http://debbuild/groovy.html once catkinized ?

   3. priorities pluginlib, nodelets
   4. bottom up, do our best, should be transparent to users
4. Future support for dry stuff
   1. rosmake
   2. Build farm: prereleases and building Debian packages
   3. Wiki integration

Process:

Keep this under 2 hours.  Requires <8 minutes per topic on the agenda.  

Proposed Process:
- 1 minute summary of mailing list discussions with proposed solution.  
  - If there’s no objections ratify and move on. 
  - Else: Participants can have 1 minute to propose an alternate solution.  At the end of that we can vote +1 style on the original or proposed alternative.  If after 10 minutes we will table any specific subtopic and return to it at the end for another 10 minutes.  

Package status change mark change manifest)

• Action items that need to be taken.

• Major issues that need to be resolved

---