<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/8.3.0/_book.yaml">
</head>
<body>

<h1 class="page-title" id="modules.File">File</h1>

{% dynamic setvar source_file "src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java" %}
{% dynamic setvar version "8.3.0" %}
{% dynamic setvar original_path "/rules/lib/builtins/File" %}
{% include "_buttons.html" %}
<!-- {% raw %} -->

This object is created during the analysis phase to represent a file or directory that will be read or written during the execution phase. It is not an open file handle, and cannot be used to directly read or write file contents. Rather, you use it to construct the action graph in a rule implementation function by passing it to action-creating functions. See the <a href='https://bazel.build/versions/8.3.0/extending/rules#files'>Rules page</a> for more information.<p>When a <code>File</code> is passed to an <a href='../builtins/Args.html'><code>Args</code></a> object without using a <code>map_each</code> function, it is converted to a string by taking the value of its <code>path</code> field.

<h2>Members</h2>
<ul>
    <li>
    <a href="#basename">basename</a>
  </li>
      <li>
    <a href="#dirname">dirname</a>
  </li>
      <li>
    <a href="#extension">extension</a>
  </li>
      <li>
    <a href="#is_directory">is_directory</a>
  </li>
      <li>
    <a href="#is_source">is_source</a>
  </li>
      <li>
    <a href="#is_symlink">is_symlink</a>
  </li>
      <li>
    <a href="#owner">owner</a>
  </li>
      <li>
    <a href="#path">path</a>
  </li>
      <li>
    <a href="#root">root</a>
  </li>
      <li>
    <a href="#short_path">short_path</a>
  </li>
      <li>
    <a href="#tree_relative_path">tree_relative_path</a>
  </li>
  </ul>

      <h2 id="basename">basename</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.basename</pre></p>

    The base name of this file. This is the name of the file inside the directory.


        <h2 id="dirname">dirname</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.dirname</pre></p>

    The name of the directory containing this file. It's taken from <a href="#path">path</a> and is always relative to the execution directory.


        <h2 id="extension">extension</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.extension</pre></p>

    The file extension of this file, following (not including) the rightmost period. Empty string if the file's basename includes no periods.


        <h2 id="is_directory">is_directory</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_directory</pre></p>

    Returns true if this is a directory. This reflects the type the file was declared as (i.e. ctx.actions.declare_directory), not its type on the filesystem, which might differ.


        <h2 id="is_source">is_source</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_source</pre></p>

    Returns true if this is a source file, i.e. it is not generated.


        <h2 id="is_symlink">is_symlink</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/bool.html">bool</a> File.is_symlink</pre></p>

    Returns true if this was declared as a symlink. This reflects the type the file was declared as (i.e. ctx.actions.declare_symlink), not its type on the filesystem, which might differ.


        <h2 id="owner">owner</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../builtins/Label.html">Label</a> File.owner</pre></p>

    A label of a target that produces this File.

         May return <code>None</code>.

        <h2 id="path">path</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.path</pre></p>

    The execution path of this file, relative to the workspace's execution directory. It consists of two parts, an optional first part called the <i>root</i> (see also the <a href="../builtins/root.html">root</a> module), and the second part which is the <code>short_path</code>. The root may be empty, which it usually is for non-generated files. For generated files it usually contains a configuration-specific path fragment that encodes things like the target CPU architecture that was used while building said file. Use the <code>short_path</code> for the path under which the file is mapped if it's in the runfiles of a binary.


        <h2 id="root">root</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../builtins/root.html">root</a> File.root</pre></p>

    The root beneath which this file resides.


        <h2 id="short_path">short_path</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.short_path</pre></p>

    The path of this file relative to its root. This excludes the aforementioned <i>root</i>, i.e. configuration-specific fragments of the path. This is also the path under which the file is mapped if it's in the runfiles of a binary.


        <h2 id="tree_relative_path">tree_relative_path</h2>
        <p><pre class="rule-signature"><a class="anchor" href="../core/string.html">string</a> File.tree_relative_path</pre></p>

    The path of this file relative to the root of the ancestor's tree, if the ancestor's <a href="#is_directory">is_directory</a> field is true. <code>tree_relative_path</code> is only available for expanded files of a directory in an action command, i.e. <a href="../builtins/Args.html#add_all">Args.add_all()</a>. For other types of files, it is an error to access this field.



</body>
</html>

<!-- {% endraw %} -->
