bundle.html

<!DOCTYPE html>
<html lang="en">

<!--
  Copyright 2014 Pants project contributors (see CONTRIBUTORS.md).
  Licensed under the Apache License, Version 2.0 (see LICENSE).
-->

<head>
  <meta charset="utf-8"/>
  <title>Create a Bundled zip or Other Archive</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="shortcut icon" href="pants-logo.ico">
  <!-- In case this is a "test publish", tell search engines where real version lives: -->
  <link rel="canonical" href="http://pantsbuild.org/bundle.html">

  <link rel="stylesheet" href="bootstrap-custom.min.css">
  <link rel="stylesheet" href="bootstrap-custom-theme.min.css">
  <link rel="stylesheet" href="docsite.css">
</head>

<body>

<div class="header">
  <nav class="navbar navbar-default navbar-static-top">
    <div class="container">
      <div class="navbar-header">
        <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
          <span class="sr-only">Toggle navigation</span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand navbar-brand-img" href="index.html">
          <img src="pants-logo.ico" alt="[pantsbuild logo]">
        </a>
        <a class="navbar-brand" href="index.html">
          Pants v1
        </a>
      </div>
      <div id="navbar" class="navbar-collapse collapse">
        <ul class="nav navbar-nav navbar-right">
          <li><a href="/">Docs</a></li>
          <li><a href="community.html">Community</a></li>
          <li><a href="https://www.github.com/pantsbuild/pants">GitHub</a></li>
          <li>
            <form class="navbar-form navbar-left search" role="search" action="https://www.google.com/search">
              <div class="form-group">
                <input type="text" name="as_q" class="form-control query" placeholder="Search">
                <input name="as_sitesearch" value="pantsbuild.org" type="hidden">
              </div>
            </form>
          </li>
        </ul>
      </div><!--/.nav-collapse -->
    </div>
    <div class="deprecated">Pants v1 is no longer maintained. See <a href="https://www.pantsbuild.org/">here</a> for the Pants v2 documentation.</div>
  </nav>
</div>

<div class="page">

  <div class="container-fluid">
    <div class="row">

      <div class="col-md-1">
      </div>

      <div class="col-md-2">
        <div class="site-toc">
          <ul>
                  <li class="toc-h1 toc-heading">
                    Getting Started
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="install.html">Installing Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="setup_repo.html">Setting Up Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="first_tutorial.html">Tutorial</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="common_tasks.html">Common Tasks</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="orgs.html">Pants for Organizations</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Pants Basics
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="why_use_pants.html">Why Use Pants?</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="first_concepts.html">Pants Concepts</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="build_files.html">BUILD files</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="target_addresses.html">Target Addresses</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="3rdparty.html">Third-Party Dependencies</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="options.html">Pants Options</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="invoking.html">Invoking Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="reporting_server.html">Reporting Server</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="ide_support.html">IDE Support</a>
                  </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#JVM-Support" aria-expanded="false" aria-controls="JVM-Support">JVM Support<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="JVM-Support">
                        <li class="toc-h1 toc-link ">
                          <a href="jvm_projects.html">JVM Projects with Pants</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="3rdparty_jvm.html">JVM Dependency Management</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="scala.html">Scala Support</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="publish.html">Publishing Artifacts</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="from_maven.html">Pants for Maven Experts</a>
                        </li>
                    </ul>
                </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#Python-Support" aria-expanded="false" aria-controls="Python-Support">Python Support<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="Python-Support">
                        <li class="toc-h1 toc-link ">
                          <a href="python_readme.html">Python Projects with Pants</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="3rdparty_py.html">Python 3rdparty Pattern</a>
                        </li>
                    </ul>
                </li>
                  <li class="toc-h1 toc-link ">
                    <a href="go_readme.html">Go support for Pants</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="node_readme.html">Node.js Support</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Code &amp; Doc Generation
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="thrift_deps.html">Thrift</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="grpcio_gen.html">Python gRPC + protobufs</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="page.html">Markdown</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Getting Help
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="tshoot.html">Troubleshooting</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="community.html">Community</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Reference
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="build_dictionary.html">Pants BUILD Dictionary</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="options_reference.html">Pants Reference</a>
                  </li>
                <li class="toc-h1">
                  <a class="sidebar-nav-heading" class="toc-drop" data-toggle="collapse" href="#Release-Notes" aria-expanded="false" aria-controls="Release-Notes">Release Notes<span class="caret"></span></a>
                    <ul class="collapse sidebar-nav sidebar-submenu" id="Release-Notes">
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.30.x.html">1.30.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.29.x.html">1.29.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.28.x.html">1.28.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.27.x.html">1.27.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.26.x.html">1.26.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.25.x.html">1.25.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.24.x.html">1.24.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.23.x.html">1.23.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.22.x.html">1.22.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.21.x.html">1.21.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.20.x.html">1.20.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.19.x.html">1.19.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.18.x.html">1.18.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.17.x.html">1.17.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.16.x.html">1.16.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.15.x.html">1.15.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.14.x.html">1.14.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.13.x.html">1.13.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.12.x.html">1.12.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.11.x.html">1.11.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.10.x.html">1.10.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.9.x.html">1.9.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.8.x.html">1.8.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.7.x.html">1.7.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.6.x.html">1.6.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.5.x.html">1.5.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.4.x.html">1.4.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.3.x.html">1.3.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.2.x.html">1.2.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.1.x.html">1.1.x Stable Releases</a>
                        </li>
                        <li class="toc-h1 toc-link ">
                          <a href="notes-1.0.x.html">1.0.x Stable Releases</a>
                        </li>
                    </ul>
                </li>
                  <li class="toc-h1 toc-heading">
                    Developer
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="dev.html">Pants Developer Center</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="export.html">Export Format</a>
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="architecture.html">Architecture</a>
                  </li>
                  <li class="toc-h1 toc-heading">
                    Blogs
                  </li>
                  <li class="toc-h1 toc-link ">
                    <a href="coursier_migration.html">Twitter&#x27;s Coursier Migration</a>
                  </li>
          </ul>
        </div> <!-- site-toc -->
      </div>

      <div class="col-md-8">
        <div class="content">

          <div class="mainflow">
              <nav class="pagetoc">
                <ul>
                    <li class="toc-h1"><a href="#problem">Problem</a></li>
                    <li class="toc-h1"><a href="#solution">Solution</a></li>
                    <li class="toc-h2"><a href="#1-through-the-build-file-recommended">1. Through the BUILD file (recommended)</a></li>
                    <li class="toc-h2"><a href="#2-via-the-command-line-which-can-override-1">2. Via the command line (which can override #1)</a></li>
                    <li class="toc-h1"><a href="#discussion">Discussion</a></li>
                    <li class="toc-h1"><a href="#see-also">See Also</a></li>
                </ul>
              </nav>

            <!-- main content start -->
            <!-- generated by pants! -->
<style>
.codehilite .hll { background-color: #ffffcc }
.codehilite  { background: #f0f0f0; }
.codehilite .c { color: #60a0b0; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF0000 } /* Error */
.codehilite .k { color: #007020; font-weight: bold } /* Keyword */
.codehilite .o { color: #666666 } /* Operator */
.codehilite .ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */
.codehilite .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #007020 } /* Comment.Preproc */
.codehilite .cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */
.codehilite .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
.codehilite .gd { color: #A00000 } /* Generic.Deleted */
.codehilite .ge { font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF0000 } /* Generic.Error */
.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #00A000 } /* Generic.Inserted */
.codehilite .go { color: #888888 } /* Generic.Output */
.codehilite .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #0044DD } /* Generic.Traceback */
.codehilite .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #007020 } /* Keyword.Pseudo */
.codehilite .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #902000 } /* Keyword.Type */
.codehilite .m { color: #40a070 } /* Literal.Number */
.codehilite .s { color: #4070a0 } /* Literal.String */
.codehilite .na { color: #4070a0 } /* Name.Attribute */
.codehilite .nb { color: #007020 } /* Name.Builtin */
.codehilite .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.codehilite .no { color: #60add5 } /* Name.Constant */
.codehilite .nd { color: #555555; font-weight: bold } /* Name.Decorator */
.codehilite .ni { color: #d55537; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #007020 } /* Name.Exception */
.codehilite .nf { color: #06287e } /* Name.Function */
.codehilite .nl { color: #002070; font-weight: bold } /* Name.Label */
.codehilite .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #062873; font-weight: bold } /* Name.Tag */
.codehilite .nv { color: #bb60d5 } /* Name.Variable */
.codehilite .ow { color: #007020; font-weight: bold } /* Operator.Word */
.codehilite .w { color: #bbbbbb } /* Text.Whitespace */
.codehilite .mb { color: #40a070 } /* Literal.Number.Bin */
.codehilite .mf { color: #40a070 } /* Literal.Number.Float */
.codehilite .mh { color: #40a070 } /* Literal.Number.Hex */
.codehilite .mi { color: #40a070 } /* Literal.Number.Integer */
.codehilite .mo { color: #40a070 } /* Literal.Number.Oct */
.codehilite .sa { color: #4070a0 } /* Literal.String.Affix */
.codehilite .sb { color: #4070a0 } /* Literal.String.Backtick */
.codehilite .sc { color: #4070a0 } /* Literal.String.Char */
.codehilite .dl { color: #4070a0 } /* Literal.String.Delimiter */
.codehilite .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #4070a0 } /* Literal.String.Double */
.codehilite .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #4070a0 } /* Literal.String.Heredoc */
.codehilite .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.codehilite .sx { color: #c65d09 } /* Literal.String.Other */
.codehilite .sr { color: #235388 } /* Literal.String.Regex */
.codehilite .s1 { color: #4070a0 } /* Literal.String.Single */
.codehilite .ss { color: #517918 } /* Literal.String.Symbol */
.codehilite .bp { color: #007020 } /* Name.Builtin.Pseudo */
.codehilite .fm { color: #06287e } /* Name.Function.Magic */
.codehilite .vc { color: #bb60d5 } /* Name.Variable.Class */
.codehilite .vg { color: #bb60d5 } /* Name.Variable.Global */
.codehilite .vi { color: #bb60d5 } /* Name.Variable.Instance */
.codehilite .vm { color: #bb60d5 } /* Name.Variable.Magic */
.codehilite .il { color: #40a070 } /* Literal.Number.Integer.Long */
</style>
<h1 id="create-a-bundled-zip-or-other-archive">Create a Bundled zip or Other Archive</h1>
<h2 id="problem">Problem</h2>
<p>You're working on a Scala or Java project and you want to bundle your project into a single ZIP file or other archive.</p>
<p><strong>Note</strong>: If you're working on a Python project, you should compile a Python executable (a <code>.pex</code> file) instead of a bundle. More information can be found in <a href="run.html">Run a Binary Target</a>.</p>
<h2 id="solution">Solution</h2>
<p>The <code>pants bundle</code> command enables you to bundle a project into a single archive in the following file formats:</p>
<ul>
<li><code>.zip</code></li>
<li><code>.tgz</code></li>
<li><code>.tar</code></li>
<li><code>.tbz2</code></li>
</ul>
<p>In order to use the <code>bundle</code> goal, you need to target a <code>jvm_app</code> definition. Here's an example target:</p>
<div class="codehilite"><pre><span></span><span class="n">jvm_app</span><span class="p">(</span>
  <span class="n">name</span><span class="o">=</span><span class="s1">'bundle'</span><span class="p">,</span>
  <span class="n">basename</span><span class="o">=</span><span class="s1">'my-project-deployable-bundle'</span><span class="p">,</span>
  <span class="n">binary</span><span class="o">=</span><span class="s1">':my-binary-target'</span><span class="p">,</span> <span class="c1"># should point to a jvm_binary target</span>
<span class="p">)</span>
</pre></div>
<p>There are two ways to specify the desired file format:</p>
<h3 id="1-through-the-build-file-recommended">1. Through the <code>BUILD</code> file (recommended)</h3>
<p>Add an <code>archive</code> parameter to your <code>jvm_app</code> target. Here's an example:</p>
<div class="codehilite"><pre><span></span><span class="n">jvm_app</span><span class="p">(</span>
  <span class="n">name</span><span class="o">=</span><span class="s1">'bundle'</span><span class="p">,</span>
  <span class="n">archive</span><span class="o">=</span><span class="s1">'zip'</span><span class="p">,</span>
  <span class="c1"># etc</span>
<span class="p">)</span>
</pre></div>
<h3 id="2-via-the-command-line-which-can-override-1">2. Via the command line (which can override #1)</h3>
<p>Add a <code>--bundle-jvm-archive</code> option when invoking the Pants executable. Here's an example:</p>
<div class="codehilite"><pre><span></span>$ ./pants bundle src/java/com/myorg/myproject:bundle --bundle-jvm-archive<span class="o">=</span>zip
</pre></div>
<p><strong>Note</strong>: If you perform <em>neither</em> of the steps explained in #1 and #2, no bundle will be created.</p>
<h2 id="discussion">Discussion</h2>
<p>When bundling is complete, you can find the resulting archive in the <code>dist</code> directory of your Pants workspace. The name of the <code>.zip</code> file is the concatenation of the path to the <code>BUILD</code> file and the target name. In this example, the path for the bundle would be <code>dist/my-project.sub-project.my-project-deployable-bundle.zip</code> (<code>my-project.sub-project</code> is the period-delimited path to the <code>BUILD</code> file and <code>my-project-deployable-bundle</code> was the <code>basename</code> assigned to the target).</p>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="jvm_library.html">Define a Scala or Java Library Target</a></li>
</ul>

            <!-- main content end -->

            <div class="generated">
              Generated by <a href="docs.html">publish_docs</a>
              from dist/markdown/html/src/docs/common_tasks/bundle.html 2022-12-03T01:08:59.419893
            </div>

          </div> <!-- mainflow -->

        </div> <!-- content -->

      </div>

      <div class="col-md-1">
      </div>

    </div> <!-- row -->
  </div> <!-- container-fluid -->

</div> <!-- page -->

<script src="https://code.jquery.com/jquery-2.2.3.min.js" integrity="sha384-I6F5OKECLVtK/BL+8iSLDEHowSAfUo76ZL9+kGAgTRdiByINKJaqTPH/QVNS1VDb" crossorigin="anonymous"></script>
<script src="bootstrap-custom.min.js"></script>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-78111411-1', 'auto');
  ga('send', 'pageview');
</script>
</body>
</html>