Metadata are needed to serve different goals:
A module is either an actual component, or an utility (a pure C++ class, a port definition, etc.) needed in a platform.
Each module is accompanied by a metadata file, which contains all information to satisfy goals.
A module description can evolve to different stages:
Il we try to wrap-up, life of a module in soclib_desc can be summarized in this picture:
We will describe these stages below.
A Module is the module description, in an abstract way.
The sole module description is not enough to compile it. If this is a SystemC (C++) module, it may have some template parameters which change the template instanciation. Therefore, user must provide the template parameters to the build system in order to compile the module’s code. This is the role of the specialization.
Module definition contains the objective description of the module, with a set of attributes:
Complete API implemented by modules is described in ModuleInterface.
With addition of template parameters, a module description can evolve into a Specialization. Specialization is a module definition with fixed template parameters. This permits:
Complete API implemented by specializations is described in SpecializationInterface.
The builder is the last thing you can obtain with module descriptions. It is able to generate BBlock and associated Action objects of soclib_builder.
Complete API implemented by component builders is described in ComponentBuilderInterface.
Upon initialization, soclib_desc scans the directories defined in metadata paths. All found modules declarations are gathered in a global database: the module index.
The module index contains all defined modules, whatever the metadata parser module that provided their definition. The index is keyed by the name of the component. See soclib-cc -l for index listing.
For better performance and lower startup times, the index is cached. See soclib-cc -X for cache cleaning.
Metadata providers are soclib-cc plugins able to extract metadata from files (or other means). With soclib-cc comes a built-in metadata provider: the .sd file format.
Metadata providers are Python modules implementing the soclib_desc.metadata_file.MetadataFile protocol, and must be registered from Configuration files with config.add_desc_parser().
Metadata files can be searched anywhere in the filesystem. Sepcified directories are searched recursively.
Default configuration searches for modules in the soclib installation (soclib/module/, soclib/communication/, soclib/iss/, soclib/lib/), and also in the current directory (where soclib-cc is executed).
Users can add new filesystem trees to index through the command line, with soclib-cc -I, or through the Configuration files with config.addDescPath().