The R13B03 release.OTP_R13B03

9 files changed, 1063 insertions, 0 deletions

diff --git a/system/doc/system_principles/Makefile b/system/doc/system_principles/Makefile
new file mode 100644
index 0000000000..b0698fec9d
--- /dev/null
+++ b/system/doc/system_principles/Makefile
@@ -0,0 +1,95 @@
+#
+# %CopyrightBegin%
+# 
+# Copyright Ericsson AB 1996-2009. All Rights Reserved.
+# 
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+# 
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+# 
+# %CopyrightEnd%
+#
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include $(ERL_TOP)/erts/vsn.mk
+#VSN=$(SYSTEM_VSN)
+
+APPLICATION=otp-system-documentation
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/doc/system_principles
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_PART_FILES = part.xml
+
+include xmlfiles.mk
+
+XML_CHAPTER_FILES=$(SYSTEM_PRINCIPLES_CHAPTER_FILES)
+
+TOPDOCDIR=..
+
+BOOK_FILES = book.xml
+
+GIF_FILES = 
+
+XML_FILES = \
+	$(BOOK_FILES) $(XML_CHAPTER_FILES) \
+	$(XML_PART_FILES) 
+
+# ----------------------------------------------------
+
+HTMLDIR = ../html/system_principles
+
+HTML_UG_FILE = $(HTMLDIR)/users_guide.html
+
+# ----------------------------------------------------
+# FLAGS 
+# ----------------------------------------------------
+XML_FLAGS += 
+DVIPS_FLAGS += 
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+docs: html
+
+local_docs: PDFDIR=../../pdf
+
+html: $(GIF_FILES) $(HTML_UG_FILE)
+
+debug opt: 
+
+clean clean_docs:
+	rm -rf $(HTMLDIR)
+	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f errs core *~ 
+
+# ----------------------------------------------------
+# Release Target
+# ---------------------------------------------------- 
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+release_docs_spec: docs
+#	$(INSTALL_DIR) $(RELEASE_PATH)/pdf
+#	$(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf
+	$(INSTALL_DIR) $(RELSYSDIR)
+	$(INSTALL_DATA) $(GIF_FILES) $(HTMLDIR)/*.html \
+		$(RELSYSDIR)
+
+release_spec:
+
diff --git a/system/doc/system_principles/book.xml b/system/doc/system_principles/book.xml
new file mode 100644
index 0000000000..868bbeecdd
--- /dev/null
+++ b/system/doc/system_principles/book.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header titlestyle="normal">
+    <copyright>
+      <year>1996</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>System Principles</title>
+    <prepared>OTP Team</prepared>
+    <docno></docno>
+    <date>1997-05-21</date>
+    <rev></rev>
+    <file>book.xml</file>
+  </header>
+  <insidecover>
+  </insidecover>
+  <pagetext>System Principles</pagetext>
+  <preamble>
+    <contents level="2"></contents>
+  </preamble>
+  <parts lift="no">
+    <xi:include href="part.xml"/>
+  </parts>
+  <listofterms></listofterms>
+  <index></index>
+</book>
+
diff --git a/system/doc/system_principles/create_target.xml b/system/doc/system_principles/create_target.xml
new file mode 100644
index 0000000000..9899b6e266
--- /dev/null
+++ b/system/doc/system_principles/create_target.xml
@@ -0,0 +1,502 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2002</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Creating a First Target System</title>
+    <prepared>Peter H&ouml;gfeldt</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2002-09-17</date>
+    <rev>A</rev>
+    <file>create_target.xml</file>
+  </header>
+
+  <section>
+    <title>Introduction</title>
+    <p>When creating a system using Erlang/OTP, the most simple way is
+      to install Erlang/OTP somewhere, install the application specific
+      code somewhere else, and then start the Erlang runtime system,
+      making sure the code path includes the application specific code.</p>
+    <p>Often it is not desirable to use an Erlang/OTP system as is. A
+      developer may create new Erlang/OTP compliant applications for a
+      particular purpose, and several original Erlang/OTP applications
+      may be irrelevant for the purpose in question. Thus, there is a
+      need to be able to create a new system based on a given
+      Erlang/OTP system, where dispensable applications are removed,
+      and a set of new applications that are included in the new
+      system. Documentation and source code is irrelevant and is
+      therefore not included in the new system.</p>
+    <p>This chapter is about creating such a system, which we call a 
+      <em>target system</em>.</p>
+    <p>In the following sections we consider creating target systems with
+      different requirements of functionality:</p>
+    <list type="bulleted">
+      <item>a <em>basic target system</em> that can be started by
+       calling the ordinary <c>erl</c> script, </item>
+      <item>a <em>simple target system</em> where also code
+       replacement in run-time can be performed, and</item>
+      <item>an <em>embedded target system</em> where there is also
+       support for logging output from the system to file for later
+       inspection, and where the system can be started automatically
+       at boot time. </item>
+    </list>
+    <p>We only consider the case when Erlang/OTP is running on a UNIX
+      system.</p>
+    <p>There is an example Erlang module <c>target_system.erl</c> that
+      contains functions for creating and installing a target system.
+      That module is used in the examples below. The source code of
+      the module is listed at the end of this chapter.</p>
+  </section>
+
+  <section>
+    <title>Creating a Target System</title>
+    <p>It is assumed that you have a working Erlang/OTP system structured
+      according to the OTP Design Principles.</p>
+    <p><em>Step 1.</em> First create a <c>.rel</c> file (see
+      <c>rel(4)</c>) that specifies the <c>erts</c> version
+      and lists all applications that should be included in the new
+      basic target system. An example is the following
+      <c>mysystem.rel</c> file:</p>
+    <code type="none">
+%% mysystem.rel
+{release,
+ {"MYSYSTEM", "FIRST"},
+ {erts, "5.1"},
+ [{kernel, "2.7"},
+  {stdlib, "1.10"},
+  {sasl, "1.9.3"},
+  {pea, "1.0"}]}.    </code>
+    <p>The listed applications are not only original Erlang/OTP
+      applications but possibly also new applications that you have
+      written yourself (here examplified by the application
+      <c>pea</c>). </p>
+    <p><em>Step 2.</em> From the directory where the <c>mysystem.rel</c>
+      file reside, start the Erlang/OTP system:</p>
+    <pre>
+os> <input>erl -pa /home/user/target_system/myapps/pea-1.0/ebin</input></pre>
+    <p>where also the path to the <c>pea-1.0</c> ebin directory is 
+      provided. </p>
+    <p><em>Step 3.</em> Now create the target system: </p>
+    <pre>
+1> <input>target_system:create("mysystem").</input></pre>
+    <p>The <c>target_system:create/1</c> function does the following:</p>
+    <list type="ordered">
+      <item>Reads the <c>mysystem.rel</c> file, and creates a new file
+      <c>plain.rel</c> which is identical to former, except that it
+       only lists the <c>kernel</c> and <c>stdlib</c> applications. </item>
+      <item>From the <c>mysystem.rel</c> and <c>plain.rel</c> files
+       creates the files <c>mysystem.script</c>,
+      <c>mysystem.boot</c>, <c>plain.script</c>, and
+      <c>plain.boot</c> through a call to
+      <c>systools:make_script/2</c>.</item>
+      <item>
+        <p>Creates the file <c>mysystem.tar.gz</c> by a call to
+          <c>systools:make_tar/2</c>. That file has the following
+          contents:</p>
+        <code type="none">
+erts-5.1/bin/
+releases/FIRST/start.boot
+releases/mysystem.rel
+lib/kernel-2.7/
+lib/stdlib-1.10/
+lib/sasl-1.9.3/
+lib/pea-1.0/        </code>
+        <p>The file <c>releases/FIRST/start.boot</c> is a copy of our
+          <c>mysystem.boot</c>, and a copy of the original
+          <c>mysystem.rel</c> has been put in the <c>releases</c>
+          directory.</p>
+      </item>
+      <item>Creates the temporary directory <c>tmp</c> and extracts the tar file
+      <c>mysystem.tar.gz</c> into that directory. </item>
+      <item>Deletes the <c>erl</c> and <c>start</c> files from
+      <c>tmp/erts-5.1/bin</c>. XXX Why.</item>
+      <item>Creates the directory <c>tmp/bin</c>.</item>
+      <item>Copies the previously creates file <c>plain.boot</c> to
+      <c>tmp/bin/start.boot</c>.</item>
+      <item>Copies the files <c>epmd</c>, <c>run_erl</c>, and
+      <c>to_erl</c> from the directory <c>tmp/erts-5.1/bin</c> to
+       the directory <c>tmp/bin</c>.</item>
+      <item>Creates the file <c>tmp/releases/start_erl.data</c> with the 
+       contents "5.1 FIRST".
+      </item>
+      <item>Recreates the file <c>mysystem.tar.gz</c> from the directories
+       in the directory <c>tmp</c>, and removes <c>tmp</c>.</item>
+    </list>
+  </section>
+
+  <section>
+    <title>Installing a Target System</title>
+    <p><em>Step 4.</em> Install the created target system in a 
+      suitable directory. </p>
+    <pre>
+2> <input>target_system:install("mysystem", "/usr/local/erl-target").</input></pre>
+    <p>The function <c>target_system:install/2</c> does the following:
+      </p>
+    <list type="ordered">
+      <item>Extracts the tar file <c>mysystem.tar.gz</c> into the target
+       directory <c>/usr/local/erl-target</c>.</item>
+      <item>In the target directory reads the file <c>releases/start_erl.data</c>
+       in order to find the Erlang runtime system version ("5.1").</item>
+      <item>Substitutes <c>%FINAL_ROOTDIR%</c> and <c>%EMU%</c> for
+      <c>/usr/local/erl-target</c> and <c>beam</c>, respectively, in
+       the files <c>erl.src</c>, <c>start.src</c>, and
+      <c>start_erl.src</c> of the target <c>erts-5.1/bin</c>
+       directory, and puts the resulting files <c>erl</c>,
+      <c>start</c>, and <c>run_erl</c> in the target <c>bin</c>
+       directory.</item>
+      <item>Finally the target <c>releases/RELEASES</c> file is created
+       from data in the <c>releases/mysystem.rel</c> file.</item>
+    </list>
+  </section>
+
+  <section>
+    <title>Starting a Target System</title>
+    <p>Now we have a target system that can be started in various ways.</p>
+    <p>We start it as a <em>basic target system</em> by invoking</p>
+    <pre>
+os> <input>/usr/local/erl-target/bin/erl</input></pre>
+    <p>where only the <c>kernel</c> and <c>stdlib</c> applications are
+      started, i.e. the system is started as an ordinary development
+      system. There are only two files needed for all this to work:
+      <c>bin/erl</c> file (obtained from <c>erts-5.1/bin/erl.src</c>)
+      and the <c>bin/start.boot</c> file (a copy of <c>plain.boot</c>).</p>
+    <p>We can also start a distributed system (requires <c>bin/epmd</c>).</p>
+    <p>To start all applications specified in the original
+      <c>mysystem.rel</c> file, use the <c>-boot</c> flag as follows:</p>
+    <pre>
+os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start</input></pre>
+    <p>We start a <em>simple target system</em> as above. The only difference
+      is that also the file <c>releases/RELEASES</c> is present for 
+      code replacement in run-time to work.</p>
+    <p>To start an <em>embedded target system</em> the shell script
+      <c>bin/start</c> is used. That shell script calls
+      <c>bin/run_erl</c>, which in turn calls <c>bin/start_erl</c>
+      (roughly, <c>start_erl</c> is an embedded variant of
+      <c>erl</c>). </p>
+    <p>The shell script <c>start</c> is only an example. You should
+      edit it to suite your needs. Typically it is executed when the
+      UNIX system boots.</p>
+    <p><c>run_erl</c> is a wrapper that provides logging of output from
+      the run-time system to file. It also provides a simple mechanism
+      for attaching to the Erlang shell (<c>to_erl</c>).</p>
+    <p><c>start_erl</c> requires the root directory
+      (<c>"/usr/local/erl-target"</c>), the releases directory
+      (<c>"/usr/local/erl-target/releases"</c>), and the location of
+      the <c>start_erl.data</c> file. It reads the run-time system
+      version (<c>"5.1"</c>) and release version (<c>"FIRST"</c>) from
+      the <c>start_erl.data</c> file, starts the run-time system of the
+      version found, and provides <c>-boot</c> flag specifying the boot
+      file of the release version found
+      (<c>"releases/FIRST/start.boot"</c>).</p>
+    <p><c>start_erl</c> also assumes that there is <c>sys.config</c> in
+      release version directory (<c>"releases/FIRST/sys.config</c>). That
+      is the topic of the next section (see below).</p>
+    <p>The <c>start_erl</c> shell script should normally not be
+      altered by the user.</p>
+  </section>
+
+  <section>
+    <title>System Configuration Parameters</title>
+    <p>As was pointed out above <c>start_erl</c> requires a
+      <c>sys.config</c> in the release version directory
+      (<c>"releases/FIRST/sys.config"</c>). If there is no such a
+      file, the system start will fail. Hence such a file has to
+      added as well.</p>
+    <p></p>
+    <p>If you have system configuration data that are neither file
+      location dependent nor site dependent, it may be convenient to
+      create the <c>sys.config</c> early, so that it becomes a part of
+      the target system tar file created by
+      <c>target_system:create/1</c>. In fact, if you create, in the
+      current directory, not only the <c>mysystem.rel</c> file, but
+      also a <c>sys.config</c> file, that latter file will be tacitly
+      put in the apropriate directory.</p>
+  </section>
+
+  <section>
+    <title>Differences from the Install Script</title>
+    <p>The above <c>install/2</c> procedure differs somewhat from that
+      of the ordinary <c>Install</c> shell script. In fact, <c>create/1</c>
+      makes the release package as complete as possible, and leave to the
+      <c>install/2</c> procedure to finish by only considering location
+      dependent files.</p>
+  </section>
+
+  <section>
+    <title>Listing of target_system.erl</title>
+    <code type="none"><![CDATA[
+-module(target_system).
+-include_lib("kernel/include/file.hrl").
+-export([create/1, install/2]).
+-define(BUFSIZE, 8192).
+
+%% Note: RelFileName below is the *stem* without trailing .rel,
+%% .script etc.
+%%
+
+%% create(RelFileName)
+%%
+create(RelFileName) ->
+    RelFile = RelFileName ++ ".rel", 
+    io:fwrite("Reading file: \\"~s\\" ...~n", [RelFile]),
+    {ok, [RelSpec]} = file:consult(RelFile),
+    io:fwrite("Creating file: \\"~s\\" from \\"~s\\" ...~n", 
+              ["plain.rel", RelFile]),
+    {release,
+     {RelName, RelVsn},
+     {erts, ErtsVsn},
+     AppVsns} = RelSpec,
+    PlainRelSpec = {release, 
+                    {RelName, RelVsn},
+                    {erts, ErtsVsn},
+                    lists:filter(fun({kernel, _}) -> 
+                                         true;
+                                    ({stdlib, _}) ->
+                                         true;
+                                    (_) ->
+                                         false
+                                 end, AppVsns)
+                   },
+    {ok, Fd} = file:open("plain.rel", [write]),
+    io:fwrite(Fd, "~p.~n", [PlainRelSpec]),
+    file:close(Fd),
+
+    io:fwrite("Making \\"plain.script\\" and \\"plain.boot\\" files ...~n"),
+    make_script("plain"),
+
+    io:fwrite("Making \\"~s.script\\" and \\"~s.boot\\" files ...~n", 
+              [RelFileName, RelFileName]),
+    make_script(RelFileName),
+
+    TarFileName = io_lib:fwrite("~s.tar.gz", [RelFileName]),
+    io:fwrite("Creating tar file \\"~s\\" ...~n", [TarFileName]),
+    make_tar(RelFileName),
+
+    io:fwrite("Creating directory \\"tmp\\" ...~n"),
+    file:make_dir("tmp"), 
+
+    io:fwrite("Extracting \\"~s\\" into directory \\"tmp\\" ...~n", [TarFileName]),
+    extract_tar(TarFileName, "tmp"),
+
+    TmpBinDir = filename:join(["tmp", "bin"]),
+    ErtsBinDir = filename:join(["tmp", "erts-" ++ ErtsVsn, "bin"]),
+    io:fwrite("Deleting \\"erl\\" and \\"start\\" in directory \\"~s\\" ...~n", 
+              [ErtsBinDir]),
+    file:delete(filename:join([ErtsBinDir, "erl"])),
+    file:delete(filename:join([ErtsBinDir, "start"])),
+
+    io:fwrite("Creating temporary directory \\"~s\\" ...~n", [TmpBinDir]),
+    file:make_dir(TmpBinDir),
+
+    io:fwrite("Copying file \\"plain.boot\\" to \\"~s\\" ...~n", 
+              [filename:join([TmpBinDir, "start.boot"])]),
+    copy_file("plain.boot", filename:join([TmpBinDir, "start.boot"])),
+
+    io:fwrite("Copying files \\"epmd\\", \\"run_erl\\" and \\"to_erl\\" from \
+"
+              "\\"~s\\" to \\"~s\\" ...~n", 
+              [ErtsBinDir, TmpBinDir]),
+    copy_file(filename:join([ErtsBinDir, "epmd"]), 
+              filename:join([TmpBinDir, "epmd"]), [preserve]),
+    copy_file(filename:join([ErtsBinDir, "run_erl"]), 
+              filename:join([TmpBinDir, "run_erl"]), [preserve]),
+    copy_file(filename:join([ErtsBinDir, "to_erl"]), 
+              filename:join([TmpBinDir, "to_erl"]), [preserve]),
+
+    StartErlDataFile = filename:join(["tmp", "releases", "start_erl.data"]),
+    io:fwrite("Creating \\"~s\\" ...~n", [StartErlDataFile]),
+    StartErlData = io_lib:fwrite("~s ~s~n", [ErtsVsn, RelVsn]),
+    write_file(StartErlDataFile, StartErlData),
+    
+    io:fwrite("Recreating tar file \\"~s\\" from contents in directory "
+              "\\"tmp\\" ...~n", [TarFileName]),
+    {ok, Tar} = erl_tar:open(TarFileName, [write, compressed]),
+    {ok, Cwd} = file:get_cwd(),
+    file:set_cwd("tmp"),
+    erl_tar:add(Tar, "bin", []),
+    erl_tar:add(Tar, "erts-" ++ ErtsVsn, []),
+    erl_tar:add(Tar, "releases", []),
+    erl_tar:add(Tar, "lib", []),
+    erl_tar:close(Tar),
+    file:set_cwd(Cwd),
+    io:fwrite("Removing directory \\"tmp\\" ...~n"),
+    remove_dir_tree("tmp"),
+    ok.
+
+
+install(RelFileName, RootDir) ->
+    TarFile = RelFileName ++ ".tar.gz", 
+    io:fwrite("Extracting ~s ...~n", [TarFile]),
+    extract_tar(TarFile, RootDir),
+    StartErlDataFile = filename:join([RootDir, "releases", "start_erl.data"]),
+    {ok, StartErlData} = read_txt_file(StartErlDataFile),
+    [ErlVsn, RelVsn| _] = string:tokens(StartErlData, " \
+"),
+    ErtsBinDir = filename:join([RootDir, "erts-" ++ ErlVsn, "bin"]),
+    BinDir = filename:join([RootDir, "bin"]),
+    io:fwrite("Substituting in erl.src, start.src and start_erl.src to\
+"
+              "form erl, start and start_erl ...\
+"),
+    subst_src_scripts(["erl", "start", "start_erl"], ErtsBinDir, BinDir, 
+                      [{"FINAL_ROOTDIR", RootDir}, {"EMU", "beam"}],
+                      [preserve]),
+    io:fwrite("Creating the RELEASES file ...\
+"),
+    create_RELEASES(RootDir, 
+                    filename:join([RootDir, "releases", RelFileName])).
+
+%% LOCALS 
+
+%% make_script(RelFileName)
+%%
+make_script(RelFileName) ->
+    Opts = [no_module_tests],
+    systools:make_script(RelFileName, Opts).
+
+%% make_tar(RelFileName)
+%%
+make_tar(RelFileName) ->
+    RootDir = code:root_dir(),
+    systools:make_tar(RelFileName, [{erts, RootDir}]).
+
+%% extract_tar(TarFile, DestDir)
+%%
+extract_tar(TarFile, DestDir) ->
+    erl_tar:extract(TarFile, [{cwd, DestDir}, compressed]).
+
+create_RELEASES(DestDir, RelFileName) ->
+    release_handler:create_RELEASES(DestDir, RelFileName ++ ".rel").
+
+subst_src_scripts(Scripts, SrcDir, DestDir, Vars, Opts) -> 
+    lists:foreach(fun(Script) ->
+                          subst_src_script(Script, SrcDir, DestDir, 
+                                           Vars, Opts)
+                  end, Scripts).
+
+subst_src_script(Script, SrcDir, DestDir, Vars, Opts) -> 
+    subst_file(filename:join([SrcDir, Script ++ ".src"]),
+               filename:join([DestDir, Script]),
+               Vars, Opts).
+
+subst_file(Src, Dest, Vars, Opts) ->
+    {ok, Conts} = read_txt_file(Src),
+    NConts = subst(Conts, Vars),
+    write_file(Dest, NConts),
+    case lists:member(preserve, Opts) of
+        true ->
+            {ok, FileInfo} = file:read_file_info(Src),
+            file:write_file_info(Dest, FileInfo);
+        false ->
+            ok
+    end.
+
+%% subst(Str, Vars)
+%% Vars = [{Var, Val}]
+%% Var = Val = string()
+%% Substitute all occurrences of %Var% for Val in Str, using the list
+%% of variables in Vars.
+%%
+subst(Str, Vars) ->
+    subst(Str, Vars, []).
+
+subst([$%, C| Rest], Vars, Result) when $A =< C, C =< $Z ->
+    subst_var([C| Rest], Vars, Result, []);
+subst([$%, C| Rest], Vars, Result) when $a =< C, C =< $z ->
+    subst_var([C| Rest], Vars, Result, []);
+subst([$%, C| Rest], Vars, Result) when  C == $_ ->
+    subst_var([C| Rest], Vars, Result, []);
+subst([C| Rest], Vars, Result) ->
+    subst(Rest, Vars, [C| Result]);
+subst([], _Vars, Result) ->
+    lists:reverse(Result).
+
+subst_var([$%| Rest], Vars, Result, VarAcc) ->
+    Key = lists:reverse(VarAcc),
+    case lists:keysearch(Key, 1, Vars) of
+        {value, {Key, Value}} ->
+            subst(Rest, Vars, lists:reverse(Value, Result));
+        false ->
+            subst(Rest, Vars, [$%| VarAcc ++ [$%| Result]])
+    end;
+subst_var([C| Rest], Vars, Result, VarAcc) ->
+    subst_var(Rest, Vars, Result, [C| VarAcc]);
+subst_var([], Vars, Result, VarAcc) ->
+    subst([], Vars, [VarAcc ++ [$%| Result]]).
+
+copy_file(Src, Dest) ->
+    copy_file(Src, Dest, []).
+
+copy_file(Src, Dest, Opts) ->
+    {ok, InFd} = file:open(Src, [raw, binary, read]),
+    {ok, OutFd} = file:open(Dest, [raw, binary, write]),
+    do_copy_file(InFd, OutFd),
+    file:close(InFd),
+    file:close(OutFd),
+    case lists:member(preserve, Opts) of
+        true ->
+            {ok, FileInfo} = file:read_file_info(Src),
+            file:write_file_info(Dest, FileInfo);
+        false ->
+            ok
+    end.
+
+do_copy_file(InFd, OutFd) ->
+    case file:read(InFd, ?BUFSIZE) of
+        {ok, Bin} ->
+            file:write(OutFd, Bin),
+            do_copy_file(InFd, OutFd);
+        eof  ->
+            ok
+    end.
+       
+write_file(FName, Conts) ->
+    {ok, Fd} = file:open(FName, [write]),
+    file:write(Fd, Conts),
+    file:close(Fd).
+
+read_txt_file(File) ->
+    {ok, Bin} = file:read_file(File),
+    {ok, binary_to_list(Bin)}.
+
+remove_dir_tree(Dir) ->
+    remove_all_files(".", [Dir]).
+
+remove_all_files(Dir, Files) ->
+    lists:foreach(fun(File) ->
+                          FilePath = filename:join([Dir, File]),
+                          {ok, FileInfo} = file:read_file_info(FilePath),
+                          case FileInfo#file_info.type of
+                              directory ->
+                                  {ok, DirFiles} = file:list_dir(FilePath), 
+                                  remove_all_files(FilePath, DirFiles),
+                                  file:del_dir(FilePath);
+                              _ ->
+                                  file:delete(FilePath)
+                          end
+                  end, Files).
+    ]]></code>
+  </section>
+</chapter>
+
diff --git a/system/doc/system_principles/error_logging.xml b/system/doc/system_principles/error_logging.xml
new file mode 100644
index 0000000000..3cb290227e
--- /dev/null
+++ b/system/doc/system_principles/error_logging.xml
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2003</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Error Logging</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>error_logging.xml</file>
+  </header>
+
+  <section>
+    <title>Error Information From the Runtime System</title>
+    <p>Error information from the runtime system, that is, information
+      about a process terminating due to an uncaught error exception,
+      is by default written to terminal (tty):</p>
+    <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 and
+      also from the standard behaviours and different Erlang/OTP
+      applications.</p>
+    <p>The exit reasons (such as <c>badarg</c> above) used by
+      the runtime system are described in
+      <seealso marker="doc/reference_manual:errors#exit_reasons">Errors and Error Handling</seealso>
+      in the Erlang Reference Manual.</p>
+    <p>The process <c>error_logger</c> and its user interface (with
+      the same name) are described in
+      <seealso marker="kernel:error_logger">error_logger(3)</seealso>.
+      It is possible to configure the system so that error information
+      is written to file instead/as well as tty. Also, it is possible
+      for user defined applications to send and format error
+      information using <c>error_logger</c>.</p>
+  </section>
+
+  <section>
+    <title>SASL Error Logging</title>
+    <p>The standard behaviors (<c>supervisor</c>, <c>gen_server</c>,
+      etc.) sends progress and error information to <c>error_logger</c>.
+      If the SASL application is started, this information is written
+      to tty as well. See
+      <seealso marker="sasl:error_logging">SASL Error Logging</seealso>
+      in the SASL User's Guide for further information.</p>
+    <pre>
+% <input>erl -boot start_sasl</input>
+Erlang (BEAM) emulator version 5.4.13 [hipe] [threads:0] [kernel-poll]
+
+
+=PROGRESS REPORT==== 31-Mar-2006::12:45:58 ===
+          supervisor: {local,sasl_safe_sup}
+             started: [{pid,&lt;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,&lt;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,&lt;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,&lt;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)
+1> </pre>
+  </section>
+</chapter>
+
diff --git a/system/doc/system_principles/make.dep b/system/doc/system_principles/make.dep
new file mode 100644
index 0000000000..28753ca5a0
--- /dev/null
+++ b/system/doc/system_principles/make.dep
@@ -0,0 +1,14 @@
+# ----------------------------------------------------
+# >>>> Do not edit this file <<<<
+# This file was automaticly generated by
+# /home/otp/bin/docdepend
+# ----------------------------------------------------
+
+
+# ----------------------------------------------------
+# TeX files that the DVI file depend on
+# ----------------------------------------------------
+
+book.dvi: book.tex create_target.tex error_logging.tex \
+		part.tex system_principles.tex
+
diff --git a/system/doc/system_principles/part.xml b/system/doc/system_principles/part.xml
new file mode 100644
index 0000000000..94bb29be57
--- /dev/null
+++ b/system/doc/system_principles/part.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>System Principles</title>
+    <prepared>OTP Team</prepared>
+    <docno></docno>
+    <date>1997-02-21</date>
+    <rev>L</rev>
+    <file>part.xml</file>
+  </header>
+  <xi:include href="system_principles.xml"/>
+  <xi:include href="error_logging.xml"/>
+  <xi:include href="create_target.xml"/>
+</part>
+
diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml
new file mode 100644
index 0000000000..27512a1660
--- /dev/null
+++ b/system/doc/system_principles/system_principles.xml
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1996</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>System Principles</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>system_principles.xml</file>
+  </header>
+
+  <section>
+    <title>Starting the System</title>
+    <p>An Erlang runtime system is started with the command <c>erl</c>:</p>
+    <pre>
+% <input>erl</input>
+Erlang (BEAM) emulator version 5.2.3.5 [hipe] [threads:0]
+
+Eshell V5.2.3.5  (abort with ^G)
+1> </pre>
+    <p><c>erl</c> understands a number of command line arguments, see
+      <c>erl(1)</c>. A number of them are also described in this
+      chapter.</p>
+    <p>Application programs can access the values of the command line
+      arguments by calling one of the functions
+      <c>init:get_argument(Key)</c>, or <c>init:get_arguments()</c>.
+      See <c>init(3)</c>.</p>
+  </section>
+
+  <section>
+    <title>Restarting and Stopping the System</title>
+    <p>The runtime system can be halted by calling <c>halt/0,1</c>.
+      See <c>erlang(3)</c>.</p>
+    <p>The module <c>init</c> contains function for restarting,
+      rebooting and stopping the runtime system. See <c>init(3)</c>.</p>
+    <pre>
+init:restart()
+init:reboot()
+init:stop()</pre>
+    <p>Also, the runtime system will terminate if the Erlang shell is
+      terminated.</p>
+  </section>
+
+  <section>
+    <marker id="BOOTSCRIPT"></marker>
+    <title>Boot Scripts</title>
+    <p>The runtime system is started using a <em>boot script</em>.
+      The boot script contains instructions on which code to load and
+      which processes and applications to start.</p>
+    <p>A boot script file has the extension <c>.script</c>.
+      The runtime system uses a binary version of the script. This
+      <em>binary boot script</em> file has the extension <c>.boot</c>.</p>
+    <p>Which boot script to use is specified by the command line flag
+      <c>-boot</c>. The extension <c>.boot</c> should be omitted.
+      Example, using the boot script <c>start_all.boot</c>:</p>
+    <pre>
+% <input>erl -boot start_all</input></pre>
+    <p>If no boot script is specified, it defaults to
+      <c>ROOT/bin/start</c>, see Default Boot Scripts below.</p>
+    <p>The command line flag <c>-init_debug</c> makes the <c>init</c>
+      process write some debug information while interpreting the boot
+      script:</p>
+    <pre>
+% <input>erl -init_debug</input>
+{progress,preloaded}
+{progress,kernel_load_completed}
+{progress,modules_loaded}
+{start,heart}
+{start,error_logger}
+...</pre>
+    <p>See <c>script(4)</c> for a detailed description of the syntax
+      and contents of the boot script.</p>
+
+    <section>
+      <title>Default Boot Scripts</title>
+      <p>Erlang/OTP comes with two boot scripts:</p>
+      <taglist>
+        <tag><c>start_clean.boot</c></tag>
+        <item>
+          <p>Loads the code for and starts the applications Kernel and
+            STDLIB.</p>
+        </item>
+        <tag><c>start_sasl.boot</c></tag>
+        <item>
+          <p>Loads the code for and starts the applications Kernel,
+            STDLIB and SASL.</p>
+        </item>
+      </taglist>
+      <p>Which of <c>start_clean</c> and <c>start_sasl</c> to use as
+        default is decided by the user when installing Erlang/OTP using
+        <c>Install</c>. The user is asked "Do you want to use a minimal
+        system startup instead of the SASL startup". If the answer is
+        yes, then <c>start_clean</c> is used, otherwise
+        <c>start_sasl</c> is used. A copy of the selected boot script
+        is made, named <c>start.boot</c> and placed in
+        the <c>ROOT/bin</c> directory.</p>
+    </section>
+
+    <section>
+      <title>User-Defined Boot Scripts</title>
+      <p>It is sometimes useful or necessary to create a user-defined
+        boot script. This is true especially when running Erlang in
+        embedded mode, see <seealso marker="#code_loading">Code Loading Strategy</seealso>.</p>
+      <p>It is possible to write a boot script manually.
+        The recommended way to create a boot script, however, is to
+        generate the boot script from a release resource file
+        <c>Name.rel</c>, using the function
+        <c>systools:make_script/1,2</c>. This requires that the source
+        code is structured as applications according to the OTP design
+        principles. (The program does not have to be started in terms of
+        OTP applications but can be plain Erlang).</p>
+      <p>Read more about <c>.rel</c> files in OTP Design Principles and
+        <c>rel(4)</c>.</p>
+      <p>The binary boot script file <c>Name.boot</c> is generated from
+        the boot script file <c>Name.script</c> using the function
+        <c>systools:script2boot(File)</c>.</p>
+    </section>
+  </section>
+
+  <section>
+    <marker id="code_loading"></marker>
+    <title>Code Loading Strategy</title>
+    <p>The runtime system can be started in either <em>embedded</em> or
+      <em>interactive</em> mode. Which one is decided by the command
+      line flag <c>-mode</c>.</p>
+    <pre>
+% <input>erl -mode embedded</input></pre>
+    <p>Default mode is <c>interactive</c>.</p>
+    <list type="bulleted">
+      <item>In embedded mode, all code is loaded during system start-up
+       according to the boot script. (Code can also be loaded later
+       by explicitly ordering the code server to do so).</item>
+      <item>In interactive mode, code is dynamically loaded when first
+       referenced. When a call to a function in a module is made, and
+       the module is not loaded, the code server searches the code path
+       and loads the module into the system.</item>
+    </list>
+    <p>Initially, the code path consists of the current
+      working directory and all object code directories under
+      <c>ROOT/lib</c>, where <c>ROOT</c> is the installation directory
+      of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c> and
+      the code server, by default, chooses the directory with
+      the highest version number among those which have the same
+      <c>Name</c>. The <c>-Vsn</c> suffix is optional. If an
+      <c>ebin</c> directory exists under the <c>Name[-Vsn]</c>
+      directory, it is this directory which is added to the code path.</p>
+    <p>The code path can be extended by using the command line flags
+      <c>-pa Directories</c> and <c>-pz Directories</c>. These will add
+      <c>Directories</c> to the head or end of the code path,
+      respectively. Example</p>
+    <pre>
+% <input>erl -pa /home/arne/mycode</input></pre>
+    <p>The code server module <c>code</c> contains a number of
+      functions for modifying and checking the search path, see
+      <c>code(3)</c>.</p>
+  </section>
+
+  <section>
+    <title>File Types</title>
+    <p>The following file types are defined in Erlang/OTP:</p>
+    <table>
+      <row>
+        <cell align="left" valign="middle"><em>File Type</em></cell>
+        <cell align="left" valign="middle"><em>File Name/Extension</em></cell>
+        <cell align="left" valign="middle"><em>Documented in</em></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">module</cell>
+        <cell align="left" valign="middle"><c>.erl</c></cell>
+        <cell align="left" valign="middle">Erlang Reference Manual</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">include file</cell>
+        <cell align="left" valign="middle"><c>.hrl</c></cell>
+        <cell align="left" valign="middle">Erlang Reference Manual</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">release resource file</cell>
+        <cell align="left" valign="middle"><c>.rel</c></cell>
+        <cell align="left" valign="middle"><c>rel(4)</c></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">application resource file</cell>
+        <cell align="left" valign="middle"><c>.app</c></cell>
+        <cell align="left" valign="middle"><c>app(4)</c></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">boot script</cell>
+        <cell align="left" valign="middle"><c>.script</c></cell>
+        <cell align="left" valign="middle"><c>script(4)</c></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">binary boot script</cell>
+        <cell align="left" valign="middle"><c>.boot</c></cell>
+        <cell align="left" valign="middle">-</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">configuration file</cell>
+        <cell align="left" valign="middle"><c>.config</c></cell>
+        <cell align="left" valign="middle"><c>config(4)</c></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">application upgrade file</cell>
+        <cell align="left" valign="middle"><c>.appup</c></cell>
+        <cell align="left" valign="middle"><c>appup(4)</c></cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">release upgrade file</cell>
+        <cell align="left" valign="middle"><c>relup</c></cell>
+        <cell align="left" valign="middle"><c>relup(4)</c></cell>
+      </row>
+      <tcaption>File Types</tcaption>
+    </table>
+  </section>
+</chapter>
+
diff --git a/system/doc/system_principles/warning.gif b/system/doc/system_principles/warning.gif
new file mode 100644
index 0000000000..96af52360e
--- /dev/null
+++ b/system/doc/system_principles/warning.gif
diff --git a/system/doc/system_principles/xmlfiles.mk b/system/doc/system_principles/xmlfiles.mk
new file mode 100644
index 0000000000..4cbc00ed52
--- /dev/null
+++ b/system/doc/system_principles/xmlfiles.mk
@@ -0,0 +1,22 @@
+#
+# %CopyrightBegin%
+# 
+# Copyright Ericsson AB 2009. All Rights Reserved.
+# 
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+# 
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+# 
+# %CopyrightEnd%
+#
+SYSTEM_PRINCIPLES_CHAPTER_FILES = \
+	system_principles.xml \
+	error_logging.xml \
+	create_target.xml