Struct Rule 

pub struct Rule { /* private fields */ }

One rule of the table: what it matches, and the settings it applies to a process that matches. A rule has no name; exe is its only required matcher, and everything else is optional.

Rule::new makes one for an exe, and the with_ methods add what it matches on and sets. A rule is its content alone: where it comes from is the Source the Table keeps beside it.

Implementations

impl Rule

pub const fn new(exe: Exe) -> Self

The rule for the processes exe matches, with no fingerprint and no setting.

pub fn with_company(self, company: Fingerprint) -> Self

The rule that also pins company on the image’s CompanyName.

pub fn with_product(self, product: Fingerprint) -> Self

The rule that also pins product on the image’s ProductName.

pub fn with_original_filename(self, original_filename: Fingerprint) -> Self

The rule that also pins original_filename on the image’s OriginalFilename.

pub fn with_dxgi(self, dxgi: impl Into<Setting<Dxgi>>) -> Self

The rule with dxgi for Rule::dxgi.

pub fn with_d3d9(self, d3d9: impl Into<Setting<D3d9>>) -> Self

The rule with d3d9 for Rule::d3d9.

pub fn with_wined3d(self, wined3d: impl Into<Setting<Wined3d>>) -> Self

The rule with wined3d for Rule::wined3d.

pub fn with_opengl(self, opengl: impl Into<Setting<OpenGl>>) -> Self

The rule with opengl for Rule::opengl.

pub fn with_dpi_aware(self, aware: impl Into<Setting<bool>>) -> Self

The rule with aware for Rule::dpi_aware.

pub fn with_large_address_aware(self, laa: impl Into<Setting<bool>>) -> Self

The rule with laa for Rule::large_address_aware.

pub fn with_gcmouse(self, on: impl Into<Setting<bool>>) -> Self

The rule with on for Rule::gcmouse.

pub fn with_force_nx(self, on: impl Into<Setting<bool>>) -> Self

The rule with on for Rule::force_nx.

pub fn with_metal_hud(self, on: impl Into<Setting<bool>>) -> Self

The rule with on for Rule::metal_hud.

pub fn with_debug_channel(self, entry: DebugChannel) -> Self

The rule with entry after its other Rule::debug_channels.

pub fn with_dll_override(self, entry: DllOverride) -> Self

The rule with entry after its other Rule::dll_overrides.

pub fn with_argument(self, argument: Argument) -> Self

The rule with argument after its other Rule::arguments.

pub fn with_arguments_override( self, arguments: impl IntoIterator<Item = Argument>, ) -> Self

The rule whose Rule::arguments_override is arguments, which may be empty to clear the arguments.

pub fn with_env(self, entry: EnvEntry) -> Self

The rule with entry after its other Rule::env entries.

pub const fn exe(&self) -> &Exe

The executable the rule matches.

pub const fn company(&self) -> Option<&Fingerprint>

The substring the image’s version CompanyName must contain, if the rule pins one.

pub const fn product(&self) -> Option<&Fingerprint>

The substring the image’s version ProductName must contain, if the rule pins one.

pub const fn original_filename(&self) -> Option<&Fingerprint>

The substring the image’s version OriginalFilename must contain, if the rule pins one.

pub const fn dxgi(&self) -> Setting<Dxgi>

The DXGI-family implementation to load, for D3D10, D3D10.1, D3D11 and D3D12 (see Dxgi): compatdb.so prepends its tree, lib/wine/dxgi/<name>, to ntdll’s builtin DLL search path when the process loads. Only Dxgi::Dxmt has D3D12 (vkd3d-proton): under Dxgi::Wined3d d3d12.dll does not load, so a game that only has D3D12 does not start.

With no rule setting it, the process gets wined3d, as in upstream Wine. builtin::dxgi_dxmt sets it for every process.

pub const fn d3d9(&self) -> Setting<D3d9>

The D3D9 implementation to load (see D3d9): compatdb.so prepends its tree, lib/wine/d3d9/<name>, to ntdll’s builtin DLL search path when the process loads.

With no rule setting it, the process gets wined3d, as in upstream Wine. builtin::d3d9_mtld3d sets it for every process.

pub const fn wined3d(&self) -> Setting<Wined3d>

The renderer of wined3d, for every wined3d user in the process (see Wined3d): the wined3d trees of Rule::dxgi and Rule::d3d9, D3D8 and DirectDraw share one wined3d, which reads its settings once. It chooses no tree.

Set, compatdb.so names the renderer in WINE_D3D_CONFIG, after the rules’ own env entries: the options a rule’s env gives the variable are kept and its renderer is replaced (see Resolution::fold_derived_env), and a value the process was started with is replaced as by any env entry. wined3d reads the variable from the environment block, and it takes precedence over wined3d’s registry settings.

With no rule setting it, compatdb.so sets nothing: a WINE_D3D_CONFIG from a rule’s env or inherited from the process that started this one applies as it is, and without one wined3d’s registry settings or its default, OpenGL.

pub const fn opengl(&self) -> Setting<OpenGl>

Which OpenGL the Mac driver gives the process (see OpenGl). winemac.drv reads the value through ntdll when the process first uses OpenGL. OpenGl::Egl does not fall back: where Zink has no GPU, as on a Mac without a Metal 4 GPU, the process gets no OpenGL.

With no rule setting it, the Mac driver gives Apple’s OpenGL, as upstream Wine does. builtin::opengl_egl sets it for every process. The value is the process’s own: the programs it starts get the value of their own rules.

pub const fn dpi_aware(&self) -> Setting<bool>

Whether the process is DPI-aware (true, system-aware) or unaware (false). win32u applies the value before the AppCompatFlags Layers registry value and the manifest, and the first setting wins, so the rule beats both. true also caps a program that asks for per-monitor awareness at system-aware.

With no rule setting it, Wine decides: the registry value, then the manifest, and otherwise unaware. So default differs from false here. builtin::dpi_aware sets it for every process.

pub const fn large_address_aware(&self) -> Setting<bool>

Whether a 32-bit process gets the 4 GB address space whatever its executable’s IMAGE_FILE_LARGE_ADDRESS_AWARE flag says. ntdll applies it after compatdb.so returns. false does not take the space away from an executable that has the flag; it only stops forcing it, so it is the same as unset. Has no effect on a 64-bit process.

With no rule setting it, the executable’s flag decides, as in upstream Wine.

pub const fn gcmouse(&self) -> Setting<bool>

Whether the Mac driver takes the mouse movement of raw input (WM_INPUT) and DirectInput from GameController’s GCMouse, in the device’s own counts, instead of from the cursor’s movement, which macOS accelerates and scales for retina. winemac.drv reads the value through ntdll when it reads its settings.

With no rule setting it, the Mac driver keeps upstream Wine’s behaviour, the cursor’s movement, which false gives too. builtin::gcmouse sets it for every process.

pub const fn force_nx(&self) -> Setting<bool>

Whether no-execute stays permanently on in a 32-bit process, even when its executable or a DLL lacks the NX_COMPAT flag, for which Wine turns it off, and whether the process cannot turn it off. ntdll reads the value the first time the process asks for or changes its execute flags. Has no effect on a 64-bit process, which always has no-execute on.

false is the same as unset: Wine’s behaviour. builtin::force_nx sets it for every process. Unlike an env entry, the value is the process’s own: the processes it starts get their own rules’ value.

pub const fn metal_hud(&self) -> Setting<bool>

Whether the Metal performance HUD shows in the process. compatdb.so turns the value into the environment entries of metal_hud_env, before this rule’s own env entries (see Resolution::fold_derived_env), so an env entry for one of the variables wins: true sets the variables that show the HUD, false removes them. Like Rule::wined3d and unlike the other scalar settings it reaches the programs the process starts, which inherit the variables. With no rule setting it, the process keeps the variables it was started with.

pub fn debug_channels(&self) -> &[DebugChannel]

WINEDEBUG entries for the processes the rule names. Wine reads WINEDEBUG before compatdb.so loads, so the library only logs them; a launcher puts them into the variable it starts Wine with (see Table::winedebug).

pub fn dll_overrides(&self) -> &[DllOverride]

WINEDLLOVERRIDES elements, which compatdb.so adds through ntdll’s load-order hook. ntdll consults them before the registry DllOverrides keys, and one for a module replaces the WINEDLLOVERRIDES entry for it, so neither can undo them.

An entry whose order is default sets no load order: it removes the entries that the rules folded before it gave its modules, so the registry and WINEDLLOVERRIDES decide for them again (see DllOverride::is_default). Module names match ASCII-case-insensitively, with or without .dll.

With no entry, WINEDLLOVERRIDES and the registry decide, as in upstream Wine. builtin::no_mono_or_gecko adds entries for every process.

pub fn arguments(&self) -> &[Argument]

Text appended to the command line when the process loads, each entry unless the command line already holds it. The test is a case-sensitive substring test, which leaves a Chromium --type= child that inherited its parent’s switches alone.

pub fn arguments_override(&self) -> Option<&[Argument]>

When set, the arguments that replace the list the rules folded before this one accumulated (see Table::resolve); Some with no entries clears it. This rule’s own Rule::arguments and those of the rules folded after it still append.

pub fn env(&self) -> &[EnvEntry]

Environment entries. The library sets them in the process’s environment block and unix environment when it loads, before any PE code runs, and the programs the process starts inherit them. The entries of a built-in rule that matches every process (exe *, no fingerprint) are defaults: such an entry sets its variable only where the process does not have it, so a value the caller exported wins, an empty one included (see Origin::env_is_default). Every other entry replaces the variable, or removes it when it has no value.

pub fn sets_nothing(&self) -> bool

Whether the rule sets nothing beyond its matchers: no scalar setting is set or reset and every list is empty, arguments_override included. Such a rule changes nothing in any process, so a launcher can leave it out of the table, for example the rule for every process that its launch-wide settings make when they set nothing.

pub fn scalar(&self, scalar: Scalar) -> Setting<ScalarValue>

What this rule says about the scalar setting scalar.

pub fn matches(&self, exe: &str, version: &VersionInfo) -> bool

Whether this rule applies to a process with the given image basename and version resource. exe matches the basename case-insensitively, or every basename when it is Exe::Any; a fingerprint field, when present, is an additional case-insensitive substring constraint on the corresponding version string (so a rule with none matches on the basename alone).

pub const fn specificity(&self) -> Specificity

How specific this rule is: a wildcard rule (a launch-wide default), one naming an executable, each with or without a version fingerprint. Table::resolve folds a wildcard rule before one naming an executable whatever their source, and within each the built-in rules before the others, a rule without a fingerprint before one with.

pub const fn is_unfingerprinted(&self) -> bool

Whether this rule matches on its executable alone. Such a rule catches every program with that file name, which is worth a warning for all but the few basenames that are unique in practice.

pub fn matches_the_same_as(&self, other: &Self) -> bool

Whether two rules would match exactly the same processes, which can only be a mistake in a hand-written table.

pub fn matchers(&self) -> String

The matchers of this rule as the log prints them: the exe, then the fingerprint values it pins in parentheses, for example WoW.exe (Blizzard Entertainment, World of Warcraft, WoW.exe).

impl Rule

pub fn set(&mut self, key: Key, value: &str) -> Result<(), FieldError>

Set the field key from value, as a launcher’s setting gives it: the value of a matcher or a scalar setting, or one more entry of a list. For a scalar, default in any case resets the setting (see Setting::Reset); for env, value is NAME=value, as for Rule::set_env. A debug_channels value is split at each , into entries of their own, as WINEDEBUG reads it, so that Table::winedebug scopes each of them to the rule’s exe; an empty entry, +relay, included, is refused.

On an error the rule is left as it was.

Errors

The FieldError of a value the key does not take: a word the setting does not know, a part that is empty or holds a NUL, and the errors of Rule::set_env. A retired value is FieldError::RetiredValue: dxgi gptk, a warning, since the built-in rules then decide as if there were no value. A setting that Key::allowed_on_any does not allow, arguments_override, in a rule whose exe is *, or an exe of * in a rule that holds one, is FieldError::ArgumentsOverrideOnAny: for every process it would take away the arguments the built-in rules give single programs. Make the rule with its exe first.

pub fn set_list<T: AsRef<str>>( &mut self, key: Key, values: impl IntoIterator<Item = T>, ) -> Result<(), FieldError>

Make the list key hold values, each read as Rule::set reads one entry, in place of the entries it had. For arguments_override that sets the override, and no values clear the arguments of the rules folded before (see Rule::arguments_override). For env each value is NAME=value.

On an error the rule is left as it was.

Errors

FieldError::NotAList for a key that holds one value, FieldError::ArgumentsOverrideOnAny as for Rule::set, even with no values, and the first error Rule::set gives for one of the values.

pub fn set_env(&mut self, name: &str, value: &str) -> Result<(), FieldError>

Add the environment entry that sets name to value after the rule’s other entries; an empty value removes the variable.

Errors

The errors of check_env_name for name, and of EnvEntry::new for value.

Trait Implementations

impl Clone for Rule

fn clone(&self) -> Rule

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rule

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Rule

fn default() -> Self

The rule for every process that sets nothing, Rule::new of Exe::Any.

impl Eq for Rule

impl PartialEq for Rule

fn eq(&self, other: &Rule) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Rule