-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Create documentation for Starlark code with stardoc
We want a single source of truth and less work by maintaining the docstring as well as the README.
- Loading branch information
Showing
14 changed files
with
280 additions
and
154 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs") | ||
|
|
||
| stardoc_with_diff_test( | ||
| name = "cc_info_mapping", | ||
| bzl_library_target = "//src/cc_info_mapping:cc_info_mapping", | ||
| ) | ||
|
|
||
| stardoc_with_diff_test( | ||
| name = "dwyu_aspect", | ||
| bzl_library_target = "//src/aspect:factory", | ||
| ) | ||
|
|
||
| update_docs() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| <!-- Generated with Stardoc: http://skydoc.bazel.build --> | ||
|
|
||
| # Motivation | ||
|
|
||
| Sometimes users don't want to follow the DWYU rules for all targets or have to work with external dependencies not following the DWYU principles. | ||
| While one can completely exclude targets from the DWYU analysis (e.g. via tags), one might not want to disable DWYU completely, but define custom rules for specific dependencies. | ||
| One can do so by defining exceptions where includes can be provided by selected transitive dependencies instead of direct dependencies. | ||
| In other words, one can virtually change which header files are treated as being available from direct dependencies. | ||
|
|
||
| One example use case for this are unit tests based on gtest. | ||
| Following strictly the DWYU principles each test using a gtest header should depend both on the gtest library and the gtest main: | ||
| ```starlark | ||
| cc_test( | ||
| name = "my_test", | ||
| srcs = ["my_test.cc"], | ||
| deps = [ | ||
| "@com_google_googletest//:gtest", | ||
| "@com_google_googletest//:gtest_main", | ||
| ], | ||
| ) | ||
| ``` | ||
| This can be considered superfluous noise without a significant benefit. | ||
| The mapping feature described here allows defining that `@com_google_googletest//:gtest_main` offers the header files from `@com_google_googletest//:gtest`. | ||
| Then a test can specify only the dependency to `@com_google_googletest//:gtest_main` without DWYU raising an error while analysing the test. | ||
|
|
||
| <a id="dwyu_make_cc_info_mapping"></a> | ||
|
|
||
| ## dwyu_make_cc_info_mapping | ||
|
|
||
| <pre> | ||
| load("@depend_on_what_you_use//src/cc_info_mapping:cc_info_mapping.bzl", "dwyu_make_cc_info_mapping") | ||
|
|
||
| dwyu_make_cc_info_mapping(<a href="#dwyu_make_cc_info_mapping-name">name</a>, <a href="#dwyu_make_cc_info_mapping-mapping">mapping</a>) | ||
| </pre> | ||
|
|
||
| Map include paths available from one or several targets to another target. | ||
|
|
||
| Create a mapping allowing treating targets as if they themselves would offer header files, which in fact are coming from their dependencies. | ||
| This enables the DWYU analysis to skip over some usage of headers provided by transitive dependencies without raising an error. | ||
|
|
||
| Using this rule and the various mapping techniques is demonstrated in the [target_mapping example](/examples/target_mapping). | ||
|
|
||
|
|
||
| **PARAMETERS** | ||
|
|
||
|
|
||
| | Name | Description | Default Value | | ||
| | :------------- | :------------- | :------------- | | ||
| | <a id="dwyu_make_cc_info_mapping-name"></a>name | Unique name for this target. Will be the prefix for all private intermediate targets. | none | | ||
| | <a id="dwyu_make_cc_info_mapping-mapping"></a>mapping | Dictionary containing various targets and how they should be mapped. Possible mappings are:<br> - An explicit list of targets which are mapped to the main target. Be careful only to choose targets which are dependencies of the main target! <br> - The `MAP_DIRECT_DEPS` token which tells the rule to map all direct dependencies to the main target. <br> - The `MAP_TRANSITIVE_DEPS` token which tells the rule to map recursively all transitive dependencies to the main target. | none | | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| <!-- Generated with Stardoc: http://skydoc.bazel.build --> | ||
|
|
||
|
|
||
|
|
||
| <a id="dwyu_aspect_factory"></a> | ||
|
|
||
| ## dwyu_aspect_factory | ||
|
|
||
| <pre> | ||
| load("@depend_on_what_you_use//src/aspect:factory.bzl", "dwyu_aspect_factory") | ||
|
|
||
| dwyu_aspect_factory(<a href="#dwyu_aspect_factory-ignored_includes">ignored_includes</a>, <a href="#dwyu_aspect_factory-recursive">recursive</a>, <a href="#dwyu_aspect_factory-skip_external_targets">skip_external_targets</a>, <a href="#dwyu_aspect_factory-skipped_tags">skipped_tags</a>, | ||
| <a href="#dwyu_aspect_factory-target_mapping">target_mapping</a>, <a href="#dwyu_aspect_factory-use_implementation_deps">use_implementation_deps</a>, <a href="#dwyu_aspect_factory-verbose">verbose</a>) | ||
| </pre> | ||
|
|
||
| Create a "Depend on What You Use" (DWYU) aspect. | ||
|
|
||
| Use the factory in a `.bzl` file to instantiate a DWYU aspect: | ||
| ```starlark | ||
| load("@depend_on_what_you_use//:defs.bzl", "dwyu_aspect_factory") | ||
|
|
||
| your_dwyu_aspect = dwyu_aspect_factory(<aspect_options>) | ||
| ``` | ||
|
|
||
|
|
||
| **PARAMETERS** | ||
|
|
||
|
|
||
| | Name | Description | Default Value | | ||
| | :------------- | :------------- | :------------- | | ||
| | <a id="dwyu_aspect_factory-ignored_includes"></a>ignored_includes | By default, DWYU ignores all headers from the standard library when comparing include statements to the dependencies. This list of headers can be seen in [std_header.py](/src/analyze_includes/std_header.py).<br> You can extend this list of ignored headers or replace it with a custom one by providing a json file with the information to this attribute.<br> Specification of possible files in the json file: <ul><li> `ignore_include_paths` : List of include paths which are ignored by the analysis. Setting this **disables ignoring the standard library include paths**. </li><li> `extra_ignore_include_paths` : List of concrete include paths which are ignored by the analysis. Those are always ignored, no matter what other fields you provide. </li><li> `ignore_include_patterns` : List of patterns for include paths which are ignored by the analysis. Patterns have to be compatible to Python [regex syntax](https://docs.python.org/3/library/re.html#regular-expression-syntax). The [match](https://docs.python.org/3/library/re.html#re.match) function is used to process the patterns. </li></ul> This feature is demonstrated in the [ignoring_includes example](/examples/ignoring_includes). | `None` | | ||
| | <a id="dwyu_aspect_factory-recursive"></a>recursive | By default, the DWYU aspect analyzes only the target it is being applied to. You can change this to recursively analyzing dependencies following the `deps` and `implementation_deps` attributes by setting this to True.<br> This feature is demonstrated in the [recursion example](/examples/recursion). | `False` | | ||
| | <a id="dwyu_aspect_factory-skip_external_targets"></a>skip_external_targets | Sometimes external dependencies are not our under control and thus analyzing them is of little value. If this flag is True, DWYU will automatically skip all targets from external workspaces. This can be useful in combination with the recursive analysis mode.<br> This feature is demonstrated in the [skipping_targets example](/examples/skipping_targets). | `False` | | ||
| | <a id="dwyu_aspect_factory-skipped_tags"></a>skipped_tags | Do not execute the DWYU analysis on targets with at least one of those tags. By default skips the analysis for targets tagged with 'no-dwyu'.<br> This feature is demonstrated in the [skipping_targets example](/examples/skipping_targets). | `["no-dwyu"]` | | ||
| | <a id="dwyu_aspect_factory-target_mapping"></a>target_mapping | Accepts a [dwyu_make_cc_info_mapping](/docs/cc_info_mapping.md) target. Allows virtually combining targets regarding which header can be provided by which dependency. For the full details see the `dwyu_make_cc_info_mapping` documentation.<br> This feature is demonstrated in the [target_mapping example](/examples/target_mapping). | `None` | | ||
| | <a id="dwyu_aspect_factory-use_implementation_deps"></a>use_implementation_deps | `cc_library` offers the attribute [`implementation_deps`](https://bazel.build/reference/be/c-cpp#cc_library.implementation_deps) to distinguish between public (aka interface) and private (aka implementation) dependencies. Headers from the private dependencies are not made available to users of the library.<br> Setting this to True allows DWYU to raise an error if headers from a `deps` dependency are used only in private files. In such a cease the dependency should be moved from `deps` to `implementation_deps`.<br> This feature is demonstrated in the [basic_usage example](/examples/basic_usage). | `False` | | ||
| | <a id="dwyu_aspect_factory-verbose"></a>verbose | If True, print debugging information about what DWYU does. | `False` | | ||
|
|
||
| **RETURNS** | ||
|
|
||
| Configured DWYU aspect | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,26 @@ | ||
| load("@bazel_skylib//:bzl_library.bzl", "bzl_library") | ||
| load("@rules_python//python:defs.bzl", "py_binary") | ||
|
|
||
| py_binary( | ||
| name = "process_target", | ||
| srcs = ["process_target.py"], | ||
| visibility = ["//visibility:public"], | ||
| ) | ||
|
|
||
| bzl_library( | ||
| name = "factory", | ||
| srcs = [ | ||
| "dwyu.bzl", | ||
| "factory.bzl", | ||
| "@bazel_tools//tools/build_defs/cc:action_names.bzl", | ||
| ], | ||
| visibility = ["//visibility:public"], | ||
| deps = [ | ||
| "//src/cc_info_mapping", | ||
| ], | ||
| ) | ||
|
|
||
| exports_files( | ||
| ["factory.bzl"], | ||
| visibility = ["//docs:__pkg__"], | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.