File 3581-features-Add-documentation-for-features-support.patch of Package erlang
From f487df72f153263910c20d7ad4cc84167ff4336d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cons=20T=20=C3=85hs?= <cons@erlang.org>
Date: Tue, 3 May 2022 17:03:25 +0200
Subject: [PATCH] [features] Add documentation for features support
---
erts/doc/src/erl_cmd.xml | 24 +++
erts/doc/src/erlang.xml | 5 +
erts/doc/src/erlc_cmd.xml | 42 +++-
lib/compiler/doc/src/compile.xml | 34 ++-
lib/stdlib/doc/src/Makefile | 3 +-
lib/stdlib/doc/src/erl_features.xml | 101 +++++++++
lib/stdlib/doc/src/ref_man.xml | 3 +-
lib/stdlib/doc/src/specs.xml | 1 +
lib/stdlib/src/Makefile | 1 +
system/doc/reference_manual/expressions.xml | 12 +-
system/doc/reference_manual/features.xml | 218 ++++++++++++++++++++
system/doc/reference_manual/macros.xml | 16 +-
system/doc/reference_manual/part.xml | 1 +
system/doc/reference_manual/xmlfiles.mk | 1 +
14 files changed, 452 insertions(+), 10 deletions(-)
create mode 100644 lib/stdlib/doc/src/erl_features.xml
create mode 100644 system/doc/reference_manual/features.xml
diff --git a/erts/doc/src/erl_cmd.xml b/erts/doc/src/erl_cmd.xml
index 98412fcf25..42901d91db 100644
--- a/erts/doc/src/erl_cmd.xml
+++ b/erts/doc/src/erl_cmd.xml
@@ -300,6 +300,18 @@ $ <input>erl \
console. Useful for running daemons and backgrounds processes. Implies
<c><![CDATA[-noinput]]></c>.</p>
</item>
+ <tag>
+ <marker id="disable-feature"></marker>
+ <c><![CDATA[-disable-feature feature]]></c>
+ </tag>
+ <item>
+ <p>Disables the
+ <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide> <c><![CDATA[feature]]></c>
+ in the runtime system. The special feature <c>all</c> can be
+ used to disable all non permanent features.
+ </p>
+ </item>
<tag><c><![CDATA[-emu_args]]></c></tag>
<item>
<p>Useful for debugging. Prints the arguments sent to the emulator.</p>
@@ -329,6 +341,18 @@ $ <input>erl \
Use the <c>configure</c> option <c>--enable-lock-counter</c> to
build the lock-counter emulator.)</p>
</item>
+ <tag>
+ <marker id="enable-feature"></marker>
+ <c><![CDATA[-enable-feature feature]]></c>
+ </tag>
+ <item>
+ <p>Enables the
+ <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide> <c><![CDATA[feature]]></c>
+ in the runtime system. The special feature <c>all</c> can be
+ used to enable all features.
+ </p>
+ </item>
<tag><c><![CDATA[-env Variable Value]]></c></tag>
<item>
<p>Sets the host OS environment variable <c><![CDATA[Variable]]></c> to
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 62f73cf747..c7dd44c42c 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -3823,6 +3823,11 @@ is_process_alive(P2Pid),
previous current code for <c><anno>Module</anno></c> will remain
until the <c>on_load</c> call has finished.
</item>
+ <tag>not_allowed</tag>
+ <item>The code in <c><anno>Binary</anno></c> has been
+ compiled with features that are currently not enabled in the
+ runtime system.
+ </item>
</taglist>
<warning>
<p>This BIF is intended for the code server (see
diff --git a/erts/doc/src/erlc_cmd.xml b/erts/doc/src/erlc_cmd.xml
index f6baefed7d..074626d9c0 100644
--- a/erts/doc/src/erlc_cmd.xml
+++ b/erts/doc/src/erlc_cmd.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>1997</year><year>2021</year>
+ <year>1997</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -142,6 +142,46 @@
<p>Use the
<seecom marker="#compile_server">compile server</seecom>.</p>
</item>
+ <tag>
+ <marker id="enable-feature"/>
+ <c>-enable-feature <Feature></c>
+ </tag>
+ <item>
+ <p>Enables the
+ <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide> <c>feature</c>
+ during compilation. The special feature <c>all</c> can be
+ used to enable all features.
+ </p>
+ </item>
+ <tag>
+ <marker id="disable-feature"/>
+ <c>-disable-feature <feature></c>
+ </tag>
+ <item>
+ <p>Disables the
+ <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide> <c>feature</c>
+ during compilation. The special feature <c>all</c> can be
+ used to disable all non permanent features.
+ </p>
+ </item>
+ <tag><c>-list-features</c></tag>
+ <item>
+ <p><marker id="list-features"/>
+ List short descriptions of the current available
+ <seeguide
+ marker="system/reference_manual:features#features">features</seeguide>.
+ </p>
+ </item>
+ <tag><c>-describe-feature <feature></c></tag>
+ <item>
+ <p><marker id="describe-feature"/>
+ Show long description and history of
+ <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide> <c>feature</c>.
+ </p>
+ </item>
<tag><c>-M</c></tag>
<item>
<p>Produces a Makefile rule to track header dependencies. The
diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml
index 28fc79e671..f61aa1ee1c 100644
--- a/lib/compiler/doc/src/compile.xml
+++ b/lib/compiler/doc/src/compile.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2021</year>
+ <year>1996</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -227,6 +227,26 @@
</p>
</item>
+ <tag><c>{feature, Feature, enable | disable}</c></tag>
+ <item>
+ <p><marker id="feature-option"/>
+ Enable (disable) the <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide>
+ <c>Feature</c> during compilation. The special feature
+ <c>all</c> can be used to enable (disable) all features.
+ </p>
+ <note>
+ <p><marker id="feature-directive"/>
+ A feature can also be enabled (disabled) using the
+ <c>-feature(Feature, enable | disable).</c> module attribute.
+ Note that this directive can only be present in a prefix
+ of the file, before exports and function definitions.
+ This is the preferred method of enabling and disabling
+ features, since it is a local property of a module.
+ </p>
+ </note>
+ </item>
+
<tag><c>makedep</c></tag>
<item>
<p>Produces a Makefile rule to track headers dependencies.
@@ -655,6 +675,18 @@ module.beam: module.erl \
emit warnings for such variables.</p>
</item>
+ <tag><c>warn_keywords</c></tag>
+ <item>
+ <p><marker id="warn-keywords"/>
+ Emits warnings when the code contains atoms that are
+ used as keywords in some <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide>.
+ When the feature is enabled, any occurrences will lead to
+ a syntax error. To prevent this, the atom has to
+ be renamed or quoted.
+ </p>
+ </item>
+
<tag><c>nowarn_unused_function</c></tag>
<item>
<p>Turns off warnings for unused local functions. Default
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile
index 8e60498fd6..8cd2ceb53c 100644
--- a/lib/stdlib/doc/src/Makefile
+++ b/lib/stdlib/doc/src/Makefile
@@ -1,7 +1,7 @@
#
# %CopyrightBegin%
#
-# Copyright Ericsson AB 1997-2021. All Rights Reserved.
+# Copyright Ericsson AB 1997-2022. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -48,6 +48,7 @@ XML_REF3_FILES = \
erl_error.xmlsrc \
erl_eval.xml \
erl_expand_records.xml \
+ erl_features.xml \
erl_id_trans.xml \
erl_internal.xml \
erl_lint.xml \
diff --git a/lib/stdlib/doc/src/erl_features.xml b/lib/stdlib/doc/src/erl_features.xml
new file mode 100644
index 0000000000..664a7858eb
--- /dev/null
+++ b/lib/stdlib/doc/src/erl_features.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <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>erl_features</title>
+ <prepared>Cons T Åhs</prepared>
+ <responsible></responsible>
+ <docno>1</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2022-05-02</date>
+ <rev>B</rev>
+ <file>erl_features.xml</file>
+ </header>
+ <module since="OTP 25.0">erl_features</module>
+ <modulesummary>Feature support.</modulesummary>
+ <description>
+ <p>This module contains functions for supporting features that can
+ be enabled/disabled in Erlang. It should be considered as mostly
+ for internal use, although there are some functions that might be
+ useful when writing tools.
+ <marker id="erl_features"/>
+ </p>
+ </description>
+
+ <datatypes>
+ <datatype>
+ <name name="feature"></name>
+ </datatype>
+ <datatype>
+ <name name="release"></name>
+ </datatype>
+ <datatype>
+ <name name="status"></name>
+ </datatype>
+ <datatype>
+ <name name="type"></name>
+ </datatype>
+ </datatypes>
+
+ <funcs>
+ <func>
+ <name name="all" arity="0" since="OTP 25.0"/>
+ <fsummary>Return all known features.</fsummary>
+ <desc>
+ <p>Return a list of all known features.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="info" arity="1" since="OTP 25.0"/>
+ <fsummary>Return information about the given feature.</fsummary>
+ <desc>
+ <p>Return a map containing information about the given feature.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="enabled" arity="0" since="OTP 25.0"/>
+ <fsummary>Return list of currently enabled features.</fsummary>
+ <desc>
+ <p>Return a list of the features that are currently enabled.
+ Note that the set of enabled is set during startup and can
+ then not be changed.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="used" arity="1" since="OTP 25.0"/>
+ <fsummary>Return features used by a module or beam file.</fsummary>
+ <desc>
+ <p>Return the list of features enabled when compiling the
+ module. The module need not be loaded, but is found if it
+ exists in the loadpath. If not all features used by the
+ module are enabled in the runtime, loading the module is not
+ allowed.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml
index 042c080cf2..e63c455ec8 100644
--- a/lib/stdlib/doc/src/ref_man.xml
+++ b/lib/stdlib/doc/src/ref_man.xml
@@ -4,7 +4,7 @@
<application xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>1996</year><year>2021</year>
+ <year>1996</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -48,6 +48,7 @@
<xi:include href="erl_error.xml"/>
<xi:include href="erl_eval.xml"/>
<xi:include href="erl_expand_records.xml"/>
+ <xi:include href="erl_features.xml"/>
<xi:include href="erl_id_trans.xml"/>
<xi:include href="erl_internal.xml"/>
<xi:include href="erl_lint.xml"/>
diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml
index 5f7e3555d8..9fdd0d1c21 100644
--- a/lib/stdlib/doc/src/specs.xml
+++ b/lib/stdlib/doc/src/specs.xml
@@ -15,6 +15,7 @@
<xi:include href="../specs/specs_erl_error.xml"/>
<xi:include href="../specs/specs_erl_eval.xml"/>
<xi:include href="../specs/specs_erl_expand_records.xml"/>
+ <xi:include href="../specs/specs_erl_features.xml"/>
<xi:include href="../specs/specs_erl_id_trans.xml"/>
<xi:include href="../specs/specs_erl_internal.xml"/>
<xi:include href="../specs/specs_erl_lint.xml"/>
diff --git a/lib/stdlib/src/Makefile b/lib/stdlib/src/Makefile
index b7b5ead962..369a448fe5 100644
--- a/lib/stdlib/src/Makefile
+++ b/lib/stdlib/src/Makefile
@@ -185,6 +185,7 @@ primary_bootstrap_compiler: \
$(BOOTSTRAP_COMPILER)/ebin/epp.beam \
$(BOOTSTRAP_COMPILER)/ebin/erl_anno.beam \
$(BOOTSTRAP_COMPILER)/ebin/erl_error.beam \
+ $(BOOTSTRAP_COMPILER)/ebin/erl_features.beam \
$(BOOTSTRAP_COMPILER)/ebin/erl_scan.beam \
$(BOOTSTRAP_COMPILER)/ebin/erl_parse.beam \
$(BOOTSTRAP_COMPILER)/ebin/erl_lint.beam \
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index b3259ec630..3a01066410 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2021</year>
+ <year>2003</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -397,9 +397,13 @@ is_valid_signal(Signal) ->
<section>
<marker id="maybe"></marker>
<title>Maybe</title>
- <note><p><c>maybe</c> is an experimental new feature introduced in
- OTP 25. By default, it is disabled. To enable <c>maybe</c>, use
- compiler option <c>{enable_feature,maybe_expr}</c>.</p></note>
+ <note><p><c>maybe</c> is an experimental new <seeguide
+ marker="system/reference_manual:features#features">feature</seeguide>
+ introduced in OTP 25. By default, it is disabled. To enable
+ <c>maybe</c>, use compiler option
+ <c>{feature,maybe_expr,enable}</c>. The feature must also be
+ enabled in the runtime using the <c>-enable-feature</c> option to
+ <c>erl</c>.</p></note>
<code type="erl"><
