xsbti

Interface VirtualFileRef

All Known Subinterfaces:

PathBasedFile, VirtualDirectory, VirtualFile, VirtualFileWrite

All Known Implementing Classes:

BasicVirtualFileRef

public interface VirtualFileRef

VirtualFileRef represents a reference to a file-like object. Unlike java.io.File or java.nio.file.Path that are tied to filesystem-related capabilities, VirtualFileRef is designed to be a less-capable pointer to an object whose main feature is having a path-like identity. The equality is expected to be implemented using the equality of the id() alone. See BasicVirtualFileRef.

VirtualFile, a subtype of VirtualFileRef supports minimally viable file-like opration needed for compilation. To illustrate the difference between the two, consider the following flow of operation.

Flow of operation

Suppose that there are two people Alice and Bob who are working on the same repo. On Alice's machine, the build tool would construct an instance of FileConverter used for the entire build. The reference implementation is sbt.internal.inc.MappedFileConverter. The build tool would pass the usual suspect of absolute paths to this MappedFileConverter such as the base directory of the working directory, Coursier cache directory, etc. Given the sequence of Scala and Java source files, MappedFileConverter will create a sequence of MappedVirtualFile whose id would look like ${BASE}/src/main/example/A.scala.

When Alice runs the compilation, Analysis file will store the VirtualFileRef represented by its id. This extends not only to the source files, but also to *.class products and library JAR files. See MRelationsNameHashing.

Suppose then we are able to package the Analysis together with the *.class files in a JAR file, Bob on a different machine can extract it, and have the same Analysis file. The only difference would be that on his machine the build tool would have created a slightly different FileConverter with different base paths. Because ${BASE}/src/main/example/A.scala would still be called the same, hopefully he can resume incremental compilation.

Difference between VirtualFileRef and VirtualFile

VirtualFileRef on its own can only have identity information to be compared against another. At the most basic level this could be implemented as BasicVirtualFileRef that has no ability of reading the content. On the other hand, VirtualFile is internally able to thaw itself back to the "real" file with the help of the FileConverter, and thus it might even be aware of the absolute paths.

So when we look at the two types VirtualFileRef and VirtualFile, VirtualFileRef could represent a "path" for either the local machine or someone else's machine; on the other hand, VirtualFile would represent something more concrete, like a local file or an in-memory file.

ok, so how would the compiler compile this?

See IncrementalCompile.scala. At the top layer of Zinc, we are passing in the source files as a sequence of VirtualFiles. The files then gets wrapped by a datatype called AbstractZincFile, which extends scala.reflect.io.AbstractFile, which the compiler is able to compile.

Method Summary

Modifier and Type	Method and Description
java.lang.String	id() Returns unique identifier for the file.
java.lang.String	name() Returns "file name" for the file.
java.lang.String[]	names()
static VirtualFileRef	of(java.lang.String id)

Method Detail

of

static VirtualFileRef of(java.lang.String id)

id

java.lang.String id()

Returns unique identifier for the file. For Java compilation it needs to contain the path structure matching the package name for example com/acme/Foo.java. It also must end with the same value as name(), Java files must end with ".java", and Scala files must end with ".scala".

name

java.lang.String name()

Returns "file name" for the file. Java files must end with ".java", and Scala files must end with ".scala".

names

java.lang.String[] names()