There are some key differences in how plugins behave in emulator software for Mac and Linux systems that authors need to be aware of to avoid unexpected effects or application crashes.

Scope

ƒh is a Windows application, and not designed to run under either MacOS or Linux, which are both Unix-derived Operating Systems. However, in common with many Windows applications, it can be used on these systems via either an emulator (which simulates the Windows environment) or VM (Virtual Machine, which enables Windows to run inside a protected space within the host system).

The most common emulators are based on WINEWine is a free and open-source compatibility layer that allows computer programs developed for Microsoft Windows to run on Unix-like operating systems. https://www.winehq.org/, an open-source application. This is most commonly implemented on Macs via commercial packages such as CrossoverCrossOver is a Microsoft Windows compatibility layer available for Linux, macOS, and Chrome OS. It enables many Windows-based applications to run on Linux, macOS, or Chrome OS operating systems. CrossOver is a retail product developed by CodeWeavers and based on or PlayOnMac that provide additional features, but on Linux use of raw WINE or packaged with PlayOnLinuxPlayOnLinux is a graphical front end for the Wine software compatibility layer which allows Linux users to install Windows-based video games, Microsoft Office, Microsoft Internet Explorer, as well as many other applications. https://www.playonlinux.com/en/, both of which are free, are more common.

Both Crossover and WINE are being developed continuously, so features and therefore plugin compatibility can vary over time. Crossover for the Mac and WINE 9.0 (the latest stable version at the time of writing) appear to be very similar in how they support ƒh, so are the basis of these notesFamily Historian version 6 and below supports two types of Notes: Local notes (associated with a single person, record, or fact); and Note Records (sometimes called Shared Notes), that can be linked to multiple records and/or facts. Version 7 introduced. Unqualified references to WINE should therefore be read as applying to either Mac/Crossover or Linux/WINE 9.0. Older versions of WINE will have additional issues, but upgrading to 9.0 is recommended for use with ƒh.

Can Plugins Detect Emulators?

We have not identified a definitive method that a plugin can use to determine whether it is running inside an emulator or not, as WINE does not appear to have a supported method for its detection. Some old plugins have used differences in the detailed ƒh file structure to detect an emulator, but this no longer works as WINE now replicates Windows user file structures precisely.

Unix-derived file systems do not use drive letters, and denote directories using forward slashes (/), with a root at simply /. Both MacOS and Linux create two fixed directories off the root, /bin for binary system files and /etc for text-based configuration files (similar in concept to Windows .ini files). WINE acts as a bridge between the host Unix-derived file system and the Windows application, so translates the root directory as Z:\, and these directories as Windows folders Z:\bin and Z:\etc, respectively. If a plugin needs to know if it is inside WINE, all it has to do is check for the presence of these folders. If they do not exist, it is definitely a native Windows installation. If they do exist, it is highly likely to be WINE, as the only other explanation is that the user has mapped a network drive or non-system local drive to Z:\, which also contains both of these folders, an extremely unlikely circumstance.

An alternative method is to check whether Emulator Compatibility Mode has been selected (available in Tools > Preferences… > Advanced…, and stored at Registry key HKLM\SOFTWARE\Calico Pie\Family Historian\2.0\Preferences\Emulator-Compat-Mode). However, exactly what this setting does and its use in future versions of ƒh is undocumented, and it relies on users setting the option correctly.

Processing Emulator Errors

Unfortunately, conventional error handling routines do not work for WINE errors, as WINE may stop with a fatal error message and close ƒh before the plugin error handling has been called.

Processing Family Historian Data

ƒh API functionsA 'function' is an expression which returns values based on computations. Typically, functions require data to be supplied to them as 'parameters'. A function in Family Historian is similar to a 'function' as used in spreadsheet applications (such as MS and objects such as Item, DateWhen an Event happened, or an Attrribute was true. and Rich TextRich text can be applied to most long text fields such as Notes and Text From Source, and offers a word-processing style of formatting. pointers appear to be fully transparent to the use of WINE, so simple plugins that just process ƒh data operate in exactly the same way in an emulator as in a native Windows system.

Cosmetic Display Issues

Windows applications operating under WINE generally have a slightly different appearance compared with native Windows, as they create their own principalThe Principal (for Individual Facts) is the person to whom the fact applies — the person who was born, had the occupation, emigrated etc.  Family Facts have two Principals — the people who married, got divorced etc. user interface elements such as window controls and message prompts, as well as using different default fonts. In general, these are no more significant than variations between different versions of Windows, as each new iteration comes with an “update” and “refresh” of the user interface styling elements.

What may be more significant is font differences in the IUP library in the two systems, and their effect on the user interface. All combinations of Windows 10/11 and ƒh 6/7 use 9 pt Segoe UI as the default IUP font. This is a Microsoft font, and current versions of WINE use 8 pt Tahoma, a significantly smaller font.

Version 7 of ƒh enables the user to set a preferred font for the general appearance of the app, and it is best practice for new plugins to respect this choice when running in ƒh7, either by using fhUtils() or reading the appropriate Registry key directly, as it gives plugin menus a similar appearance to the main app. Unfortunately, while this may enhance overall plugin appearance, it does not guarantee consistent presentation between Windows and WINE, as the same font may be rendered at a different absolute screen size.

Advanced users who share either plugin or ƒh font settings between Windows and WINE may also run into difficulties, as they have different font sets, and what is available in one may not be available in the other, but this is probably a very niche application.

These issues are not unique to WINE due to the potential font variability that ƒh 7 provides, and are largely overcome by ensuring that plugins use relative size (expressed relative to the average character size in the active font) rather than absolute size in screen pixels. Plugin authors should check their plugins with a range of fonts (say a narrow 8 pt font to a wide 14 pt option) to ensure that there are no unexpected effects, particularly for plugins that have relatively busy menus.

Known Incompatibilities

File Access Issues

Windows and Unix-derived operating systems have significant differences in how files are defined, so it is perhaps not surprising that this is the area that most affects ƒh plugins.

LuaThe language in which Family Historian plugins are written. originated in the Unix world, so the basic language and its libraries has a much more “Unix feel” to it than Windows. The standard library for Lua file management is the Lua File System (lfs in the Unix-preferred lower case style), which is provided with ƒh. File attributesEvents are things that happened to an Individual and Attributes are things that described them. are retrieved using the lfs.attributes(..) function, which retrieves all Unix properties, but not those such as ShortName, ShortPath or Type that are undefined in Unix. Unix files are not subject to the 8+3 length limit of DOS and pre-95 versions of Windows, so do not need them.

Unfortunately, lfs does not support Unicode (non-Latin file and path names), so plugins that need this facility now use the Microsoft File System Object (FSO) for file management, which is Unicode compatible. This is most conveniently done for new plugins via the provided fhFileUtils() library, which provides a convenient wrapper for FSO functions, but for simple file and folder management it is not difficult to use FSO directly if backwards compatibility is required.

WINE does not support retrieving the Windows-only file and folder attributes Short Name, Short Path or Type, and any attempt to do so will cause an immediate crash. These specific properties are highly unlikely to be required for ƒh plugins, but early versions of both fhFileUtils() or personal variants of that used in store plugins for backwards compatibility retrieved all properties for convenience. These have now been removed from the latest version of fhFileUtils(..) (ƒh 7.0.23 or later), and will gradually be removed from existing store plugins in due course.

Perhaps more surprisingly, WINE also does not support the various timestamp attributes for folders (perhaps because Windows folders have significant differences to Unix directories, which are only files with specific attributes). These have also now been made optional in fhFileUtils(..). There is currently no recommended method for obtaining Unicode folder timestamps in plugins, other than copying the folder to a “safe” name and using lfs, which could potentially involve very large folders.

Registry Settings

Occasionally, a plugin may need to read (and exceptionally modify, if it is part of the plugins stated function) a ƒh Registry setting. The application-specific part of the WINE Registry is managed by ƒh, so is fully compatible with operation in native Windows.

The system-specific part of the WINE Registry is NOT the full Windows version, and does not support all Windows keys. Store plugins are specifically prohibited from modifying system Registry settings, but may need to read a setting such as Windows colours, locale, etc. Such plugins should be tested in WINE to ensure that the required setting is supported.

Windows Commands

Exceptionally, a Store plugin may need to call a Windows command directly in order to achieve something that cannot readily be done in any other way, such as reading Registry keys to and from file for backup or restore, or copying a large number of files automatically. Not all such commands are supported in WINE, and the following table lists known supported and unsupported examples:

Command	Supported	Typical Use
reg	yes	reg import and reg export are used for backup and restore
robocopy	no	copying multiple files, similar to long-deprecated xcopy command but many more options
xcopy	yes	more restricted version of robocopy
taskkill (PowerShell)	no	close ƒh automatically (subject to specific approval from Plugin StorePublished plugins can be downloaded from the Family Historian Plugin Store. Admin)
get-process (PowerShell)	no	detect multiple instances of ƒh