command_line_interface.h revision fbaaef999ba563838ebd00874ed8a1c01fbf286d
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@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 48namespace google { 49namespace protobuf { 50 51class FileDescriptor; // descriptor.h 52class DescriptorPool; // descriptor.h 53 54namespace compiler { 55 56class CodeGenerator; // code_generator.h 57class DiskSourceTree; // importer.h 58 59// This class implements the command-line interface to the protocol compiler. 60// It is designed to make it very easy to create a custom protocol compiler 61// supporting the languages of your choice. For example, if you wanted to 62// create a custom protocol compiler binary which includes both the regular 63// C++ support plus support for your own custom output "Foo", you would 64// write a class "FooGenerator" which implements the CodeGenerator interface, 65// then write a main() procedure like this: 66// 67// int main(int argc, char* argv[]) { 68// google::protobuf::compiler::CommandLineInterface cli; 69// 70// // Support generation of C++ source and headers. 71// google::protobuf::compiler::cpp::CppGenerator cpp_generator; 72// cli.RegisterGenerator("--cpp_out", &cpp_generator, 73// "Generate C++ source and header."); 74// 75// // Support generation of Foo code. 76// FooGenerator foo_generator; 77// cli.RegisterGenerator("--foo_out", &foo_generator, 78// "Generate Foo file."); 79// 80// return cli.Run(argc, argv); 81// } 82// 83// The compiler is invoked with syntax like: 84// protoc --cpp_out=outdir --foo_out=outdir --proto_path=src src/foo.proto 85// 86// For a full description of the command-line syntax, invoke it with --help. 87class LIBPROTOC_EXPORT CommandLineInterface { 88 public: 89 CommandLineInterface(); 90 ~CommandLineInterface(); 91 92 // Register a code generator for a language. 93 // 94 // Parameters: 95 // * flag_name: The command-line flag used to specify an output file of 96 // this type. The name must start with a '-'. If the name is longer 97 // than one letter, it must start with two '-'s. 98 // * generator: The CodeGenerator which will be called to generate files 99 // of this type. 100 // * help_text: Text describing this flag in the --help output. 101 // 102 // Some generators accept extra parameters. You can specify this parameter 103 // on the command-line by placing it before the output directory, separated 104 // by a colon: 105 // protoc --foo_out=enable_bar:outdir 106 // The text before the colon is passed to CodeGenerator::Generate() as the 107 // "parameter". 108 void RegisterGenerator(const string& flag_name, 109 CodeGenerator* generator, 110 const string& help_text); 111 112 // Run the Protocol Compiler with the given command-line parameters. 113 // Returns the error code which should be returned by main(). 114 // 115 // It may not be safe to call Run() in a multi-threaded environment because 116 // it calls strerror(). I'm not sure why you'd want to do this anyway. 117 int Run(int argc, const char* const argv[]); 118 119 // Call SetInputsAreCwdRelative(true) if the input files given on the command 120 // line should be interpreted relative to the proto import path specified 121 // using --proto_path or -I flags. Otherwise, input file names will be 122 // interpreted relative to the current working directory (or as absolute 123 // paths if they start with '/'), though they must still reside inside 124 // a directory given by --proto_path or the compiler will fail. The latter 125 // mode is generally more intuitive and easier to use, especially e.g. when 126 // defining implicit rules in Makefiles. 127 void SetInputsAreProtoPathRelative(bool enable) { 128 inputs_are_proto_path_relative_ = enable; 129 } 130 131 // Provides some text which will be printed when the --version flag is 132 // used. The version of libprotoc will also be printed on the next line 133 // after this text. 134 void SetVersionInfo(const string& text) { 135 version_info_ = text; 136 } 137 138 139 private: 140 // ----------------------------------------------------------------- 141 142 class ErrorPrinter; 143 class DiskOutputDirectory; 144 class ErrorReportingFileOutput; 145 146 // Clear state from previous Run(). 147 void Clear(); 148 149 // Remaps each file in input_files_ so that it is relative to one of the 150 // directories in proto_path_. Returns false if an error occurred. This 151 // is only used if inputs_are_proto_path_relative_ is false. 152 bool MakeInputsBeProtoPathRelative( 153 DiskSourceTree* source_tree); 154 155 // Parse all command-line arguments. 156 bool ParseArguments(int argc, const char* const argv[]); 157 158 // Parses a command-line argument into a name/value pair. Returns 159 // true if the next argument in the argv should be used as the value, 160 // false otherwise. 161 // 162 // Exmaples: 163 // "-Isrc/protos" -> 164 // name = "-I", value = "src/protos" 165 // "--cpp_out=src/foo.pb2.cc" -> 166 // name = "--cpp_out", value = "src/foo.pb2.cc" 167 // "foo.proto" -> 168 // name = "", value = "foo.proto" 169 bool ParseArgument(const char* arg, string* name, string* value); 170 171 // Interprets arguments parsed with ParseArgument. 172 bool InterpretArgument(const string& name, const string& value); 173 174 // Print the --help text to stderr. 175 void PrintHelpText(); 176 177 // Generate the given output file from the given input. 178 struct OutputDirective; // see below 179 bool GenerateOutput(const FileDescriptor* proto_file, 180 const OutputDirective& output_directive); 181 182 // Implements --encode and --decode. 183 bool EncodeOrDecode(const DescriptorPool* pool); 184 185 // Implements the --descriptor_set_out option. 186 bool WriteDescriptorSet(const vector<const FileDescriptor*> parsed_files); 187 188 // ----------------------------------------------------------------- 189 190 // The name of the executable as invoked (i.e. argv[0]). 191 string executable_name_; 192 193 // Version info set with SetVersionInfo(). 194 string version_info_; 195 196 // Map from flag names to registered generators. 197 struct GeneratorInfo { 198 CodeGenerator* generator; 199 string help_text; 200 }; 201 typedef map<string, GeneratorInfo> GeneratorMap; 202 GeneratorMap generators_; 203 204 // Stuff parsed from command line. 205 enum Mode { 206 MODE_COMPILE, // Normal mode: parse .proto files and compile them. 207 MODE_ENCODE, // --encode: read text from stdin, write binary to stdout. 208 MODE_DECODE // --decode: read binary from stdin, write text to stdout. 209 }; 210 211 Mode mode_; 212 213 enum ErrorFormat { 214 ERROR_FORMAT_GCC, // GCC error output format (default). 215 ERROR_FORMAT_MSVS // Visual Studio output (--error_format=msvs). 216 }; 217 218 ErrorFormat error_format_; 219 220 vector<pair<string, string> > proto_path_; // Search path for proto files. 221 vector<string> input_files_; // Names of the input proto files. 222 223 // output_directives_ lists all the files we are supposed to output and what 224 // generator to use for each. 225 struct OutputDirective { 226 string name; 227 CodeGenerator* generator; 228 string parameter; 229 string output_location; 230 }; 231 vector<OutputDirective> output_directives_; 232 233 // When using --encode or --decode, this names the type we are encoding or 234 // decoding. (Empty string indicates --decode_raw.) 235 string codec_type_; 236 237 // If --descriptor_set_out was given, this is the filename to which the 238 // FileDescriptorSet should be written. Otherwise, empty. 239 string descriptor_set_name_; 240 241 // True if --include_imports was given, meaning that we should 242 // write all transitive dependencies to the DescriptorSet. Otherwise, only 243 // the .proto files listed on the command-line are added. 244 bool imports_in_descriptor_set_; 245 246 // Was the --disallow_services flag used? 247 bool disallow_services_; 248 249 // See SetInputsAreProtoPathRelative(). 250 bool inputs_are_proto_path_relative_; 251 252 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CommandLineInterface); 253}; 254 255} // namespace compiler 256} // namespace protobuf 257 258} // namespace google 259#endif // GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__ 260