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, 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			_ => {
156				unreachable!("Unsupported entity: {:#?}", entity)
157			}
158		}
159		ControlFlow::Continue(())
160	}
161
162	fn goodbye(mut self) {
163		// Some module level comments like "bioinspired" are not attached to anything and libclang
164		// doesn't seem to offer a way to extract them, do it the hard way then.
165		// That's actually the case for all modules starting with OpenCV 4.8.0 so this is now a single
166		// method of extracting comments
167		let mut comment = String::with_capacity(2048);
168		let mut found_module_comment = false;
169		let module_path = self
170			.opencv_module_header_dir
171			.join(format!("{}.hpp", self.module.opencv_name()));
172		if let Ok(module_file) = File::open(module_path).map(BufReader::new) {
173			let mut defgroup_found = false;
174			line_reader(module_file, |line| {
175				if !found_module_comment && line.trim_start().starts_with("/**") {
176					found_module_comment = true;
177					defgroup_found = false;
178				}
179				if found_module_comment {
180					if comment.contains("@defgroup") {
181						defgroup_found = true;
182					}
183					comment.push_str(line);
184					if line.trim_end().ends_with("*/") {
185						if defgroup_found {
186							return ControlFlow::Break(());
187						} else {
188							comment.clear();
189							found_module_comment = false;
190						}
191					}
192				}
193				ControlFlow::Continue(())
194			});
195		}
196		if found_module_comment {
197			self.visitor.visit_module_comment(comment);
198		}
199		for inject_func_fact in &self.gen_env.settings.func_inject {
200			let inject_func: Func = inject_func_fact();
201			if !inject_func.kind().as_class_method().is_some() {
202				self.visitor.visit_func(inject_func);
203			}
204		}
205		for generated in self.gen_env.settings.generator_module_tweaks.generate_types {
206			if let Ok(generated) = GeneratedType::try_from(generated()) {
207				self.visitor.visit_generated_type(generated);
208			}
209		}
210		self.visitor.goodbye();
211	}
212}
213
214impl<'tu, 'r, V: GeneratorVisitor<'tu>> OpenCvWalker<'tu, 'r, V> {
215	pub fn new(module: SupportedModule, opencv_module_header_dir: &'r Path, visitor: V, gen_env: GeneratorEnv<'tu>) -> Self {
216		Self {
217			module,
218			opencv_module_header_dir,
219			visitor,
220			func_names: NamePool::with_capacity(512),
221			gen_env,
222		}
223	}
224
225	fn process_const(visitor: &mut V, const_decl: Entity<'tu>) {
226		let cnst = Const::new(const_decl);
227		if cnst.exclude_kind().is_included() {
228			visitor.visit_const(cnst);
229		}
230	}
231
232	fn process_class(visitor: &mut V, gen_env: &mut GeneratorEnv<'tu>, class_decl: Entity<'tu>) {
233		if gen_env.get_export_config(class_decl).is_some() {
234			let cls = Class::new(class_decl, gen_env);
235			if cls.exclude_kind().is_included() {
236				cls.generated_types().into_iter().for_each(|dep| {
237					visitor.visit_generated_type(dep);
238				});
239				let _ = class_decl.walk_enums_while(|enm| {
240					Self::process_enum(visitor, enm);
241					ControlFlow::Continue(())
242				});
243				let _ = class_decl.walk_classes_while(|sub_cls| {
244					if !gen_env.get_export_config(sub_cls).is_some() {
245						gen_env.make_export_config(sub_cls).class_kind_override = if Class::new(sub_cls, gen_env).can_be_simple() {
246							ClassKindOverride::Simple
247						} else {
248							ClassKindOverride::Boxed
249						};
250					}
251					Self::process_class(visitor, gen_env, sub_cls);
252					ControlFlow::Continue(())
253				});
254				let _ = class_decl.walk_typedefs_while(|tdef| {
255					Self::process_typedef(visitor, gen_env, tdef);
256					ControlFlow::Continue(())
257				});
258				let cls = Class::new(class_decl, gen_env);
259				if let Some(enm) = cls.as_enum() {
260					visitor.visit_enum(enm);
261				} else {
262					visitor.visit_class(cls);
263				}
264			}
265		}
266	}
267
268	fn process_enum(visitor: &mut V, enum_decl: Entity<'tu>) {
269		let enm = Enum::new(enum_decl);
270		if enm.exclude_kind().is_included() {
271			for cnst in enm.consts() {
272				if cnst.exclude_kind().is_included() {
273					visitor.visit_const(cnst);
274				}
275			}
276			if !enm.is_anonymous() {
277				visitor.visit_enum(enm);
278			}
279		}
280	}
281
282	fn process_func(visitor: &mut V, func_names: &mut NamePool, gen_env: &GeneratorEnv<'tu>, func_decl: Entity<'tu>) {
283		if let Some(e) = gen_env.get_export_config(func_decl) {
284			let mut func = Func::new(func_decl, gen_env);
285			if let Some(func_fact) = gen_env.settings.func_replace.get(&mut func.matcher()) {
286				func = func_fact(&func)
287			}
288			if func.exclude_kind().is_included() {
289				let mut processor = |mut func: Func<'tu, '_>| {
290					func.generated_types().into_iter().for_each(|dep| {
291						visitor.visit_generated_type(dep);
292					});
293					if !e.only_generated_types {
294						let mut name = func.rust_leafname(FishStyle::No).into_owned().into();
295						let mut rust_custom_leafname = None;
296						if func_names.make_unique_name(&mut name).is_changed() {
297							rust_custom_leafname = Some(name.into());
298						}
299						func.set_rust_custom_leafname(rust_custom_leafname);
300						visitor.visit_func(func);
301					}
302				};
303				if let Some(specs) = gen_env.settings.func_specialize.get(&mut func.matcher()) {
304					for spec in specs {
305						processor(func.clone().specialize(spec));
306					}
307				} else {
308					processor(func);
309				}
310			}
311		}
312	}
313
314	fn process_typedef(visitor: &mut V, gen_env: &GeneratorEnv<'tu>, typedef_decl: Entity<'tu>) {
315		let typedef = Typedef::try_new(typedef_decl, gen_env);
316		if typedef.exclude_kind().is_included() {
317			match typedef {
318				NewTypedefResult::Typedef(typedef) => {
319					let export = gen_env.get_export_config(typedef_decl).is_some() || {
320						let underlying_type = typedef.underlying_type_ref();
321						underlying_type.kind().is_function()
322							|| !underlying_type.exclude_kind().is_ignored()
323							|| underlying_type
324								.template_kind()
325								.as_template_specialization()
326								.is_some_and(|templ| {
327									settings::IMPLEMENTED_GENERICS.contains(templ.cpp_name(CppNameStyle::Reference).as_ref())
328								})
329					};
330
331					if export {
332						typedef
333							.generated_types()
334							.into_iter()
335							.for_each(|dep| visitor.visit_generated_type(dep));
336						visitor.visit_typedef(typedef)
337					}
338				}
339				NewTypedefResult::Class(_) | NewTypedefResult::Enum(_) => {
340					// don't generate those because libclang will also emit normal classes and enums too
341				}
342			}
343		}
344	}
345}
346
347/// Main workhorse for generating OpenCV bindings for a specific module
348///
349/// Full binding generation for a module is happening in the following major phases:
350/// 1. Headers are parsed with `libclang`
351/// 2. [crate::generator_env::GeneratorEnvPopulator] collects the data necessary in the binding generation (1st pass)
352/// 3. Binding entities are extracted using the data from step 2 (2nd pass)
353/// 4. Specific source files are generated by [crate::writer::RustNativeBindingWriter] (at the moment)
354#[derive(Debug)]
355pub struct Generator {
356	clang_include_dirs: Vec<PathBuf>,
357	opencv_include_dir: PathBuf,
358	opencv_module_header_dir: PathBuf,
359	src_cpp_dir: PathBuf,
360	clang: ManuallyDrop<Clang>,
361}
362
363impl Drop for Generator {
364	fn drop(&mut self) {
365		const BAD_VERSIONS: [&str; 2] = [" 19.", " 20."];
366		if !(cfg!(windows)
367			&& cfg!(feature = "clang-runtime")
368			&& BAD_VERSIONS
369				.iter()
370				.any(|bad_version| clang::get_version().contains(bad_version)))
371		{
372			// `clang` has an issue on Windows when running with the `runtime` feature and clang-19+:
373			// https://github.com/KyleMayes/clang-rs/issues/63
374			// So we avoid dropping clang in that case as a workaround.
375			// `clang::get_version()` is string like "Apple clang version 15.0.0 (clang-1500.1.0.2.5)"
376			unsafe {
377				ManuallyDrop::drop(&mut self.clang);
378			}
379		} else {
380			eprintln!("=== Windows + clang-runtime + clang version is known to be problematic, skipping drop of Generator");
381		}
382	}
383}
384
385impl Generator {
386	pub fn new(opencv_include_dir: &Path, additional_include_dirs: &[&Path], src_cpp_dir: &Path) -> Self {
387		let clang_bin = clang_sys::support::Clang::find(None, &[]).expect("Can't find clang binary");
388		let mut clang_include_dirs = clang_bin.cpp_search_paths.unwrap_or_default();
389		for additional_dir in additional_include_dirs {
390			match canonicalize(additional_dir) {
391				Ok(dir) => clang_include_dirs.push(dir),
392				Err(err) => {
393					eprintln!(
394						"=== Cannot canonicalize one of the additional_include_dirs: {}, reason: {}",
395						additional_dir.display(),
396						err
397					);
398				}
399			};
400		}
401		let mut opencv_module_header_dir = opencv_include_dir.join("opencv2.framework/Headers");
402		if !opencv_module_header_dir.exists() {
403			opencv_module_header_dir = opencv_include_dir.join("opencv2");
404		}
405		Self {
406			clang_include_dirs,
407			opencv_include_dir: canonicalize(opencv_include_dir).expect("Can't canonicalize opencv_include_dir"),
408			opencv_module_header_dir: canonicalize(opencv_module_header_dir).expect("Can't canonicalize opencv_module_header_dir"),
409			src_cpp_dir: canonicalize(src_cpp_dir).expect("Can't canonicalize src_cpp_dir"),
410			clang: ManuallyDrop::new(Clang::new().expect("Can't initialize clang")),
411		}
412	}
413
414	fn handle_diags(diags: &[Diagnostic], panic_on_error: bool) {
415		if !diags.is_empty() {
416			let mut has_error = false;
417			eprintln!("=== WARNING: {} diagnostic messages", diags.len());
418			for diag in diags {
419				if !has_error && matches!(diag.get_severity(), Severity::Error | Severity::Fatal) {
420					has_error = true;
421				}
422				eprintln!("===    {diag}");
423			}
424			if has_error && panic_on_error {
425				panic!("=== Errors during header parsing");
426			}
427		}
428	}
429
430	pub fn is_clang_loaded(&self) -> bool {
431		#[cfg(feature = "clang-runtime")]
432		{
433			clang_sys::is_loaded()
434		}
435		#[cfg(not(feature = "clang-runtime"))]
436		{
437			true
438		}
439	}
440
441	pub fn clang_version(&self) -> String {
442		clang::get_version()
443	}
444
445	pub fn build_clang_command_line_args(&self) -> Vec<Cow<'static, str>> {
446		let mut args = self
447			.clang_include_dirs
448			.iter()
449			.map(|d| format!("-isystem{}", d.to_str().expect("Incorrect system include path")).into())
450			.chain([&self.opencv_include_dir, &self.src_cpp_dir].iter().flat_map(|d| {
451				let include_path = d.to_str().expect("Incorrect include path");
452				[format!("-I{include_path}").into(), format!("-F{include_path}").into()]
453			}))
454			.collect::<Vec<_>>();
455		args.push("-DOCVRS_PARSING_HEADERS".into());
456		args.push("-includeocvrs_common.hpp".into());
457		args.push("-std=c++17".into());
458		// allow us to use some custom clang args
459		let clang_arg = env::var_os("OPENCV_CLANG_ARGS");
460		if let Some(clang_arg) = clang_arg.as_ref().and_then(|s| s.to_str()) {
461			args.extend(Shlex::new(clang_arg).map(Cow::Owned));
462		}
463		args
464	}
465
466	/// Runs the clang header parsing, check for the compilation errors and hands off to `entity_processor`
467	pub fn pre_process(&self, module: SupportedModule, panic_on_error: bool, entity_processor: impl FnOnce(Entity)) {
468		let module = module.opencv_name();
469		let index = Index::new(&self.clang, true, false);
470		let mut module_file = self.src_cpp_dir.join(format!("{module}.hpp"));
471		if !module_file.exists() {
472			module_file = self.opencv_module_header_dir.join(format!("{module}.hpp"));
473		}
474		let root_tu = index
475			.parser(module_file)
476			.arguments(&self.build_clang_command_line_args())
477			.detailed_preprocessing_record(true)
478			.skip_function_bodies(true)
479			.parse()
480			.unwrap_or_else(|_| panic!("Cannot parse module: {module}"));
481		Self::handle_diags(&root_tu.get_diagnostics(), panic_on_error);
482		entity_processor(root_tu.get_entity());
483	}
484
485	/// Runs the full binding generation process using the supplied `visitor`
486	pub fn generate(&self, module: SupportedModule, panic_on_error: bool, visitor: impl for<'tu> GeneratorVisitor<'tu>) {
487		self.pre_process(module, panic_on_error, |root_entity| {
488			let gen_env = GeneratorEnv::global(module, root_entity);
489			let opencv_walker = OpenCvWalker::new(module, &self.opencv_module_header_dir, visitor, gen_env);
490			root_entity.walk_opencv_entities(opencv_walker);
491		});
492	}
493}
opencv_binding_generator/generator.rs

opencv_binding_generator/
generator.rs
