xref: /aosp_15_r20/external/cronet/third_party/protobuf/python/protobuf_distutils/README.md (revision 6777b5387eb2ff775bb5750e3f5d96f37fb7352b) 
1# Python setuptools extension
2
3This is an extension for Python setuptools which uses an installed protobuf
4compiler (`protoc`) to generate Python sources.
5
6## Installing
7
8To use this extension, it needs to be installed so it can be imported by other
9projects' setup.py.
10
11```shell
12$ python setup.py build
13$ python -m pip install .
14```
15
16(If you want to test changes to the extension, you can use `python setup.py
17develop`.)
18
19## Usage
20
21### Example setup.py configuration
22
23```python
24from setuptools import setup
25setup(
26    # ...
27    name='example_project',
28
29    # Require this package, but only for setup (not installation):
30    setup_requires=['protobuf_distutils'],
31
32    options={
33        # See below for details.
34        'generate_py_protobufs': {
35            'source_dir':        'path/to/protos',
36            'extra_proto_paths': ['path/to/other/project/protos'],
37            'output_dir':        'path/to/project/sources',  # default '.'
38            'proto_files':       ['relative/path/to/just_this_file.proto'],
39            'protoc':            'path/to/protoc.exe',
40        },
41    },
42)
43```
44
45### Example build invocation
46
47These steps will generate protobuf sources so they are included when building
48and installing `example_project` (see above):
49
50```shell
51$ python setup.py generate_py_protobufs
52$ python setup.py build
53$ python -m pip install .
54```
55
56## Options
57
58- `source_dir`:
59
60  This is the directory holding .proto files to be processed.
61
62  The default behavior is to generate sources for all .proto files found under
63  `source_dir`, recursively. This behavior can be controlled with options below.
64
65- `proto_root_path`:
66
67  This is the root path for resolving imports in source .proto files.
68
69  The default is the shortest prefix of `source_dir` among `[source_dir] +
70  self.extra_proto_paths`.
71
72- `extra_proto_paths`:
73
74  Specifies additional paths that should be used to find imports, in
75  addition to `source_dir`.
76
77  This option can be used to specify the path to other protobuf sources,
78  which are imported by files under `source_dir`.  No Python code will
79  be generated for .proto files under `extra_proto_paths`.
80
81- `output_dir`:
82
83  Specifies where generated code should be placed.
84
85  Typically, this should be the root package that generated Python modules
86  should be below.
87
88  The generated files will be placed under `output_dir` according to the
89  relative source paths under `proto_root_path`. For example, the source file
90  `${proto_root_path}/subdir/message.proto` will be generated as the Python
91  module `${output_dir}/subdir/message_pb2.py`.
92
93- `proto_files`:
94
95  A list of strings, specific .proto file paths for generating code, instead of
96  searching for all .proto files under `source_path`.
97
98  These paths are relative to `source_dir`. For example, to generate code
99  for just `${source_dir}/subdir/message.proto`, specify
100  `['subdir/message.proto']`.
101
102- `protoc`:
103
104  By default, the protoc binary (the Protobuf compiler) is found by
105  searching the environment path. To use a specific protoc binary, its
106  path can be specified. Resolution of the `protoc` value is as follows:
107  1. If the `--protoc=VALUE` flag is passed to `generate_py_protobufs`,
108     then `VALUE` will be used.
109     For example:
110     ```shell
111     $ python setup.py generate_py_protobufs --protoc=/path/to/protoc
112     ```
113  2. Otherwise, if a value was set in the `options`, it will be used.
114     (See "Example setup.py configuration," above.)
115  3. Otherwise, if the `PROTOC` environment variable is set, it will be
116     used. For example:
117     For example:
118     ```shell
119     $ PROTOC=/path/to/protoc python setup.py generate_py_protobufs
120     ```
121  4. Otherwise, `$PATH` will be searched.
122