1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // http://code.google.com/p/protobuf/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
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
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.
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.
31 // Author: kenton@google.com (Kenton Varda)
32 // Based on original Protocol Buffers design by
33 // Sanjay Ghemawat, Jeff Dean, and others.
35 // Implements the Protocol Compiler front-end such that it may be reused by
36 // custom compilers written to support other languages.
38 #ifndef GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__
39 #define GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__
41 #include <google/protobuf/stubs/common.h>
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
58 class CodeGenerator; // code_generator.h
59 class GeneratorContext; // code_generator.h
60 class DiskSourceTree; // importer.h
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:
70 // int main(int argc, char* argv[]) {
71 // google::protobuf::compiler::CommandLineInterface cli;
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.");
78 // // Support generation of Foo code.
79 // FooGenerator foo_generator;
80 // cli.RegisterGenerator("--foo_out", &foo_generator,
81 // "Generate Foo file.");
83 // return cli.Run(argc, argv);
86 // The compiler is invoked with syntax like:
87 // protoc --cpp_out=outdir --foo_out=outdir --proto_path=src src/foo.proto
89 // For a full description of the command-line syntax, invoke it with --help.
90 class LIBPROTOC_EXPORT CommandLineInterface {
92 CommandLineInterface();
93 ~CommandLineInterface();
95 // Register a code generator for a language.
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
103 // * help_text: Text describing this flag in the --help output.
105 // Some generators accept extra parameters. You can specify this parameter
106 // on the command-line by placing it before the output directory, separated
108 // protoc --foo_out=enable_bar:outdir
109 // The text before the colon is passed to CodeGenerator::Generate() as the
111 void RegisterGenerator(const string& flag_name,
112 CodeGenerator* generator,
113 const string& help_text);
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);
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.
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".
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.
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);
159 // Run the Protocol Compiler with the given command-line parameters.
160 // Returns the error code which should be returned by main().
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[]);
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;
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
181 void SetVersionInfo(const string& text) {
182 version_info_ = text;
187 // -----------------------------------------------------------------
190 class GeneratorContextImpl;
191 class MemoryOutputStream;
193 // Clear state from previous Run().
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);
202 // Return status for ParseArguments() and InterpretArgument().
203 enum ParseArgumentStatus {
204 PARSE_ARGUMENT_DONE_AND_CONTINUE,
205 PARSE_ARGUMENT_DONE_AND_EXIT,
209 // Parse all command-line arguments.
210 ParseArgumentStatus ParseArguments(int argc, const char* const argv[]);
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,
218 // name = "-I", value = "src/protos"
219 // "--cpp_out=src/foo.pb2.cc" ->
220 // name = "--cpp_out", value = "src/foo.pb2.cc"
222 // name = "", value = "foo.proto"
223 bool ParseArgument(const char* arg, string* name, string* value);
225 // Interprets arguments parsed with ParseArgument.
226 ParseArgumentStatus InterpretArgument(const string& name,
227 const string& value);
229 // Print the --help text to stderr.
230 void PrintHelpText();
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,
243 // Implements --encode and --decode.
244 bool EncodeOrDecode(const DescriptorPool* pool);
246 // Implements the --descriptor_set_out option.
247 bool WriteDescriptorSet(const vector<const FileDescriptor*> parsed_files);
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);
262 // -----------------------------------------------------------------
264 // The name of the executable as invoked (i.e. argv[0]).
265 string executable_name_;
267 // Version info set with SetVersionInfo().
268 string version_info_;
270 // Registered generators.
271 struct GeneratorInfo {
273 string option_flag_name;
274 CodeGenerator* generator;
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_;
286 // See AllowPlugins(). If this is empty, plugins aren't allowed.
287 string plugin_prefix_;
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_;
294 // Stuff parsed from command line.
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.
304 ERROR_FORMAT_GCC, // GCC error output format (default).
305 ERROR_FORMAT_MSVS // Visual Studio output (--error_format=msvs).
308 ErrorFormat error_format_;
310 vector<pair<string, string> > proto_path_; // Search path for proto files.
311 vector<string> input_files_; // Names of the input proto files.
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
319 string output_location;
321 vector<OutputDirective> output_directives_;
323 // When using --encode or --decode, this names the type we are encoding or
324 // decoding. (Empty string indicates --decode_raw.)
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_;
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_;
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_;
340 // Was the --disallow_services flag used?
341 bool disallow_services_;
343 // See SetInputsAreProtoPathRelative().
344 bool inputs_are_proto_path_relative_;
346 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CommandLineInterface);
349 } // namespace compiler
350 } // namespace protobuf
352 } // namespace google
353 #endif // GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__