1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // http://code.google.com/p/protobuf/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 // Author: kenton (at) google.com (Kenton Varda) 32 // Based on original Protocol Buffers design by 33 // Sanjay Ghemawat, Jeff Dean, and others. 34 // 35 // Implements the Protocol Compiler front-end such that it may be reused by 36 // custom compilers written to support other languages. 37 38 #ifndef GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__ 39 #define GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__ 40 41 #include <google/protobuf/stubs/common.h> 42 #include <string> 43 #include <vector> 44 #include <map> 45 #include <set> 46 #include <utility> 47 48 namespace google { 49 namespace protobuf { 50 51 class FileDescriptor; // descriptor.h 52 class DescriptorPool; // descriptor.h 53 class FileDescriptorProto; // descriptor.pb.h 54 template<typename T> class RepeatedPtrField; // repeated_field.h 55 56 namespace compiler { 57 58 class CodeGenerator; // code_generator.h 59 class GeneratorContext; // code_generator.h 60 class DiskSourceTree; // importer.h 61 62 // This class implements the command-line interface to the protocol compiler. 63 // It is designed to make it very easy to create a custom protocol compiler 64 // supporting the languages of your choice. For example, if you wanted to 65 // create a custom protocol compiler binary which includes both the regular 66 // C++ support plus support for your own custom output "Foo", you would 67 // write a class "FooGenerator" which implements the CodeGenerator interface, 68 // then write a main() procedure like this: 69 // 70 // int main(int argc, char* argv[]) { 71 // google::protobuf::compiler::CommandLineInterface cli; 72 // 73 // // Support generation of C++ source and headers. 74 // google::protobuf::compiler::cpp::CppGenerator cpp_generator; 75 // cli.RegisterGenerator("--cpp_out", &cpp_generator, 76 // "Generate C++ source and header."); 77 // 78 // // Support generation of Foo code. 79 // FooGenerator foo_generator; 80 // cli.RegisterGenerator("--foo_out", &foo_generator, 81 // "Generate Foo file."); 82 // 83 // return cli.Run(argc, argv); 84 // } 85 // 86 // The compiler is invoked with syntax like: 87 // protoc --cpp_out=outdir --foo_out=outdir --proto_path=src src/foo.proto 88 // 89 // For a full description of the command-line syntax, invoke it with --help. 90 class LIBPROTOC_EXPORT CommandLineInterface { 91 public: 92 CommandLineInterface(); 93 ~CommandLineInterface(); 94 95 // Register a code generator for a language. 96 // 97 // Parameters: 98 // * flag_name: The command-line flag used to specify an output file of 99 // this type. The name must start with a '-'. If the name is longer 100 // than one letter, it must start with two '-'s. 101 // * generator: The CodeGenerator which will be called to generate files 102 // of this type. 103 // * help_text: Text describing this flag in the --help output. 104 // 105 // Some generators accept extra parameters. You can specify this parameter 106 // on the command-line by placing it before the output directory, separated 107 // by a colon: 108 // protoc --foo_out=enable_bar:outdir 109 // The text before the colon is passed to CodeGenerator::Generate() as the 110 // "parameter". 111 void RegisterGenerator(const string& flag_name, 112 CodeGenerator* generator, 113 const string& help_text); 114 115 // Register a code generator for a language. 116 // Besides flag_name you can specify another option_flag_name that could be 117 // used to pass extra parameters to the registered code generator. 118 // Suppose you have registered a generator by calling: 119 // command_line_interface.RegisterGenerator("--foo_out", "--foo_opt", ...) 120 // Then you could invoke the compiler with a command like: 121 // protoc --foo_out=enable_bar:outdir --foo_opt=enable_baz 122 // This will pass "enable_bar,enable_baz" as the parameter to the generator. 123 void RegisterGenerator(const string& flag_name, 124 const string& option_flag_name, 125 CodeGenerator* generator, 126 const string& help_text); 127 128 // Enables "plugins". In this mode, if a command-line flag ends with "_out" 129 // but does not match any registered generator, the compiler will attempt to 130 // find a "plugin" to implement the generator. Plugins are just executables. 131 // They should live somewhere in the PATH. 132 // 133 // The compiler determines the executable name to search for by concatenating 134 // exe_name_prefix with the unrecognized flag name, removing "_out". So, for 135 // example, if exe_name_prefix is "protoc-" and you pass the flag --foo_out, 136 // the compiler will try to run the program "protoc-foo". 137 // 138 // The plugin program should implement the following usage: 139 // plugin [--out=OUTDIR] [--parameter=PARAMETER] PROTO_FILES < DESCRIPTORS 140 // --out indicates the output directory (as passed to the --foo_out 141 // parameter); if omitted, the current directory should be used. --parameter 142 // gives the generator parameter, if any was provided. The PROTO_FILES list 143 // the .proto files which were given on the compiler command-line; these are 144 // the files for which the plugin is expected to generate output code. 145 // Finally, DESCRIPTORS is an encoded FileDescriptorSet (as defined in 146 // descriptor.proto). This is piped to the plugin's stdin. The set will 147 // include descriptors for all the files listed in PROTO_FILES as well as 148 // all files that they import. The plugin MUST NOT attempt to read the 149 // PROTO_FILES directly -- it must use the FileDescriptorSet. 150 // 151 // The plugin should generate whatever files are necessary, as code generators 152 // normally do. It should write the names of all files it generates to 153 // stdout. The names should be relative to the output directory, NOT absolute 154 // names or relative to the current directory. If any errors occur, error 155 // messages should be written to stderr. If an error is fatal, the plugin 156 // should exit with a non-zero exit code. 157 void AllowPlugins(const string& exe_name_prefix); 158 159 // Run the Protocol Compiler with the given command-line parameters. 160 // Returns the error code which should be returned by main(). 161 // 162 // It may not be safe to call Run() in a multi-threaded environment because 163 // it calls strerror(). I'm not sure why you'd want to do this anyway. 164 int Run(int argc, const char* const argv[]); 165 166 // Call SetInputsAreCwdRelative(true) if the input files given on the command 167 // line should be interpreted relative to the proto import path specified 168 // using --proto_path or -I flags. Otherwise, input file names will be 169 // interpreted relative to the current working directory (or as absolute 170 // paths if they start with '/'), though they must still reside inside 171 // a directory given by --proto_path or the compiler will fail. The latter 172 // mode is generally more intuitive and easier to use, especially e.g. when 173 // defining implicit rules in Makefiles. 174 void SetInputsAreProtoPathRelative(bool enable) { 175 inputs_are_proto_path_relative_ = enable; 176 } 177 178 // Provides some text which will be printed when the --version flag is 179 // used. The version of libprotoc will also be printed on the next line 180 // after this text. 181 void SetVersionInfo(const string& text) { 182 version_info_ = text; 183 } 184 185 186 private: 187 // ----------------------------------------------------------------- 188 189 class ErrorPrinter; 190 class GeneratorContextImpl; 191 class MemoryOutputStream; 192 193 // Clear state from previous Run(). 194 void Clear(); 195 196 // Remaps each file in input_files_ so that it is relative to one of the 197 // directories in proto_path_. Returns false if an error occurred. This 198 // is only used if inputs_are_proto_path_relative_ is false. 199 bool MakeInputsBeProtoPathRelative( 200 DiskSourceTree* source_tree); 201 202 // Return status for ParseArguments() and InterpretArgument(). 203 enum ParseArgumentStatus { 204 PARSE_ARGUMENT_DONE_AND_CONTINUE, 205 PARSE_ARGUMENT_DONE_AND_EXIT, 206 PARSE_ARGUMENT_FAIL 207 }; 208 209 // Parse all command-line arguments. 210 ParseArgumentStatus ParseArguments(int argc, const char* const argv[]); 211 212 // Parses a command-line argument into a name/value pair. Returns 213 // true if the next argument in the argv should be used as the value, 214 // false otherwise. 215 // 216 // Exmaples: 217 // "-Isrc/protos" -> 218 // name = "-I", value = "src/protos" 219 // "--cpp_out=src/foo.pb2.cc" -> 220 // name = "--cpp_out", value = "src/foo.pb2.cc" 221 // "foo.proto" -> 222 // name = "", value = "foo.proto" 223 bool ParseArgument(const char* arg, string* name, string* value); 224 225 // Interprets arguments parsed with ParseArgument. 226 ParseArgumentStatus InterpretArgument(const string& name, 227 const string& value); 228 229 // Print the --help text to stderr. 230 void PrintHelpText(); 231 232 // Generate the given output file from the given input. 233 struct OutputDirective; // see below 234 bool GenerateOutput(const vector<const FileDescriptor*>& parsed_files, 235 const OutputDirective& output_directive, 236 GeneratorContext* generator_context); 237 bool GeneratePluginOutput(const vector<const FileDescriptor*>& parsed_files, 238 const string& plugin_name, 239 const string& parameter, 240 GeneratorContext* generator_context, 241 string* error); 242 243 // Implements --encode and --decode. 244 bool EncodeOrDecode(const DescriptorPool* pool); 245 246 // Implements the --descriptor_set_out option. 247 bool WriteDescriptorSet(const vector<const FileDescriptor*> parsed_files); 248 249 // Get all transitive dependencies of the given file (including the file 250 // itself), adding them to the given list of FileDescriptorProtos. The 251 // protos will be ordered such that every file is listed before any file that 252 // depends on it, so that you can call DescriptorPool::BuildFile() on them 253 // in order. Any files in *already_seen will not be added, and each file 254 // added will be inserted into *already_seen. If include_source_code_info is 255 // true then include the source code information in the FileDescriptorProtos. 256 static void GetTransitiveDependencies( 257 const FileDescriptor* file, 258 bool include_source_code_info, 259 set<const FileDescriptor*>* already_seen, 260 RepeatedPtrField<FileDescriptorProto>* output); 261 262 // ----------------------------------------------------------------- 263 264 // The name of the executable as invoked (i.e. argv[0]). 265 string executable_name_; 266 267 // Version info set with SetVersionInfo(). 268 string version_info_; 269 270 // Registered generators. 271 struct GeneratorInfo { 272 string flag_name; 273 string option_flag_name; 274 CodeGenerator* generator; 275 string help_text; 276 }; 277 typedef map<string, GeneratorInfo> GeneratorMap; 278 GeneratorMap generators_by_flag_name_; 279 GeneratorMap generators_by_option_name_; 280 // A map from generator names to the parameters specified using the option 281 // flag. For example, if the user invokes the compiler with: 282 // protoc --foo_out=outputdir --foo_opt=enable_bar ... 283 // Then there will be an entry ("--foo_out", "enable_bar") in this map. 284 map<string, string> generator_parameters_; 285 286 // See AllowPlugins(). If this is empty, plugins aren't allowed. 287 string plugin_prefix_; 288 289 // Maps specific plugin names to files. When executing a plugin, this map 290 // is searched first to find the plugin executable. If not found here, the 291 // PATH (or other OS-specific search strategy) is searched. 292 map<string, string> plugins_; 293 294 // Stuff parsed from command line. 295 enum Mode { 296 MODE_COMPILE, // Normal mode: parse .proto files and compile them. 297 MODE_ENCODE, // --encode: read text from stdin, write binary to stdout. 298 MODE_DECODE // --decode: read binary from stdin, write text to stdout. 299 }; 300 301 Mode mode_; 302 303 enum ErrorFormat { 304 ERROR_FORMAT_GCC, // GCC error output format (default). 305 ERROR_FORMAT_MSVS // Visual Studio output (--error_format=msvs). 306 }; 307 308 ErrorFormat error_format_; 309 310 vector<pair<string, string> > proto_path_; // Search path for proto files. 311 vector<string> input_files_; // Names of the input proto files. 312 313 // output_directives_ lists all the files we are supposed to output and what 314 // generator to use for each. 315 struct OutputDirective { 316 string name; // E.g. "--foo_out" 317 CodeGenerator* generator; // NULL for plugins 318 string parameter; 319 string output_location; 320 }; 321 vector<OutputDirective> output_directives_; 322 323 // When using --encode or --decode, this names the type we are encoding or 324 // decoding. (Empty string indicates --decode_raw.) 325 string codec_type_; 326 327 // If --descriptor_set_out was given, this is the filename to which the 328 // FileDescriptorSet should be written. Otherwise, empty. 329 string descriptor_set_name_; 330 331 // True if --include_imports was given, meaning that we should 332 // write all transitive dependencies to the DescriptorSet. Otherwise, only 333 // the .proto files listed on the command-line are added. 334 bool imports_in_descriptor_set_; 335 336 // True if --include_source_info was given, meaning that we should not strip 337 // SourceCodeInfo from the DescriptorSet. 338 bool source_info_in_descriptor_set_; 339 340 // Was the --disallow_services flag used? 341 bool disallow_services_; 342 343 // See SetInputsAreProtoPathRelative(). 344 bool inputs_are_proto_path_relative_; 345 346 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CommandLineInterface); 347 }; 348 349 } // namespace compiler 350 } // namespace protobuf 351 352 } // namespace google 353 #endif // GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__ 354