(Introduced in 4.08)
Since OCaml 4.08, it is possible to mark components (such as value or type declarations) in signatures with “alerts” that will be reported when those components are referenced. This generalizes the notion of “deprecated” components which were previously reported as warning 3. Those alerts can be used for instance to report usage of unsafe features, or of features which are only available on some platforms, etc.
Alert categories are identified by a symbolic identifier (a lowercase identifier, following the usual lexical rules) and an optional message. The identifier is used to control which alerts are enabled, and which ones are turned into fatal errors. The message is reported to the user when the alert is triggered (i.e. when the marked component is referenced).
The ocaml.alert or alert attribute serves two purposes: (i) to mark component with an alert to be triggered when the component is referenced, and (ii) to control which alerts are enabled.
When marking a component, the attribute takes an identifier possibly followed by a message. Here is an example of a value declaration marked with an alert:
Here unix is the identifier for the alert. If this alert category is enabled, any reference to U.fork will produce a message at compile time, which can be turned or not into a fatal error.
For other structure or signature components, the syntax is as follows:
When the typer coerces a signature with alerts to a signature with different alerts:
any alert that isn’t passed through, i.e. the alert on x here, gets triggered.
Finally, to alert when the module corresponding to a file is referenced, a floating attribute can be written at the top of the “.mli” file (i.e. before any other non-attribute item), or the top of the “.ml” file if there is no “.mli” file:
Controlling which alerts are enabled and whether they are turned into fatal errors is done either through the compiler’s command-line option -alert <spec> or locally in the code through the alert or ocaml.alert attribute taking a single string payload <spec>. In both cases, the syntax for <spec> is a concatenation of items of the form:
As a special case, if id is all, it stands for all alerts.
Here are some examples:
(* Disable all alerts, reenables just unix (as a soft alert) and window
(as a fatal-error), for the rest of the current structure *)
[@@@alert "-all--all+unix@window"]
...
let x =
(* Locally disable the window alert *)
begin[@alert "-window"]
...
end
Before OCaml 4.08, there was support for a single kind of deprecation alert. It is now known as the deprecated alert, but legacy attributes to trigger it and the legacy ways to control it as warning 3 are still supported. For instance, passing -w +3 on the command-line is equivalent to -alert +deprecated, and:
is equivalent to: