README

Introduction
============

Depslint is a tool for analyzing and verifying build dependencies. It
was written to assist switching a large project build system from an
existing complex legacy solution to ninja.

The tool works by running a complete build under 'strace',
recording relevant system calls to discover real 'dependencies',
and then verifying that dependencies defined in the ninja manifest and
the corresponding depfiles are correct.

Purpose
============
Verify a build manifest for:

* Correctness of the 'first build' (e.g., building following a
  pristine checkout, before any dep files are available). This is
  mostly useful for projects with autogenerated headers, to verify
  that build rules enforce autogenerated files to be created before
  including source files are compiled.

* Correctness of the 'incremental build' (e.g., rebuild following a
  modification of any of the files under the build tree when the tree
  already contains some of the build products and dep files).

* Redundant dependency specifications in the manifest making incremental
  rebuilds longer than needed.

* More..

Quick usage guide
=================
cd ~/myproject
ninja -t clean
git clean -fdX

# You can substitute the above with a suitable command cleaning your
# build tree.

~/depslint/depstrace.py ninja

# The above will build your project under 'strace', parse output and
# store discovered dependency information in 'deps.lst'. The complete
# strace output will also be stored in 'strace_log.txt' for debugging,
# if necessary.

~/depslint/depslint.py --stats=all

# Parse build.ninja, load depfiles, build dependency graph and
# validate it using 'real' dependency information in 'deps.lst'. If
# '.depslint' file is available, it can be used to set
# 'IGNORED_SUFFICES' and 'IMPLICIT_DEPS_MATCHERS' to ignore certain
# dependecy issues. Tool output with extra details is stored to
# 'depslint.log'.

Documentation
=============
The documentation will eventually appear under doc/.

Hacking & Testing
=================

There are unit-tests available under 'tests' directory. You can run
these as: 'python -m unittest tests' under project root. If you wish
to contribute changes, it would be best if you will add supporting
tests as well.