220 lines
8.8 KiB
Protocol Buffer
220 lines
8.8 KiB
Protocol Buffer
/*
|
|
* Copyright 2014 Google Inc. 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.
|
|
*/
|
|
|
|
syntax = "proto3";
|
|
|
|
package kythe.proto;
|
|
option java_package = "com.google.devtools.kythe.proto";
|
|
|
|
import "google/protobuf/any.proto";
|
|
import "kythe/proto/storage.proto";
|
|
|
|
// CompilationAnalyzer services are exposed by any program that wants to plug
|
|
// into the Kythe pipeline to perform per-compilation analysis.
|
|
service CompilationAnalyzer {
|
|
// Analyze is the main entry point for the analysis driver to send work to the
|
|
// analyzer. The analysis may produce many outputs which will be streamed as
|
|
// framed AnalysisOutput messages.
|
|
//
|
|
// A driver may choose to retry analyses that return RPC errors. It should
|
|
// not retry analyses that are reported as finished unless it is necessary to
|
|
// recover from an external production issue.
|
|
rpc Analyze(AnalysisRequest) returns (stream AnalysisOutput) {}
|
|
}
|
|
|
|
// FileDataServices are used by a CompilationAnalyzer to retrieve the contents of
|
|
// input files required for analysis.
|
|
service FileDataService {
|
|
// Get returns the contents of one or more files needed for analysis. It is
|
|
// the server's responsibility to do any caching necessary to make this
|
|
// perform well, so that an analyzer does not need to implement its own
|
|
// caches unless it is doing something unusual.
|
|
//
|
|
// For each distinct path/digest pair in the request, the server must return
|
|
// exactly one response. The order of the responses is arbitrary.
|
|
//
|
|
// For each requested file, one or both of the path and digest fields must be
|
|
// nonempty, otherwise an error is returned. It is not an error for there to
|
|
// be no requested files, however.
|
|
rpc Get(FilesRequest) returns (stream FileData) {}
|
|
}
|
|
|
|
// An AnalysisRequest instructs an analyzer to perform an analysis on a single
|
|
// CompilationUnit.
|
|
message AnalysisRequest {
|
|
// The compilation to analyze.
|
|
CompilationUnit compilation = 1;
|
|
|
|
// The address of a file data service to use. If this is provided, it should
|
|
// be used in preference to any other file data service the analyzer may know
|
|
// about for this compilation.
|
|
string file_data_service = 2;
|
|
}
|
|
|
|
// AnalysisOutput contains an output artifact for the current analysis taking
|
|
// place. A given analysis may not produce any outputs. It is okay for an
|
|
// indexer to send an empty AnalysisOutput message if needed to keep the RPC
|
|
// channel alive; the driver must correctly handle this.
|
|
message AnalysisOutput {
|
|
bytes value = 1;
|
|
}
|
|
|
|
// Describes a single unit of compilation.
|
|
message CompilationUnit {
|
|
// The base VName for the compilation and any generated VNames from its
|
|
// analysis. Generally, the `language` component designates the language of
|
|
// the compilation's sources.
|
|
VName v_name = 1;
|
|
|
|
// The revision of the compilation.
|
|
string revision = 2;
|
|
|
|
// All files that might be touched in the course of this compilation.
|
|
// Consumers of the CompilationUnit may not assume anything about the order
|
|
// of the elements of this field.
|
|
repeated FileInput required_input = 3;
|
|
|
|
// Set by the extractor to indicate that the original input had compile
|
|
// errors. This is used to check validity of the sharded analysis.
|
|
bool has_compile_errors = 4;
|
|
|
|
// The arguments to pass to a compiler tool for this compilation unit,
|
|
// including the compiler executable, flags, and input files.
|
|
repeated string argument = 5;
|
|
|
|
// Of those files in `required_input`, the ones that this CompilationUnit
|
|
// is intended to analyze. This is necessary to support languages like Go,
|
|
// where a single translation unit may contain many source files that must all
|
|
// be processed at once (while excluding source files that belong to other
|
|
// CUs/packages, if any).
|
|
repeated string source_file = 6;
|
|
|
|
// The output key of the CompilationUnit; for example, the object file that
|
|
// it writes. The output key for a compilation should match the path in the
|
|
// FileInfo message of a dependent compilation that consumes its output.
|
|
string output_key = 7;
|
|
|
|
// ContextDependentVersionColumn and ContextDependentVersionRow
|
|
// define a table that relates input contexts (keyed by a single
|
|
// source context per row) to tuples of (byte offset * linked context).
|
|
// When a FileInput F being processed in context C refers to another
|
|
// FileInput F' at offset O (perhaps because F has an #include directive at O)
|
|
// the context in which F' should be processed is the linked context derived
|
|
// from this table.
|
|
message ContextDependentVersionColumn {
|
|
// The byte offset into the file resource.
|
|
int32 offset = 1;
|
|
// The signature for the resulting context.
|
|
string linked_context = 2;
|
|
}
|
|
|
|
// See ContextDependentVersionColumn for details.
|
|
// It is valid for a ContextDependentVersionRow to have no columns. In this
|
|
// case, the associated FileInput was seen to exist in some context C, but
|
|
// did not refer to any other FileInputs while in that context.
|
|
message ContextDependentVersionRow {
|
|
// The context to be applied to all columns.
|
|
string source_context = 1;
|
|
// A map from byte offsets to linked contexts.
|
|
repeated ContextDependentVersionColumn column = 2;
|
|
// If true, this version should always be processed regardless of any
|
|
// claiming.
|
|
bool always_process = 3;
|
|
}
|
|
|
|
message FileInput {
|
|
// If set, overrides the `v_name` in the `CompilationUnit` for deriving
|
|
// VNames during analysis.
|
|
VName v_name = 1;
|
|
|
|
// The file's metadata. It is invalid to provide a FileInput without both
|
|
// the file's path and digest.
|
|
FileInfo info = 2;
|
|
|
|
// The file's context-dependent versions.
|
|
repeated ContextDependentVersionRow context = 3;
|
|
}
|
|
|
|
// The absolute path of the current working directory where the build tool
|
|
// was invoked. During analysis, a file whose path has working_directory
|
|
// plus a path separator as an exact prefix is considered accessible from
|
|
// that same path without said prefix. It is only necessary to set this
|
|
// field if the build tool requires it.
|
|
string working_directory = 8;
|
|
|
|
// For languages that make use of resource contexts (like C++), the context
|
|
// that should be initially entered.
|
|
// TODO(zarko): What is a "resource context"? Needs a clear definition and/or
|
|
// a link to one.
|
|
string entry_context = 9;
|
|
|
|
// An Env message represents the name and value of a single environment
|
|
// variable in the build environment.
|
|
message Env {
|
|
string name = 1;
|
|
string value = 2;
|
|
}
|
|
|
|
// A collection of environment variables that the build environment expects
|
|
// to be set. As a rule, we only record variables here that must be set to
|
|
// specific values for the build to work. Users of this field may not assume
|
|
// anything about the order of values; in particular the pipeline is free to
|
|
// sort by name in order to canonicalize the message.
|
|
repeated Env environment = 10;
|
|
|
|
// Per-language or per-tool details.
|
|
repeated google.protobuf.Any details = 11;
|
|
}
|
|
|
|
// A FilesRequest specifies a collection of files to be fetched from a
|
|
// FileDataService.
|
|
message FilesRequest {
|
|
repeated FileInfo files = 1;
|
|
}
|
|
|
|
// A FileInfo identifies a file used for analysis.
|
|
// At least one of the path and digest fields must be non-empty.
|
|
message FileInfo {
|
|
// The path of the file relative to the working directory of the compilation
|
|
// command, which is typically the root of the build.
|
|
// For example:
|
|
// file/base/file.cc
|
|
// ../../base/atomic_ref_count.h
|
|
string path = 1;
|
|
|
|
// The lowercase ascii hex SHA-256 digest of the file contents.
|
|
string digest = 2;
|
|
}
|
|
|
|
// A FileData carries the content of a single file, as returned from the Get
|
|
// method of a FileDataService.
|
|
message FileData {
|
|
// The content of the file, if known. If missing == true, this field must be
|
|
// empty.
|
|
bytes content = 1;
|
|
|
|
// A (possibly normalized) copy of the non-empty fields of the FileInfo
|
|
// message from the Get request. If either field from the original request
|
|
// was empty, the server may optionally fill in that field in the reply if it
|
|
// is known. For example, if the client requested a file by path only and
|
|
// the server found it, the reply MAY fill in the digest.
|
|
FileInfo info = 2;
|
|
|
|
// If true, no data are available for the requested file, and the content
|
|
// field must be empty. If false, the content field contains the complete
|
|
// file content (which may be empty).
|
|
bool missing = 3;
|
|
}
|