diff options
Diffstat (limited to 'system/doc/system_principles/create_target.xmlsrc')
| -rw-r--r-- | system/doc/system_principles/create_target.xmlsrc | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc new file mode 100644 index 0000000000..bc2a76db47 --- /dev/null +++ b/system/doc/system_principles/create_target.xmlsrc @@ -0,0 +1,267 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2002</year><year>2011</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 are included. 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>In the <c>sasl</c> application there is an example Erlang + module <c>target_system.erl</c> that contains functions for + creating and installing a target system. This module is used in + the examples below, and 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/FIRST/mysystem.rel +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></p> + <p>The release resource file <c>mysystem.rel</c> is duplicated + in the tar file. Originally, this file was only stored in + the <c>releases</c> directory in order to make it possible + for the <c>release_handler</c> to extract this file + separately. After unpacking the tar + file, <c>release_handler</c> would automatically copy the + file to <c>releases/FIRST</c>. However, sometimes the tar + file is unpacked without involving + the <c>release_handler</c> (e.g. when unpacking the first + target system) and therefore the file is now instead + duplicated in the tar file so no manual copying is + necessary.</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>. These files will be created again from + source when installing the release.</item> + <item>Creates the directory <c>tmp/bin</c>.</item> + <item>Copies the previously created 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". This file is to be passed as data + file to the <c>start_erl</c> script. + </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 + be 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> + <p>This module can also be found in the <c>examples</c> directory + of the <c>sasl</c> application.</p> + <codeinclude file="../../../lib/sasl/examples/src/target_system.erl" tag="%module" type="erl"></codeinclude> + + </section> +</chapter> |