8.22 Alerts

(Introduced in 4.08)

Since OCaml 4.08, it is possible to mark components (such as value ortype declarations) in signatures with “alerts” that will be reportedwhen 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 unsafefeatures, or of features which are only available on some platforms,etc.

Alert categories are identified by a symbolic identifier (a lowercaseidentifier, following the usual lexical rules) and an optionalmessage. The identifier is used to control which alerts are enabled,and which ones are turned into fatal errors. The message is reportedto the user when the alert is triggered (i.e. when the markedcomponent is referenced).

The ocaml.alert or alert attribute serves two purposes: (i) tomark component with an alert to be triggered when the component isreferenced, and (ii) to control which alert names are enabled. In thefirst form, the attribute takes an identifier possiblyfollowed by a message. Here is an example of a value declaration markedwith an alert:

module U: sig
  val fork: unit -> bool
    [@@alert unix "This function is only available under Unix."]
end

Here unix is the identifier for the alert. If this alert categoryis enabled, any reference to U.fork will produce a message atcompile time, which can be turned or not into a fatal error.

And here is another example as a floating attribute on topof an “.mli” file (i.e. before any other non-attribute item)or on top of an “.ml” file without a corresponding interface file,so that any reference to that unit will trigger the alert:

[@@@alert unsafe "This module is unsafe!"]

Controlling which alerts are enabled and whether they are turned intofatal errors is done either through the compiler’s command-line option-alert <spec> or locally in the code through the alert orocaml.alert attribute taking a single string payload <spec>. Inboth cases, the syntax for <spec> is a concatenation of items of theform:

• +id enables alert id.
• -id disables alert id.
• ++id turns alert id into a fatal error.
• —id turns alert id into non-fatal mode.
• @id equivalent to ++id+id (enables id and turns it into a fatal-error)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 deprecationalert. It is now known as the deprecated alert, but legacyattributes to trigger it and the legacy ways to control it as warning3 are still supported. For instance, passing -w +3 on thecommand-line is equivant to -alert +deprecated, and:

val x: int
  [@@@ocaml.deprecated "Please do something else"]

is equivalent to:

val x: int
  [@@@ocaml.alert deprecated "Please do something else"]