Add autoware_ament_auto_package() macro to maintain Autoware's include structure

[youtalk]

Checklist

• I've read the contribution guidelines.
• I've searched other issues and no duplicate issues were found.
• I've agreed with the maintainers that I can plan this task.

Description

Add a new autoware_ament_auto_package() CMake macro to autoware_cmake that maintains Autoware's include structure (autoware/<module>/) across ROS 2 Humble, Jazzy, and Kilted+, eliminating deprecation warnings while preserving compatibility with Autoware's naming conventions.

Purpose

Starting with ROS 2 Kilted, ament_auto_package() will change its default behavior to install headers to include/${PROJECT_NAME}/ instead of include/. This creates a conflict with Autoware's naming convention:

• Autoware package names: autoware_<module> (e.g., autoware_interpolation)
• Autoware include paths: autoware/<module>/ (e.g., #include "autoware/interpolation/...")

With the new ROS 2 Kilted behavior, headers would be installed to:

include/autoware_interpolation/autoware/interpolation/  ❌ (incorrect duplication)

Instead of the intended:

include/autoware/interpolation/  ✅ (correct Autoware structure)

Currently, packages using ament_auto_package() with include directories generate deprecation warnings:

CMake Warning at /opt/ros/humble/share/ament_cmake_auto/cmake/ament_auto_package.cmake:41 (message):
  Package 'autoware_interpolation' installs the include directory
  'include' but it is not under 'include/autoware_interpolation'.

The purpose of this task is to provide a centralized solution in autoware_cmake that:

1. Eliminates these warnings across all Autoware packages
2. Ensures future compatibility with ROS 2 Kilted
3. Maintains Autoware's established include structure conventions
4. Enables gradual adoption across Autoware projects

Possible approaches

Approach A: Add autoware_ament_auto_package() macro to autoware_cmake (Recommended)

Implementation: Create a new autoware_ament_auto_package() macro that replicates ament_auto_package() functionality while explicitly installing headers to include/ destination.

Advantages:

• Centralized solution available to all Autoware packages
• Drop-in replacement for ament_auto_package()
• Gradual adoption possible (warnings don't break builds in Humble)
• Future-proof for ROS 2 Kilted

Code location: autoware_cmake/cmake/autoware_ament_auto_package.cmake

Usage example:

find_package(autoware_cmake REQUIRED)
autoware_package()

# ... library/executable definitions ...

autoware_ament_auto_package()  # Instead of ament_auto_package()

Approach B: Use USE_SCOPED_HEADER_INSTALL_DIR flag

Implementation: Add USE_SCOPED_HEADER_INSTALL_DIR flag to autoware_package() and continue using ament_auto_package().

Disadvantages:

• Would create include/autoware_interpolation/ structure, breaking #include "autoware/interpolation/..." includes
• Requires changing all include statements across the codebase
• Breaks Autoware's established naming convention

Not recommended.

Definition of done

• autoware_ament_auto_package() macro added to autoware_cmake
• Macro replicates all ament_auto_package() functionality:
  • Export build/run dependencies
  • Install headers to include/ (maintaining Autoware structure)
  • Export and install libraries
  • Install executables
  • Support INSTALL_TO_PATH and INSTALL_TO_SHARE parameters
• Documentation updated with usage instructions
• Example added showing migration from ament_auto_package() to autoware_ament_auto_package()
• Tested on at least one package from autoware_core
• CI passes
• Release notes updated