diff options
Diffstat (limited to 'system/doc/system_principles')
| -rw-r--r-- | system/doc/system_principles/Makefile | 95 | ||||
| -rw-r--r-- | system/doc/system_principles/book.xml | 43 | ||||
| -rw-r--r-- | system/doc/system_principles/create_target.xml | 502 | ||||
| -rw-r--r-- | system/doc/system_principles/error_logging.xml | 116 | ||||
| -rw-r--r-- | system/doc/system_principles/make.dep | 14 | ||||
| -rw-r--r-- | system/doc/system_principles/part.xml | 35 | ||||
| -rw-r--r-- | system/doc/system_principles/system_principles.xml | 236 | ||||
| -rw-r--r-- | system/doc/system_principles/warning.gif | bin | 0 -> 1498 bytes | |||
| -rw-r--r-- | system/doc/system_principles/xmlfiles.mk | 22 |
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ö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,<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) +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 Binary files differnew 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 |
