github.com/sercand/please@v13.4.0+incompatible/docs/dependencies.html (about)

     1  <h1>Third-party dependencies</h1>
     2  
     3  <p>Sooner or later, most projects end up needing a dependency on some
     4    third-party libraries, and one of the jobs of the build system is to
     5    manage those as well. Please is no exception to this, but it bears a
     6    little discussion since most systems handle this differently.</p>
     7  
     8  <p>In Please, third-party dependencies can be created in any BUILD file
     9    and manipulated as any other build rule. We encourage methods of fetching
    10    them that are repeatable; typically each language has one that matches
    11    up to a common package manager, for example:
    12    <ul>
    13      <li><a href="lexicon.html#go_get">go_get</a></li>
    14      <li><a href="lexicon.html#pip_library">pip_library</a></li>
    15      <li><a href="lexicon.html#maven_jar">maven_jar</a></li>
    16    </ul>
    17    Each of these require explicit declarations of all their dependencies in the
    18    BUILD file; this is how we pin dependencies & guarantee reproducibility.<br/>
    19    There are one or two alternatives that show slightly different approaches
    20    (e.g. <a href="lexicon.html#python_wheel">python_wheel</a> or
    21    <a href="lexicon.html#maven_jars">maven_jars</a>) as well, and
    22    <a href="lexicon.html#remote_file">remote_file</a> which is a general tool to
    23    download anything (although often more work is required to actually build it)</p>
    24  
    25  <p>The typical idiom we use is to place BUILD files under a third_party directory,
    26    to make it clear where they're coming from. Commonly we separate them by language
    27    for multi-language repos as well.<br/>
    28    See <a href="https://github.com/thought-machine/please/tree/master/third_party/go">third_party/go</a>,
    29    <a href="https://github.com/thought-machine/please/tree/master/third_party/python">third_party/python</a> and
    30    <a href="https://github.com/thought-machine/please/tree/master/third_party/java">third_party/java</a>
    31    in Please's repo for some examples of what these look like.</p>
    32  
    33  <p>There's no explicit command to download third-party dependencies (e.g. <code>plz fetch</code> or similar).
    34    Dependencies are built as part of the build process along with everything else, so
    35    their downloads can be parallelised with compiling other targets.</p>
    36  
    37  <h2>Comparison to other systems</h2>
    38  
    39  <p>For users familiar with Bazel, we expect that writing BUILD files won't be
    40    challenging, the main difference being that there is no direct equivalent to
    41    Bazel's WORKSPACE file. As mentioned above, third-party dependencies can occur
    42    wherever you choose to put them in normal BUILD files.<br/>
    43    Right now there is no direct equivalent to Bazel's <code>new_http_archive</code>
    44    and similar, but this is definitely on the <s>roadmap</s> wishlist.</p>
    45  
    46  <p>If you've used Buck before, the model is pretty similar to fetching Maven jars
    47    using the bucklet for it. This is not entirely coincidental since we were previously
    48    using Buck so initially Please had to mimic the same interface - but we also
    49    quite liked it and decided to keep on in the same way.</p>
    50  
    51  <p>If you're coming from Gradle or Maven, it's a little more alien due to being less language-specific
    52    and requiring full transitive dependencies to be specified.<br/>
    53    <a href="lexicon.html#maven_jars">maven_jars</a> is the closest equivalent to declaring
    54    Maven dependencies in the same way that Gradle does it; it works by communicating with
    55    Maven repositories to find dependencies and generating more BUILD rules for them. This can
    56    be a little unreliable though, since the Maven package format is complex, and your dependencies
    57    aren't fully within your control and can change between builds - we recommend
    58    <a href="lexicon.html#maven_jar">maven_jar</a> instead, but understand it's more work to set up.</p>
    59  
    60  <p><code>requirements.txt</code> files from Python are not usually especially difficult to
    61    translate using <a href="lexicon.html#pip_library">pip_library</a>; again we require listing
    62    transitive dependencies explicitly, but this is not normally too onerous for Python.<br/>
    63    Since Please needs to know precisely what will be output, the rules can sometimes need a little
    64    tweaking when the output names don't correspond to the package names (or often a package outputs
    65    a single .py file instead of a directory).</p>
    66  
    67  <p><a href="lexicon.html#go_get">go_get</a> works pretty similarly to the usual <code>go get</code>
    68    tool, but again only outputs a single package at a time. Writing up the dependencies can be
    69    eased by using something like <code>go list -f '{{.Deps}}' &lt;package&gt;</code> to discover
    70    all the dependencies for the package in question.</p>