← Back to branch summary

~clint-fewbar/ubuntu/precise/erlang/merge-15b

« back to all changes in this revision

Viewing changes to system/doc/system_principles/create_target.xmlsrc

  • Committer: Package Import Robot
  • Author(s): Sergei Golovan
  • Date: 2011-12-15 19:20:10 UTC
  • mfrom: (1.1.18) (3.5.15 sid)
  • mto: (3.5.16 sid)
  • mto: This revision was merged to the branch mainline in revision 33.
  • Revision ID: package-import@ubuntu.com-20111215192010-jnxcfe3tbrpp0big
Tags: 1:15.b-dfsg-1
* New upstream release.
* Upload to experimental because this release breaks external drivers
  API along with ABI, so several applications are to be fixed.
* Removed SSL patch because the old SSL implementation is removed from
  the upstream distribution.
* Removed never used patch which added native code to erlang beam files.
* Removed the erlang-docbuilder binary package because the docbuilder
  application was dropped by upstream.
* Documented dropping ${erlang-docbuilder:Depends} substvar in
  erlang-depends(1) manpage.
* Made erlang-base and erlang-base-hipe provide virtual package
  erlang-abi-15.b (the number means the first erlang version, which
  provides current ABI).

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/system_principles/create_target.xmlsrc
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2002</year><year>2011</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
 
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
 
 
22
    </legalnotice>
 
23
 
 
24
    <title>Creating a First Target System</title>
 
25
    <prepared>Peter H&ouml;gfeldt</prepared>
 
26
    <responsible></responsible>
 
27
    <docno></docno>
 
28
    <approved></approved>
 
29
    <checked></checked>
 
30
    <date>2002-09-17</date>
 
31
    <rev>A</rev>
 
32
    <file>create_target.xml</file>
 
33
  </header>
 
34
 
 
35
  <section>
 
36
    <title>Introduction</title>
 
37
    <p>When creating a system using Erlang/OTP, the most simple way is
 
38
      to install Erlang/OTP somewhere, install the application specific
 
39
      code somewhere else, and then start the Erlang runtime system,
 
40
      making sure the code path includes the application specific code.</p>
 
41
    <p>Often it is not desirable to use an Erlang/OTP system as is. A
 
42
      developer may create new Erlang/OTP compliant applications for a
 
43
      particular purpose, and several original Erlang/OTP applications
 
44
      may be irrelevant for the purpose in question. Thus, there is a
 
45
      need to be able to create a new system based on a given
 
46
      Erlang/OTP system, where dispensable applications are removed,
 
47
      and a set of new applications are included. Documentation and
 
48
      source code is irrelevant and is therefore not included in the
 
49
      new system.</p>
 
50
    <p>This chapter is about creating such a system, which we call a
 
51
      <em>target system</em>.</p>
 
52
    <p>In the following sections we consider creating target systems with
 
53
      different requirements of functionality:</p>
 
54
    <list type="bulleted">
 
55
      <item>a <em>basic target system</em> that can be started by
 
56
       calling the ordinary <c>erl</c> script, </item>
 
57
      <item>a <em>simple target system</em> where also code
 
58
       replacement in run-time can be performed, and</item>
 
59
      <item>an <em>embedded target system</em> where there is also
 
60
       support for logging output from the system to file for later
 
61
       inspection, and where the system can be started automatically
 
62
       at boot time. </item>
 
63
    </list>
 
64
    <p>We only consider the case when Erlang/OTP is running on a UNIX
 
65
      system.</p>
 
66
    <p>In the <c>sasl</c> application there is an example Erlang
 
67
      module <c>target_system.erl</c> that contains functions for
 
68
      creating and installing a target system.  This module is used in
 
69
      the examples below, and the source code of the module is listed
 
70
      at the end of this chapter.</p>
 
71
  </section>
 
72
 
 
73
  <section>
 
74
    <title>Creating a Target System</title>
 
75
    <p>It is assumed that you have a working Erlang/OTP system structured
 
76
      according to the OTP Design Principles.</p>
 
77
    <p><em>Step 1.</em> First create a <c>.rel</c> file (see
 
78
      <c>rel(4)</c>) that specifies the <c>erts</c> version
 
79
      and lists all applications that should be included in the new
 
80
      basic target system. An example is the following
 
81
      <c>mysystem.rel</c> file:</p>
 
82
    <code type="none">
 
83
%% mysystem.rel
 
84
{release,
 
85
 {"MYSYSTEM", "FIRST"},
 
86
 {erts, "5.1"},
 
87
 [{kernel, "2.7"},
 
88
  {stdlib, "1.10"},
 
89
  {sasl, "1.9.3"},
 
90
  {pea, "1.0"}]}.    </code>
 
91
    <p>The listed applications are not only original Erlang/OTP
 
92
      applications but possibly also new applications that you have
 
93
      written yourself (here examplified by the application
 
94
      <c>pea</c>). </p>
 
95
    <p><em>Step 2.</em> From the directory where the <c>mysystem.rel</c>
 
96
      file reside, start the Erlang/OTP system:</p>
 
97
    <pre>
 
98
os> <input>erl -pa /home/user/target_system/myapps/pea-1.0/ebin</input></pre>
 
99
    <p>where also the path to the <c>pea-1.0</c> ebin directory is
 
100
      provided. </p>
 
101
    <p><em>Step 3.</em> Now create the target system: </p>
 
102
    <pre>
 
103
1> <input>target_system:create("mysystem").</input></pre>
 
104
    <p>The <c>target_system:create/1</c> function does the following:</p>
 
105
    <list type="ordered">
 
106
      <item>Reads the <c>mysystem.rel</c> file, and creates a new file
 
107
      <c>plain.rel</c> which is identical to former, except that it
 
108
       only lists the <c>kernel</c> and <c>stdlib</c> applications. </item>
 
109
      <item>From the <c>mysystem.rel</c> and <c>plain.rel</c> files
 
110
       creates the files <c>mysystem.script</c>,
 
111
      <c>mysystem.boot</c>, <c>plain.script</c>, and
 
112
      <c>plain.boot</c> through a call to
 
113
      <c>systools:make_script/2</c>.</item>
 
114
      <item>
 
115
        <p>Creates the file <c>mysystem.tar.gz</c> by a call to
 
116
          <c>systools:make_tar/2</c>. That file has the following
 
117
          contents:</p>
 
118
        <code type="none">
 
119
erts-5.1/bin/
 
120
releases/FIRST/start.boot
 
121
releases/FIRST/mysystem.rel
 
122
releases/mysystem.rel
 
123
lib/kernel-2.7/
 
124
lib/stdlib-1.10/
 
125
lib/sasl-1.9.3/
 
126
lib/pea-1.0/        </code>
 
127
        <p>The file <c>releases/FIRST/start.boot</c> is a copy of our
 
128
          <c>mysystem.boot</c></p>
 
129
        <p>The release resource file <c>mysystem.rel</c> is duplicated
 
130
          in the tar file. Originally, this file was only stored in
 
131
          the <c>releases</c> directory in order to make it possible
 
132
          for the <c>release_handler</c> to extract this file
 
133
          separately. After unpacking the tar
 
134
          file, <c>release_handler</c> would automatically copy the
 
135
          file to <c>releases/FIRST</c>. However, sometimes the tar
 
136
          file is unpacked without involving
 
137
          the <c>release_handler</c> (e.g. when unpacking the first
 
138
          target system) and therefore the file is now instead
 
139
          duplicated in the tar file so no manual copying is
 
140
          necessary.</p>
 
141
      </item>
 
142
      <item>Creates the temporary directory <c>tmp</c> and extracts the tar file
 
143
      <c>mysystem.tar.gz</c> into that directory. </item>
 
144
      <item>Deletes the <c>erl</c> and <c>start</c> files from
 
145
      <c>tmp/erts-5.1/bin</c>. These files will be created again from
 
146
      source when installing the release.</item>
 
147
      <item>Creates the directory <c>tmp/bin</c>.</item>
 
148
      <item>Copies the previously created file <c>plain.boot</c> to
 
149
      <c>tmp/bin/start.boot</c>.</item>
 
150
      <item>Copies the files <c>epmd</c>, <c>run_erl</c>, and
 
151
      <c>to_erl</c> from the directory <c>tmp/erts-5.1/bin</c> to
 
152
       the directory <c>tmp/bin</c>.</item>
 
153
      <item>Creates the file <c>tmp/releases/start_erl.data</c> with
 
154
       the contents "5.1 FIRST". This file is to be passed as data
 
155
       file to the <c>start_erl</c> script.
 
156
      </item>
 
157
      <item>Recreates the file <c>mysystem.tar.gz</c> from the directories
 
158
       in the directory <c>tmp</c>, and removes <c>tmp</c>.</item>
 
159
    </list>
 
160
  </section>
 
161
 
 
162
  <section>
 
163
    <title>Installing a Target System</title>
 
164
    <p><em>Step 4.</em> Install the created target system in a
 
165
      suitable directory. </p>
 
166
    <pre>
 
167
2> <input>target_system:install("mysystem", "/usr/local/erl-target").</input></pre>
 
168
    <p>The function <c>target_system:install/2</c> does the following:
 
169
      </p>
 
170
    <list type="ordered">
 
171
      <item>Extracts the tar file <c>mysystem.tar.gz</c> into the target
 
172
       directory <c>/usr/local/erl-target</c>.</item>
 
173
      <item>In the target directory reads the file <c>releases/start_erl.data</c>
 
174
       in order to find the Erlang runtime system version ("5.1").</item>
 
175
      <item>Substitutes <c>%FINAL_ROOTDIR%</c> and <c>%EMU%</c> for
 
176
      <c>/usr/local/erl-target</c> and <c>beam</c>, respectively, in
 
177
       the files <c>erl.src</c>, <c>start.src</c>, and
 
178
      <c>start_erl.src</c> of the target <c>erts-5.1/bin</c>
 
179
       directory, and puts the resulting files <c>erl</c>,
 
180
      <c>start</c>, and <c>run_erl</c> in the target <c>bin</c>
 
181
       directory.</item>
 
182
      <item>Finally the target <c>releases/RELEASES</c> file is created
 
183
       from data in the <c>releases/mysystem.rel</c> file.</item>
 
184
    </list>
 
185
  </section>
 
186
 
 
187
  <section>
 
188
    <title>Starting a Target System</title>
 
189
    <p>Now we have a target system that can be started in various ways.</p>
 
190
    <p>We start it as a <em>basic target system</em> by invoking</p>
 
191
    <pre>
 
192
os> <input>/usr/local/erl-target/bin/erl</input></pre>
 
193
    <p>where only the <c>kernel</c> and <c>stdlib</c> applications are
 
194
      started, i.e. the system is started as an ordinary development
 
195
      system. There are only two files needed for all this to work:
 
196
      <c>bin/erl</c> file (obtained from <c>erts-5.1/bin/erl.src</c>)
 
197
      and the <c>bin/start.boot</c> file (a copy of <c>plain.boot</c>).</p>
 
198
    <p>We can also start a distributed system (requires <c>bin/epmd</c>).</p>
 
199
    <p>To start all applications specified in the original
 
200
      <c>mysystem.rel</c> file, use the <c>-boot</c> flag as follows:</p>
 
201
    <pre>
 
202
os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start</input></pre>
 
203
    <p>We start a <em>simple target system</em> as above. The only difference
 
204
      is that also the file <c>releases/RELEASES</c> is present for
 
205
      code replacement in run-time to work.</p>
 
206
    <p>To start an <em>embedded target system</em> the shell script
 
207
      <c>bin/start</c> is used. That shell script calls
 
208
      <c>bin/run_erl</c>, which in turn calls <c>bin/start_erl</c>
 
209
      (roughly, <c>start_erl</c> is an embedded variant of
 
210
      <c>erl</c>). </p>
 
211
    <p>The shell script <c>start</c> is only an example. You should
 
212
      edit it to suite your needs. Typically it is executed when the
 
213
      UNIX system boots.</p>
 
214
    <p><c>run_erl</c> is a wrapper that provides logging of output from
 
215
      the run-time system to file. It also provides a simple mechanism
 
216
      for attaching to the Erlang shell (<c>to_erl</c>).</p>
 
217
    <p><c>start_erl</c> requires the root directory
 
218
      (<c>"/usr/local/erl-target"</c>), the releases directory
 
219
      (<c>"/usr/local/erl-target/releases"</c>), and the location of
 
220
      the <c>start_erl.data</c> file. It reads the run-time system
 
221
      version (<c>"5.1"</c>) and release version (<c>"FIRST"</c>) from
 
222
      the <c>start_erl.data</c> file, starts the run-time system of the
 
223
      version found, and provides <c>-boot</c> flag specifying the boot
 
224
      file of the release version found
 
225
      (<c>"releases/FIRST/start.boot"</c>).</p>
 
226
    <p><c>start_erl</c> also assumes that there is <c>sys.config</c> in
 
227
      release version directory (<c>"releases/FIRST/sys.config"</c>). That
 
228
      is the topic of the next section (see below).</p>
 
229
    <p>The <c>start_erl</c> shell script should normally not be
 
230
      altered by the user.</p>
 
231
  </section>
 
232
 
 
233
  <section>
 
234
    <title>System Configuration Parameters</title>
 
235
    <p>As was pointed out above <c>start_erl</c> requires a
 
236
      <c>sys.config</c> in the release version directory
 
237
      (<c>"releases/FIRST/sys.config"</c>). If there is no such a
 
238
      file, the system start will fail. Hence such a file has to
 
239
      be added as well.</p>
 
240
    <p></p>
 
241
    <p>If you have system configuration data that are neither file
 
242
      location dependent nor site dependent, it may be convenient to
 
243
      create the <c>sys.config</c> early, so that it becomes a part of
 
244
      the target system tar file created by
 
245
      <c>target_system:create/1</c>. In fact, if you create, in the
 
246
      current directory, not only the <c>mysystem.rel</c> file, but
 
247
      also a <c>sys.config</c> file, that latter file will be tacitly
 
248
      put in the apropriate directory.</p>
 
249
  </section>
 
250
 
 
251
  <section>
 
252
    <title>Differences from the Install Script</title>
 
253
    <p>The above <c>install/2</c> procedure differs somewhat from that
 
254
      of the ordinary <c>Install</c> shell script. In fact, <c>create/1</c>
 
255
      makes the release package as complete as possible, and leave to the
 
256
      <c>install/2</c> procedure to finish by only considering location
 
257
      dependent files.</p>
 
258
  </section>
 
259
 
 
260
  <section>
 
261
    <title>Listing of target_system.erl</title>
 
262
    <p>This module can also be found in the <c>examples</c> directory
 
263
      of the <c>sasl</c> application.</p>
 
264
    <codeinclude file="../../../lib/sasl/examples/src/target_system.erl" tag="%module" type="erl"></codeinclude>
 
265
 
 
266
  </section>
 
267
</chapter>