opencv_binding_generator/
generator.rs

1use std::borrow::Cow;
2use std::env;
3use std::fs::File;
4use std::io::BufReader;
5use std::mem::ManuallyDrop;
6use std::ops::ControlFlow;
7use std::path::{Path, PathBuf};
8
9use clang::diagnostic::{Diagnostic, Severity};
10use clang::{Clang, Entity, EntityKind, Index};
11use dunce::canonicalize;
12use shlex::Shlex;
13
14use crate::name_pool::NamePool;
15use crate::type_ref::{CppNameStyle, FishStyle, TypeRef, TypeRefKind};
16use crate::typedef::NewTypedefResult;
17use crate::writer::rust_native::element::RustElement;
18use crate::{
19	get_definition_text, line_reader, settings, AbstractRefWrapper, Class, ClassKindOverride, Const, Element, EntityExt,
20	EntityWalkerExt, EntityWalkerVisitor, Enum, Func, GeneratorEnv, SmartPtr, SupportedModule, Tuple, Typedef, Vector,
21};
22
23#[derive(Debug)]
24pub enum GeneratedType<'tu, 'ge> {
25	AbstractRefWrapper(AbstractRefWrapper<'tu, 'ge>),
26	Vector(Vector<'tu, 'ge>),
27	SmartPtr(SmartPtr<'tu, 'ge>),
28	Tuple(Tuple<'tu, 'ge>),
29}
30
31impl<'tu, 'ge> TryFrom<TypeRef<'tu, 'ge>> for GeneratedType<'tu, 'ge> {
32	type Error = ();
33
34	fn try_from(value: TypeRef<'tu, 'ge>) -> Result<Self, Self::Error> {
35		match value.kind().into_owned() {
36			TypeRefKind::StdVector(vec) => Ok(Self::Vector(vec)),
37			TypeRefKind::StdTuple(tuple) => Ok(Self::Tuple(tuple)),
38			TypeRefKind::SmartPtr(ptr) => Ok(Self::SmartPtr(ptr)),
39			_ => Err(()),
40		}
41	}
42}
43
44/// Visitor of the different supported OpenCV entities, used in conjunction with [Generator]
45#[allow(unused)]
46pub trait GeneratorVisitor<'tu>: Sized {
47	/// Check whether the visitor is interested in entities from the specified file
48	fn wants_file(&mut self, path: &Path) -> bool {
49		true
50	}
51
52	/// Top-level module comment
53	fn visit_module_comment(&mut self, comment: String) {}
54
55	/// Top-level constant
56	fn visit_const(&mut self, cnst: Const<'tu>) {}
57
58	/// Top-level enum
59	fn visit_enum(&mut self, enm: Enum<'tu, '_>) {}
60
61	/// Top-level function
62	fn visit_func(&mut self, func: Func<'tu, '_>) {}
63
64	/// Top-level type alias
65	fn visit_typedef(&mut self, typedef: Typedef<'tu, '_>) {}
66
67	/// Top-level class or an internal class of another class
68	fn visit_class(&mut self, class: Class<'tu, '_>) {}
69
70	/// Dependent generated type like `std::vector<Mat>` or `std::tuple<1, 2, 3>`
71	fn visit_generated_type(&mut self, typ: GeneratedType<'tu, '_>) {}
72
73	/// Called at the end of the visitation
74	fn goodbye(self) {}
75}
76
77/// Bridge between [EntityWalkerVisitor] and [GeneratorVisitor]
78///
79/// It takes [Entity]s supplied by the entity walker, extracts their export data (whether the entity should appear in bindings at
80/// all or is internal) and calls the corresponding method in [GeneratorVisitor] based on their type. This is the 2nd pass of the
81/// binding generation.
82pub struct OpenCvWalker<'tu, 'r, V> {
83	module: SupportedModule,
84	opencv_module_header_dir: &'r Path,
85	visitor: V,
86	func_names: NamePool,
87	gen_env: GeneratorEnv<'tu>,
88}
89
90impl<'tu, V: GeneratorVisitor<'tu>> EntityWalkerVisitor<'tu> for OpenCvWalker<'tu, '_, V> {
91	fn wants_file(&mut self, path: &Path) -> bool {
92		self.visitor.wants_file(path) || path.ends_with("ocvrs_common.hpp")
93	}
94
95	fn visit_entity(&mut self, entity: Entity<'tu>) -> ControlFlow<()> {
96		match entity.get_kind() {
97			EntityKind::MacroDefinition => Self::process_const(&mut self.visitor, entity),
98			EntityKind::MacroExpansion => {
99				if let Some(name) = entity.get_name() {
100					const BOXED: [&str; 6] = [
101						"CV_EXPORTS",
102						"CV_EXPORTS_W",
103						"CV_WRAP",
104						"GAPI_EXPORTS",
105						"GAPI_EXPORTS_W",
106						"GAPI_WRAP",
107					];
108					const SIMPLE: [&str; 4] = [
109						"CV_EXPORTS_W_SIMPLE",
110						"CV_EXPORTS_W_PARAMS",
111						"CV_EXPORTS_W_MAP",
112						"GAPI_EXPORTS_W_SIMPLE",
113					];
114					const RENAME: [&str; 2] = ["CV_EXPORTS_AS", "CV_WRAP_AS"];
115					if BOXED.contains(&name.as_str()) {
116						self.gen_env.make_export_config(entity);
117					} else if SIMPLE.contains(&name.as_str()) {
118						self.gen_env.make_export_config(entity).class_kind_override = ClassKindOverride::Simple;
119					} else if let Some(rename_macro) = RENAME.iter().find(|&r| r == &name) {
120						if let Some(new_name) = get_definition_text(entity)
121							.strip_prefix(rename_macro)
122							.and_then(|s| s.strip_prefix('('))
123							.and_then(|d| d.strip_suffix(')'))
124						{
125							self.gen_env.make_export_config(entity);
126							self.gen_env.make_rename_config(entity).rename = new_name.trim().into();
127						}
128					} else if name == "CV_NORETURN" {
129						self.gen_env.make_export_config(entity).no_return = true;
130					} else if name == "CV_NOEXCEPT" {
131						self.gen_env.make_export_config(entity).no_except = true;
132					} else if name == "CV_DEPRECATED" || name == "CV_DEPRECATED_EXTERNAL" {
133						self.gen_env.make_export_config(entity).deprecated = true;
134					} else if name == "CV_NODISCARD_STD" || name == "CV_NODISCARD" {
135						self.gen_env.make_export_config(entity).no_discard = true;
136					} else if name == "OCVRS_ONLY_DEPENDENT_TYPES" {
137						self.gen_env.make_export_config(entity).only_generated_types = true;
138					}
139				}
140			}
141			EntityKind::ClassDecl
142			| EntityKind::ClassTemplate
143			| EntityKind::ClassTemplatePartialSpecialization
144			| EntityKind::StructDecl => Self::process_class(&mut self.visitor, &mut self.gen_env, entity),
145			EntityKind::EnumDecl => Self::process_enum(&mut self.visitor, &self.gen_env, entity),
146			EntityKind::FunctionDecl => Self::process_func(&mut self.visitor, &mut self.func_names, &self.gen_env, entity),
147			EntityKind::TypedefDecl | EntityKind::TypeAliasDecl => Self::process_typedef(&mut self.visitor, &self.gen_env, entity),
148			EntityKind::VarDecl => {
149				if !entity.is_mutable() {
150					Self::process_const(&mut self.visitor, entity);
151				} else {
152					unreachable!("Unsupported VarDecl: {:#?}", entity)
153				}
154			}
155			_ => unreachable!("Unsupported entity: {:#?}", entity),
156		}
157		ControlFlow::Continue(())
158	}
159
160	fn goodbye(mut self) {
161		// Some module level comments like "bioinspired" are not attached to anything and libclang
162		// doesn't seem to offer a way to extract them, do it the hard way then.
163		// That's actually the case for all modules starting with OpenCV 4.8.0 so this is now a single
164		// method of extracting comments
165		let mut comment = String::with_capacity(2048);
166		let mut found_module_comment = false;
167		let module_path = self
168			.opencv_module_header_dir
169			.join(format!("{}.hpp", self.module.opencv_name()));
170		if let Ok(module_file) = File::open(module_path).map(BufReader::new) {
171			let mut defgroup_found = false;
172			line_reader(module_file, |line| {
173				if !found_module_comment && line.trim_start().starts_with("/**") {
174					found_module_comment = true;
175					defgroup_found = false;
176				}
177				if found_module_comment {
178					if comment.contains("@defgroup") {
179						defgroup_found = true;
180					}
181					comment.push_str(line);
182					if line.trim_end().ends_with("*/") {
183						if defgroup_found {
184							return ControlFlow::Break(());
185						} else {
186							comment.clear();
187							found_module_comment = false;
188						}
189					}
190				}
191				ControlFlow::Continue(())
192			});
193		}
194		if found_module_comment {
195			self.visitor.visit_module_comment(comment);
196		}
197		for inject_func_fact in &self.gen_env.settings.func_inject {
198			let inject_func: Func = inject_func_fact();
199			if !inject_func.kind().as_class_method().is_some() {
200				self.visitor.visit_func(inject_func);
201			}
202		}
203		for generated in self.gen_env.settings.generator_module_tweaks.generate_types {
204			if let Ok(generated) = GeneratedType::try_from(generated()) {
205				self.visitor.visit_generated_type(generated);
206			}
207		}
208		self.visitor.goodbye();
209	}
210}
211
212impl<'tu, 'r, V: GeneratorVisitor<'tu>> OpenCvWalker<'tu, 'r, V> {
213	pub fn new(module: SupportedModule, opencv_module_header_dir: &'r Path, visitor: V, gen_env: GeneratorEnv<'tu>) -> Self {
214		Self {
215			module,
216			opencv_module_header_dir,
217			visitor,
218			func_names: NamePool::with_capacity(512),
219			gen_env,
220		}
221	}
222
223	fn process_const(visitor: &mut V, const_decl: Entity<'tu>) {
224		let cnst = Const::new(const_decl);
225		if cnst.exclude_kind().is_included() {
226			visitor.visit_const(cnst);
227		}
228	}
229
230	fn process_class(visitor: &mut V, gen_env: &mut GeneratorEnv<'tu>, class_decl: Entity<'tu>) {
231		if gen_env.get_export_config(class_decl).is_some() {
232			let cls = Class::new(class_decl, gen_env);
233			if cls.exclude_kind().is_included() {
234				cls.generated_types().into_iter().for_each(|dep| {
235					visitor.visit_generated_type(dep);
236				});
237				let _ = class_decl.walk_enums_while(|enm| {
238					Self::process_enum(visitor, gen_env, enm);
239					ControlFlow::Continue(())
240				});
241				let _ = class_decl.walk_classes_while(|sub_cls| {
242					if !gen_env.get_export_config(sub_cls).is_some() {
243						gen_env.make_export_config(sub_cls).class_kind_override = if Class::new(sub_cls, gen_env).can_be_simple() {
244							ClassKindOverride::Simple
245						} else {
246							ClassKindOverride::Boxed
247						};
248					}
249					Self::process_class(visitor, gen_env, sub_cls);
250					ControlFlow::Continue(())
251				});
252				let _ = class_decl.walk_typedefs_while(|tdef| {
253					Self::process_typedef(visitor, gen_env, tdef);
254					ControlFlow::Continue(())
255				});
256				let cls = Class::new(class_decl, gen_env);
257				if let Some(enm) = cls.as_enum() {
258					visitor.visit_enum(enm);
259				} else {
260					visitor.visit_class(cls);
261				}
262			}
263		}
264	}
265
266	fn process_enum(visitor: &mut V, gen_env: &GeneratorEnv<'tu>, enum_decl: Entity<'tu>) {
267		let enm = Enum::new(enum_decl, gen_env);
268		if enm.exclude_kind().is_included() {
269			for cnst in enm.consts() {
270				if cnst.exclude_kind().is_included() {
271					visitor.visit_const(cnst);
272				}
273			}
274			if !enm.is_anonymous() {
275				visitor.visit_enum(enm);
276			}
277		}
278	}
279
280	fn process_func(visitor: &mut V, func_names: &mut NamePool, gen_env: &GeneratorEnv<'tu>, func_decl: Entity<'tu>) {
281		if let Some(e) = gen_env.get_export_config(func_decl) {
282			let mut func = Func::new(func_decl, gen_env);
283			if let Some(func_fact) = gen_env.settings.func_replace.get(&mut func.matcher()) {
284				func = func_fact(&func)
285			}
286			if func.exclude_kind().is_included() {
287				let mut processor = |mut func: Func<'tu, '_>| {
288					func.generated_types().into_iter().for_each(|dep| {
289						visitor.visit_generated_type(dep);
290					});
291					if !e.only_generated_types {
292						let mut name = func.rust_leafname(FishStyle::No).into_owned().into();
293						let mut rust_custom_leafname = None;
294						if func_names.make_unique_name(&mut name).is_changed() {
295							rust_custom_leafname = Some(name.into());
296						}
297						func.set_rust_custom_leafname(rust_custom_leafname);
298						visitor.visit_func(func);
299					}
300				};
301				if let Some(specs) = gen_env.settings.func_specialize.get(&mut func.matcher()) {
302					for spec in specs {
303						processor(func.clone().specialize(spec));
304					}
305				} else {
306					processor(func);
307				}
308			}
309		}
310	}
311
312	fn process_typedef(visitor: &mut V, gen_env: &GeneratorEnv<'tu>, typedef_decl: Entity<'tu>) {
313		let typedef = Typedef::try_new(typedef_decl, gen_env);
314		if typedef.exclude_kind().is_included() {
315			match typedef {
316				NewTypedefResult::Typedef(typedef) => {
317					let export = gen_env.get_export_config(typedef_decl).is_some() || {
318						let underlying_type = typedef.underlying_type_ref();
319						underlying_type.kind().is_function()
320							|| !underlying_type.exclude_kind().is_ignored()
321							|| underlying_type
322								.template_kind()
323								.as_template_specialization()
324								.is_some_and(|templ| {
325									settings::IMPLEMENTED_GENERICS.contains(templ.cpp_name(CppNameStyle::Reference).as_ref())
326								})
327					};
328
329					if export {
330						typedef
331							.generated_types()
332							.into_iter()
333							.for_each(|dep| visitor.visit_generated_type(dep));
334						visitor.visit_typedef(typedef)
335					}
336				}
337				NewTypedefResult::Class(_) | NewTypedefResult::Enum(_) => {
338					// don't generate those because libclang will also emit normal classes and enums too
339				}
340			}
341		}
342	}
343}
344
345/// Main workhorse for generating OpenCV bindings for a specific module
346///
347/// Full binding generation for a module is happening in the following major phases:
348/// 1. Headers are parsed with `libclang`
349/// 2. [crate::generator_env::GeneratorEnvPopulator] collects the data necessary in the binding generation (1st pass)
350/// 3. Binding entities are extracted using the data from step 2 (2nd pass)
351/// 4. Specific source files are generated by [crate::writer::RustNativeBindingWriter] (at the moment)
352#[derive(Debug)]
353pub struct Generator {
354	clang_include_dirs: Vec<PathBuf>,
355	opencv_include_dir: PathBuf,
356	opencv_module_header_dir: PathBuf,
357	src_cpp_dir: PathBuf,
358	clang: ManuallyDrop<Clang>,
359}
360
361impl Drop for Generator {
362	fn drop(&mut self) {
363		const BAD_VERSIONS: [&str; 3] = [" 19.", " 20.", " 21."];
364		// `clang` has an issue on Windows when running with the `runtime` feature and clang-19+:
365		// https://github.com/KyleMayes/clang-rs/issues/63
366		// So we avoid dropping clang in that case as a workaround.
367		// `clang::get_version()` is a string like "Apple clang version 15.0.0 (clang-1500.1.0.2.5)"
368		if cfg!(windows)
369			&& cfg!(feature = "clang-runtime")
370			&& BAD_VERSIONS
371				.iter()
372				.any(|bad_version| clang::get_version().contains(bad_version))
373		{
374			eprintln!("=== Windows + clang-runtime + clang version is known to be problematic, skipping drop of Generator");
375			return;
376		}
377		unsafe {
378			ManuallyDrop::drop(&mut self.clang);
379		}
380	}
381}
382
383impl Generator {
384	pub fn new(opencv_include_dir: &Path, additional_include_dirs: &[&Path], src_cpp_dir: &Path) -> Self {
385		let clang_bin = clang_sys::support::Clang::find(None, &[]).expect("Can't find clang binary");
386		let mut clang_include_dirs = clang_bin.cpp_search_paths.unwrap_or_default();
387		for additional_dir in additional_include_dirs {
388			match canonicalize(additional_dir) {
389				Ok(dir) => clang_include_dirs.push(dir),
390				Err(err) => {
391					eprintln!(
392						"=== Cannot canonicalize one of the additional_include_dirs: {}, reason: {}",
393						additional_dir.display(),
394						err
395					);
396				}
397			};
398		}
399		let mut opencv_module_header_dir = opencv_include_dir.join("opencv2.framework/Headers");
400		if !opencv_module_header_dir.exists() {
401			opencv_module_header_dir = opencv_include_dir.join("opencv2");
402		}
403		Self {
404			clang_include_dirs,
405			opencv_include_dir: canonicalize(opencv_include_dir).expect("Can't canonicalize opencv_include_dir"),
406			opencv_module_header_dir: canonicalize(opencv_module_header_dir).expect("Can't canonicalize opencv_module_header_dir"),
407			src_cpp_dir: canonicalize(src_cpp_dir).expect("Can't canonicalize src_cpp_dir"),
408			clang: ManuallyDrop::new(Clang::new().expect("Can't initialize clang")),
409		}
410	}
411
412	fn handle_diags(diags: &[Diagnostic], panic_on_error: bool) {
413		if !diags.is_empty() {
414			let mut has_error = false;
415			eprintln!("=== WARNING: {} diagnostic messages", diags.len());
416			for diag in diags {
417				if !has_error && matches!(diag.get_severity(), Severity::Error | Severity::Fatal) {
418					has_error = true;
419				}
420				eprintln!("===    {diag}");
421			}
422			if has_error && panic_on_error {
423				panic!("=== Errors during header parsing");
424			}
425		}
426	}
427
428	pub fn is_clang_loaded(&self) -> bool {
429		#[cfg(feature = "clang-runtime")]
430		{
431			clang_sys::is_loaded()
432		}
433		#[cfg(not(feature = "clang-runtime"))]
434		{
435			true
436		}
437	}
438
439	pub fn clang_version(&self) -> String {
440		clang::get_version()
441	}
442
443	pub fn build_clang_command_line_args(&self) -> Vec<Cow<'static, str>> {
444		let mut args = self
445			.clang_include_dirs
446			.iter()
447			.map(|d| format!("-isystem{}", d.to_str().expect("Incorrect system include path")).into())
448			.chain([&self.opencv_include_dir, &self.src_cpp_dir].iter().flat_map(|d| {
449				let include_path = d.to_str().expect("Incorrect include path");
450				[format!("-I{include_path}").into(), format!("-F{include_path}").into()]
451			}))
452			.collect::<Vec<_>>();
453		args.push("-DOCVRS_PARSING_HEADERS".into());
454		args.push("-includeocvrs_common.hpp".into());
455		args.push("-std=c++17".into());
456		// allow us to use some custom clang args
457		let clang_arg = env::var_os("OPENCV_CLANG_ARGS");
458		if let Some(clang_arg) = clang_arg.as_ref().and_then(|s| s.to_str()) {
459			args.extend(Shlex::new(clang_arg).map(Cow::Owned));
460		}
461		args
462	}
463
464	/// Runs the clang header parsing, check for the compilation errors and hands off to `entity_processor`
465	pub fn pre_process(&self, module: SupportedModule, panic_on_error: bool, entity_processor: impl FnOnce(Entity)) {
466		let module = module.opencv_name();
467		let index = Index::new(&self.clang, true, false);
468		let mut module_file = self.src_cpp_dir.join(format!("{module}.hpp"));
469		if !module_file.exists() {
470			module_file = self.opencv_module_header_dir.join(format!("{module}.hpp"));
471		}
472		let root_tu = index
473			.parser(module_file)
474			.arguments(&self.build_clang_command_line_args())
475			.detailed_preprocessing_record(true)
476			.skip_function_bodies(true)
477			.parse()
478			.unwrap_or_else(|_| panic!("Cannot parse module: {module}"));
479		Self::handle_diags(&root_tu.get_diagnostics(), panic_on_error);
480		entity_processor(root_tu.get_entity());
481	}
482
483	/// Runs the full binding generation process using the supplied `visitor`
484	pub fn generate(&self, module: SupportedModule, panic_on_error: bool, visitor: impl for<'tu> GeneratorVisitor<'tu>) {
485		self.pre_process(module, panic_on_error, |root_entity| {
486			let gen_env = GeneratorEnv::global(module, root_entity);
487			let opencv_walker = OpenCvWalker::new(module, &self.opencv_module_header_dir, visitor, gen_env);
488			root_entity.walk_opencv_entities(opencv_walker);
489		});
490	}
491}
opencv_binding_generator/generator.rs

opencv_binding_generator/
generator.rs
