tonic/
macros.rs

1/*
2 *
3 * Copyright 2025 gRPC authors.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to
7 * deal in the Software without restriction, including without limitation the
8 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 * sell copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 *
23 */
24
25/// Include generated proto server and client items.
26///
27/// You must specify the gRPC package name.
28///
29/// ```rust,ignore
30/// mod pb {
31///     tonic::include_proto!("helloworld");
32/// }
33/// ```
34///
35/// # Note:
36/// **This only works if the tonic-build output directory has been unmodified**.
37/// The default output directory is set to the [`OUT_DIR`] environment variable.
38/// If the output directory has been modified, the following pattern may be used
39/// instead of this macro.
40///
41/// ```rust,ignore
42/// mod pb {
43///     include!("/relative/protobuf/directory/helloworld.rs");
44/// }
45/// ```
46/// You can also use a custom environment variable using the following pattern.
47/// ```rust,ignore
48/// mod pb {
49///     include!(concat!(env!("PROTOBUFS"), "/helloworld.rs"));
50/// }
51/// ```
52///
53/// [`OUT_DIR`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts
54#[macro_export]
55macro_rules! include_proto {
56    ($package: tt) => {
57        include!(concat!(env!("OUT_DIR"), concat!("/", $package, ".rs")));
58    };
59}
60
61/// Include an encoded `prost_types::FileDescriptorSet` as a `&'static [u8]`. The parameter must be
62/// the stem of the filename passed to `file_descriptor_set_path` for the `tonic-build::Builder`,
63/// excluding the `.bin` extension.
64///
65/// For example, a file descriptor set compiled like this in `build.rs`:
66///
67/// ```rust,ignore
68/// let descriptor_path = PathBuf::from(env::var("OUT_DIR").unwrap()).join("my_descriptor.bin")
69/// tonic_build::configure()
70///     .file_descriptor_set_path(&descriptor_path)
71///     .compile_protos(&["proto/reflection.proto"], &["proto/"])?;
72/// ```
73///
74/// Can be included like this:
75///
76/// ```rust,ignore
77/// mod pb {
78///     pub(crate) const FILE_DESCRIPTOR_SET: &[u8] = tonic::include_file_descriptor_set!("my_descriptor");
79/// }
80/// ```
81///
82/// # Note:
83/// **This only works if the tonic-build output directory has been unmodified**.
84/// The default output directory is set to the [`OUT_DIR`] environment variable.
85/// If the output directory has been modified, the following pattern may be used
86/// instead of this macro.
87///
88/// ```rust,ignore
89/// mod pb {
90///     pub(crate) const FILE_DESCRIPTOR_SET: &[u8] = include_bytes!("/relative/protobuf/directory/descriptor_name.bin");
91/// }
92/// ```
93///
94/// [`OUT_DIR`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts
95#[macro_export]
96macro_rules! include_file_descriptor_set {
97    ($package: tt) => {
98        include_bytes!(concat!(env!("OUT_DIR"), concat!("/", $package, ".bin")))
99    };
100}
tonic/macros.rs

tonic/
macros.rs
