<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2022</year><year>2022</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>Features</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>features.xml</file>
  </header>
  <p>
    <marker id="features"/>
    Introduced in OTP 25, Erlang has the concept of selectable features.
    A feature can change, add or remove behaviour of the language and/or
    runtime system.  Examples can include
  </p>
  <list>
    <item>Adding new syntactical constructs to the language</item>
    <item>Change the semantics of an existing construct</item>
    <item>Change the behaviour of some runtime aspect</item>
  </list>
  <p>
    A feature will start out with a status of experimental part of OTP,
    making it possible to try out for users and give feedback.  The
    possibility to try out features is enabled by options to the
    compiler, directives in a module and options to the runtime system.
    Even when a feature is not experimental it will still be possible to
    enable or disable it.  This makes it possible to adapt a code base
    at a suitable pace instead of being forced when changing to a new
    release.
  </p>
  <p>
    The status of a feature will eventually end up as being either a
    permanent part of OTP or rejected, being removed and no longer
    selectable.
  </p>

  <section>
    <title>Life cycle of features</title>
    <p>A feature is in one of four possible states:</p>
    <taglist>
      <tag>Experimental</tag>
      <item>The initial state, is meant for trying out and collecting
      feedback.  The feature can be enabled but is disabled by
      default.</item>
      <tag>Approved</tag>
      <item>The feature has been finalised and is now part of OTP.  By
      default it is enabled, but can be disabled.</item>
      <tag>Permanent</tag>
      <item>The feature is now a permanent part of OTP.  It can no
      longer be disabled.</item>
      <tag>Rejected</tag>
      <item>The feature never reached the approved state and will not
      be part of OTP.  It cannot be enabled.</item>
    </taglist>
    <p>
      After leaving the experimental state, a feature can enter any of
      the other three states, and if the next state is approved, the
      feature will eventually end up in the permanent state.  A feature
      can change state only in connection with a release.
    </p>
    <p>
      A feature may be in the approved state for several releases.
    </p>
    <table>
      <row>
        <cell>State</cell>
        <cell>Default</cell>
        <cell>Configurable</cell>
        <cell>Available</cell>
      </row>
      <row>
        <cell>Experimental</cell>
        <cell>disabled</cell>
        <cell>yes</cell>
        <cell>yes</cell>
      </row>
      <row>
        <cell>Approved</cell>
        <cell>enabled</cell>
        <cell>yes</cell>
        <cell>yes</cell>
      </row>
      <row>
        <cell>Permanent</cell>
        <cell>enabled</cell>
        <cell>no</cell>
        <cell>yes</cell>
      </row>
      <row>
        <cell>Rejected</cell>
        <cell>disabled</cell>
        <cell>no</cell>
        <cell>no</cell>
      </row>
      <tcaption>Feature States</tcaption>
    </table>
    <list>
      <item>Being configurable means the possibility to enable or
      disable the feature by means of compiler options and directives
      in the file being compiled.</item>
      <item>Being available can be seen using the
      <c>FEATURE_AVAILABLE</c> macro.</item>
    </list>
  </section>

  <section>
    <title>Enabling and Disabling Features</title>
    <p>To use a feature that is in the experimental state, it has to
    be enabled during compilation.  This can be done in a number of
    different ways:
    </p>
    <taglist>
      <tag>Options to <c>erlc</c></tag>
      <item>Options <seecom
      marker="erts:erlc#enable-feature"><c>-enable-feature</c></seecom>
      and <seecom
      marker="erts:erlc#disable-feature"><c>-disable-feature</c></seecom>
      can be used to enable or disable individal features.</item>
      <tag>Compiler options</tag>
      <item>The compiler option <seeerl
      marker="compiler:compile#feature-option"><c>{feature,
      &lt;feature&gt;, enable|disable}</c></seeerl> can be used either
      as a <c>+&lt;term&gt;</c> option to <c>erlc</c>, in the options
      argument to function in the <c>compile</c> module, or in the
      <c>-compile(..)</c> attribute in a file.</item>
      <tag>The feature directive</tag>
      <item>Inside a prefix of a module, one can use a <seeerl
      marker="compiler:compile#feature-directive"><c>-feature(&lt;feature&gt;,
      enable|disable)</c></seeerl> directive.  This is the preferred
      method of enabling and disabling features.</item>
    </taglist>
    <p>
      Note that to load a module compiled with features enabled, the
      corresponding features must be enabled in the runtime.  This
      is done using options <seecom
      marker="erts:erl#enable-feature"><c>-enable-feature</c></seecom>
      and <seecom
      marker="erts:erl#disable-feature"><c>-disable-feature</c></seecom>
      to <c>erl</c>.  This is to allow the possibility to prevent
      the use of experimental features in, e.g., production.  This
      will catch experimental features used in both own and third
      party components.  An active choice to use experimental
      features must be done.
    </p>
  </section>

  <section>
    <title>Preprocessor Additions</title>
    <p>
      To allow for conditional compilation during transitioning of a
      code base and/or trying out experimental features <seeguide
      marker="system/reference_manual:macros#predefined-macros">feature</seeguide>
      <c>predefined macros</c> <c>?FEATURE_AVAILABLE(Feature)</c> and
      <c>?FEATURE_ENABLED(Feature)</c> are available.
    </p>
  </section>

  <section>
    <title>Information about Existing Features</title>
    <p>
    The module <c>erl_features</c> <seeerl
    marker="stdlib:erl_features"><c>erl_features</c></seeerl> exports
    a number of functions that can be used to obtain information about
    current features as well as the features used when compiling a
    module.
    </p>
    <p>One can also use the <c>erlc</c> options <seecom
    marker="erts:erlc#list-features"><c>-list-features</c></seecom>
    and <seecom
    marker="erts:erlc#describe-feature"><c>-describe-feature
    &lt;feature&gt;</c></seecom> to get information about existing
    features.
    </p>
    <p>
      Additionally, there is the compiler option
      <seeerl
      marker="compiler:compile#warn-keywords"><c>warn_keywords</c></seeerl>
      that can be used to find atoms in the code base that might
      collide with keywords in features not yet enabled.
    </p>
  </section>

  <section>
    <title>Existing Features</title>
    <p>
      The following configurable features exist:
    </p>
    <taglist>
      <tag><c>maybe_expr</c> (experimental)</tag>
      <item>
        Implementation of the <seeguide
        marker="expressions#maybe"><c>maybe</c></seeguide> expression
        proposed in <url href="https://www.erlang.org/eeps/eep-0049">EEP 49</url>.</item>
    </taglist>
  </section>
</chapter>
