Protocol Buffers : Language Guide (proto3) - Options

• Protocol Buffers : Language Guide (proto3) - Options

Index

• Defining A Message Type
• Scalar Value Types
• Default Values
• Enumerations
• Using Other Message Types
• Nested Types
• Updating A Message Type
• Unknown Fields
• Any
• Oneof
• Maps
• Packages
• Defining Services
• JSON Mapping
• Options
• Generating Your Classes

Options

Individual declarations in a .proto file can be annotated with a number of options. Options do not change the overall meaning of a declaration, but may affect the way it is handled in a particular context. The complete list of available options is defined in google/protobuf/descriptor.proto.
.proto 파일에서 개별 선언에 여러 옵션을 추가할 수 있다. 옵션은 선언의 전체 의미를 변경하지 않지만 특정 상황에서 선언이 처리되는 방식에 영향을 미칠 수 있다. 사용 가능한 옵션의 전체 목록은 Google/proto/proto에 정의되어 있다.

Some options are file-level options, meaning they should be written at the top-level scope, not inside any message, enum, or service definition. Some options are message-level options, meaning they should be written inside message definitions. Some options are field-level options, meaning they should be written inside field definitions. Options can also be written on enum types, enum values, service types, and service methods; however, no useful options currently exist for any of these.
일부 옵션은 파일 수준 옵션으로, 메시지, 열거 또는 서비스 정의가 아닌 최상위 범위에서 작성되어야 한다. 일부 옵션은 메시지 수준 옵션이며, 메시지 정의 안에 기록해야 한다. 일부 옵션은 필드 수준 옵션이며, 필드 정의에 입력해야 한다. 열거형, 열거형 값, 서비스 유형 및 서비스 방법에도 옵션을 쓸 수 있지만 현재 이러한 옵션에 대한 유용한 옵션은 없다.

Here are a few of the most commonly used options:
가장 일반적으로 사용되는 몇 가지 옵션은 다음과 같다.

• java_package (file option): The package you want to use for your generated Java classes. If no explicit java_package option is given in the .proto file, then by default the proto package (specified using the "package" keyword in the .proto file) will be used. However, proto packages generally do not make good Java packages since proto packages are not expected to start with reverse domain names. If not generating Java code, this option has no effect.
  java_package(파일 옵션): 생성된 Java 클래스에 사용할 패키지. .proto 파일에 명시적 java_package 옵션이 제공되지 않은 경우, 기본적으로 .proto 파일에서 "package" 키워드를 사용하여 지정된 양성자 패키지가 사용된다. 그러나 프로토 패키지는 역방향 도메인 이름으로 시작하지 않을 것으로 예상되므로 일반적으로 프로토 패키지는 좋은 Java 패키지를 만들 수 없다. Java 코드를 생성하지 않으면 이 옵션은 영향을 받지 않는다.

  option java_package = "com.example.foo";

• java_multiple_files (file option): Causes top-level messages, enums, and services to be defined at the package level, rather than inside an outer class named after the .proto file.
  java_multiple_files(파일 옵션): .proto 파일 이름을 딴 외부 클래스 내부가 아닌 최상위 메시지, 열거값 및 서비스를 패키지 수준에서 정의한다.

  option java_multiple_files = true;

• java_outer_classname (file option): The class name for the outermost Java class (and hence the file name) you want to generate. If no explicit java_outer_classname is specified in the .proto file, the class name will be constructed by converting the .proto file name to camel-case (so foo_bar.proto becomes FooBar.java). If not generating Java code, this option has no effect.
  java_outer_classname(파일 옵션): 생성할 가장 바깥쪽 Java 클래스(따라서 파일 이름)의 클래스 이름이다. .proto 파일에 명시적인 java_outer_classname이 지정되지 않은 경우 .proto 파일 이름을 낙타 케이스(foo_bar.proava)로 변환하여 클래스 이름을 구성한다. Java 코드를 생성하지 않으면 이 옵션은 영향을 받지 않는다.

  option java_outer_classname = "Ponycopter";

• ptimize_for (file option): Can be set to SPEED, CODE_SIZE, or LITE_RUNTIME. This affects the C++ and Java code generators (and possibly third-party generators) in the following ways:
  ptimize_for (파일 옵션): SPEED, CODE_SIZE 또는 LITE_RUNTIME으로 설정할 수 있다. 이 문제는 다음과 같은 방법으로 C++ 및 Java 코드 생성기(또는 타사 생성기일 수 있음)에 영향을 미친다.
  • SPEED (default): The protocol buffer compiler will generate code for serializing, parsing, and performing other common operations on your message types. This code is highly optimized.
    SPEED(기본값): 프로토콜 버퍼 컴파일러가 메시지 유형에 대해 직렬화, 구문 분석 및 기타 일반 작업을 수행하기 위한 코드를 생성한다. 이 코드는 매우 최적화되어 있다.
  • CODE_SIZE: The protocol buffer compiler will generate minimal classes and will rely on shared, reflection-based code to implement serialialization, parsing, and various other operations. The generated code will thus be much smaller than with SPEED, but operations will be slower. Classes will still implement exactly the same public API as they do in SPEED mode. This mode is most useful in apps that contain a very large number .proto files and do not need all of them to be blindingly fast.
    CODE_SIZE: 프로토콜 버퍼 컴파일러는 최소 클래스를 생성하고 공유된 반사 기반 코드를 사용하여 직렬화, 구문 분석 및 다양한 기타 작업을 구현한다. 따라서 생성된 코드는 SPEED보다 훨씬 작아지지만 작업 속도가 느려진다. 여전히 클래스는 SPEED 모드에서와 동일한 공용 API를 구현한다. 이 모드는 매우 많은 수의 .proto 파일이 포함된 앱에서 가장 유용하며 모든 파일이 맹목적으로 빠를 필요가 없다.
  • LITE_RUNTIME: The protocol buffer compiler will generate classes that depend only on the "lite" runtime library (libprotobuf-lite instead of libprotobuf). The lite runtime is much smaller than the full library (around an order of magnitude smaller) but omits certain features like descriptors and reflection. This is particularly useful for apps running on constrained platforms like mobile phones. The compiler will still generate fast implementations of all methods as it does in SPEED mode. Generated classes will only implement the MessageLite interface in each language, which provides only a subset of the methods of the full Message interface.
    LITE_RUNTIME: 프로토콜 버퍼 컴파일러는 "Lite" 런타임 라이브러리(libprotobuf 대신 llibprotectobuf-lite)에만 의존하는 클래스를 생성한다. Lite 런타임은 전체 라이브러리보다 훨씬 작지만(크기 정도) 설명자 및 반사와 같은 특정 기능은 사용하지 않는다. 이는 특히 휴대폰과 같이 제한된 플랫폼에서 실행되는 애플리케이션에 유용하다. 컴파일러는 여전히 SPEED 모드에서처럼 모든 방법을 신속하게 구현할 수 있다. 생성된 클래스는 각 언어의 MessageLite 인터페이스만 구현하며, 전체 메시지 인터페이스 메서드의 하위 집합만 제공한다.

  option optimize_for = CODE_SIZE;

• cc_enable_arenas (file option): Enables arena allocation for C++ generated code.
  cc_enable_arenas(파일 옵션): C++ 생성 코드에 대한 영역 할당을 활성화한다.
• objc_class_prefix (file option): Sets the Objective-C class prefix which is prepended to all Objective-C generated classes and enums from this .proto. There is no default. You should use prefixes that are between 3-5 uppercase characters as recommended by Apple. Note that all 2 letter prefixes are reserved by Apple.
  objc_class_prefix(파일 옵션): 이 .proto의 모든 Objective-C 생성 클래스 및 Enum에 붙는 Object-C 클래스 접두사를 설정한다. 기본값은 없다. Apple에서 권장하는 대로 3~5자 사이의 접두사를 사용해야 한다. 두 문자 접두사 모두 Apple에서 예약되어 있다.
• deprecated (field option): If set to true, indicates that the field is deprecated and should not be used by new code. In most languages this has no actual effect. In Java, this becomes a @Deprecated annotation. In the future, other language-specific code generators may generate deprecation annotations on the field's accessors, which will in turn cause a warning to be emitted when compiling code which attempts to use the field. If the field is not used by anyone and you want to prevent new users from using it, consider replacing the field declaration with a reserved statement.
  사용되지 않음(필드 옵션): true로 설정하면 필드가 더 이상 사용되지 않으며 새 코드에서 사용되지 않아야 함을 나타낸다. 대부분의 언어에서 이것은 실제 효과가 없다. Java에서 이는 @반복된 주석이 된다. 향후에는 다른 언어별 코드 생성기가 필드의 접근자에 대해 감가 상각 주석을 생성할 수 있으며, 이로 인해 필드를 사용하려고 하는 코드를 컴파일할 때 경고가 차례로 발생한다. 필드가 다른 사용자가 사용하지 않고 새 사용자가 필드를 사용하지 못하도록 하려면 필드 선언을 예약된 문으로 바꾸는 것이 좋다.

  int32 old_field = 6 [deprecated=true];

Custom Options 사용자 지정 옵션

Protocol Buffers also allows you to define and use your own options. This is an advanced feature which most people don't need. If you do think you need to create your own options, see the Proto2 Language Guide for details. Note that creating custom options uses extensions, which are permitted only for custom options in proto3.
프로토콜 버퍼를 사용하면 자신의 옵션을 정의하고 사용할 수도 있다. 이것은 대부분의 사람들이 필요로 하지 않는 진보된 기능이다. 자신만의 옵션을 만들어야 한다고 생각하는 경우 자세한 내용은 Proto2 언어 가이드를 참조하라. 사용자 정의 옵션을 생성하면 proto3의 사용자 정의 옵션에만 허용되는 확장이 사용된다.