Permalink
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (185 sloc) 8.31 KB
/*
* 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";
option cc_enable_arenas = true;
import "google/protobuf/any.proto";
import "kythe/proto/filecontext.proto";
import "kythe/proto/storage.proto";
// 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;
// The revision marker that should be attributed to this compilation.
string revision = 3;
// An identifier for the current analysis.
string build_id = 4;
}
// 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.
//
// The format of value is determined by the analyzer. Kythe language indexers
// emit wire-format kythe.proto.Entry messages.
message AnalysisOutput {
bytes value = 1;
// An analyzer may optionally report the final result of analysis by
// populating this field in the last output it emits.
//
// Constraints: If final_result is set, value must be unset, and once a
// final_result has been sent no further outputs may be sent. The driver must
// enforce these constraints by aborting and discarding the request if the
// analyzer sends additional data after the final_result. It is legal for the
// analyzer to omit any final_result, in which case the driver will assume
// that the analysis was completed successfully.
AnalysisResult final_result = 10;
// TODO(fromberger): Convert these fields to a single oneof, to enforce the
// mutual exclusion explicitly. For now I'm leaving them separate to make it
// easier to migrate existing uses.
}
// AnalysisResult documents the analyzer's opinion of an analysis request.
message AnalysisResult {
enum Status {
COMPLETE = 0; // analysis completed successfully without error
INCOMPLETE = 1; // analysis ended after partial results
INVALID_REQUEST = 2; // the analysis request was invalid for this analyzer
}
Status status = 1; // the status code describing the result
string summary = 2; // a human-readable error message for use in diagnostics
}
// 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;
reserved 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;
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 version table.
// TODO(schroederc): add as a details message
ContextDependentVersion context = 3 [deprecated = true];
// Per-language or per-tool details.
repeated google.protobuf.Any details = 4;
}
// 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;
}
// A CompilationBundle carries a CompilationUnit and its required FileData.
message CompilationBundle {
// The CompilationUnit to be analyzed.
CompilationUnit unit = 1;
// File data for the CompilationUnit's required_input.
repeated FileData files = 2;
}
// A compilation unit combined with index terms.
message IndexedCompilation {
CompilationUnit unit = 1;
Index index = 2;
message Index {
// Revision markers at which this compilation record is indexed.
repeated string revisions = 1;
}
}