buildtools/checkdeps/README.md

   1 # DEPS Files
   2
   3 DEPS files specify which files the sources in a directory tree may include.
   4
   5 ## File format
   6
   7 First you have the normal module-level deps. These are the ones used by
   8 gclient. An example would be:
   9
  10 ```
  11 deps = {
  12   "base":"http://foo.bar/trunk/base"
  13 }
  14 ```
  15
  16 DEPS files not in the top-level of a module won't need this. Then you have any
  17 additional include rules. You can add (using `+`) or subtract (using `-`) from
  18 the previously specified rules (including module-level deps). You can also
  19 specify a path that is allowed for now but that we intend to remove, using `!`;
  20 this is treated the same as `+` when `check_deps` is run by our bots, but a
  21 presubmit step will show a warning if you add a new include of a file that is
  22 only allowed by `!`.
  23
  24 Note that for .java files, there is currently no difference between `+` and
  25 `!`, even in the presubmit step.
  26
  27 ```
  28 include_rules = [
  29   # Code should be able to use base (it's specified in the module-level
  30   # deps above), but nothing in "base/evil" because it's evil.
  31   "-base/evil",
  32
  33   # But this one subdirectory of evil is OK.
  34   "+base/evil/not",
  35
  36   # And it can include files from this other directory even though there is
  37   # no deps rule for it.
  38   "+tools/crime_fighter",
  39
  40   # This dependency is allowed for now but work is ongoing to remove it,
  41   # so you shouldn't add further dependencies on it.
  42   "!base/evil/ok_for_now.h",
  43 ]
  44 ```
  45
  46 If you have certain include rules that should only be applied for some files
  47 within this directory and subdirectories, you can write a section named
  48 `specific_include_rules` that is a hash map of regular expressions to the list
  49 of rules that should apply to files matching them. Note that such rules will
  50 always be applied before the rules from `include_rules` have been applied, but
  51 the order in which rules associated with different regular expressions is
  52 applied is arbitrary.
  53
  54 ```
  55 specific_include_rules = {
  56   ".*_(unit|browser|api)test\.cc": [
  57     "+libraries/testsupport",
  58   ],
  59 }
  60 ```
  61
  62 You can optionally ignore the rules inherited from parent directories, similar
  63 to "set noparent" in OWNERS files. For example, adding `noparent = True` in
  64 //ash/components/DEPS will cause rules from //ash/DEPS to be ignored, thereby
  65 forcing each //ash/component/foo to explicitly declare foo's dependencies.
  66
  67 ```
  68 noparent = True
  69 ```
  70
  71 # Directory structure
  72
  73 DEPS files may be placed anywhere in the tree. Each one applies to all
  74 subdirectories, where there may be more DEPS files that provide additions or
  75 subtractions for their own sub-trees.
  76
  77 There is an implicit rule for the current directory (where the DEPS file lives)
  78 and all of its subdirectories. This prevents you from having to explicitly
  79 allow the current directory everywhere. This implicit rule is applied first, so
  80 you can modify or remove it using the normal include rules.
  81
  82 The rules are processed in order. This means you can explicitly allow a higher
  83 directory and then take away permissions from sub-parts, or the reverse.
  84
  85 Note that all directory separators must be `/` slashes (Unix-style) and not
  86 backslashes. All directories should be relative to the source root and use
  87 only lowercase.