| /* |
| * Copyright 2014 The Kythe 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. |
| */ |
| |
| syntax = "proto3"; |
| |
| package kythe.proto; |
| |
| option go_package = "analysis_go_proto"; |
| option java_package = "com.google.devtools.kythe.proto"; |
| option cc_enable_arenas = true; |
| |
| import "google/protobuf/any.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 VNames generated from its |
| // analysis. The `v_name` field does not identify a compilation unit, but |
| // provides the information the analyzer needs to correctly label the |
| // entities described by its source. At minimum, this should include the |
| // `corpus` and `language` the unit belongs to, and if appropriate the |
| // `root`. The `v_name` of an object in the code is formed by merging its |
| // specifics into this basis. |
| // |
| // This VName also serves as the default basis for any required inputs that |
| // do not provide their own `v_name` field. As such, the general logic for |
| // constructing VNames for entities arising a given source path should be: |
| // { |
| // corpus: unit.required_input[path].v_name.corpus OR unit.v_name.corpus |
| // root: unit.required_input[path].v_name.root OR unit.v_name.root |
| // path: unit.required_input[path].v_name.path OR path |
| // } |
| // The above applies generally, but specific node kinds may have rules which |
| // override this logic. |
| 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. Values for fields which are not explicitly set |
| // should be taken from the CompilationUnit's VName or (for path) FileInfo. |
| 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; |
| |
| reserved 3; |
| |
| // 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; |
| } |
| } |