diff options
Diffstat (limited to 'system/doc/system_principles')
| -rw-r--r-- | system/doc/system_principles/Makefile | 9 | ||||
| -rw-r--r-- | system/doc/system_principles/create_target.xmlsrc | 10 | ||||
| -rw-r--r-- | system/doc/system_principles/error_logging.xml | 117 | ||||
| -rw-r--r-- | system/doc/system_principles/misc.xml | 198 | ||||
| -rw-r--r-- | system/doc/system_principles/part.xml | 3 | ||||
| -rw-r--r-- | system/doc/system_principles/system_principles.xml | 4 | ||||
| -rw-r--r-- | system/doc/system_principles/versions.xml | 70 | ||||
| -rw-r--r-- | system/doc/system_principles/xmlfiles.mk | 9 |
8 files changed, 342 insertions, 78 deletions
diff --git a/system/doc/system_principles/Makefile b/system/doc/system_principles/Makefile index 77edea8f58..5110b73373 100644 --- a/system/doc/system_principles/Makefile +++ b/system/doc/system_principles/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1996-2016. All Rights Reserved. +# Copyright Ericsson AB 1996-2018. 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. @@ -28,6 +28,7 @@ include $(ERL_TOP)/erts/vsn.mk #VSN=$(SYSTEM_VSN) APPLICATION=otp-system-documentation +XMLDIR := $(XMLDIR)/system_principles # ---------------------------------------------------- # Release directory specification # ---------------------------------------------------- @@ -52,6 +53,8 @@ XML_FILES = \ $(BOOK_FILES) $(XML_CHAPTER_FILES) \ $(XML_PART_FILES) +XML_GEN_FILES = $(SYSTEM_PRINCIPLES_CHAPTER_GEN_FILES:%=$(XMLDIR)/%) + # ---------------------------------------------------- HTMLDIR = ../html/system_principles @@ -67,7 +70,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -78,7 +80,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc index f9b27ffc35..47b84e5760 100644 --- a/system/doc/system_principles/create_target.xmlsrc +++ b/system/doc/system_principles/create_target.xmlsrc @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2002</year><year>2016</year> + <year>2002</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -263,6 +263,14 @@ os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI current directory create not only the file <c>mysystem.rel</c>, but also file <c>sys.config</c>, the latter file is tacitly put in the appropriate directory.</p> + <p>However, it can also be convenient to replace variables in + within a <c>sys.config</c> on the target after unpacking but + before running the release. If you have a <c>sys.config.src</c> + it will be included and is not required to be a valid Erlang term + file like <c>sys.config</c>. Before running the release you must + have a valid <c>sys.config</c> in the same directory, so using + <c>sys.config.src</c> requires having some tool to populate what is + needed and write <c>sys.config</c> to disk before booting the release.</p> </section> <section> diff --git a/system/doc/system_principles/error_logging.xml b/system/doc/system_principles/error_logging.xml index c99d59ddb7..9cbf7a2e94 100644 --- a/system/doc/system_principles/error_logging.xml +++ b/system/doc/system_principles/error_logging.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -39,80 +39,71 @@ <code type="none"><![CDATA[ =ERROR REPORT==== 9-Dec-2003::13:25:02 === Error in process <0.27.0> with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,eval_loop,2}]}]]></code> - <p>The error information is handled by the <em>error logger</em>, a - system process registered as <c>error_logger</c>. This process - receives all error messages from the Erlang runtime system as - well as from the standard behaviours and different Erlang/OTP - applications.</p> + <p>The error information is handled by Logger, which is part of + the Kernel application.</p> <p>The exit reasons (such as <c>badarg</c>) used by the runtime system are described in <seealso marker="doc/reference_manual:errors#exit_reasons"> Errors and Error Handling</seealso>.</p> - <p>For information about the process <c>error_logger</c> and its user - interface (with the same name), see the - <seealso marker="kernel:error_logger">error_logger(3)</seealso> - manual page in Kernel. The system can be configured so that - error information - is written to file or to tty, or both. In addition, user-defined - applications can send and format error information using - <c>error_logger</c>.</p> + <p>For information about Logger and its user + interface, see the + <seealso marker="kernel:logger">logger(3)</seealso> + manual page and + the <seealso marker="kernel:logger_chapter">Logging</seealso> + section in the Kernel User's Guide. The system can be configured so that + log events are + written to file or to tty, or both. In addition, user-defined + applications can send and format log events using + Logger.</p> </section> <section> - <title>SASL Error Logging</title> + <title>Log events from OTP behaviours</title> <p>The standard behaviours (<c>supervisor</c>, <c>gen_server</c>, - and so on) send progress and error information to <c>error_logger</c>. - If the SASL application is started, this information is - written to tty as well. For more information, see + and so on) send progress and error information to + Logger. Progress reports are by default not logged, but can be + enabled by setting the primary log level to <c>info</c>, for + example by using the Kernel configuration + parameter <c>logger_level</c>. Supervisor reports, crash reports + and other error and information reports are by default logged + through the log handler which is set up when the Kernel + application is started.</p> + <p>Prior to Erlang/OTP 21.0, supervisor, crash, and progress + reports were only logged when the SASL application was + running. This behaviour can, for backwards compatibility, be + enabled by setting the Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_sasl_compatible"> + <c>logger_sasl_compatible</c></seealso> + to <c>true</c>. For more information, see <seealso marker="sasl:error_logging">SASL Error Logging</seealso> in the SASL User's Guide.</p> <pre> -% <input>erl -boot start_sasl</input> -Erlang (BEAM) emulator version 5.4.13 [hipe] [threads:0] [kernel-poll] +% <input>erl -kernel logger_level info</input> +Erlang/OTP 21 [erts-10.0] [source-13c50db] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe] - -=PROGRESS REPORT==== 31-Mar-2006::12:45:58 === - supervisor: {local,sasl_safe_sup} - started: [{pid,<0.33.0>}, - {name,alarm_handler}, - {mfa,{alarm_handler,start_link,[]}}, - {restart_type,permanent}, - {shutdown,2000}, - {child_type,worker}] - -=PROGRESS REPORT==== 31-Mar-2006::12:45:58 === - supervisor: {local,sasl_safe_sup} - started: [{pid,<0.34.0>}, - {name,overload}, - {mfa,{overload,start_link,[]}}, - {restart_type,permanent}, - {shutdown,2000}, - {child_type,worker}] - -=PROGRESS REPORT==== 31-Mar-2006::12:45:58 === - supervisor: {local,sasl_sup} - started: [{pid,<0.32.0>}, - {name,sasl_safe_sup}, - {mfa,{supervisor, - start_link, - [{local,sasl_safe_sup},sasl,safe]}}, - {restart_type,permanent}, - {shutdown,infinity}, - {child_type,supervisor}] - -=PROGRESS REPORT==== 31-Mar-2006::12:45:58 === - supervisor: {local,sasl_sup} - started: [{pid,<0.35.0>}, - {name,release_handler}, - {mfa,{release_handler,start_link,[]}}, - {restart_type,permanent}, - {shutdown,2000}, - {child_type,worker}] - -=PROGRESS REPORT==== 31-Mar-2006::12:45:58 === - application: sasl - started_at: nonode@nohost -Eshell V5.4.13 (abort with ^G) +=PROGRESS REPORT==== 8-Jun-2018::16:54:19.916404 === + application: kernel + started_at: nonode@nohost +=PROGRESS REPORT==== 8-Jun-2018::16:54:19.922908 === + application: stdlib + started_at: nonode@nohost +=PROGRESS REPORT==== 8-Jun-2018::16:54:19.925755 === + supervisor: {local,kernel_safe_sup} + started: [{pid,<0.74.0>}, + {id,disk_log_sup}, + {mfargs,{disk_log_sup,start_link,[]}}, + {restart_type,permanent}, + {shutdown,1000}, + {child_type,supervisor}] +=PROGRESS REPORT==== 8-Jun-2018::16:54:19.926056 === + supervisor: {local,kernel_safe_sup} + started: [{pid,<0.75.0>}, + {id,disk_log_server}, + {mfargs,{disk_log_server,start_link,[]}}, + {restart_type,permanent}, + {shutdown,2000}, + {child_type,worker}] +Eshell V10.0 (abort with ^G) 1> </pre> </section> </chapter> diff --git a/system/doc/system_principles/misc.xml b/system/doc/system_principles/misc.xml new file mode 100644 index 0000000000..dd6c2a1336 --- /dev/null +++ b/system/doc/system_principles/misc.xml @@ -0,0 +1,198 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2018</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>Support, Compatibility, Deprecations, and Removal</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2018-05-21</date> + <rev></rev> + <file>misc.xml</file> + </header> + + <section> + <marker id="supported_releases"/> + <title>Supported Releases</title> + <p> + In general, bugs are only fixed on the latest + <seealso marker="versions#releases_and_patches">release</seealso>, + and new features are introduced in the upcoming release that is + under development. However, when we, due to internal reasons, fix + bugs on older releases, these will be available and announced as well. + </p> + <p> + Due to the above, pull requests are only accepted on the + <c>maint</c> and the <c>master</c> branches in our + <url href="https://github.com/erlang/otp">git repository</url>. + The <c>maint</c> branch contains changes planned for the next + <seealso marker="versions#releases_and_patches">maintenance patch package</seealso> + on the latest OTP release and the <c>master</c> branch contain + changes planned for the upcoming OTP release. + </p> + </section> + + <section> + <marker id="compatibility"/> + <title>Compatibility</title> + <p> + We always strive to remain as compatible as possible + even in the cases where we give no compatibility guarantees. + </p> + <p> + Different parts of the system will be handled differently + regarding compatibility. The following items describe how + different parts of the system are handled. + </p> + <taglist> + <tag>Erlang Distribution</tag> + <item> + <p> + Erlang nodes can communicate across at least + two preceding and two subsequent releases. + </p> + </item> + <tag>Compiled BEAM Code, NIF Libraries and Drivers</tag> + <item> + <p> + Compiled code can be loaded on at least two + subsequent releases. + </p> + <p> + Loading on previous releases is <em>not</em> supported. + </p> + </item> + <tag>Compiled HiPE Code</tag> + <item> + <p> + Compiled HiPE code can be loaded on the exact same build + of ERTS that was used when compiling the code. It might + however work on other builds, the emulator verifies + checksums in order to determine if it can load the code + or not. Note that HiPE has some limitations. For more + information see the documentation of the + <seealso marker="hipe:HiPE_app">HiPE</seealso> application. + </p> + </item> + <tag>APIs</tag> + <item> + <p>Compatible between releases.</p> + </item> + <tag>Compiler Warnings</tag> + <item> + <p>New warnings may be issued between releases.</p> + </item> + <tag>Command Line Arguments</tag> + <item> + <p>Incompatible changes may occur between releases.</p> + </item> + <tag>OTP Build Procedures</tag> + <item><p>Incompatible changes may occur between releases.</p></item> + </taglist> + <p> + Under certain circumstances incompatible changes might be + introduced even in parts of the system that should be compatible + between releases. Things that might trigger incompatible changes + like this are: + </p> + <taglist> + <tag>Security Issues</tag> + <item> + <p> + It might be necessary to introduce incompatible changes + in order to solve a security issue. This kind of + incompatibility might occur in a patch. + </p> + </item> + <tag>Bug Fixes</tag> + <item> + <p> + We will not be bug-compatible. A bug fix might introduce + incompatible changes. This kind of incompatibility + might occur in a patch. + </p> + </item> + <tag>Severe Previous Design Issues</tag> + <item> + <p> + Some parts of OTP were designed a very long time ago and + did not necessarily take today's computing environments into + account. In some cases the consequences of those design + decisions are too severe. This may be performance wise, + scalability wise, etc. If we deem the consequences too + severe, we might introduce incompatible changes. This kind + of incompatibility will not be introduced in a patch, but + instead in the next release. + </p> + </item> + </taglist> + <p> + Peripheral, trace, and debug functionality is at greater + risk of being changed in an incompatible way than functionality + in the language itself and core libraries used during operation. + </p> + </section> + + <section> + <marker id="deprecation"/> + <title>Deprecation</title> + <p> + Functionality is deprecated when new functionality is + introduced that is preferred to be used instead of the + old functionality that is being deprecated. The deprecation + does <em>not</em> imply removal of the functionality unless + an upcoming removal is explicitly stated in the deprecation. + </p> + <p> + Deprecated functionality will be documented as deprecated, and + compiler warnings will be issued, when appropriate, as + early as possible. That is, the new preferred functionality + will appear at the same time as the deprecation is issued. + A new deprecation will at least be announced in a release + note and the documentation. + </p> + </section> + + <section> + <marker id="removal"/> + <title>Removal</title> + <p> + Legacy solutions may eventually need to be removed. In such + cases, they will be phased out on a long enough time period + to give users the time to adapt. Before removal of + functionality it will be deprecated at least during one + release with an explicit announcement about + the upcoming removal. A new deprecation will at least be + announced in a release note and the documentation. + </p> + <p> + Peripheral, trace, and debug functionality is at greater + risk of removal than functionality in the language itself + and core libraries used during operation. + </p> + </section> + +</chapter> + diff --git a/system/doc/system_principles/part.xml b/system/doc/system_principles/part.xml index 1b87ecd350..6699389eec 100644 --- a/system/doc/system_principles/part.xml +++ b/system/doc/system_principles/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1997</year><year>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,4 +34,5 @@ <xi:include href="create_target.xml"/> <xi:include href="upgrade.xml"/> <xi:include href="versions.xml"/> + <xi:include href="misc.xml"/> </part> diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml index 3605df3ade..500522d778 100644 --- a/system/doc/system_principles/system_principles.xml +++ b/system/doc/system_principles/system_principles.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1996</year><year>2015</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -93,7 +93,7 @@ init:stop()</pre> {progress,kernel_load_completed} {progress,modules_loaded} {start,heart} -{start,error_logger} +{start,logger} ...</pre> <p>For a detailed description of the syntax and contents of the boot script, see the <c>script(4)</c> manual page in SASL.</p> diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml index b9f7fa4bf6..fbdcc6b2b0 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2014</year><year>2016</year> + <year>2014</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,9 +32,9 @@ <rev></rev> <file>versions.xml</file> </header> - <marker id="versions section"></marker> <section> + <marker id="versions section"></marker> <title>OTP Version</title> <p>As of OTP release 17, the OTP release number corresponds to the major part of the OTP version. The OTP version as a concept was @@ -136,8 +136,8 @@ </section> <section> - <title>Version Scheme</title> <marker id="version_scheme"/> + <title>Version Scheme</title> <note><p>The version scheme was changed as of OTP 17.0. This implies that application versions used prior to OTP 17.0 do not adhere to this version scheme. <seealso marker="#otp_17_0_app_versions">A list of @@ -181,7 +181,7 @@ goes for application versions.</p> <p>In general, versions can have more than three parts. The versions are then only partially ordered. Such - versions are only used in exceptional cases. When an extra + versions are only used when branching off from another branch. When an extra part (out of the normal three parts) is added to a version number, a new branch of versions is made. The new branch has a linear order against the base version. However, versions on different @@ -207,8 +207,68 @@ </section> <section> - <title>OTP 17.0 Application Versions</title> + <marker id="releases_and_patches"/> + <title>Releases and Patches</title> + <p> + When a new OTP release is released it will have an OTP + version on the form <c><Major>.0</c> where the + major OTP version number equals the release number. + The major version number is increased one step since the + last major version. All other OTP versions with the same + major OTP version number are patches on that OTP release. + </p> + <p> + Patches are either released as maintenance patch packages + or emergency patch packages. The only difference is that + maintenance patch packages are planned and usually contain + more changes than emergency patch packages. Emergency patch + packages are released to solve one or more specific issues + when such are discovered. + </p> + <p> + The release of a maintenance patch package usually imply + an increase of the OTP <c><Minor></c> version while + the release of an emergency patch package usually imply an + increase of the OTP <c><Patch></c> version. This is + however not necessarily always the case since changes of + OTP versions are based on the actual changes in the code + and not based on whether the patch was planned or not. + For more information see the + <seealso marker="#version_scheme">Version Scheme</seealso> + section above. + </p> + </section> + + <section> + <marker id="otp_versions_tree"/> + <title>OTP Versions Tree</title> + <p> + All released OTP versions can be found in the + <url href="http://www.erlang.org/download/otp_versions_tree.html">OTP + Versions Tree</url> which is automatically updated whenever + we release a new OTP version. Note that every version number as + such explicitly define its position in the version tree. Nothing + more than the version numbers are needed in order to construct + the tree. The root of the tree is OTP version 17.0 which is when + we introduced the new + <seealso marker="#version_scheme">version scheme</seealso>. The + green versions are normal versions released on the main track. + Old <seealso marker="#releases_and_patches">OTP releases</seealso> + will be maintained for a while on <c>maint</c> branches that have + branched off from the main track. Old <c>maint</c> branches always + branch off from the main track when the next OTP release is + introduced into the main track. Versions on these old <c>maint</c> + branches are marked blue. Besides the green and blue versions, + there are also gray versions. These are versions on branches + introduced in order to fix a specific problem for a specific + customer on a specific base version. Branches with gray versions + will typically become dead ends very quickly if not immediately. + </p> + </section> + + <section> <marker id="otp_17_0_app_versions"/> + <title>OTP 17.0 Application Versions</title> <p>The following list details the application versions that were part of OTP 17.0. If the normal part of an application version number compares diff --git a/system/doc/system_principles/xmlfiles.mk b/system/doc/system_principles/xmlfiles.mk index c3c3bb4731..353c2c7f7f 100644 --- a/system/doc/system_principles/xmlfiles.mk +++ b/system/doc/system_principles/xmlfiles.mk @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2009-2016. All Rights Reserved. +# Copyright Ericsson AB 2009-2018. 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. @@ -20,6 +20,9 @@ SYSTEM_PRINCIPLES_CHAPTER_FILES = \ system_principles.xml \ error_logging.xml \ - create_target.xml \ upgrade.xml \ - versions.xml + versions.xml \ + misc.xml + +SYSTEM_PRINCIPLES_CHAPTER_GEN_FILES = \ + create_target.xml |