Limitations

The Compat library has a number of limitations. Complete backwards compatibility cannot be provided due to the scope of Compat and for technical reasons. The scope is intentionally restricted in order to limit the size of Compat and to ensure that the library stays maintainable.

Emacs version 24.4 is chosen as the oldest version supported by Compat, since Elisp has seen significant changes at that version. Since 24.4 Emacs major versions consistently bump the major version number. On the library level, subr-x was introduced in 24.4. Most popular Emacs packages already require 24.4 or even newer versions of Emacs. Supporting for more historical Emacs versions would complicate maintenance while only few packages and users would benefit.

Below we list a number of reasons why certain functionality cannot be provided. Note that in some special cases exceptions can be made and functions can still be added to Compat even if they satisfy the criteria from the list. In case you miss functionality which you think should belong here, a report would be much appreciated.

• The additional functionality is a command or a user-facing minor or major mode. Compat is limited to functionality on the “library level”. Generally functions provided by Compat are non-interactive, such that the user interface (M-x) is unaffected by the presence of Compat.
• The function is not useful for package authors or not intended to be used by packages, but is only useful on the configuration level. The macro setopt is such an example.
• Private (double dashed) functions are not ported back. If Compat includes some private functions, they are meant purely for internal usage.
• The added or extended function belongs to the “application level” and not the “library level”. Features which are not preloaded often belong to the “application level”. Application examples are programming modes or modes like Dired, IRC and Gnus. If these modes are extended with new functions, these are not ported back.
• An existing function or macro was extended by some new functionality. To support these cases, the function or macro would have to be advised. Since this is invasive and adds significant overhead, even when the new feature is not used, Compat does not use advices. As a compromise, compatibility functions and macros with a changed calling convention or behavior can be accessed via the compat-function and compat-call macros. In this manual we call such definitions Extended Definitions. An example is the function plist-get. Note that extended functions are subject to closer scrutiny, since their usage via compat-call is not completely painless. If a particular extended function does not see much usage or the extension yields only marginal benefits, we may not provide it as part of Compat.
• Bug fixes are usually not ported back as part of Compat. Sometimes library functions show wrong behavior for edge cases. In those cases Compat could in principle provide a compatibility function which is invoked via compat-call. Such extended definitions would increase the maintenance burden of Compat. At the same time the benefits would be small given that Compat does not override existing definitions.
• The definition belongs to an Emacs core package, which is also distributed via ELPA. Compat does not have to provide backward compatibility for core packages since the updated package can be installed directly from ELPA. Examples include the libraries xref, project, seq, map and transient.
• New functionality depends on an entire new, non-trivial core library, which is infeasible to duplicate within Compat. If a backport of such a library is required, the preferred approach is to either release the library separately on GNU ELPA as a core package or as a separately maintained GNU ELPA package. An example is the iso8601 library.
• New functionality was implemented in the C core, or depends on external libraries that cannot be reasonably duplicated in the scope of a compatibility library. Sometimes new functions on the C level rely on internal data structures, which we cannot access, rendering a backport impossible. For example a missing libxml or libtreesitter cannot be emulated.
• The semantics of Elisp changed on a deep level. For example the addition of big integer support in Emacs 27.1 cannot be replicated on the level of Compat.