← Back to branch summary

~statik/ubuntu/maverick/erlang/erlang-merge-testing

« back to all changes in this revision

Viewing changes to system/doc/embedded/target.xml

  • Committer: Elliot Murphy
  • Date: 2010-06-08 03:55:44 UTC
  • mfrom: (3.5.6 squeeze)
  • Revision ID: elliot@elliotmurphy.com-20100608035544-dd8zh2swk7jr5rz2
* Merge with Debian unstable; remaining Ubuntu changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to. (LP #438365)
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
* Added missing symlinks to /usr/include for a few new header files.
* Fixed generation of ${erlang-base:Depends} and ${erlang-x11:Depends}
  substitution variables.
* Added a fix for a re:compile/2 crash on a long regular expression.
* Changed urgency to medium as the change fixes a security bug.
* Manpages in section 1 are needed even if only arch-dependent packages are
  built. So, re-enabled them.
* Fixed HiPE architecture recognition for powerpc Debian architecture.
* Moved xsltproc and fop to build-depends-indep and do not build
  documentation if only architecture-specific packages are built.
* Refreshed all patches.
* Made Emacs look in man5 and man7 for Erlang manpages and added code
  skeleton files to erlang-mode package.
* New upstream release.
* Moved manpages from incorrect sections 4 and 6 to correct 5 and 7
  (closes: #498492).
* Made manpages regexp in Emacs mode match only 3erl pages in section 3.
* Removed docb_gen script which is no longer needed to build manpages.
* Added erlang-doc package which contains documentation in HTML and PDF
  formats. This package replaces erlang-doc-html package and it's easier
  to synchronize it with the main Erlang packages as it's built from
  a single source package (closes: #558451).
* Removed RPATH from ssl and crypto application binaries as required by
  Debian policy.
* Added libwxgtk2.4-dev and libwxgtk2.6-dev to build conflicts.
* Added a few dpendencies for erlang-dialyzer, erlang-et, erlang-observer
  and erlang-examples packages which now call functions from more modules
  than in 1:13.b.3.
* Added a workaround which disables vfork() for hppa architecture
  (closes: #562218).
* Strictened check for JDK 1.5 adding a call to String(int[], int, int)
  because GCJ 4.4 doesn't implement it and OpenJDK isn't available for all
  architectures.
* Fixed erlang-manpages package section.
* Made erlang-depends add only substvars which are requested in
  debian/control file. This minimizes number of warnings from dh_gencontrol.
  Also, improved descriptions of the functions in erlang-depends escript.
* Added erlang-erl-docgen package to erlang-nox dependencies.
* Made dummy packages erlang-nox and erlang-x11 architecture all.
* Cleaned up working with custom substitution variables in debian/rules.
* Reorganized debian/rules to ensure that manpages arent built twice, and
  aren't built at all if only architecture-dependent packages are requested.
* Fixed project links in README.Debian.
* Added a new package erlang-jinterface which provides tools for
  communication of Java programs with Erlang processes. This adds build
  depandency on default-jdk and as a result enables Java module for IDL
  compiler.
* Bumped standards version to 3.8.4.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/embedded/target.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1996</year><year>2009</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>Installation of Embedded Environment</title>
 
25
    <prepared>Peter H&ouml;gfeldt</prepared>
 
26
    <responsible>Peter H&ouml;gfeldt</responsible>
 
27
    <docno></docno>
 
28
    <approved>(Peter H&ouml;gfeldt</approved>
 
29
    <checked></checked>
 
30
    <date>1997-05-26</date>
 
31
    <rev>C</rev>
 
32
    <file>target.sgml</file>
 
33
  </header>
 
34
  <p>This chapter is about installing a Embedded Environment. Solaris 
 
35
    2.5.1 is the only UNIX operating system supported for embedded systems. 
 
36
    The following topics are considered,</p>
 
37
  <list type="bulleted">
 
38
    <item>
 
39
      <p>Creation of user and installation directory,</p>
 
40
    </item>
 
41
    <item>
 
42
      <p>Installation of Embedded Environment,</p>
 
43
    </item>
 
44
    <item>
 
45
      <p>Configuration for automatic start at reboot,</p>
 
46
    </item>
 
47
    <item>
 
48
      <p>Making a hardware watchdog available,</p>
 
49
    </item>
 
50
    <item>
 
51
      <p>Changing permission for reboot,</p>
 
52
    </item>
 
53
    <item>
 
54
      <p>Patches for Solaris 2.5.1,</p>
 
55
    </item>
 
56
    <item>
 
57
      <p>Configuration of the os_mon application.</p>
 
58
    </item>
 
59
  </list>
 
60
  <p>Several of the procedures described below require expert knowledge of
 
61
    the Solaris 2 operating system. For most of them super user privilege is 
 
62
    needed.</p>
 
63
 
 
64
  <section>
 
65
    <title>Creation of user and installation directory</title>
 
66
    <p>It is recommended that the Embedded Environment is run by an ordinary
 
67
      user, i.e. a user which does not have super user privileges. </p>
 
68
    <p>Throughout this chapter we assume that the user name is <c>otpuser</c>,
 
69
      and that the home directory of that user is,</p>
 
70
    <pre>
 
71
/export/home/otpuser    </pre>
 
72
    <p>Furthermore, we assume that in the home directory of <c>otpuser</c>,
 
73
      there is a directory named <c>otp</c>, the full path of which is,</p>
 
74
    <pre>
 
75
/export/home/otpuser/otp    </pre>
 
76
    <p>This directory is the <em>installation directory</em> of the Embedded 
 
77
      Environment.</p>
 
78
  </section>
 
79
 
 
80
  <section>
 
81
    <title>Installation of Embedded Environment</title>
 
82
    <p>The procedure for installation of a Embedded Environment does not differ
 
83
      from that of a Development Environment (see the chapter <em>Installation of Development Environment</em>), except for the following,</p>
 
84
    <list type="bulleted">
 
85
      <item>
 
86
        <p>the (compressed) tape archive file should be extracted in 
 
87
          the installation directory as defined above, and,</p>
 
88
      </item>
 
89
      <item>
 
90
        <p>there is no need to link the start script to a standard directory
 
91
          like <c>/usr/local/bin</c>.</p>
 
92
      </item>
 
93
    </list>
 
94
    <p>The details for extracting the tape archive file is not repeated here.</p>
 
95
  </section>
 
96
 
 
97
  <section>
 
98
    <title>Configuration for Automatic Start at Boot</title>
 
99
    <p>A true Embedded Environment has to start when the system boots. This 
 
100
      section accounts for the necessary configurations needed to achieve
 
101
      that.</p>
 
102
    <p>The embedded environment and all the applications will  start automatically
 
103
      if the script file shown below is added to the <c>/etc/rc3.d</c> directory.
 
104
      The file must be owned and readable by <c>root</c>, and its name cannot
 
105
      be arbitrarily assigned. The following name is recommended,</p>
 
106
    <pre>
 
107
S75otp.system    </pre>
 
108
    <p>For further details on initialization (and termination) scripts, and
 
109
      naming thereof, see the file <c>/etc/init.d/README</c> on a Solaris
 
110
      2.5.1 system.</p>
 
111
    <pre>
 
112
#!/bin/sh
 
113
#  
 
114
#  File name:  S75otp.system
 
115
#  Purpose:    Automatically starts Erlang and applications when the 
 
116
#              system starts
 
117
#  Author:     janne@erlang.ericsson.se
 
118
#  Resides in: /etc/rc3.d
 
119
#
 
120
 
 
121
if [ ! -d /usr/bin ]
 
122
then                    # /usr not mounted
 
123
        exit
 
124
fi
 
125
 
 
126
killproc() {            # kill the named process(es)
 
127
        pid=`/usr/bin/ps -e |
 
128
             /usr/bin/grep -w $1 |
 
129
             /usr/bin/sed -e 's/^  *//' -e 's/ .*//'`
 
130
        [ "$pid" != "" ] &amp;&amp; kill $pid
 
131
}
 
132
 
 
133
# Start/stop processes required for Erlang
 
134
 
 
135
case "$1" in
 
136
'start')
 
137
        # Start the Erlang emulator
 
138
        #
 
139
        su - otpuser -c "/export/home/otpuser/otp/bin/start" &amp;
 
140
        ;;
 
141
'stop')
 
142
        killproc beam
 
143
        ;;
 
144
*)
 
145
        echo "Usage: $0 { start | stop }"
 
146
        ;;
 
147
esac    </pre>
 
148
    <p>The file <c>/export/home/otpuser/otp/bin/start</c> referred to in the 
 
149
      above script, is precisely the script <c>start</c> described in the next
 
150
      chapter of this guide, <em>Starting an Embedded System</em>. The script 
 
151
      variable <c>OTP_ROOT</c> in that <c>start</c> script corresponds to 
 
152
      the example path </p>
 
153
    <pre>
 
154
/export/home/otpuser/otp    </pre>
 
155
    <p>used in this section. The <c>start</c> script should be edited
 
156
      accordingly.</p>
 
157
    <p>Use of the <c>killproc</c> procedure in the above script could
 
158
      be combined with a call to <c>erl_call</c>, e.g.</p>
 
159
    <pre>
 
160
  $SOME_PATH/erl_call -n Node init stop    </pre>
 
161
    <p>in order to take Erlang down gracefully (see the <c>erl_call(1)</c> 
 
162
      reference manual page for further details on the use of <c>erl_call</c>).
 
163
      That however requires that Erlang runs as a distributed node which is 
 
164
      not always the case.</p>
 
165
    <p>The <c>killproc</c> procedure should not be removed: the purpose is
 
166
      here to move from run level 3 (multi-user mode with networking resources)
 
167
      to run level 2 (multi-user mode without such resources), in which Erlang
 
168
      should not run.</p>
 
169
  </section>
 
170
 
 
171
  <section>
 
172
    <title>Hardware Watchdog</title>
 
173
    <p>For Solaris 2.5.1 running on VME boards from Force Computers, there
 
174
      is a possibility to activate the onboard hardware watchdog, provided a
 
175
      VME bus driver is added to the operating system. For further details
 
176
      see the <em>Embedded Systems</em> documentation.</p>
 
177
    <p>See also the <c>heart(3)</c> reference manual page in <em>Kernel</em>.</p>
 
178
  </section>
 
179
 
 
180
  <section>
 
181
    <title>Changing permissions for reboot</title>
 
182
    <p>If the <c>HEART_COMMAND</c> environment variable is to be set in
 
183
      the <c>start</c> script of the next chapter, <em>Starting an Embedded System</em>, and if the value shall be set to the path of the Solaris 
 
184
      <c>reboot</c> command, i.e.</p>
 
185
    <pre>
 
186
HEART_COMMAND=/usr/sbin/reboot    </pre>
 
187
    <p>the ownership and file permissions for <c>/usr/sbin/reboot</c> must
 
188
      be changed as follows,</p>
 
189
    <pre>
 
190
chown 0 /usr/sbin/reboot
 
191
chmod 4755 /usr/sbin/reboot    </pre>
 
192
    <p>See also the <c>heart(3)</c> reference manual page in <em>Kernel</em>.</p>
 
193
  </section>
 
194
 
 
195
  <section>
 
196
    <title>The TERM environment variable</title>
 
197
    <p>When the Erlang runtime system is automatically started from the 
 
198
      <c>S75otp.system</c> script the <c>TERM</c> environment variable
 
199
      has to be set. The following is a minimal setting,</p>
 
200
    <pre>
 
201
TERM=sun    </pre>
 
202
    <p>which should be added to the <c>start</c> script described in the
 
203
      next chapter.</p>
 
204
  </section>
 
205
 
 
206
  <section>
 
207
    <title>Patches for Solaris 2.5.1</title>
 
208
    <p>For proper functioning of flushing file system data to disk, the
 
209
      Solaris 2.5.1 specific patch with number 103640-02 must be added
 
210
      to the operating system.</p>
 
211
  </section>
 
212
 
 
213
  <section>
 
214
    <title>Installation of module os_sup in application os_mon</title>
 
215
    <p>The following four installation procedures requires superuser privilege.</p>
 
216
 
 
217
    <section>
 
218
      <title>Installation</title>
 
219
      <list type="ordered">
 
220
        <item>
 
221
          <p><em>Make a copy the Solaris standard configuration file for syslogd.</em></p>
 
222
          <list type="bulleted">
 
223
            <item>
 
224
              <p>Make a copy the Solaris standard configuration file for syslogd.
 
225
                This file is usually named <c>syslog.conf</c> and found in the <c>/etc</c>
 
226
                directory.</p>
 
227
            </item>
 
228
            <item>
 
229
              <p>The file name of the copy must be <c>syslog.conf.ORIG</c> but the 
 
230
                directory location is optional. Usually it is <c>/etc</c>.
 
231
                </p>
 
232
              <p>A simple way to do this is to issue the command</p>
 
233
              <code type="none">
 
234
    cp /etc/syslog.conf /etc/syslog.conf.ORIG</code>
 
235
            </item>
 
236
          </list>
 
237
        </item>
 
238
        <item>
 
239
          <p><em>Make an Erlang specific configuration file for syslogd.</em></p>
 
240
          <list type="bulleted">
 
241
            <item>
 
242
              <p>Make an edited copy of the back-up copy previously made.</p>
 
243
            </item>
 
244
            <item>
 
245
              <p>The file name must be <c>syslog.conf.OTP</c> and the path 
 
246
                must be the same as the back-up copy.</p>
 
247
            </item>
 
248
            <item>
 
249
              <p>The format of the configuration file is found in the man page for
 
250
                <c>syslog.conf(5)</c>, by issuing the command <c>man syslog.conf</c>.</p>
 
251
            </item>
 
252
            <item>
 
253
              <p>Usually a line is added which should state:</p>
 
254
              <list type="bulleted">
 
255
                <item>
 
256
                  <p>which types of information that will be supervised by Erlang,</p>
 
257
                </item>
 
258
                <item>
 
259
                  <p>the name of the file (actually a named pipe) that should receive
 
260
                    the information.</p>
 
261
                </item>
 
262
              </list>
 
263
            </item>
 
264
            <item>
 
265
              <p>If e.g. only information originating from the unix-kernel should
 
266
                be supervised, the line should begin with <c>kern.LEVEL</c> (for the 
 
267
                possible values of <c>LEVEL</c> see <c>syslog.conf(5)</c>).</p>
 
268
            </item>
 
269
            <item>
 
270
              <p>After at least one tab-character, the line added should contain
 
271
                the full name of the named pipe where syslogd writes its information. The
 
272
                path must be the same as for the <c>syslog.conf.ORIG</c> and
 
273
                <c>syslog.conf.OTP</c> files. The file name must be <c>syslog.otp</c>.</p>
 
274
            </item>
 
275
            <item>
 
276
              <p>If the directory for the <c>syslog.conf.ORIG</c> and
 
277
                <c>syslog.conf.OTP</c> files is <c>/etc</c> the line in
 
278
                <c>syslog.conf.OTP</c> will look like:</p>
 
279
              <code type="none">
 
280
   kern.LEVEL                /etc/syslog.otp              </code>
 
281
            </item>
 
282
          </list>
 
283
        </item>
 
284
        <item>
 
285
          <p><em>Check the file privileges of the configuration files.</em></p>
 
286
          <list type="bulleted">
 
287
            <item>
 
288
              <p>The configuration files should have <c>rw-r--r--</c> file 
 
289
                privileges and be owned by root.</p>
 
290
            </item>
 
291
            <item>
 
292
              <p>A simple way to do this is to issue the commands</p>
 
293
              <code type="none">
 
294
  chmod 644 /etc/syslog.conf
 
295
  chmod 644 /etc/syslog.conf.ORIG
 
296
  chmod 644 /etc/syslog.conf.OTP              </code>
 
297
            </item>
 
298
            <item>
 
299
              <p><em>Note:</em> If the <c>syslog.conf.ORIG</c> and 
 
300
                <c>syslog.conf.OTP</c> files are not in the <c>/etc</c> directory, 
 
301
                the file path in the second and third command must be modified.</p>
 
302
            </item>
 
303
          </list>
 
304
        </item>
 
305
        <item>
 
306
          <p><em>Modify file privileges and ownership of the mod_syslog utility.</em></p>
 
307
          <list type="bulleted">
 
308
            <item>
 
309
              <p>The file privileges and ownership of the <c>mod_syslog</c> utility
 
310
                must be modified.</p>
 
311
            </item>
 
312
            <item>
 
313
              <p>The full name of the binary executable file is derived from the 
 
314
                position of the <c>os_mon</c> application if the file system by adding 
 
315
                <c>/priv/bin/mod_syslog</c>. The generic full name of the binary executable
 
316
                file is thus</p>
 
317
              <code type="none"><![CDATA[
 
318
  <OTP_ROOT>/lib/os_mon-<rev>/priv/bin/mod_syslog              ]]></code>
 
319
              <p><em>Example:</em> If the path to the otp-root is
 
320
                <c>/usr/otp</c>, thus the path to the <c>os_mon</c> application is 
 
321
                <c>/usr/otp/lib/os_mon-1.0</c> (assuming revision 1.0) and the full name 
 
322
                of the binary executable file is 
 
323
                <c>/usr/otp/lib/os_mon-1.0/priv/bin/mod_syslog</c>.</p>
 
324
            </item>
 
325
            <item>
 
326
              <p>The binary executable file must be owned by root, have 
 
327
                <c>rwsr-xr-x</c> file privileges, in particular the setuid bit of
 
328
                user must be set.</p>
 
329
            </item>
 
330
            <item>
 
331
              <p>A simple way to do this is to issue the commands</p>
 
332
              <code type="none"><![CDATA[
 
333
  cd <OTP_ROOT>/lib/os_mon-<rev>/priv/bin/mod_syslog
 
334
  chmod 4755 mod_syslog
 
335
  chown root mod_syslog              ]]></code>
 
336
            </item>
 
337
          </list>
 
338
        </item>
 
339
      </list>
 
340
    </section>
 
341
 
 
342
    <section>
 
343
      <title>Testing the application configuration file</title>
 
344
      <p>The following procedure does not require root privilege.</p>
 
345
      <list type="bulleted">
 
346
        <item>
 
347
          <p>Ensure that the configuration parameters for the <c>os_sup</c>
 
348
            module in the <c>os_mon</c> application are correct.</p>
 
349
        </item>
 
350
        <item>
 
351
          <p>Browse the application configuration file (do <em>not</em> edit
 
352
            it). The full name of the application configuration file is derived
 
353
            from the position of the os_mon-application if the file system by adding
 
354
            <c>/ebin/os_mon.app</c>.</p>
 
355
          <p>The generic full name of the file is thus</p>
 
356
          <code type="none"><![CDATA[
 
357
   <OTP_ROOT>/lib/os_mon-<rev>/ebin/os_mon.app.          ]]></code>
 
358
          <p><em>Example:</em> If the path to the otp-root is <c>/usr/otp</c>,
 
359
            thus the path to the <c>os_mon</c> application is <c>/usr/otp/lib/os_mon-1.0</c> (assuming revision 1.0) and the full name of the binary executable file
 
360
            is <c>/usr/otp/lib/os_mon-1.0/ebin/os_mon.app</c>.</p>
 
361
        </item>
 
362
        <item>
 
363
          <p>Ensure that the following configuration parameters are bound to
 
364
            the correct values.</p>
 
365
        </item>
 
366
      </list>
 
367
      <table>
 
368
        <row>
 
369
          <cell align="left" valign="top"><em>Parameter</em></cell>
 
370
          <cell align="left" valign="top"><em>Function</em></cell>
 
371
          <cell align="left" valign="top"><em>Standard value</em></cell>
 
372
        </row>
 
373
        <row>
 
374
          <cell align="left" valign="middle">start_os_sup</cell>
 
375
          <cell align="left" valign="middle">Specifies if os_sup will be started or not.</cell>
 
376
          <cell align="left" valign="middle"><c>true</c>for the first instance on the hardware; <c>false</c>for the other instances.</cell>
 
377
        </row>
 
378
        <row>
 
379
          <cell align="left" valign="middle">os_sup_own</cell>
 
380
          <cell align="left" valign="middle">The directory for (1)the back-up copy, (2) the Erlang specific configuration file  for syslogd.</cell>
 
381
          <cell align="left" valign="middle"><c>"/etc"</c></cell>
 
382
        </row>
 
383
        <row>
 
384
          <cell align="left" valign="middle">os_sup_syslogconf</cell>
 
385
          <cell align="left" valign="middle">The full name for the  Solaris standard configuration file for syslogd </cell>
 
386
          <cell align="left" valign="middle"><c>"/etc/syslog.conf"</c></cell>
 
387
        </row>
 
388
        <row>
 
389
          <cell align="left" valign="middle">error_tag</cell>
 
390
          <cell align="left" valign="middle">The tag for the messages that are sent to the error logger in the Erlang runtime system.</cell>
 
391
          <cell align="left" valign="middle"><c>std_error</c></cell>
 
392
        </row>
 
393
        <tcaption>Configuration Parameters</tcaption>
 
394
      </table>
 
395
      <p>If the values listed in the <c>os_mon.app</c> does not suite your 
 
396
        needs, you should <c>not</c> edit that file. Instead you should
 
397
        <em>override</em> values in a <em>system configuration file</em>, the
 
398
        full pathname of which is given on the command line to <c>erl</c>.</p>
 
399
      <p><em>Example:</em> The following is an example of the contents of an
 
400
        application configuration file.</p>
 
401
      <p></p>
 
402
      <pre>
 
403
[{os_mon, [{start_os_sup, true}, {os_sup_own, "/etc"}, 
 
404
 {os_sup_syslogconf, "/etc/syslog.conf"}, {os_sup_errortag, std_error}]}].      </pre>
 
405
    </section>
 
406
 
 
407
    <section>
 
408
      <title>Related documents</title>
 
409
      <p>See also the <c>os_mon(3)</c>, <c>application(3)</c> and <c>erl(1)</c>
 
410
        reference manual pages.</p>
 
411
    </section>
 
412
  </section>
 
413
</chapter>
 
414