1 /* 2 * Copyright 2014 Google Inc. All rights reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 syntax = "proto3"; 18 19 package kythe.proto; 20 option java_package = "com.google.devtools.kythe.proto"; 21 22 import "google/protobuf/any.proto"; 23 import "kythe/proto/storage.proto"; 24 25 // CompilationAnalyzer services are exposed by any program that wants to plug 26 // into the Kythe pipeline to perform per-compilation analysis. 27 service CompilationAnalyzer { 28 // Analyze is the main entry point for the analysis driver to send work to the 29 // analyzer. The analysis may produce many outputs which will be streamed as 30 // framed AnalysisOutput messages. 31 // 32 // A driver may choose to retry analyses that return RPC errors. It should 33 // not retry analyses that are reported as finished unless it is necessary to 34 // recover from an external production issue. 35 rpc Analyze(AnalysisRequest) returns (stream AnalysisOutput) {} 36 } 37 38 // FileDataServices are used by a CompilationAnalyzer to retrieve the contents of 39 // input files required for analysis. 40 service FileDataService { 41 // Get returns the contents of one or more files needed for analysis. It is 42 // the server's responsibility to do any caching necessary to make this 43 // perform well, so that an analyzer does not need to implement its own 44 // caches unless it is doing something unusual. 45 // 46 // For each distinct path/digest pair in the request, the server must return 47 // exactly one response. The order of the responses is arbitrary. 48 // 49 // For each requested file, one or both of the path and digest fields must be 50 // nonempty, otherwise an error is returned. It is not an error for there to 51 // be no requested files, however. 52 rpc Get(FilesRequest) returns (stream FileData) {} 53 } 54 55 // An AnalysisRequest instructs an analyzer to perform an analysis on a single 56 // CompilationUnit. 57 message AnalysisRequest { 58 // The compilation to analyze. 59 CompilationUnit compilation = 1; 60 61 // The address of a file data service to use. If this is provided, it should 62 // be used in preference to any other file data service the analyzer may know 63 // about for this compilation. 64 string file_data_service = 2; 65 } 66 67 // AnalysisOutput contains an output artifact for the current analysis taking 68 // place. A given analysis may not produce any outputs. It is okay for an 69 // indexer to send an empty AnalysisOutput message if needed to keep the RPC 70 // channel alive; the driver must correctly handle this. 71 message AnalysisOutput { 72 bytes value = 1; 73 } 74 75 // Describes a single unit of compilation. 76 message CompilationUnit { 77 // The base VName for the compilation and any generated VNames from its 78 // analysis. Generally, the `language` component designates the language of 79 // the compilation's sources. 80 VName v_name = 1; 81 82 // The revision of the compilation. 83 string revision = 2; 84 85 // All files that might be touched in the course of this compilation. 86 // Consumers of the CompilationUnit may not assume anything about the order 87 // of the elements of this field. 88 repeated FileInput required_input = 3; 89 90 // Set by the extractor to indicate that the original input had compile 91 // errors. This is used to check validity of the sharded analysis. 92 bool has_compile_errors = 4; 93 94 // The arguments to pass to a compiler tool for this compilation unit, 95 // including the compiler executable, flags, and input files. 96 repeated string argument = 5; 97 98 // Of those files in `required_input`, the ones that this CompilationUnit 99 // is intended to analyze. This is necessary to support languages like Go, 100 // where a single translation unit may contain many source files that must all 101 // be processed at once (while excluding source files that belong to other 102 // CUs/packages, if any). 103 repeated string source_file = 6; 104 105 // The output key of the CompilationUnit; for example, the object file that 106 // it writes. The output key for a compilation should match the path in the 107 // FileInfo message of a dependent compilation that consumes its output. 108 string output_key = 7; 109 110 // ContextDependentVersionColumn and ContextDependentVersionRow 111 // define a table that relates input contexts (keyed by a single 112 // source context per row) to tuples of (byte offset * linked context). 113 // When a FileInput F being processed in context C refers to another 114 // FileInput F' at offset O (perhaps because F has an #include directive at O) 115 // the context in which F' should be processed is the linked context derived 116 // from this table. 117 message ContextDependentVersionColumn { 118 // The byte offset into the file resource. 119 int32 offset = 1; 120 // The signature for the resulting context. 121 string linked_context = 2; 122 } 123 124 // See ContextDependentVersionColumn for details. 125 // It is valid for a ContextDependentVersionRow to have no columns. In this 126 // case, the associated FileInput was seen to exist in some context C, but 127 // did not refer to any other FileInputs while in that context. 128 message ContextDependentVersionRow { 129 // The context to be applied to all columns. 130 string source_context = 1; 131 // A map from byte offsets to linked contexts. 132 repeated ContextDependentVersionColumn column = 2; 133 // If true, this version should always be processed regardless of any 134 // claiming. 135 bool always_process = 3; 136 } 137 138 message FileInput { 139 // If set, overrides the `v_name` in the `CompilationUnit` for deriving 140 // VNames during analysis. 141 VName v_name = 1; 142 143 // The file's metadata. It is invalid to provide a FileInput without both 144 // the file's path and digest. 145 FileInfo info = 2; 146 147 // The file's context-dependent versions. 148 repeated ContextDependentVersionRow context = 3; 149 } 150 151 // The absolute path of the current working directory where the build tool 152 // was invoked. During analysis, a file whose path has working_directory 153 // plus a path separator as an exact prefix is considered accessible from 154 // that same path without said prefix. It is only necessary to set this 155 // field if the build tool requires it. 156 string working_directory = 8; 157 158 // For languages that make use of resource contexts (like C++), the context 159 // that should be initially entered. 160 // TODO(zarko): What is a "resource context"? Needs a clear definition and/or 161 // a link to one. 162 string entry_context = 9; 163 164 // An Env message represents the name and value of a single environment 165 // variable in the build environment. 166 message Env { 167 string name = 1; 168 string value = 2; 169 } 170 171 // A collection of environment variables that the build environment expects 172 // to be set. As a rule, we only record variables here that must be set to 173 // specific values for the build to work. Users of this field may not assume 174 // anything about the order of values; in particular the pipeline is free to 175 // sort by name in order to canonicalize the message. 176 repeated Env environment = 10; 177 178 // Per-language or per-tool details. 179 repeated google.protobuf.Any details = 11; 180 } 181 182 // A FilesRequest specifies a collection of files to be fetched from a 183 // FileDataService. 184 message FilesRequest { 185 repeated FileInfo files = 1; 186 } 187 188 // A FileInfo identifies a file used for analysis. 189 // At least one of the path and digest fields must be non-empty. 190 message FileInfo { 191 // The path of the file relative to the working directory of the compilation 192 // command, which is typically the root of the build. 193 // For example: 194 // file/base/file.cc 195 // ../../base/atomic_ref_count.h 196 string path = 1; 197 198 // The lowercase ascii hex SHA-256 digest of the file contents. 199 string digest = 2; 200 } 201 202 // A FileData carries the content of a single file, as returned from the Get 203 // method of a FileDataService. 204 message FileData { 205 // The content of the file, if known. If missing == true, this field must be 206 // empty. 207 bytes content = 1; 208 209 // A (possibly normalized) copy of the non-empty fields of the FileInfo 210 // message from the Get request. If either field from the original request 211 // was empty, the server may optionally fill in that field in the reply if it 212 // is known. For example, if the client requested a file by path only and 213 // the server found it, the reply MAY fill in the digest. 214 FileInfo info = 2; 215 216 // If true, no data are available for the requested file, and the content 217 // field must be empty. If false, the content field contains the complete 218 // file content (which may be empty). 219 bool missing = 3; 220 } 221