Merge pull request #1275 from bitcraze/krichardsson/deps

Add dependency checker tool

.gitignore

@@ -46,3 +46,5 @@ build/
 **/*.cmd
 **/*.a
 *.elf
+
+tools/dependency/web/data.js

docs/development/dependency_tool.md

@@ -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/).*$'`