======
rtcomp
======

---------------------------
manage composite components
---------------------------

.. include:: ../common/docinfo_block.txt

Synopsis
========

rtcomp [options] <manager[:name]|composite component path>

Description
===========

Composes multiple components into a single composite component, exposing
a selection of their ports externally. A new composition can be created
or an existing composition edited. New members can be added to  and
members removed from existing compositions, and the exported ports list
can be changed. The type of composition to create can be specified.

The required option is either the path to an existing composition to
edit, or the path to a manager to create the composition in. If a
manager is specified, a name for the new composition can be specified,
separated from the manager path by a colon. If a name is not specified,
a default name will be chosen. See the Examples_ section for examples.

When specifying components to add or remove, a list of ports to export
or hide can be specified after the component path, separated from the
path by a colon. The ports in the list should be comma-separated. See
the Examples_ section for examples.

Options
=======

-a ADD, --add=ADD
  A component to include in the composition. Specify a comma-separated
  list of ports to export after the component name, separated by a
  colon.

-o OPTIONS, --options=OPTIONS
  Extra options to pass to the component on creation.

-r REMOVE, --remove=REMOVE
  A component or ports to remove from the composition.

-t TYPE, --type=TYPE
  Type of composite component to create. [Default:
  PeriodicECSharedComposite]

.. include:: ../common/common_opts.txt

.. include:: ../common/common_body.txt

Examples
========

::

  $ rtcomp /localhost/manager.mgr:MotorUnit -a
  /localhost/Motor0.rtc:out -a /localhost/Controller0.rtc:in,out

Create a composite component using the ``Motor0.rtc`` and
``Controller0.rtc`` components, exposing the ``in`` and ``out`` ports of
``Controller0.rtc`` and the ``out`` port of ``Motor0.rtc``. The
component's instance name will be ``MotorUnit``.

::

  $ rtcomp /localhost/MotorUnit.rtc -a /localhost/Sensor0.rtc:out

Edit the existing ``MotorUnit.rtc`` composite component, adding the
``Sensor0.rtc`` component as a new user and exporting its ``out`` port.

::

  $ rtcomp /localhost/MotorUnit.rtc -a /localhost/Sensor0.rtc:in

Edit the existing ``MotorUnit.rtc``, which already contains
``Sensor0.rtc`` as a member, to export the ``in`` port of
``Sensor0.rtc``.

::

  $ rtcomp /localhost/MotorUnit.rtc -r /localhost/Sensor0.rtc:out

Edit the existing ``MotorUnit.rtc``, which already contains
``Sensor0.rtc`` as a member, to hide the ``out`` port of
``Sensor0.rtc``.

::

  $ rtcomp /localhost/MotorUnit.rtc -r /localhost/Controller0.rtc:in,out

Edit the existing ``MotorUnit.rtc``, which already contains
``Controller0.rtc`` as a member, to hide the ``in`` and ``out`` ports of
``Controller0.rtc``.

::

  $ rtcomp /localhost/MotorUnit.rtc -r /localhost/Controller0.rtc -r
  /localhost/Motor0.rtc

Edit the existing ``MotorUnit.rtc``, which already contains
``Controller0.rtc`` and ``Motor0.rtc`` as a members, to remove them from
the composition.


See Also
========

``rtmgr`` (1)

