export.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>Export Format</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/export.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
        </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>
  </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-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 toc-heading">
                  JVM
                </li>
                <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 3rdparty Pattern</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>
                <li class="toc-h1 toc-heading">
                  Python
                </li>
                <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>
                <li class="toc-h1 toc-heading">
                  Go
                </li>
                <li class="toc-h1 toc-link ">
                  <a href="go_readme.html">Go support for Pants</a>
                </li>
                <li class="toc-h1 toc-heading">
                  Codegen
                </li>
                <li class="toc-h1 toc-link ">
                  <a href="thrift_deps.html">Thrift</a>
                </li>
                <li class="toc-h1 toc-heading">
                  Docgen
                </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 toc-heading">
                  Release Notes
                </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>
                <li class="toc-h1 toc-link ">
                  <a href="notes-master.html">Master Pre-Releases</a>
                </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 toc-here">
                  Export Format
                </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="#export-format">Export Format</a></li>
                    <li class="toc-h1"><a href="#top-level-fields">Top Level fields</a></li>
                    <li class="toc-h2"><a href="#version">Version</a></li>
                    <li class="toc-h2"><a href="#libraries">Libraries</a></li>
                    <li class="toc-h2"><a href="#targets">Targets</a></li>
                    <li class="toc-h1"><a href="#example-export-output">Example export output</a></li>
                    <li class="toc-h1"><a href="#export-format-changes">Export Format Changes</a></li>
                    <li class="toc-h2"><a href="#109">1.0.9</a></li>
                    <li class="toc-h2"><a href="#108">1.0.8</a></li>
                    <li class="toc-h2"><a href="#107">1.0.7</a></li>
                    <li class="toc-h2"><a href="#106">1.0.6</a></li>
                    <li class="toc-h2"><a href="#105">1.0.5</a></li>
                    <li class="toc-h2"><a href="#104">1.0.4</a></li>
                    <li class="toc-h2"><a href="#103">1.0.3</a></li>
                    <li class="toc-h2"><a href="#102">1.0.2</a></li>
                    <li class="toc-h2"><a href="#101">1.0.1</a></li>
                    <li class="toc-h2"><a href="#100">1.0.0</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 .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #007020 } /* Comment.Preproc */
.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: #808080 } /* 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: #0040D0 } /* 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 .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 .sb { color: #4070a0 } /* Literal.String.Backtick */
.codehilite .sc { color: #4070a0 } /* Literal.String.Char */
.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 .vc { color: #bb60d5 } /* Name.Variable.Class */
.codehilite .vg { color: #bb60d5 } /* Name.Variable.Global */
.codehilite .vi { color: #bb60d5 } /* Name.Variable.Instance */
.codehilite .il { color: #40a070 } /* Literal.Number.Integer.Long */
</style>
<h1 id="export-format">Export Format</h1>
<p>The configuration for a set of targets can be exported out of pants into JSON format using
the <code>pants export</code> goal.  This could useful for integrating Pants with another build tool.
The <a href="https://github.com/pantsbuild/intellij-pants-plugin">Pants Support IntelliJ plugin</a> uses
the export goal to get information out of Pants to configure IntelliJ.</p>
<p>This page captures the specification of the data provided by the export goal.
See the Changelog section below for differences between versions of the export format.</p>
<h1 id="top-level-fields">Top Level fields</h1>
<ul>
<li>"version" :  A string representing the version number of the export format.</li>
<li>"libraries" : Dictionary of paths to .jar files resolved by pants required to compile the
  project.</li>
<li>"targets" : Dictionary of targets defined in BUILD files.</li>
<li>"distributions" : Information about JVM distributions.</li>
<li>"jvm_platforms" : Information about JVM platforms(language level and additionals arguments).</li>
<li>"python_setup" : Information about Python setup(interpreters and chroots for them).</li>
</ul>
<h2 id="version">Version</h2>
<p>Version number for identifying the export file format output. This version number will
change when there is a change to the output format.  The version number specification is as follows:</p>
<p><code>&lt;major_version&gt;.&lt;minor_version&gt;.&lt;patch_version&gt;</code></p>
<ul>
<li><code>&lt;major_version&gt;</code> : Increment this field when there is a major format change</li>
<li><code>&lt;minor_version&gt;</code> : Increment this field when there is a minor change that breaks backward
     compatibility for an existing field or a field is removed.</li>
<li><code>&lt;patch_version&gt;</code> : Increment this field when a minor format change that just adds information
     that an application can safely ignore.</li>
</ul>
<h2 id="libraries">Libraries</h2>
<p>Represents all of the external jars that have been resolved by pants.  The value for libraries
is represented by a dictionary as follows:</p>
<p><code>{ &lt;jar_coordinate&gt; : { &lt;conf_name&gt; : &lt;jar_file&gt; } }</code></p>
<ul>
<li><code>&lt;jar_coordinate&gt;</code> : key representing this jar.  Usually <code>&lt;org&gt;:&lt;name&gt;:&lt;rev&gt;</code></li>
<li><code>&lt;conf_name&gt;</code> : Ivy conf this jar was resolved for.  Usually one of <code>default</code>, <code>sources</code>,
    or <code>javadoc</code></li>
<li><code>&lt;jar_file&gt;</code> : Path to the resolved jar file.</li>
</ul>
<h2 id="targets">Targets</h2>
<p>The targets field contains all of the targets exported from pants BUILD file definitions.  The
value for targets is represented by a dctionary of target specs mapped to a dictionary of the
fields defined in the target:</p>
<p><code>{ &lt;target_spec&gt; : &lt;target_field_mapping&gt; }</code></p>
<ul>
<li><code>&lt;target_spec&gt;</code> :  <code>"&lt;path_to_build_file&gt;:&lt;target_name&gt;"</code></li>
<li><code>&lt;target_field_mapping&gt;</code> : Dictionary of target fields  (TBD)</li>
</ul>
<h1 id="example-export-output">Example export output</h1>
<p>The following is an abbreviated export file from a command in the pants repo:</p>
<div class="codehilite"><pre>{
    "version": "1.0.4",
    "libraries": {
        "commons-logging:commons-logging:1.1.1": {
            "default": "/Users/user/.ivy2/pants/commons-logging/commons-logging/jars/commons-logging-1.1.1.jar"
        },
        "commons-codec:commons-codec:1.6": {
            "default": "/Users/user/.ivy2/pants/commons-codec/commons-codec/jars/commons-codec-1.6.jar"
        },
        "org.apache.httpcomponents:httpclient:4.2.5": {
            "default": "/Users/user/.ivy2/pants/org.apache.httpcomponents/httpclient/jars/httpclient-4.2.5.jar"
        },
        ...
    },
    # distributions settings provided as an example from another repo
    "distributions": {
        "darwin": [
            "/Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/Contents/Home",
            "/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home"
        ],
        "linux": [
            "/usr/java/jdk1.8.0_45",
            "/usr/java/jdk1.7.0_80"
        ]
    },
   "jvm_platforms": {
        "platforms": {
            "java6": {
                "source_level": "1.6",
                "args": [],
                "target_level": "1.6"
            }
        },
        "default_platform": "java6"
    },
    "python_setup": {
        "interpreters": {
            "CPython-2.7.10": {
                "binary": "/Users/user/pants/build-support/pants_dev_deps.venv/bin/python2.7",
                "chroot": "/Users/user/pants/.pants.d/python-setup/chroots/e8da2c200f36ca0a1b8a60c12590a59209250b1a"
            }
        },
        "default_interpreter": "CPython-2.7.10"
    },
    "targets": {
        "examples/tests/java/org/pantsbuild/example/usethrift:usethrift": {
            "is_code_gen": false,
            "excludes": [],
            "target_type": "TEST",
            "libraries": [
                "junit:junit:4.12",
                "org.hamcrest:hamcrest-core:1.3",
                "junit:junit:latest.integration"
            ],
            "platform": "java6",
            "pants_target_type": "junit_tests",
            "globs": {
                "globs": [
                    "examples/tests/java/org/pantsbuild/example/usethrift/UseThriftTest.java"
                ]
            },
            "targets": [
                "3rdparty:junit",
                "examples/src/thrift/org/pantsbuild/example/distance:distance-java",
                "examples/src/thrift/org/pantsbuild/example/precipitation:precipitation-java",
                ".pants.d/gen/thrift/isolated/examples.src.thrift.org.pantsbuild.example.distance.distance-java:examples.src.thrift.org.pantsbuild.example.distance.distance-java",
                ".pants.d/gen/thrift/isolated/examples.src.thrift.org.pantsbuild.example.precipitation.precipitation-java:examples.src.thrift.org.pantsbuild.example.precipitation.precipitation-java"
            ],
            "roots": [
                {
                    "source_root": "/Users/user/pants/examples/tests/java/org/pantsbuild/example/usethrift",
                    "package_prefix": "org.pantsbuild.example.usethrift"
                }
            ]
        },
        "examples/src/python/example/hello/greet:greet": {
            "is_code_gen": false,
            "python_interpreter": "CPython-2.7.10",
            "target_type": "SOURCE",
            "libraries": [],
            "pants_target_type": "python_library",
            "globs": {
                "globs": [
                    "examples/src/python/example/hello/greet/*.py"
                ]
            },
            "targets": [
                "3rdparty/python:ansicolors"
            ],
            "roots": [
                {
                    "source_root": "/Users/user/pants/examples/src/python/example/hello/greet",
                    "package_prefix": "example.hello.greet"
                }
            ]
        },

        ...
   }
}
</pre></div>
<h1 id="export-format-changes">Export Format Changes</h1>
<h2 id="109">1.0.9</h2>
<p>Added 'is_target_root' field to target</p>
<h2 id="108">1.0.8</h2>
<p>Conditionally added 'transitive' and 'scope' fields to target</p>
<h2 id="107">1.0.7</h2>
<p>Added 'test_platform' to target and 'preferred_jvm_distributions' section</p>
<h2 id="106">1.0.6</h2>
<p>Added 'is_synthetic' field to target</p>
<h2 id="105">1.0.5</h2>
<p>Added 'id' to target</p>
<h2 id="104">1.0.4</h2>
<p>If a target class is registered under multiple aliases returns the last one</p>
<h2 id="103">1.0.3</h2>
<p>Added information about jdk settings</p>
<h2 id="102">1.0.2</h2>
<p>Handle jars with classifiers</p>
<h2 id="101">1.0.1</h2>
<p>Information about excludes</p>
<h2 id="100">1.0.0</h2>
<p>Initial Version</p>

            <!-- main content end -->

            <div class="generated">
              Generated by <a href="docs.html">publish_docs</a>
              from dist/markdown/html/src/docs/export.html 2017-05-29T10:30:50.590411
            </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>