Skip to content

Latest commit

 

History

History
309 lines (223 loc) · 7.68 KB

Metadata.md

File metadata and controls

309 lines (223 loc) · 7.68 KB
Raw

Metadata

Table of Contents

This document describes metadata used in the project. The status of the document is beta.

Purpose

The purpose of metadata in the project is to automate works in development and project management, to ensure the project policies, and to extend the project to support third-party projects.

Files

.eil.yml

The metadata file of a component. Each component must have .eil.yml in the root directory of the component. The file format is YAML.

An example path: components/ads111x/.eil.yml.

persons.yml

persons.yml is a YAML file that contains a list of Persons.

groups.yml

groups.yml is a YAML file that contains a list of Groups.

targets.yml

targets.yml is a YAML file that contains a list of Targets.

Resources

Resources defined here represents various objects used in the metadata.

A resource has unique name as a primary key.

When referring to a resource in another resource, use name as key and its value to identify the resource. As a shorthand, you may use the name of a resource as String. In this case, the value is assumed to be name: $VALUE.

When a resource expects a Person as a value,

foo:
  name: trombik

This is a shorthand version of the above example:

foo: trombik

Person

A Person represents a person. Person is used to describe a copyrights holder and a code owner. A Person must be defined in persons.yml file.

Name Type Description Required
name String A unique ID string of the person. Use GitHub account or GitHub project if the person has one Yes
full_name String Full name of the person or the project No
gh_id String GitHub account name or project name No
email String Email address of the person No
website String Web site URL No

When any of gh_id, email, or website is not available, person must have a full name because it is used to identify the source of code.

If the person does not have gh_id, use the full name for name. For example, when the full name is "Foo Bar", use name: FooB.

Person should have one or more of optional keys so that one can contact the person.

Examples:

name: trombik
gh_id: trombik
full_name: Tomoyuki Sakurai
email: y@trombik.org
website: https://github.com/trombik
name: foo
full_name: Foo `bar` buz
# XXX other keys are optional, but strongly recommended.

Target

Name Type Description Required
name String Name of the build target in esp-idf, or esp8266. Yes

An example:

name: esp32

License

Name Type Description Required
name String SPDX License Identifier (see the list of licenses) Yes

An example:

name: BSD-3

Copyright

Name Type Description Required
author Person Copyrights holder. See also Person. No
name String The value of name of Person. A shorthand for author No
year Integer Registration year of the copyrights Yes

Copyright must have only one of author and name, not both.

Examples:

name: trombik
year: 2021

The above example is a shorthand form of:

author:
  name: trombik
year: 2021

Group

A Group represents a group of Components. A Group must be in groups.yml.

Name Type Description Required
name String A unique ID of the group Yes
description String Description of the group Yes

name should be short, and memorable. Use - as a word separator. It must not include spaces ([0-9a-zA-Z-]+ in regular expression).

An example:

name: adc-dac
description: ADC/DAC libraries

Metadata

Metadata is the content of .eil.yml. Metadata includes non-empty list of Component under components top level key.

An example:

---
components:
  - name: foo
  # ... other keys go here ...

Component

Name Type Description Required
name String The name of the component. Must be unique. Yes
description String A short description of the component. Yes
group Group The primary group name of the component. Yes
groups A list of Group A list of zero or more of Group No
code_owners A list of Person A list of one or more of Person Yes
depends A list of Component Zero or more of component that the component depends on No
thread_safe Strnig One of yes, no, and N/A Yes
targets A list of Target One or more of supported target Yes
licenses A list of License One or more of licenses used in the component Yes
copyrights A list of Copyright One or more of copyright holder Yes

FIXME depends must be a list because some drivers have conditional REQUIRES in CMakeLists.txt.

Usages of metadata in the project

The current implementation uses ruby and rspec ruby gem to validate metadata in all components, and generate README.md.

Requirements are:

  • ruby 2.7 (other version should also work)
  • bundler

After installing requirements, run:

bundle install

Validating metadata of components

To validate metadata, run:

bundle exec rake -C devtools rspec

The implementation uses rspec to validate metadata because:

  1. the output is readable
  2. requires less ruby knowledge to maintain the spec than validating everything in ruby code
  3. porting tests to other languages is easier than porting ruby code

Under spec directory, there are:

  • spec_helper.rb, which is a helper for the test
  • *_spec.rb, which is a test script
  • other ruby files, such as person.rb, which are class definitions used in the test

The ruby classes for the test validate minimum requirements only, such as the .eil.yml file exists, or a resource has a required primary key. Actual test should be performed in *_spec.rb files.

Generating README.md

README.md is generated from the metadata and README.md.erb. To update README.md, run the following command at the repository root directory:

bundle exec rake -C devtools readme > README.md

Known issues

conditional depends

Some CMakeLists.txt conditionally sets REQUIRES. depends does not handle the following case.

# for esp32
depends:
  - name: driver
  - name: freertos
  - name: log
# for esp8266
depends:
  - name: esp8266
  - name: freertos
  - name: log

A possible solution:

depends:
  - name: driver
    target:
      - name: esp32
      - name: esp32s2
      - name: esp32c3
  - name: esp8266
    target:
      - name: esp8266
  - name: freertos
  - name: log