ose: Expand OSE docs

1 files changed, 95 insertions, 2 deletions

diff --git a/lib/ose/doc/src/ose_intro.xml b/lib/ose/doc/src/ose_intro.xml
index 8fe723ba83..0dd3ec409e 100644
--- a/lib/ose/doc/src/ose_intro.xml
+++ b/lib/ose/doc/src/ose_intro.xml
@@ -34,6 +34,62 @@
   </section>
 
   <section>
+    <title>Starting Erlang/OTP</title>
+    <p>
+      Starting Erlang/OTP on OSE is not as simple as on Unix/Windows (yet).
+      First of all you have to explicitly use the beam (or beam.smp) executables
+      found in erts-X.Y.Z/bin as the load module that you run. This in turn
+      means that you have to supply the raw beam arguments to the emulator
+      when starting. Fortunately <c>erl</c> on Unix/Windows has a
+      undocumented flag called <c>-emu_args_exit</c> that can be used to
+      figure out what the arguments to beam look like. For example:</p>
+      <code># erl +Mut false +A 10 +S 4:4 +Muycs256 +P 2096 +Q 2096 -emu_args_exit
+-Mut
+false
+-A
+10
+-S
+4:4
+-Muycs256
+-P
+2096
+-Q
+2096
+--
+-root
+/usr/local/lib/erlang
+-progname
+erl
+--
+-home
+/home/erlang
+--</code>
+    <p>
+      The arguments are printed on seperate lines to make it possible to know
+      what has to be quoted with &quot;. Each line is one quotable unit.
+      So taking the arguments above you can supply them to pm_create or
+      just execute directly on the command line. For example:</p>
+      <code>rtose@acp3400> pm_install erlang /mst/erlang/erts-6.0/bin/beam.smp
+rtose@acp3400> pm_create -c ARGV="-Mut false -A 10 -S 4:4 -Muycs256 -P 2096 -Q 2099 -- -root /mst/erlang -progname erl -- -home /mst/erlang --" erlang
+pid: 0x110059
+rtose@acp3400> pm_start 0x110059</code>
+    <p>
+      Also note that since we are running erl to figure out the arguments on a
+      seperate machine the paths have to be updated. In the example above
+      <c>/usr/local/lib/erlang</c> was replaced by <c>/mst/erlang/</c>. The
+      goal is to in future releases not have to do the special argument handling
+      but for now (17.0-rc2) you have to do it.
+    </p>
+    <note>
+      Because of a limitation in the way the OSE handles stdio when starting
+      load modules using pm_install/create the Erlang shell only reads every
+      other command from stdin. However if you start Erlang using run_erl
+      you do not have this problem. So it is highly recommended that you
+      start Erlang using run_erl.
+    </note>
+  </section>
+
+  <section>
     <title>run_erl and to_erl</title>
     <p>
       In OSE run_erl and to_erl are combined into a single load module called
@@ -48,13 +104,50 @@
 	installing and exectuting the first part of the command. If nothing
 	if given the basename of the load module will be used for this value.
 	Example:
-	<code>pm_install erlang /path/to/erlang/vm
-run_erl -daemon -block erlang /pipe/ /mst/erlang_logs/ "erl -A 10"</code>
+	<code>pm_install erlang /path/to/erlang/vm/beam.smp
+run_erl -daemon -block erlang /pipe/ /mst/erlang_logs/ "beam.smp -A 1 -- -root /mst/erlang -- -home /mst --"</code>
 	</item>
       </taglist>
+      The same argument munching as when starting Erlang/OTP without run_erl
+      has to be done. If <c>-daemon</c> is given then all error printouts
+      are sent to the ramlog.
       See also
       <seealso marker="erts:run_erl">run_erl</seealso> for more details.
     </p>
+    <p>
+      Below is an example of how to get started with <c>run_erl_lm</c>.
+      <code>rtose@acp3400> pm_install run_erl_lm /mst/erlang/erts-6.0/bin/run_erl_lm
+rtose@acp3400> pm_create run_erl_lm
+pid: 0x1c005d
+rtose@acp3400> pm_start 0x1c005d
+rtose@acp3400> mkdir /mst/erlang_log
+rtose@acp3400> run_erl -daemon /pipe/ /mst/erlang_log/ "/mst/erlang/erts-6.0/bin/beam.smp -A 1 -- -root /mst/erlang -- -home /mst --"
+rtose@acp3400> to_erl
+Attaching to /pipe/erlang.pipe.1 (^C to exit)
+os:type().
+{ose,release}
+2>
+'to_erl' terminated.</code>
+      Note that Ctrl-C is used instead of Ctrl-D to exit the to_erl shell.
+    </p>
+  </section>
+
+  <section>
+    <title>epmd</title>
+    <p>
+      In OSE epmd will not be started automatically so if you want to use
+      Erlang distribution you have to manually start epmd.
+    </p>
+  </section>
+
+  <section>
+    <title>VM Process Priorities</title>
+    <p>
+      It is possible to set the priorities you want for the OSE processes that
+      thr emulator creates in the lmconf. An example of how to do it can be
+      found in the default lmconf file in
+      $ERL_TOP/erts/emulator/sys/ose/default.lmconf.
+    </p>
   </section>
 
 </chapter>