GNOME.org
 

[Notes] [Git][BuildStream/buildstream][jennis/filter-docs] 2 commits: filter.py/filter.yaml: Documentation improvements

Title: GitLab

James Ennis pushed to branch jennis/filter-docs at BuildStream / buildstream

Commits:

2 changed files:

Changes:

  • buildstream/plugins/elements/filter.py
    ... ... @@ -20,25 +20,127 @@
    20 20 
     """
    21 21 
     filter - Extract a subset of files from another element
    22 22 
     =======================================================
    23 
    -This filters another element by producing an output that is a subset of
    24 
    -the filtered element.
    23 
    +Filter another element by producing an output that is a subset of
    24 
    +the parent element's output. Subsets are defined by the parent element's
    25 
    +:ref:`split rules <public_split_rules>`.
    25 26
    26 
    -To specify the element to filter, specify it as the one and only build
    27 
    -dependency to filter. See :ref:`Dependencies <format_dependencies>`
    28 
    -for what dependencies are and how to specify them.
    27 
    +Overview
    28 
    +--------
    29 
    +A filter element must have exactly one *build* dependency, where said
    30 
    +dependency is the 'parent' element which we would like to filter.
    31 
    +Runtime dependencies may also be specified, which can be useful to propagate
    32 
    +forward from this filter element onto its reverse dependencies.
    33 
    +See :ref:`Dependencies <format_dependencies>` to see how we specify dependencies.
    29 34
    30 
    -Dependencies aside from the filtered element may be specified, but
    31 
    -they must be runtime dependencies only. This can be useful to propagate
    32 
    -runtime dependencies forward from this filter element onto its reverse
    33 
    -dependencies.
    35 
    +When workspaces are opened, closed or reset on a filter element, or this
    36 
    +element is tracked, the filter element will transparently pass on the command
    37 
    +to its parent element (the sole build-dependency).
    34 38
    35 
    -When workspaces are opened, closed or reset on this element, or this
    36 
    -element is tracked, instead of erroring due to a lack of sources, this
    37 
    -element will transparently pass on the command to its sole build-dependency.
    39 
    +Example
    40 
    +-------
    41 
    +Consider a simple import element, ``import.bst`` which imports the local files
    42 
    +'foo', 'bar' and 'baz' (each stored in ``files/``, relative to the project's root):
    38 43
    39 
    -The default configuration and possible options are as such:
    40 
    -  .. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml
    41 
    -     :language: yaml
    44 
    +.. code:: yaml
    45 
    +
    46 
    +   kind: import
    47 
    +
    48 
    +   # Specify sources to import
    49 
    +   sources:
    50 
    +   - kind: local
    51 
    +     path: files
    52 
    +
    53 
    +   # Specify public domain data, visible to other elements
    54 
    +   public:
    55 
    +     bst:
    56 
    +       split-rules:
    57 
    +         foo:
    58 
    +         - /foo
    59 
    +         bar:
    60 
    +         - /bar
    61 
    +
    62 
    +.. note::
    63 
    +
    64 
    +   We can make an element's metadata visible to all reverse dependencies by making use
    65 
    +   of the ``public:`` field. See the :ref:`public data documentation <format_public>`
    66 
    +   for more information.
    67 
    +
    68 
    +In this example, ``import.bst`` will serve as the 'parent' of the filter element, thus
    69 
    +its output will be filtered. It is important to understand that the artifact of the
    70 
    +above element will contain the files: 'foo', 'bar' and 'baz'.
    71 
    +
    72 
    +Now, to produce an element whose artifact contains the file 'foo', and exlusively 'foo',
    73 
    +we can define the following filter, ``filter-foo.bst``:
    74 
    +
    75 
    +.. code:: yaml
    76 
    +
    77 
    +   kind: filter
    78 
    +
    79 
    +   # Declare the sole build-dependency of the filter element
    80 
    +   depends:
    81 
    +   - filename: import.bst
    82 
    +     type: build
    83 
    +
    84 
    +   # Declare a list of domains to include in the filter's artifact
    85 
    +   config:
    86 
    +     include:
    87 
    +     - foo
    88 
    +
    89 
    +.. note::
    90 
    +
    91 
    +   We can also specify build-dependencies with a 'build-depends' field which has been
    92 
    +   available since :ref:`format version 14 <project_format_version>`. See the
    93 
    +   :ref:`Build-Depends documentation <format_build_depends>` for more detail.
    94 
    +
    95 
    +It should be noted that an 'empty' ``include:`` list would, by default, include all
    96 
    +split-rules specified in the parent element, which, in this example, would be the
    97 
    +files 'foo' and 'bar' (the file 'baz' was not covered by any split rules).
    98 
    +
    99 
    +Equally, we can use the ``exclude:`` statement to create the same artifact (which
    100 
    +only contains the file 'foo') by declaring the following element, ``exclude-bar.bst``:
    101 
    +
    102 
    +.. code:: yaml
    103 
    +
    104 
    +   kind: filter
    105 
    +
    106 
    +   # Declare the sole build-dependency of the filter element
    107 
    +   depends:
    108 
    +   - filename: import.bst
    109 
    +     type: build
    110 
    +
    111 
    +   # Declare a list of domains to exclude in the filter's artifact
    112 
    +   config:
    113 
    +     exclude:
    114 
    +     - bar
    115 
    +
    116 
    +In addition to the ``include:`` and ``exclude:`` fields, there exists an ``include-orphans:``
    117 
    +(Boolean) field, which defaults to ``False``. This will determine whether to include files
    118 
    +which are not present in the 'split-rules'. For example, if we wanted to filter out all files
    119 
    +which are not included as split rules we can define the following element, ``filter-misc.bst``:
    120 
    +
    121 
    +.. code:: yaml
    122 
    +
    123 
    +   kind: filter
    124 
    +
    125 
    +   # Declare the sole build-dependency of the filter element
    126 
    +   depends:
    127 
    +   - filename: import.bst
    128 
    +     type: build
    129 
    +
    130 
    +   # Filter out all files which are not declared as split rules
    131 
    +   config:
    132 
    +     exclude:
    133 
    +     - foo
    134 
    +     - bar
    135 
    +     include-orphans: True
    136 
    +
    137 
    +The artifact of ``filter-misc.bst`` will only contain the file 'baz'.
    138 
    +
    139 
    +Below is more information regarding the the default configurations and possible options
    140 
    +of the filter element:
    141 
    +
    142 
    +.. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml
    143 
    +   :language: yaml
    42 144 
     """
    43 145
    44 146 
     from buildstream import Element, ElementError, Scope

  • buildstream/plugins/elements/filter.yaml
    ... ... @@ -2,20 +2,21 @@
    2 2 
     # Filter element configuration
    3 3 
     config:
    4 4
    5 
    -  # A list of domains to include from each artifact, as
    6 
    -  # they were defined in the element's 'split-rules'.
    5 
    +  # A list of domains to include in each artifact, as
    6 
    +  # they were defined as public data in the parent
    7 
    +  # element's 'split-rules'.
    7 8 
       #
    8 9 
       # Since domains can be added, it is not an error to
    9 10 
       # specify domains which may not exist for all of the
    10 11 
       # elements in this composition.
    11 12 
       #
    12 13 
       # The default empty list indicates that all domains
    13 
    -  # from each dependency should be included.
    14 
    +  # of the parent's artifact should be included.
    14 15 
       #
    15 16 
       include: []
    16 17
    17 18 
       # A list of domains to exclude from each artifact, as
    18 
    -  # they were defined in the element's 'split-rules'.
    19 
    +  # they were defined in the parent element's 'split-rules'.
    19 20 
       #
    20 21 
       # In the case that a file is spoken for by a domain
    21 22 
       # in the 'include' list and another in the 'exclude'
    ... ... @@ -23,7 +24,7 @@ config:
    23 24 
       exclude: []
    24 25
    25 26 
       # Whether to include orphan files which are not
    26 
    -  # included by any of the 'split-rules' present on
    27 
    -  # a given element.
    27 
    +  # included by any of the 'split-rules' present in
    28 
    +  # the parent element.
    28 29 
       #
    29 30 
       include-orphans: False

    • —
    View it on GitLab.
    You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.

    [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]