recommends

Required: No
Type: List of component references
Condition: Partial (no unless)

Components can provide hints about other recommended components to the rest of the project. During project resolution, it is possible that a requirement cannot be satisfied because multiple components provide an implementation. If any of the components already present in the project recommends a specific implementation, this component shall be selected for inclusion. The list of recommends is only used to resolve unsatisfied requirements after project resolution has failed produce a complete project using only provides/requires/recommends.

If multiple conflicting implementations are recommended, the choice must be given to the user in the same way as if nothing was recommended, but the recommended implementations can be highlighted. If the recommended implementation is instantiable, all instances in the instance list of the recommendation are added to the project. If multiple components recommend different instances of the same component to fulfill a requirement, the choice of which instances to add must be given to the user in the same way as when components recommend different components to fulfil the requirement.

Key	Required	Type	Description
id	Yes	String	ID of the recommended component
instance	If component is instantiable	List of strings	List of instance names. Subject to instance naming restrictions /[A-Za-z0-9_]+/, since instance names must be usable as C/C++ symbols.
condition	No	List of features	The recommendation is considered if all the given features are present
vendor	No	String	The vendor of the SDK extension the component is from. Only the vendors listed under extension/vendor or sdk/vendor key may be used.
package	No	String	The ID of the SDK extension the component is from. Only SDK extensions listed using the extension/id or sdk/id key may be used.

The id, package, and vendor fields together form a component reference. For details on what a component reference is, and how the package and vendor fields affect resolution, see the component reference.

When an instantiable component has been added to the project due to being recommended, GUI tools are recommended to recognize if the user adds more instances of the component, effectively making it explicitly selected, which removes the recommendation and thus the instance that was automatically added. In this case, the GUI tool should either prompt the user whether they want to preserve the previously automatically-added instance as an explicit instance in the project, or automatically elevate it to an explicit instance without prompt.

Examples

Basic Example (Fully Implicit)

---
# A simple UART component that provides iostream_transport
id: iostream_usart
provides:
  - name: iostream_transport

---
# A board configuration component that recommends using UART for iostream
id: board_config
recommends:
  - id: iostream_usart
    instance: [vcom]

---
# The iostream component that needs a transport
id: iostream
requires:
  - name: iostream_transport

In the above example, if a project includes the iostream component, which requires iostream_transport, the dependency resolver will look for available implementations of iostream_transport. Since the board_config component recommends iostream_usart with the instance name vcom, this recommendation will guide the resolver to select iostream_usart as the appropriate implementation.

Because this recommendation is fully implicit — meaning it does not specify a particular package or vendor — the resolver is restricted to choose the implementation of iostream_usart only from the containing package.

Cross-Extension Example

---
# From vendor: silabs, package: bluetooth_stack
id: ble_connection
provides:
  - name: bluetooth_connection
requires:
  - name: led_indicator
---
# From vendor: silabs, package: platform_common
id: rgb_led
provides:
  - name: led_indicator
  - name: rgb_led
---
# From vendor: partner_company, package: custom_drivers
id: advanced_rgb
provides:
  - name: led_indicator
  - name: rgb_led
---
# From vendor: silabs, package: bluetooth_stack
id: connection_preferences
recommends:
  # Fully qualified reference to ensure specific implementation
  - id: rgb_led
    package: platform_common
    vendor: silabs
---
# From vendor: partner_company, package: custom_drivers
id: custom_preferences
recommends:
  # Package-specific reference to ensure implementation from custom_drivers
  - id: advanced_rgb
    package: custom_drivers

When a project includes the ble_connection component, which requires led_indicator, the resolver determines the appropriate implementation based on component-specific preferences. If connection_preferences is present, the resolver selects rgb_led from Silicon Labs' platform_common package. If custom_preferences is present instead, the resolver selects advanced_rgb from the custom_drivers package.

In the absence of either preference component, the resolver cannot infer a preferred implementation and prompts the user to choose among basic_led, rgb_led, or advanced_rgb. When both connection_preferences and custom_preferences are present, the resolver identifies a conflict between competing recommendations and requires the user to manually resolve it by selecting the appropriate led_indicator implementation.