protobuf/compiler/plugin.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2008 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Author: kenton@google.com (Kenton Varda)
0009 //
0010 // Front-end for protoc code generator plugins written in C++.
0011 //
0012 // To implement a protoc plugin in C++, simply write an implementation of
0013 // CodeGenerator, then create a main() function like:
0014 //   int main(int argc, char* argv[]) {
0015 //     MyCodeGenerator generator;
0016 //     return google::protobuf::compiler::PluginMain(argc, argv, &generator);
0017 //   }
0018 // You must link your plugin against libprotobuf and libprotoc.
0019 //
0020 // The core part of PluginMain is to invoke the given CodeGenerator on a
0021 // CodeGeneratorRequest to generate a CodeGeneratorResponse. This part is
0022 // abstracted out and made into function GenerateCode so that it can be reused,
0023 // for example, to implement a variant of PluginMain that does some
0024 // preprocessing on the input CodeGeneratorRequest before feeding the request
0025 // to the given code generator.
0026 //
0027 // To get protoc to use the plugin, do one of the following:
0028 // * Place the plugin binary somewhere in the PATH and give it the name
0029 //   "protoc-gen-NAME" (replacing "NAME" with the name of your plugin).  If you
0030 //   then invoke protoc with the parameter --NAME_out=OUT_DIR (again, replace
0031 //   "NAME" with your plugin's name), protoc will invoke your plugin to generate
0032 //   the output, which will be placed in OUT_DIR.
0033 // * Place the plugin binary anywhere, with any name, and pass the --plugin
0034 //   parameter to protoc to direct it to your plugin like so:
0035 //     protoc --plugin=protoc-gen-NAME=path/to/mybinary --NAME_out=OUT_DIR
0036 //   On Windows, make sure to include the .exe suffix:
0037 //     protoc --plugin=protoc-gen-NAME=path/to/mybinary.exe --NAME_out=OUT_DIR
0038
0039 #ifndef GOOGLE_PROTOBUF_COMPILER_PLUGIN_H__
0040 #define GOOGLE_PROTOBUF_COMPILER_PLUGIN_H__
0041
0042 #include <string>
0043
0044 // Must be included last.
0045 #include "google/protobuf/port_def.inc"
0046
0047 namespace google {
0048 namespace protobuf {
0049 namespace compiler {
0050
0051 class CodeGenerator;  // code_generator.h
0052 class CodeGeneratorRequest;
0053 class CodeGeneratorResponse;
0054
0055 // Implements main() for a protoc plugin exposing the given code generator.
0056 PROTOC_EXPORT int PluginMain(int argc, char* argv[],
0057                              const CodeGenerator* generator);
0058
0059
0060 // Generates code using the given code generator. Returns true if the code
0061 // generation is successful. If the code generation fails, error_msg may be
0062 // populated to describe the failure cause.
0063 bool GenerateCode(const CodeGeneratorRequest& request,
0064                   const CodeGenerator& generator,
0065                   CodeGeneratorResponse* response, std::string* error_msg);
0066
0067 }  // namespace compiler
0068 }  // namespace protobuf
0069 }  // namespace google
0070
0071 #include "google/protobuf/port_undef.inc"
0072
0073 #endif  // GOOGLE_PROTOBUF_COMPILER_PLUGIN_H__