Simplify BSP Maintenance with YML Files!

Problem
Currently, the CI (Continuous Integration) system in the RT-Thread repository primarily checks the BSP (Board Support Package) for basic GPIO and UART compilation configurations. This limitation may result in certain .c files not being detected, potentially causing compilation issues during system updates. By adding YML files to the BSP, we can expand the CI system to compile additional configurations, ensuring more comprehensive code coverage during the build process.

Benefits of Introducing YML Files:

1. Readability and Ease of Use: YML files use a simple and clear format that is close to human language, making them easy to read and understand. Even non-technical users can easily edit them.
2. Centralized Management: YML files allow for all configuration options to be managed in one place, simplifying updates and reducing the risk of errors caused by scattered management.
3. Version Control Friendly: As text files, YML files can be easily integrated with version control systems like Git. This allows tracking of configuration changes and makes it easy to revert to previous versions if needed.
4. Strong Extensibility: With a well-structured format, YML files support nested configurations, making them suitable for describing complex setups. They are also easy to extend to meet new requirements.
5. Automated Integration: YML configuration files can seamlessly integrate with CI/CD tools, enabling automated build, test, and deployment processes, ensuring consistency across different environments.

The main content of the YML file is as follows:

Introduction
In our RT-Thread repository, the CI checks for BSPs already cover the majority of them. All configuration settings are centralized in the .github/workflows/bsp_buildings.yml file. When a new BSP is submitted, the relevant configuration can simply be added to this YML file. This process has been applied to over 300 BSPs, and every Pull Request (PR) automatically triggers the corresponding checks.

Here’s a sample of the content from the bsp_buildings.yml file:

Previously, there was an article on the forum explaining how to use “attach” files to expand the scope of CI checks. The current goal is essentially the same: to have CI detect more configurations and compile more .c files. Additionally, users can upload their own commonly used configurations for reuse. You can search for the keyword “attach” on the RT-Thread forum to check out the article.

Attach:
This can be roughly understood as different config options provided to CI for compilation checks.

YML File
We’ve introduced a YML file that includes all the configurations, making it easier to manage and update. This method serves the same purpose as the attach file functionality, but using a YML file is more manageable and easier to edit. The attached file method is still supported, so both approaches are currently compatible.

Example YML File:
Link to YML File

How to Add a YML File

Step 1: Add ci.attachconfig.yml
Place the file in the .ci/attachconfig/ci.attachconfig.yml folder within your BSP directory. For example:
bsp/nrf5x/nrf5340/.ci/attachconfig/ci.attachconfig.yml

Reference Link:
Link to Example YML File
Make sure not to change the folder structure or file name.

Step 2: Add the Corresponding CONFIG
In the YML file, specify the menuconfig options that need to be enabled. For example, to test segger_rtt, use the following configuration:
(Provide specific configuration details here)

The configurations here refer to the differing settings. After runningmenuconfig, you can check the differences in the .config file to identify these modified configurations. Note that you only need to include the main menuconfig options that you’ve changed. For example, if you select the packageCONFIG_PKG_USING_SEGGER_RTT, there’s no need to add other default configurations—only the ones that have been modified should be included.

If you want to disable a specific configuration, simply set it as CONFIG_RT_USING_SERIAL_V2=n.

Step 3: Submit a PR for Validation
After submitting a PR, a check for all BSPs will typically be triggered:
CI Check for All BSPs
This is where the CI system validates all BSPs.

Check your BSP to verify if the changes have taken effect.

Here, you can check whether the compilation passed. If it didn’t, you’ll need to modify the corresponding .c files.

Additional Features
Add SCons Parameters
If you need to enforce strict compilation using the -strict flag, simply add the parameter scons_arg:
For example:

Adding Dependencies
If you want to reuse previous configurations, you can refer to the image below and add a depends node.

Adding References
If you want to reuse the previous scons_arg: parameters, you can refer to the format below:

The main functionality is implemented in bsp_buildings.py.

Summary
By introducing YML configuration files, we can effectively store and manage commonly used menuconfig configurations. This approach helps maintain a stable configuration environment in CI, ensuring that commonly used configurations don’t cause issues during compilation. When adding YML files, it’s recommended to follow these rules:

• Use a separate YML file to store all configurations.
• Ensure each configuration name is unique; if they are the same, separate them with a -- as per YML syntax.
• Try to include all modified configurations in kconfig to make verification easier.
• Use # for comments.

References:

• Official Documentation: YAML Specification
• YML to JSON: js-yaml
• YML Syntax Tutorial: https://mp.weixin.qq.com/s/S6l5KHyufsV0FGDgm-ZW9g