David L. Jones | ff06e23 | 2020-08-31 10:40:57 -0700 | [diff] [blame] | 1 | # Python setuptools extension |
| 2 | |
| 3 | This is an extension for Python setuptools which uses an installed protobuf |
| 4 | compiler (`protoc`) to generate Python sources. |
| 5 | |
| 6 | ## Installing |
| 7 | |
| 8 | To use this extension, it needs to be installed so it can be imported by other |
| 9 | projects' setup.py. |
| 10 | |
| 11 | ```shell |
| 12 | $ python setup.py build |
David L. Jones | f4aa17b | 2020-09-14 20:06:39 -0700 | [diff] [blame] | 13 | $ python -m pip install . |
David L. Jones | ff06e23 | 2020-08-31 10:40:57 -0700 | [diff] [blame] | 14 | ``` |
| 15 | |
| 16 | (If you want to test changes to the extension, you can use `python setup.py |
| 17 | develop`.) |
| 18 | |
| 19 | ## Usage |
| 20 | |
| 21 | ### Example setup.py configuration |
| 22 | |
| 23 | ```python |
| 24 | from setuptools import setup |
| 25 | setup( |
| 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 | |
| 47 | These steps will generate protobuf sources so they are included when building |
| 48 | and installing `example_project` (see above): |
| 49 | |
| 50 | ```shell |
| 51 | $ python setup.py generate_py_protobufs |
| 52 | $ python setup.py build |
David L. Jones | f4aa17b | 2020-09-14 20:06:39 -0700 | [diff] [blame] | 53 | $ python -m pip install . |
David L. Jones | ff06e23 | 2020-08-31 10:40:57 -0700 | [diff] [blame] | 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 |
David L. Jones | ad29d40 | 2020-10-02 13:36:49 -0700 | [diff] [blame] | 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. |