// Copyright 2018 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.lib.skylarkbuildapi; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkValue; /** * The interface for files in Skylark. */ @SkylarkModule( name = "File", category = SkylarkModuleCategory.BUILTIN, doc = "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 " + "Rules page for more information." + "" + "
When a File
is passed to an Args
"
+ "object without using a map_each
function, it is converted to a string by "
+ "taking the value of its path
field."
)
public interface FileApi extends SkylarkValue {
@SkylarkCallable(name = "dirname", structField = true,
doc = "The name of the directory containing this file. It's taken from "
+ "path and is always relative to the execution directory.")
public String getDirname();
@SkylarkCallable(name = "basename", structField = true,
doc = "The base name of this file. This is the name of the file inside the directory.")
public String getFilename();
@SkylarkCallable(name = "extension", structField = true, doc = "The file extension of this file.")
public String getExtension();
@SkylarkCallable(name = "owner", structField = true, allowReturnNones = true,
doc = "A label of a target that produces this File."
)
public Label getOwnerLabel();
@SkylarkCallable(
name = "root",
structField = true,
doc = "The root beneath which this file resides."
)
public FileRootApi getRoot();
@SkylarkCallable(
name = "is_source",
structField = true,
doc = "Returns true if this is a source file, i.e. it is not generated."
)
public boolean isSourceArtifact();
// TODO(rduan): Document this Skylark method once TreeArtifact is no longer experimental.
@SkylarkCallable(name = "is_directory", structField = true, documented = false)
public boolean isTreeArtifact();
@SkylarkCallable(
name = "short_path",
structField = true,
doc =
"The path of this file relative to its root. This excludes the aforementioned "
+ "root, 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."
)
public String getRunfilesPathString();
@SkylarkCallable(
name = "path",
structField = true,
doc =
"The execution path of this file, relative to the workspace's execution directory. It "
+ "consists of two parts, an optional first part called the root (see also the "
+ "root module), and the second part which is the "
+ "short_path
. 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 "
+ "short_path
for the path under which the file is mapped if it's in the "
+ "runfiles of a binary."
)
public String getExecPathString();
}