Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add dependency checker tool #1275

Merged
merged 2 commits into from
Apr 25, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,5 @@ build/
**/*.cmd
**/*.a
*.elf

tools/dependency/web/data.js
67 changes: 67 additions & 0 deletions docs/development/dependency_tool.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: Dependency tool
page_id: dependency_tool
---

There is a tool that can be used to visualize and analyze dependencies in the source file tree. the code for the tool is
located in `tools/dependency` and is called by running the `deps.py` file.

The tool extracts subsets of the full file tree, based on user input, and either visualize the subset, or count the
number of files.

The tool uses information from the source files, but also from intermediate files generated by kbuild, for that reason
valid results will only be available after a successful build. The results are based on the current build configuration,
for instance created by `make menuconfig`. Remember to run `make` before using the tool.

In visualizations, c-files are shown as triangles and h-files as circles. The color is based on the first part of the
path. Hovering over a file shows the full path. A node with dependencies can be highlighted by clicking it, and it can
be moved by dragging.

## Example uses

### Visualize dependencies of commander.c

Use the `-d` flag for finding dependencies and the `-v` for visualizing the result.

`./tools/dependency/deps.py -d -v src/modules/src/commander.c`

The tool will first try to find the full target (`src/modules/src/commander.c` in this case) in the file tree, if not
found, it will try to find the target in the file names. This makes it possible to do
`./tools/dependency/deps.py -d -v commander.c` instead. Note: it there would exist two `commander.c` files in the
file tree, at different paths, both of them would be included.

It is possible to limit the number of levels of dependencies to search for using the `-l` flag. To only show one level
of dependencies, use `./tools/dependency/deps.py -d -l 1 -v commander.c`

### Visualize all files that include deck.h

Use the `-u` to find the files that is using a file.

`./tools/dependency/deps.py -u -v cpx.h`

### Visualize multiple targets

More than one target can be used `./tools/dependency/deps.py -d -l 1 -v commander.c cpx.c` will show first level
dependencies to commander.c and cpx.c

It is also possible to use regex for targets. If the target does not match a full path, or a file name, the tool will
try to interpret it as a regex. For instance, to show all files in src/hal/interface/, use
`./tools/dependency/deps.py -v src/hal/interface/.*`

### Visualizing dependencies from one location to another

Use the `-f` flag. The first target is the "from" location and the rest is the "to" location. To visualize dependencies
from /src/platform to /src/utils, use `./tools/dependency/deps.py -f -v src/platform/.* src/utils/.*`

To show dependencies form a directory to "all other directories", you can use regex. The following essentially means
find dependencies from "platform" to "anything but platform":
`./tools/dependency/deps.py -f -v src/platform/.* '^src/(?!platform/).*$'`

### Count files

The `-t` flag prints the total number of files found, `./tools/dependency/deps.py -d -t src/modules/src/commander.c`.
`-cc` counts the number of c-files and `-hh` counts the number of h-files.

The `-z` flag returns a non-zero result (fail) if the total file count is not zero. This is useful in build tools to
make sure there are no "backwards" dependencies. For instance, if we want to make sure files in src/utils do not have
dependencies to files outside src/utils, use `./tools/dependency/deps.py -f -z src/utils/.* '^src/(?!utils/).*$'`
Loading