temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 1 | // Protocol Buffers - Google's data interchange format |
kenton@google.com | 24bf56f | 2008-09-24 20:31:01 +0000 | [diff] [blame] | 2 | // Copyright 2008 Google Inc. All rights reserved. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 3 | // http://code.google.com/p/protobuf/ |
| 4 | // |
kenton@google.com | 24bf56f | 2008-09-24 20:31:01 +0000 | [diff] [blame] | 5 | // Redistribution and use in source and binary forms, with or without |
| 6 | // modification, are permitted provided that the following conditions are |
| 7 | // met: |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 8 | // |
kenton@google.com | 24bf56f | 2008-09-24 20:31:01 +0000 | [diff] [blame] | 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. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 18 | // |
kenton@google.com | 24bf56f | 2008-09-24 20:31:01 +0000 | [diff] [blame] | 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. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 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 | |
| 48 | namespace google { |
| 49 | namespace protobuf { |
| 50 | |
| 51 | class FileDescriptor; // descriptor.h |
temporal | 779f61c | 2008-08-13 03:15:00 +0000 | [diff] [blame] | 52 | class DescriptorPool; // descriptor.h |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 53 | class FileDescriptorProto; // descriptor.pb.h |
| 54 | template<typename T> class RepeatedPtrField; // repeated_field.h |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 55 | |
| 56 | namespace compiler { |
| 57 | |
| 58 | class CodeGenerator; // code_generator.h |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 59 | class GeneratorContext; // code_generator.h |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 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: |
temporal | 742e409 | 2008-08-27 19:25:48 +0000 | [diff] [blame] | 87 | // protoc --cpp_out=outdir --foo_out=outdir --proto_path=src src/foo.proto |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 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 | |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 115 | // Enables "plugins". In this mode, if a command-line flag ends with "_out" |
| 116 | // but does not match any registered generator, the compiler will attempt to |
| 117 | // find a "plugin" to implement the generator. Plugins are just executables. |
| 118 | // They should live somewhere in the PATH. |
| 119 | // |
| 120 | // The compiler determines the executable name to search for by concatenating |
| 121 | // exe_name_prefix with the unrecognized flag name, removing "_out". So, for |
| 122 | // example, if exe_name_prefix is "protoc-" and you pass the flag --foo_out, |
| 123 | // the compiler will try to run the program "protoc-foo". |
| 124 | // |
| 125 | // The plugin program should implement the following usage: |
| 126 | // plugin [--out=OUTDIR] [--parameter=PARAMETER] PROTO_FILES < DESCRIPTORS |
| 127 | // --out indicates the output directory (as passed to the --foo_out |
| 128 | // parameter); if omitted, the current directory should be used. --parameter |
| 129 | // gives the generator parameter, if any was provided. The PROTO_FILES list |
| 130 | // the .proto files which were given on the compiler command-line; these are |
| 131 | // the files for which the plugin is expected to generate output code. |
| 132 | // Finally, DESCRIPTORS is an encoded FileDescriptorSet (as defined in |
| 133 | // descriptor.proto). This is piped to the plugin's stdin. The set will |
| 134 | // include descriptors for all the files listed in PROTO_FILES as well as |
| 135 | // all files that they import. The plugin MUST NOT attempt to read the |
| 136 | // PROTO_FILES directly -- it must use the FileDescriptorSet. |
| 137 | // |
| 138 | // The plugin should generate whatever files are necessary, as code generators |
| 139 | // normally do. It should write the names of all files it generates to |
| 140 | // stdout. The names should be relative to the output directory, NOT absolute |
| 141 | // names or relative to the current directory. If any errors occur, error |
| 142 | // messages should be written to stderr. If an error is fatal, the plugin |
| 143 | // should exit with a non-zero exit code. |
| 144 | void AllowPlugins(const string& exe_name_prefix); |
| 145 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 146 | // Run the Protocol Compiler with the given command-line parameters. |
| 147 | // Returns the error code which should be returned by main(). |
| 148 | // |
| 149 | // It may not be safe to call Run() in a multi-threaded environment because |
| 150 | // it calls strerror(). I'm not sure why you'd want to do this anyway. |
| 151 | int Run(int argc, const char* const argv[]); |
| 152 | |
| 153 | // Call SetInputsAreCwdRelative(true) if the input files given on the command |
| 154 | // line should be interpreted relative to the proto import path specified |
| 155 | // using --proto_path or -I flags. Otherwise, input file names will be |
| 156 | // interpreted relative to the current working directory (or as absolute |
| 157 | // paths if they start with '/'), though they must still reside inside |
| 158 | // a directory given by --proto_path or the compiler will fail. The latter |
| 159 | // mode is generally more intuitive and easier to use, especially e.g. when |
| 160 | // defining implicit rules in Makefiles. |
| 161 | void SetInputsAreProtoPathRelative(bool enable) { |
| 162 | inputs_are_proto_path_relative_ = enable; |
| 163 | } |
| 164 | |
| 165 | // Provides some text which will be printed when the --version flag is |
| 166 | // used. The version of libprotoc will also be printed on the next line |
| 167 | // after this text. |
| 168 | void SetVersionInfo(const string& text) { |
| 169 | version_info_ = text; |
| 170 | } |
| 171 | |
| 172 | |
| 173 | private: |
| 174 | // ----------------------------------------------------------------- |
| 175 | |
| 176 | class ErrorPrinter; |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 177 | class GeneratorContextImpl; |
kenton@google.com | 5f12164 | 2009-12-23 07:03:06 +0000 | [diff] [blame] | 178 | class MemoryOutputStream; |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 179 | |
| 180 | // Clear state from previous Run(). |
| 181 | void Clear(); |
| 182 | |
| 183 | // Remaps each file in input_files_ so that it is relative to one of the |
| 184 | // directories in proto_path_. Returns false if an error occurred. This |
| 185 | // is only used if inputs_are_proto_path_relative_ is false. |
| 186 | bool MakeInputsBeProtoPathRelative( |
| 187 | DiskSourceTree* source_tree); |
| 188 | |
| 189 | // Parse all command-line arguments. |
| 190 | bool ParseArguments(int argc, const char* const argv[]); |
| 191 | |
| 192 | // Parses a command-line argument into a name/value pair. Returns |
| 193 | // true if the next argument in the argv should be used as the value, |
| 194 | // false otherwise. |
| 195 | // |
| 196 | // Exmaples: |
| 197 | // "-Isrc/protos" -> |
| 198 | // name = "-I", value = "src/protos" |
| 199 | // "--cpp_out=src/foo.pb2.cc" -> |
| 200 | // name = "--cpp_out", value = "src/foo.pb2.cc" |
| 201 | // "foo.proto" -> |
| 202 | // name = "", value = "foo.proto" |
| 203 | bool ParseArgument(const char* arg, string* name, string* value); |
| 204 | |
| 205 | // Interprets arguments parsed with ParseArgument. |
| 206 | bool InterpretArgument(const string& name, const string& value); |
| 207 | |
| 208 | // Print the --help text to stderr. |
| 209 | void PrintHelpText(); |
| 210 | |
| 211 | // Generate the given output file from the given input. |
| 212 | struct OutputDirective; // see below |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 213 | bool GenerateOutput(const vector<const FileDescriptor*>& parsed_files, |
kenton@google.com | 5f12164 | 2009-12-23 07:03:06 +0000 | [diff] [blame] | 214 | const OutputDirective& output_directive, |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 215 | GeneratorContext* generator_context); |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 216 | bool GeneratePluginOutput(const vector<const FileDescriptor*>& parsed_files, |
| 217 | const string& plugin_name, |
| 218 | const string& parameter, |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 219 | GeneratorContext* generator_context, |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 220 | string* error); |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 221 | |
temporal | 779f61c | 2008-08-13 03:15:00 +0000 | [diff] [blame] | 222 | // Implements --encode and --decode. |
| 223 | bool EncodeOrDecode(const DescriptorPool* pool); |
| 224 | |
| 225 | // Implements the --descriptor_set_out option. |
| 226 | bool WriteDescriptorSet(const vector<const FileDescriptor*> parsed_files); |
| 227 | |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 228 | // Get all transitive dependencies of the given file (including the file |
| 229 | // itself), adding them to the given list of FileDescriptorProtos. The |
| 230 | // protos will be ordered such that every file is listed before any file that |
| 231 | // depends on it, so that you can call DescriptorPool::BuildFile() on them |
| 232 | // in order. Any files in *already_seen will not be added, and each file |
| 233 | // added will be inserted into *already_seen. |
| 234 | static void GetTransitiveDependencies( |
| 235 | const FileDescriptor* file, |
| 236 | set<const FileDescriptor*>* already_seen, |
| 237 | RepeatedPtrField<FileDescriptorProto>* output); |
| 238 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 239 | // ----------------------------------------------------------------- |
| 240 | |
| 241 | // The name of the executable as invoked (i.e. argv[0]). |
| 242 | string executable_name_; |
| 243 | |
| 244 | // Version info set with SetVersionInfo(). |
| 245 | string version_info_; |
| 246 | |
| 247 | // Map from flag names to registered generators. |
| 248 | struct GeneratorInfo { |
| 249 | CodeGenerator* generator; |
| 250 | string help_text; |
| 251 | }; |
| 252 | typedef map<string, GeneratorInfo> GeneratorMap; |
| 253 | GeneratorMap generators_; |
| 254 | |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 255 | // See AllowPlugins(). If this is empty, plugins aren't allowed. |
| 256 | string plugin_prefix_; |
| 257 | |
| 258 | // Maps specific plugin names to files. When executing a plugin, this map |
| 259 | // is searched first to find the plugin executable. If not found here, the |
| 260 | // PATH (or other OS-specific search strategy) is searched. |
| 261 | map<string, string> plugins_; |
| 262 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 263 | // Stuff parsed from command line. |
temporal | 779f61c | 2008-08-13 03:15:00 +0000 | [diff] [blame] | 264 | enum Mode { |
| 265 | MODE_COMPILE, // Normal mode: parse .proto files and compile them. |
| 266 | MODE_ENCODE, // --encode: read text from stdin, write binary to stdout. |
| 267 | MODE_DECODE // --decode: read binary from stdin, write text to stdout. |
| 268 | }; |
| 269 | |
| 270 | Mode mode_; |
| 271 | |
kenton@google.com | f663b16 | 2009-04-15 19:50:54 +0000 | [diff] [blame] | 272 | enum ErrorFormat { |
| 273 | ERROR_FORMAT_GCC, // GCC error output format (default). |
| 274 | ERROR_FORMAT_MSVS // Visual Studio output (--error_format=msvs). |
| 275 | }; |
| 276 | |
| 277 | ErrorFormat error_format_; |
| 278 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 279 | vector<pair<string, string> > proto_path_; // Search path for proto files. |
| 280 | vector<string> input_files_; // Names of the input proto files. |
| 281 | |
| 282 | // output_directives_ lists all the files we are supposed to output and what |
| 283 | // generator to use for each. |
| 284 | struct OutputDirective { |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 285 | string name; // E.g. "--foo_out" |
| 286 | CodeGenerator* generator; // NULL for plugins |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 287 | string parameter; |
| 288 | string output_location; |
| 289 | }; |
| 290 | vector<OutputDirective> output_directives_; |
| 291 | |
temporal | 779f61c | 2008-08-13 03:15:00 +0000 | [diff] [blame] | 292 | // When using --encode or --decode, this names the type we are encoding or |
| 293 | // decoding. (Empty string indicates --decode_raw.) |
| 294 | string codec_type_; |
| 295 | |
| 296 | // If --descriptor_set_out was given, this is the filename to which the |
| 297 | // FileDescriptorSet should be written. Otherwise, empty. |
| 298 | string descriptor_set_name_; |
| 299 | |
| 300 | // True if --include_imports was given, meaning that we should |
| 301 | // write all transitive dependencies to the DescriptorSet. Otherwise, only |
| 302 | // the .proto files listed on the command-line are added. |
| 303 | bool imports_in_descriptor_set_; |
| 304 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 305 | // Was the --disallow_services flag used? |
| 306 | bool disallow_services_; |
| 307 | |
| 308 | // See SetInputsAreProtoPathRelative(). |
| 309 | bool inputs_are_proto_path_relative_; |
| 310 | |
| 311 | GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CommandLineInterface); |
| 312 | }; |
| 313 | |
| 314 | } // namespace compiler |
| 315 | } // namespace protobuf |
| 316 | |
| 317 | } // namespace google |
| 318 | #endif // GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__ |