Narrow an implementation export

An export of implementation needs can hold many needs, and you may want only a few of them in the graph. This page shows how to read only the needs you name. A need that you do not name is not read, and it is not checked.

Before you start

  • The export and the Doxygen output of the implementation exist. The content extractor reads both (see The content extractor).

  • The source files that the Doxygen output names are in a repository that the configuration maps under repositories:.

Name the needs you want

Put the key need-ids in the implementations block. Its value is the list of need identifiers to read. The example below also sets types and path-root, because most real exports need them. All paths are relative to the directory of the file.

case: ./case
repositories:
  library: ../library
producer:
  implementations:
    repository: library
    export: needs/api-needs.json
    doxygen: xml/api
    types: [impl]
    path-root: include/
    need-ids:
      - IMPL-QUEUE-DEFINE
      - IMPL-queue-put
      - IMPL-queue-get
      - IMPL-queue-peek

What each key does:

  • types keeps the needs of the listed types.

  • need-ids keeps the needs with the listed identifiers.

  • path-root puts a directory in front of each path that the Doxygen output names (SEG-SREQ-349).

When you give both types and need-ids, a need is read only when both admit it. Give need-ids alone, and the type of a need does not matter. Give neither, and every need is read.

The names of all the keys, for every block, are in the key list of the configuration loader: The names of the keys. This page does not repeat the list. A key that is not on that list is refused (SEG-SREQ-376).

What happens to a need you did not name

The extractor does not read it, and it does not check it. A need that has no title, or a bad link, is not refused when it is not in the list (SEG-SREQ-374). A need that is in the list keeps every check.

An identifier that names no need

Every identifier in the list must name a need of the export that the configured types admit. If one does not, the extractor refuses the configuration. The error names every such identifier, one on each line (SEG-SREQ-360). A typing error in an identifier then stops the run, and the graph is never built without the need you wanted.

A mistyped key

The loader refuses a key that it does not know (SEG-SREQ-376). If you write need_ids and not need-ids, the command exits with status 2. The message names the key and where it stands, and it lists the keys of that place. The case does not change.