github.com/sercand/please@v13.4.0+incompatible/docs/subrepos.html

<h1>Subrepos</h1>

<p class="experimental">This feature is still experimental; some aspects may not work fully
  or at all just yet. Proceed with caution!</p>

<p>It is possible to pull in dependencies from separate repositories using Please.
  These are called subrepos and are defined in BUILD files.</p>

<p>They're heavily based on Bazel's similar concept and a certain amount of interoperability
  is possible.</p>

<h2>Defining a subrepo</h2>

<p>Subrepos are defined using builtins like <a href="lexicon.html#http_archive">http_archive</a> or
  <a href="lexicon.html#new_http_archive">new_http_archive</a>. These download a remote file and
  extract it, and make the contents available to other rules. The main difference is that
  <code>new_http_archive</code> needs to be given a BUILD file but <code>http_archive</code>
  uses one existing within the file.</p>

<p>For example (as seen at the root of the Please repo):
  <pre><code>http_archive(
    name = "pleasings",
    hashes = ["388baebf9381c619f13507915f16d0165a5dc13e"],
    strip_prefix = "pleasings-f0c549b375067802400699247106e4907de917c2",
    urls = ["https://github.com/thought-machine/pleasings/archive/f0c549b375067802400699247106e4907de917c2.zip"],
)
</code></pre></p>

<p>Currently, subrepo rules only work when placed at the repo root. In future we intend to
  lift this restriction. In Bazel compatibility mode they can also be used within the
  WORKSPACE file.</p>

<h2>Using subrepos</h2>

<p>Rules within subrepos can be referenced using an <code>@</code> prefix on rules, anywhere
  where a build rule would normally be accepted. For example:
  <pre><code>subinclude("@pleasings//go:go_bindata")

cc_test(
    name = "my_test",
    ...
    deps = [
        "@pleasings//eggs:spam",
    ],
)
</code></pre>

  In this case <code>pleasings</code> corresponds to the name of the subrepo as declared in
  the <code>http_archive</code> rule above.</p>

<p>Subrepos also underpin <a href="cross_compiling.html">cross-compiling</a> and share the same
  syntax; you can use that to reference architectures as well. There is currently some ambiguity
  here and so it is best not to define subrepo names that match cross-compile architectures.</p>

<p>If the subrepo and the package names are the same, for example, <code>@unittest_cpp//:unittest_cpp</code>,
    the build label reference to the target can be abbreviated, like so:</p>

<pre><code>
cc_test(
    name = "my_test",
    ...
    deps = [
        "@unittest_cpp",
    ],
)
</code></pre>