How can I gracefully stop loading a package based on Mathematica version number?

Question

I recently shared some work with a colleague and realized that his having v12 caused issues, as I used some new-to-13 functions.

How can I put a requirement for a minimum version into my package?

Here's an example Futuristic.m which Exit[]s upon realizing that I don't have v14 yet.

BeginPackage["Futuristic`"]

amazingFeature::usage="Whoa, dude.  
The functionality of this amazingFeature requires the latest Mathematica";

Begin["`Private`"]

lowestAllowedVersionNumber=14;
If[$VersionNumber < lowestAllowedVersionNumber,
    (
        Print["Loading the Futuristic package failed.  
               You need version "<>ToString[lowestAllowedVersionNumber]];
        Exit[]
    )
]

amazingFeature[x_]:=2 x

End[]
EndPackage[]

If, from a front-end kernel I do

Get["~/Desktop/Futuristic.m"]

it prints the error message and exits.

However, exiting is extremely aggressive design. If I were in the middle of a calculation with a lot of definitions already built up, I'd be upset if the kernel exited.

Upon trying to load I want one of two things to happen:

• If the user has a recent-enough version, just load as expected.
• Otherwise:
  • Print a message telling the user that loading the Futuristic package failed, as above.
  • Quickly exit from the package definition.
  • Do not leave the user with any definitions from inside the Futuristic package at all. That includes (in the above example) lowestAllowedVersionNumber.

Is that possible? Is there a "standard" way to do it?

I thought one way would be to add a requirement to the BeginPackage statement, such as BeginPackage["Futuristic``",{"FunctionPoles``"}]. Since FunctionPoles is new in 13, if it's available then the user has v13. Trying BeginPackage["Futuristic``",{"FancyNewv14Function``"}] does produce error messages, but doesn't prevent the package from being loaded, amazingFeature is still available. I can wrap it in Check and exit,

Check[BeginPackage["Futuristic`","FancyNewv14Context`"],Exit[]];

but this still uses the aggressive Exit[], rather than gracefully preventing the rest of the package from being processed.

Answer 1

I second the suggestion of Szabolcs, in that paclets provide a clean declarative way of WL version - aware distribution of your package. You can have multiple paclets for the same package, with different paclet version and minimal WL version indicated in their PacletInfo file, and paclet manager will automatically pick the paclet with maximal paclet version, compatible with WL version requirements, at installation time.

OTOH, using Abort[] doesn't look like a good solution in this case, since it is too disruptive.

---

Should you insist on your suggested scheme, I can offer some solution, which should work when the package is loaded with Get or Needs from a file. It will not work when the package is evaluated interactively in the FrontEnd, however.

Here is a tiny package AbortPackageLoad.m, which you can place next to your own package, or anywhere else on $Path:

BeginPackage["AbortPackageLoad`"]

AbortPackageLoad::usage = 
"AbortPackageLoad[context, metadata] attempts to gracefully abort loading \
of a package from where it is called. The second optional argument may \
contain the metadata association, describing the specific reason for abort \
and associated information."

AbortPackageLoad::genfail = 
"Loading of package `1` failed for certain internal reason";

AbortPackageLoad::invldver = 
"Loading of package `1` failed. You need version `2`";


Begin["`Private`"]

$reasonMessageMap = <|
  "general" -> Function[Message[AbortPackageLoad::genfail]]
  ,
  "invalid_version" -> Function[
    {context, meta},
    Message[AbortPackageLoad::invldver, context, meta["RequiredVersion"]]
  ]
|>

removeContext[cont_String] /; MemberQ[Contexts[], cont] := 
  Quiet @ Remove[Evaluate[cont <> "*"]]

AbortPackageLoad[context_][metadata_ : <|"FailureReason" -> "general"|>] :=
  With[
    {private = context <> "Private`"}
    ,
    $reasonMessageMap[Lookup[metadata, "FailureReason", "general"]][
      context, metadata
    ];
    If[$InputFileName =!= "",
      Scan[removeContext, {context, private}];    
      Unprotect[$Packages];
      $Packages = DeleteCases[$Packages, context];
      Protect[$Packages];
      If[$Context === private, End[]];
      If[$Context === context, EndPackage[]];
      $ContextPath = DeleteCases[$ContextPath, context];
      Return[$Failed, Get]
    ];
]

End[]

EndPackage[]

Here is one way to use it in your package:

BeginPackage["Futuristic`"]

amazingFeature::usage = "Whoa, dude.  
The functionality of this amazingFeature requires the latest \
Mathematica";

`Private`abort = AbortPackageLoad`AbortPackageLoad[$Context];

Begin["`Private`"]

Needs["AbortPackageLoad`"]

lowestAllowedVersionNumber = 14;

If[$VersionNumber < lowestAllowedVersionNumber, 
  abort[<|
    "FailureReason" -> "invalid_version", 
    "RequiredVersion" -> "14+"
  |>]
];

amazingFeature[x_] := 2 x

End[]

EndPackage[]

---

EDIT

In response to the suggestion by Szabolcs in comments, I have modified the AbortPackageLoad function, so that it can also be used at the very top of the package file, before BeginPackage[] statement - if that's desirable / preferable. Or even inside the package, after BeginPackage[] but before Begin["`Private`"]. This is how it could be used in this fashion:

Block[{$ContextPath},
  Needs["AbortPackageLoad`"];
  If[$VersionNumber < 14, 
    AbortPackageLoad`AbortPackageLoad["Futuristic`"][<|
      "FailureReason" -> "invalid_version", 
      "RequiredVersion" -> "14+"
    |>]
  ];
]

BeginPackage["Futuristic`"]

...

EndPackage[]

END EDIT

---

The way AbortPackageLoad works is to clean and remove the public and private contexts of the package being loaded, then clean up global variables $Package and $ContextPath, ensure that package contexts are properly closed (so that $Context will point back to whatever context was there before loading your package), and finally, crucially, uses two-argument Return to return from Get early. Since Needs calls Get internally, this will work for Needs too.

When package is loaded from file, this mechanism works, because the file is parsed line by line, and complete expressions further in the file are not sent to evaluation early. When you execute the package from a FrontEnd cell, this will not work, because expressions further in the cell will still be parsed and send for evaluation. There are some ways to cancel the rest of evaluation queue, but I wasn't convinced that they are robust enough for this use case, so I excluded FrontEnd evaluation use case with the check If[$InputFileName =!= "", ...].

I don't see obvious cases where the above solution will break for non-MX packages loaded with Get / Needs, but OTOH I would still hesitate to use it in production code.