1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// https://developers.google.com/protocol-buffers/
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 <cstdint>
42#include <map>
43#include <memory>
44#include <set>
45#include <string>
46#include <unordered_map>
47#include <unordered_set>
48#include <utility>
49#include <vector>
50
51#include <google/protobuf/stubs/common.h>
52
53// Must be included last.
54#include <google/protobuf/port_def.inc>
55
56namespace google {
57namespace protobuf {
58
59class Descriptor; // descriptor.h
60class DescriptorDatabase; // descriptor_database.h
61class DescriptorPool; // descriptor.h
62class FileDescriptor; // descriptor.h
63class FileDescriptorSet; // descriptor.h
64class FileDescriptorProto; // descriptor.pb.h
65template <typename T>
66class RepeatedPtrField; // repeated_field.h
67class SimpleDescriptorDatabase; // descriptor_database.h
68
69namespace compiler {
70
71class CodeGenerator; // code_generator.h
72class GeneratorContext; // code_generator.h
73class DiskSourceTree; // importer.h
74
75// This class implements the command-line interface to the protocol compiler.
76// It is designed to make it very easy to create a custom protocol compiler
77// supporting the languages of your choice. For example, if you wanted to
78// create a custom protocol compiler binary which includes both the regular
79// C++ support plus support for your own custom output "Foo", you would
80// write a class "FooGenerator" which implements the CodeGenerator interface,
81// then write a main() procedure like this:
82//
83// int main(int argc, char* argv[]) {
84// google::protobuf::compiler::CommandLineInterface cli;
85//
86// // Support generation of C++ source and headers.
87// google::protobuf::compiler::cpp::CppGenerator cpp_generator;
88// cli.RegisterGenerator("--cpp_out", &cpp_generator,
89// "Generate C++ source and header.");
90//
91// // Support generation of Foo code.
92// FooGenerator foo_generator;
93// cli.RegisterGenerator("--foo_out", &foo_generator,
94// "Generate Foo file.");
95//
96// return cli.Run(argc, argv);
97// }
98//
99// The compiler is invoked with syntax like:
100// protoc --cpp_out=outdir --foo_out=outdir --proto_path=src src/foo.proto
101//
102// The .proto file to compile can be specified on the command line using either
103// its physical file path, or a virtual path relative to a directory specified
104// in --proto_path. For example, for src/foo.proto, the following two protoc
105// invocations work the same way:
106// 1. protoc --proto_path=src src/foo.proto (physical file path)
107// 2. protoc --proto_path=src foo.proto (virtual path relative to src)
108//
109// If a file path can be interpreted both as a physical file path and as a
110// relative virtual path, the physical file path takes precedence.
111//
112// For a full description of the command-line syntax, invoke it with --help.
113class PROTOC_EXPORT CommandLineInterface {
114 public:
115 static const char* const kPathSeparator;
116
117 CommandLineInterface();
118 ~CommandLineInterface();
119
120 // Register a code generator for a language.
121 //
122 // Parameters:
123 // * flag_name: The command-line flag used to specify an output file of
124 // this type. The name must start with a '-'. If the name is longer
125 // than one letter, it must start with two '-'s.
126 // * generator: The CodeGenerator which will be called to generate files
127 // of this type.
128 // * help_text: Text describing this flag in the --help output.
129 //
130 // Some generators accept extra parameters. You can specify this parameter
131 // on the command-line by placing it before the output directory, separated
132 // by a colon:
133 // protoc --foo_out=enable_bar:outdir
134 // The text before the colon is passed to CodeGenerator::Generate() as the
135 // "parameter".
136 void RegisterGenerator(const std::string& flag_name, CodeGenerator* generator,
137 const std::string& help_text);
138
139 // Register a code generator for a language.
140 // Besides flag_name you can specify another option_flag_name that could be
141 // used to pass extra parameters to the registered code generator.
142 // Suppose you have registered a generator by calling:
143 // command_line_interface.RegisterGenerator("--foo_out", "--foo_opt", ...)
144 // Then you could invoke the compiler with a command like:
145 // protoc --foo_out=enable_bar:outdir --foo_opt=enable_baz
146 // This will pass "enable_bar,enable_baz" as the parameter to the generator.
147 void RegisterGenerator(const std::string& flag_name,
148 const std::string& option_flag_name,
149 CodeGenerator* generator,
150 const std::string& help_text);
151
152 // Enables "plugins". In this mode, if a command-line flag ends with "_out"
153 // but does not match any registered generator, the compiler will attempt to
154 // find a "plugin" to implement the generator. Plugins are just executables.
155 // They should live somewhere in the PATH.
156 //
157 // The compiler determines the executable name to search for by concatenating
158 // exe_name_prefix with the unrecognized flag name, removing "_out". So, for
159 // example, if exe_name_prefix is "protoc-" and you pass the flag --foo_out,
160 // the compiler will try to run the program "protoc-gen-foo".
161 //
162 // The plugin program should implement the following usage:
163 // plugin [--out=OUTDIR] [--parameter=PARAMETER] PROTO_FILES < DESCRIPTORS
164 // --out indicates the output directory (as passed to the --foo_out
165 // parameter); if omitted, the current directory should be used. --parameter
166 // gives the generator parameter, if any was provided (see below). The
167 // PROTO_FILES list the .proto files which were given on the compiler
168 // command-line; these are the files for which the plugin is expected to
169 // generate output code. Finally, DESCRIPTORS is an encoded FileDescriptorSet
170 // (as defined in descriptor.proto). This is piped to the plugin's stdin.
171 // The set will include descriptors for all the files listed in PROTO_FILES as
172 // well as all files that they import. The plugin MUST NOT attempt to read
173 // the PROTO_FILES directly -- it must use the FileDescriptorSet.
174 //
175 // The plugin should generate whatever files are necessary, as code generators
176 // normally do. It should write the names of all files it generates to
177 // stdout. The names should be relative to the output directory, NOT absolute
178 // names or relative to the current directory. If any errors occur, error
179 // messages should be written to stderr. If an error is fatal, the plugin
180 // should exit with a non-zero exit code.
181 //
182 // Plugins can have generator parameters similar to normal built-in
183 // generators. Extra generator parameters can be passed in via a matching
184 // "_opt" parameter. For example:
185 // protoc --plug_out=enable_bar:outdir --plug_opt=enable_baz
186 // This will pass "enable_bar,enable_baz" as the parameter to the plugin.
187 //
188 void AllowPlugins(const std::string& exe_name_prefix);
189
190 // Run the Protocol Compiler with the given command-line parameters.
191 // Returns the error code which should be returned by main().
192 //
193 // It may not be safe to call Run() in a multi-threaded environment because
194 // it calls strerror(). I'm not sure why you'd want to do this anyway.
195 int Run(int argc, const char* const argv[]);
196
197 // DEPRECATED. Calling this method has no effect. Protocol compiler now
198 // always try to find the .proto file relative to the current directory
199 // first and if the file is not found, it will then treat the input path
200 // as a virtual path.
201 void SetInputsAreProtoPathRelative(bool /* enable */) {}
202
203 // Provides some text which will be printed when the --version flag is
204 // used. The version of libprotoc will also be printed on the next line
205 // after this text.
206 void SetVersionInfo(const std::string& text) { version_info_ = text; }
207
208
209 private:
210 // -----------------------------------------------------------------
211
212 class ErrorPrinter;
213 class GeneratorContextImpl;
214 class MemoryOutputStream;
215 typedef std::unordered_map<std::string, std::unique_ptr<GeneratorContextImpl>>
216 GeneratorContextMap;
217
218 // Clear state from previous Run().
219 void Clear();
220
221 // Remaps the proto file so that it is relative to one of the directories
222 // in proto_path_. Returns false if an error occurred.
223 bool MakeProtoProtoPathRelative(DiskSourceTree* source_tree,
224 std::string* proto,
225 DescriptorDatabase* fallback_database);
226
227 // Remaps each file in input_files_ so that it is relative to one of the
228 // directories in proto_path_. Returns false if an error occurred.
229 bool MakeInputsBeProtoPathRelative(DiskSourceTree* source_tree,
230 DescriptorDatabase* fallback_database);
231
232 // Fails if these files use proto3 optional and the code generator doesn't
233 // support it. This is a permanent check.
234 bool EnforceProto3OptionalSupport(
235 const std::string& codegen_name, uint64_t supported_features,
236 const std::vector<const FileDescriptor*>& parsed_files) const;
237
238
239 // Return status for ParseArguments() and InterpretArgument().
240 enum ParseArgumentStatus {
241 PARSE_ARGUMENT_DONE_AND_CONTINUE,
242 PARSE_ARGUMENT_DONE_AND_EXIT,
243 PARSE_ARGUMENT_FAIL
244 };
245
246 // Parse all command-line arguments.
247 ParseArgumentStatus ParseArguments(int argc, const char* const argv[]);
248
249 // Read an argument file and append the file's content to the list of
250 // arguments. Return false if the file cannot be read.
251 bool ExpandArgumentFile(const std::string& file,
252 std::vector<std::string>* arguments);
253
254 // Parses a command-line argument into a name/value pair. Returns
255 // true if the next argument in the argv should be used as the value,
256 // false otherwise.
257 //
258 // Examples:
259 // "-Isrc/protos" ->
260 // name = "-I", value = "src/protos"
261 // "--cpp_out=src/foo.pb2.cc" ->
262 // name = "--cpp_out", value = "src/foo.pb2.cc"
263 // "foo.proto" ->
264 // name = "", value = "foo.proto"
265 bool ParseArgument(const char* arg, std::string* name, std::string* value);
266
267 // Interprets arguments parsed with ParseArgument.
268 ParseArgumentStatus InterpretArgument(const std::string& name,
269 const std::string& value);
270
271 // Print the --help text to stderr.
272 void PrintHelpText();
273
274 // Loads proto_path_ into the provided source_tree.
275 bool InitializeDiskSourceTree(DiskSourceTree* source_tree,
276 DescriptorDatabase* fallback_database);
277
278 // Verify that all the input files exist in the given database.
279 bool VerifyInputFilesInDescriptors(DescriptorDatabase* fallback_database);
280
281 // Parses input_files_ into parsed_files
282 bool ParseInputFiles(DescriptorPool* descriptor_pool,
283 DiskSourceTree* source_tree,
284 std::vector<const FileDescriptor*>* parsed_files);
285
286 // Generate the given output file from the given input.
287 struct OutputDirective; // see below
288 bool GenerateOutput(const std::vector<const FileDescriptor*>& parsed_files,
289 const OutputDirective& output_directive,
290 GeneratorContext* generator_context);
291 bool GeneratePluginOutput(
292 const std::vector<const FileDescriptor*>& parsed_files,
293 const std::string& plugin_name, const std::string& parameter,
294 GeneratorContext* generator_context, std::string* error);
295
296 // Implements --encode and --decode.
297 bool EncodeOrDecode(const DescriptorPool* pool);
298
299 // Implements the --descriptor_set_out option.
300 bool WriteDescriptorSet(
301 const std::vector<const FileDescriptor*>& parsed_files);
302
303 // Implements the --dependency_out option
304 bool GenerateDependencyManifestFile(
305 const std::vector<const FileDescriptor*>& parsed_files,
306 const GeneratorContextMap& output_directories,
307 DiskSourceTree* source_tree);
308
309 // Get all transitive dependencies of the given file (including the file
310 // itself), adding them to the given list of FileDescriptorProtos. The
311 // protos will be ordered such that every file is listed before any file that
312 // depends on it, so that you can call DescriptorPool::BuildFile() on them
313 // in order. Any files in *already_seen will not be added, and each file
314 // added will be inserted into *already_seen. If include_source_code_info is
315 // true then include the source code information in the FileDescriptorProtos.
316 // If include_json_name is true, populate the json_name field of
317 // FieldDescriptorProto for all fields.
318 static void GetTransitiveDependencies(
319 const FileDescriptor* file, bool include_json_name,
320 bool include_source_code_info,
321 std::set<const FileDescriptor*>* already_seen,
322 RepeatedPtrField<FileDescriptorProto>* output);
323
324 // Implements the --print_free_field_numbers. This function prints free field
325 // numbers into stdout for the message and it's nested message types in
326 // post-order, i.e. nested types first. Printed range are left-right
327 // inclusive, i.e. [a, b].
328 //
329 // Groups:
330 // For historical reasons, groups are considered to share the same
331 // field number space with the parent message, thus it will not print free
332 // field numbers for groups. The field numbers used in the groups are
333 // excluded in the free field numbers of the parent message.
334 //
335 // Extension Ranges:
336 // Extension ranges are considered ocuppied field numbers and they will not be
337 // listed as free numbers in the output.
338 void PrintFreeFieldNumbers(const Descriptor* descriptor);
339
340 // -----------------------------------------------------------------
341
342 // The name of the executable as invoked (i.e. argv[0]).
343 std::string executable_name_;
344
345 // Version info set with SetVersionInfo().
346 std::string version_info_;
347
348 // Registered generators.
349 struct GeneratorInfo {
350 std::string flag_name;
351 std::string option_flag_name;
352 CodeGenerator* generator;
353 std::string help_text;
354 };
355 typedef std::map<std::string, GeneratorInfo> GeneratorMap;
356 GeneratorMap generators_by_flag_name_;
357 GeneratorMap generators_by_option_name_;
358 // A map from generator names to the parameters specified using the option
359 // flag. For example, if the user invokes the compiler with:
360 // protoc --foo_out=outputdir --foo_opt=enable_bar ...
361 // Then there will be an entry ("--foo_out", "enable_bar") in this map.
362 std::map<std::string, std::string> generator_parameters_;
363 // Similar to generator_parameters_, but stores the parameters for plugins.
364 std::map<std::string, std::string> plugin_parameters_;
365
366 // See AllowPlugins(). If this is empty, plugins aren't allowed.
367 std::string plugin_prefix_;
368
369 // Maps specific plugin names to files. When executing a plugin, this map
370 // is searched first to find the plugin executable. If not found here, the
371 // PATH (or other OS-specific search strategy) is searched.
372 std::map<std::string, std::string> plugins_;
373
374 // Stuff parsed from command line.
375 enum Mode {
376 MODE_COMPILE, // Normal mode: parse .proto files and compile them.
377 MODE_ENCODE, // --encode: read text from stdin, write binary to stdout.
378 MODE_DECODE, // --decode: read binary from stdin, write text to stdout.
379 MODE_PRINT, // Print mode: print info of the given .proto files and exit.
380 };
381
382 Mode mode_ = MODE_COMPILE;
383
384 enum PrintMode {
385 PRINT_NONE, // Not in MODE_PRINT
386 PRINT_FREE_FIELDS, // --print_free_fields
387 };
388
389 PrintMode print_mode_ = PRINT_NONE;
390
391 enum ErrorFormat {
392 ERROR_FORMAT_GCC, // GCC error output format (default).
393 ERROR_FORMAT_MSVS // Visual Studio output (--error_format=msvs).
394 };
395
396 ErrorFormat error_format_ = ERROR_FORMAT_GCC;
397
398 // True if we should treat warnings as errors that fail the compilation.
399 bool fatal_warnings_ = false;
400
401 std::vector<std::pair<std::string, std::string> >
402 proto_path_; // Search path for proto files.
403 std::vector<std::string> input_files_; // Names of the input proto files.
404
405 // Names of proto files which are allowed to be imported. Used by build
406 // systems to enforce depend-on-what-you-import.
407 std::set<std::string> direct_dependencies_;
408 bool direct_dependencies_explicitly_set_ = false;
409
410 // If there's a violation of depend-on-what-you-import, this string will be
411 // presented to the user. "%s" will be replaced with the violating import.
412 std::string direct_dependencies_violation_msg_;
413
414 // output_directives_ lists all the files we are supposed to output and what
415 // generator to use for each.
416 struct OutputDirective {
417 std::string name; // E.g. "--foo_out"
418 CodeGenerator* generator; // NULL for plugins
419 std::string parameter;
420 std::string output_location;
421 };
422 std::vector<OutputDirective> output_directives_;
423
424 // When using --encode or --decode, this names the type we are encoding or
425 // decoding. (Empty string indicates --decode_raw.)
426 std::string codec_type_;
427
428 // If --descriptor_set_in was given, these are filenames containing
429 // parsed FileDescriptorSets to be used for loading protos. Otherwise, empty.
430 std::vector<std::string> descriptor_set_in_names_;
431
432 // If --descriptor_set_out was given, this is the filename to which the
433 // FileDescriptorSet should be written. Otherwise, empty.
434 std::string descriptor_set_out_name_;
435
436 // If --dependency_out was given, this is the path to the file where the
437 // dependency file will be written. Otherwise, empty.
438 std::string dependency_out_name_;
439
440 // True if --include_imports was given, meaning that we should
441 // write all transitive dependencies to the DescriptorSet. Otherwise, only
442 // the .proto files listed on the command-line are added.
443 bool imports_in_descriptor_set_;
444
445 // True if --include_source_info was given, meaning that we should not strip
446 // SourceCodeInfo from the DescriptorSet.
447 bool source_info_in_descriptor_set_ = false;
448
449 // Was the --disallow_services flag used?
450 bool disallow_services_ = false;
451
452 // When using --encode, this will be passed to SetSerializationDeterministic.
453 bool deterministic_output_ = false;
454
455 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CommandLineInterface);
456};
457
458} // namespace compiler
459} // namespace protobuf
460} // namespace google
461
462#include <google/protobuf/port_undef.inc>
463
464#endif // GOOGLE_PROTOBUF_COMPILER_COMMAND_LINE_INTERFACE_H__
465