<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="linuxemu">
<chapterinfo>
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Restructured and parts updated by </contrib>
</author>
<!-- 22 Mar 2000 -->
</authorgroup>
<authorgroup>
<author>
<firstname>Brian N.</firstname>
<surname>Handy</surname>
<contrib>Originally contributed by </contrib>
</author>
<author>
<firstname>Rich</firstname>
<surname>Murphey</surname>
</author>
</authorgroup>
</chapterinfo>
<title>&linux; Binary Compatibility</title>
<sect1 id="linuxemu-synopsis">
<title>Synopsis</title>
<indexterm><primary>Linux binary
compatibility</primary></indexterm>
<indexterm>
<primary>binary compatibility</primary>
<secondary>Linux</secondary>
</indexterm>
<para>&os; provides binary compatibility with &linux;, allowing
users to install and run &linux; binaries on a &os; system.
Many companies and developers develop only for &linux;, and
binary compatibility allows &os; users to run about 90% of all
&linux; applications without modification. This includes
productivity applications, games, and more. It has even been
reported that, in some situations, &linux; binaries perform
better on &os; than they do on &linux;.</para>
<para>However, some &linux;-specific operating system features
are not supported under &os;. For example, &linux; binaries
will not work on &os; if they overly use &i386; specific
calls, such as enabling virtual 8086 mode.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>How to enable &linux; binary compatibility on a &os;
system.</para>
</listitem>
<listitem>
<para>How to install additional &linux; shared
libraries.</para>
</listitem>
<listitem>
<para>How to install &linux; applications on a &os;
system.</para>
</listitem>
<listitem>
<para>The implementation details of &linux; compatibility in
&os;.</para>
</listitem>
</itemizedlist>
<para>Before reading this chapter, you should:</para>
<itemizedlist>
<listitem>
<para>Know how to install <link linkend="ports">additional
third-party software</link>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="linuxemu-lbc-install">
<title>Installation</title>
<indexterm><primary>Ports Collection</primary></indexterm>
<para>&linux; libararies are not installed on &os; by default
and &linux; binary compatibility is not enabled by default.
&linux; libraries can be installed using the &os; Ports
Collection. Alternately, &linux; libraries can be installed
<link linkend="linuxemu-libs-manually">manually</link>.</para>
<para>Using the Ports Collection is by far the easiest way to
install &linux; libraries:</para>
<screen>&prompt.root; <userinput>cd
/usr/ports/emulators/linux_base-f10</userinput> &prompt.root; <userinput>make install distclean</userinput></screen>
<para>Once the port is installed, enable &linux; binary
compatibility by loading the <literal>linux</literal>
module. Type the following as
<username>root</username>:</para>
<screen>&prompt.root; <userinput>kldload linux</userinput></screen>
<para>In order for &linux; compatibility to always be enabled at
boot time, add the following line to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>linux_enable="YES"</programlisting>
<para>To verify that the module is loaded, use
&man.kldstat.8;:</para>
<screen>&prompt.user; <userinput>kldstat</userinput>
Id Refs Address Size Name
1 2 0xc0100000 16bdb8 kernel
7 1 0xc24db000 d000 linux.ko</screen>
<indexterm>
<primary>kernel options</primary>
<secondary>COMPAT_LINUX</secondary>
</indexterm>
<para>Users who prefer to statically link &linux; binary
compatibility into the kernel should add <literal>options
COMPAT_LINUX</literal> to the custom kernel configuration
file. Compile and install the new kernel as described in <xref
linkend="kernelconfig"/>.</para>
<sect2 id="linuxemu-libs-manually">
<title>Installing Libraries Manually</title>
<para>While using the Ports Collection is recommended, &linux;
libraries can be installed manually. The &linux; shared
libraries required by a program and the runtime linker
should be copied to <filename
class="directory">/compat/linux</filename>. Any shared
libraries opened by &linux; programs run under &os; will
look in this directory first. For example, if a &linux;
program loads <filename>/lib/libc.so</filename>, &os; will
first try to open
<filename>/compat/linux/lib/libc.so</filename>, and if that
does not exist, it will then try
<filename>/lib/libc.so</filename>. Shared libraries should
be installed to <filename
class="directory">/compat/linux/lib</filename> rather than
to the paths that the &linux; <command>ld.so</command>
reports.</para>
<para>Generally, one will need to look for the shared
libraries that &linux; binaries depend on only the first few
times that a &linux; program is installed on &os;. After a
while, there will be a sufficient set of &linux; shared
libraries on the system to be able to run newly imported
&linux; binaries without any extra work.</para>
<sect3>
<title>How to Install Additional Shared Libraries</title>
<indexterm><primary>shared libraries</primary></indexterm>
<para>If the <literal>linux_base</literal> port is installed
and an application still complains about missing shared
libraries, there are two methods <username>root</username>
can use to determine which shared libraries the &linux;
binaries need.</para>
<para>If a &linux; system is available, determine which shared
libraries the application needs, and copy them to the &os;
system.</para>
<informalexample>
<para>In this example, FTP was used to download the &linux;
binary of <application>Doom</application> on a &linux;
system . To check which shared libraries it needs, run
<command>ldd linuxdoom</command>:</para>
<screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen>
<indexterm><primary>symbolic links</primary></indexterm>
<para>Copy all the files in the last column into
<filename class="directory">/compat/linux</filename> on
the &os; system, with the names in the first column as
symbolic links pointing to them. This example will result
in the following files on the &os; system:</para>
<screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen>
<blockquote>
<note>
<para>If a &linux; shared library already exists with a
matching major revision number to the first column of
the <command>ldd</command> output, it does not need to
be copied to the file named in the last column, as the
existing library should work. It is advisable to copy
the shared library if it is a newer version, though.
The old one can be removed, as long as the symbolic
link points to the new one. For example, these
libraries exist on the system:</para>
<screen>/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen>
<para>and a binary claims to require a later version
according to the output of
<command>ldd</command>:</para>
<screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen>
<para>If it is only one or two versions out of date
in the trailing digit, do not worry about copying
<filename>/lib/libc.so.4.6.29</filename>, because
the program should work fine with the slightly older
version. However, it is safe to replace the
<filename>libc.so</filename>:</para>
<screen>/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen>
</note>
</blockquote>
<blockquote>
<note>
<para>The symbolic link mechanism is
<emphasis>only</emphasis> needed for &linux; binaries
as the &os; runtime linker takes care of looking for
matching major revision numbers.</para>
</note>
</blockquote>
</informalexample>
</sect3>
</sect2>
<sect2>
<title>Installing &linux; ELF Binaries</title>
<indexterm>
<primary>Linux</primary>
<secondary>ELF binaries</secondary>
</indexterm>
<para>ELF binaries sometimes require an extra step of
<quote>branding</quote>. If an unbranded ELF binary is
executed, it will generate an error message like the
following:</para>
<screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
ELF binary type not known
Abort</screen>
<para>To help the &os; kernel distinguish between a &os;
ELF binary and a &linux; binary, use &man.brandelf.1;:</para>
<screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
<indexterm><primary>GNU toolchain</primary></indexterm>
<para>Since the GNU toolchain places the appropriate branding
information into ELF binaries automatically, this step is
usually not necessary.</para>
</sect2>
<sect2>
<title>Installing a &linux; RPM Based Application</title>
<para>&os; uses its own package database to track all software
installed from the Ports Collection. However, the &linux; RPM
database is not supported.</para>
<para>In order to install a &linux; RPM-based application, first
install the <filename
role="package">archivers/rpm2cpio</filename> package or
port. Once installed, <username>root</username> can use this
command to install a <filename>.rpm</filename> as
follows:</para>
<screen>&prompt.root; <userinput>cd /compat/linux</userinput>
&prompt.root; <userinput>rpm2cpio -q < /path/to/linux.archive.rpm | cpio -id</userinput></screen>
<para>If necessary, <command>brandelf</command> the installed
ELF binaries, but <emphasis>not</emphasis> the libraries.
Note that this will prevent a clean uninstall.</para>
</sect2>
<sect2>
<title>Configuring the Hostname Resolver</title>
<para>If DNS does not work or this error appears:</para>
<screen>resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keyword</screen>
<para>Configure
<filename>/compat/linux/etc/host.conf</filename> as
follows:</para>
<programlisting>order hosts, bind
multi on</programlisting>
<para>This order specifies that
<filename>/etc/hosts</filename> is searched first and DNS
is searched second. When
<filename>/compat/linux/etc/host.conf</filename> does not
exist, &linux; applications use
<filename>/etc/host.conf</filename> and complain about the
incompatible &os; syntax. Remove
<literal>bind</literal> if a name server is not configured
using <filename>/etc/resolv.conf</filename>.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-mathematica">
<sect1info>
<authorgroup>
<author>
<firstname>Boris</firstname>
<surname>Hollas</surname>
<contrib>Updated for Mathematica 5.X by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Installing &mathematica;</title>
<indexterm>
<primary>applications</primary>
<secondary><application>Mathematica</application></secondary>
</indexterm>
<para>This section describes the process of installing the
&linux; version of <application>&mathematica; 5.X</application>
onto a &os; system. <application>&mathematica;</application>
is a commercial, computational software program used in
scientific, engineering, and mathematical fields. It is
available from <ulink
url="http://www.wolfram.com/mathematica/">Wolfram
Research</ulink>.</para>
<sect2>
<title>Running the &mathematica; Installer</title>
<para>First, tell &os; that
<application>&mathematica;</application>'s &linux;
binaries use the &linux; Application Binary Interface
<acronym>ABI</acronym>. The easiest way to do this is to
set the default ELF brand to &linux; for all unbranded
binaries with the command:</para>
<screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>
<para>&os; will now assume that unbranded ELF binaries
use the &linux; <acronym>ABI</acronym> which should allow the
installer to execute from the CDROM.</para>
<para>Copy the <filename>MathInstaller</filename> to the hard
drive:</para>
<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen>
<para>In this file, replace <literal>/bin/sh</literal> in
the first line with <literal>/compat/linux/bin/sh</literal>.
This ensures that the installer is executed by the &linux;
version of &man.sh.1;. Next, replace all occurrences of
<literal>Linux)</literal> with <literal>FreeBSD)</literal>
using a text editor or the script below in the next section.
This tells the <application>&mathematica;</application>
installer, to treat &os; as a &linux;-like operating
system. Invoking <command>MathInstaller</command> should now
install <application>&mathematica;</application>.</para>
</sect2>
<sect2>
<title>Modifying the &mathematica; Executables</title>
<para>The shell scripts that
<application>&mathematica;</application> created during
installation have to be modified before use. When using
<filename
class="directory">/usr/local/bin</filename> as the directory
for the <application>&mathematica;</application>
executables, symlinks in this directory will point to files
called <filename>math</filename>,
<filename>mathematica</filename>,
<filename>Mathematica</filename>, and
<filename>MathKernel</filename>. In each of these, replace
<literal>Linux)</literal> with <literal>FreeBSD)</literal>
using a text editor or the following shell script:</para>
<programlisting>#!/bin/sh
cd /usr/local/bin
for i in math mathematica Mathematica MathKernel
do sed 's/Linux)/FreeBSD)/g' $i > $i.tmp
sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp > $i
rm $i.tmp
chmod a+x $i
done</programlisting>
</sect2>
<sect2>
<title>Obtaining a &mathematica; Password</title>
<indexterm>
<primary>Ethernet</primary>
<secondary>MAC address</secondary>
</indexterm>
<para>When <application>&mathematica;</application> is started
for the first time, it will ask for a password. If a password
had not yet been obtained from Wolfram Research, run
<command>mathinfo</command> in the installation directory to
obtain the <quote>machine ID</quote>. This machine ID is
based solely on the MAC address of the first Ethernet card,
as the copy of <application>&mathematica;</application> cannot
run on different machines.</para>
<para>When registering with Wolfram Research, provide the
<quote>machine ID</quote> and they will respond with a
corresponding password consisting of groups of numbers.</para>
</sect2>
<sect2>
<title>Running the &mathematica; Frontend over a Network</title>
<para><application>&mathematica;</application> uses some special
fonts to display characters not present in any of the standard
font sets. <application>Xorg</application> requires these
fonts to be installed locally. This means that these fonts
need to be copied from the CDROM or from a host with
<application>&mathematica;</application> installed to the
local machine. These fonts are normally stored in
<filename
class="directory">/cdrom/Unix/Files/SystemFiles/Fonts</filename>
on the CDROM, or <filename
class="directory">/usr/local/mathematica/SystemFiles/Fonts</filename>
on the hard drive. The actual fonts are in the subdirectories
<filename class="directory">Type1</filename> and
<filename class="directory">X</filename>. There are several
ways to use them, as described below.</para>
<para>The first way is to copy the fonts into one of the
existing font directories in <filename
class="directory">/usr/local/lib/X11/fonts</filename> then
running &man.mkfontdir.1; within the directory containing the
new fonts.</para>
<para>The second way to do this is to copy the directories to
<filename
class="directory">/usr/local/lib/X11/fonts</filename>:</para>
<screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts</userinput>
&prompt.root; <userinput>mkdir X</userinput>
&prompt.root; <userinput>mkdir MathType1</userinput>
&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
&prompt.root; <userinput>cp X/* /usr/local/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>cp Type1/* /usr/local/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>mkfontdir</userinput>
&prompt.root; <userinput>cd ../MathType1</userinput>
&prompt.root; <userinput>mkfontdir</userinput></screen>
<para>Now add the new font directories to the font path:</para>
<screen>&prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>xset fp rehash</userinput></screen>
<para>When using the <application>&xorg;</application> server,
these font directories can be loaded automatically by adding
them to <filename>/etc/X11/xorg.conf</filename>.</para>
<indexterm><primary>fonts</primary></indexterm>
<para>If <filename
class="directory">/usr/local/lib/X11/fonts/Type1</filename>
does not already exist, change the name of the <filename
class="directory">MathType1</filename> directory in the
example above to <filename
class="directory">Type1</filename>.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-maple">
<sect1info>
<authorgroup>
<author>
<firstname>Aaron</firstname>
<surname>Kaplan</surname>
<!-- <address><email>aaron@lo-res.org</email></address>-->
<contrib>Contributed by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Robert</firstname>
<surname>Getschmann</surname>
<!-- <address><email>rob@getschmann.org</email></address>-->
<contrib>Thanks to </contrib>
</author>
</authorgroup>
</sect1info>
<title>Installing &maple;</title>
<indexterm>
<primary>applications</primary>
<secondary><application>Maple</application></secondary>
</indexterm>
<para><application>&maple;</application> is a commercial
mathematics program similar to
<application>&mathematica;</application>. This software must be
purchased and licensed from <ulink
url="http://www.maplesoft.com/products/maple/">Maplesoft</ulink>.
To install the &linux; version of this software on &os;, follow
these steps.</para>
<procedure>
<step><para>Execute the <filename>INSTALL</filename> shell
script from the product distribution. Choose the
<quote>RedHat</quote> option when prompted by the
installation program. A typical installation directory
might be <filename
class="directory">/usr/local/maple</filename>.</para></step>
<step>
<para>Copy the license to
<filename>/usr/local/maple/license/license.dat</filename>.</para>
</step>
<step>
<para>Install the <application>FLEXlm</application> license
manager by running the
<filename>INSTALL_LIC</filename> install shell script that
comes with <application>&maple;</application>. Specify
the primary hostname for the machine for the license
server.</para>
</step>
<step>
<para>Patch
<filename>/usr/local/maple/bin/maple.system.type</filename>
with the following:</para>
<programlisting> ----- snip ------------------
*** maple.system.type.orig Sun Jul 8 16:35:33 2001
--- maple.system.type Sun Jul 8 16:35:51 2001
***************
*** 72,77 ****
--- 72,78 ----
# the IBM RS/6000 AIX case
MAPLE_BIN="bin.IBM_RISC_UNIX"
;;
+ "FreeBSD"|\
"Linux")
# the Linux/x86 case
# We have two Linux implementations, one for Red Hat and
----- snip end of patch -----</programlisting>
<para>Note that no whitespace should be present after
<literal>"FreeBSD"|\</literal>.</para>
<para>This patch instructs <application>&maple;</application>
to recognize &os; as a type of &linux;
system. The <filename>bin/maple</filename> shell script
calls the <filename>bin/maple.system.type</filename> shell
script which in turn calls <command>uname -a</command> to
find out the operating system name. Depending on the OS
name it will find out which binaries to use.</para></step>
<step><para>Start the license server.</para>
<para>The following script, installed as
<filename>/usr/local/rtc/rc.d/lmgrd</filename> is a
convenient way to start up <command>lmgrd</command>:</para>
<programlisting> ----- snip ------------
#! /bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
export PATH
LICENSE_FILE=/usr/local/maple/license/license.dat
LOG=/var/log/lmgrd.log
case "$1" in
start)
lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
echo -n " lmgrd"
;;
stop)
lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
;;
*)
echo "Usage: `basename $0` {start|stop}" 1>&2
exit 64
;;
esac
exit 0
----- snip ------------</programlisting></step>
<step><para>Test that
<application>&maple;</application> starts:</para>
<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
&prompt.user; <userinput>./xmaple</userinput></screen>
<para>Once everything is working, consider writing
Maplesoft to let them know you would like a native &os;
version!</para></step>
</procedure>
<sect2>
<title>Common Pitfalls</title>
<itemizedlist>
<listitem><para><command>lmgrd</command> is known to be
picky about the license file and to dump core if there
are any problems. A correct license file should look
like this:</para>
<programlisting>#
=======================================================
# License File for UNIX Installations ("Pointer File")
# =======================================================
SERVER chillig ANY
#USE_SERVER
VENDOR maplelmg
FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
SN=XXXXXXXXX</programlisting>
<note>
<para>In this example, the serial number and key were
replaced with <literal>X</literal>.
<hostid>chillig</hostid> is the hostname.</para>
</note>
<para>Editing the license file works as long as the
<quote>FEATURE</quote> line is not edited. That line is
protected by the license key.</para></listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="linuxemu-matlab">
<sect1info>
<authorgroup>
<author>
<firstname>Dan</firstname>
<surname>Pelleg</surname>
<contrib>Contributed by </contrib>
</author>
<!-- daniel+handbook@pelleg.org -->
</authorgroup>
</sect1info>
<title>Installing &matlab;</title>
<indexterm>
<primary>applications</primary>
<secondary><application>MATLAB</application></secondary>
</indexterm>
<para>This document describes the process of installing the
&linux; version of <application>&matlab; version
6.5</application> onto a &os; system. It works quite well,
with the exception of the
<application>&java.virtual.machine;</application> which is
described further in <xref linkend="matlab-jre"/>.</para>
<para>The &linux; version of <application>&matlab;</application>
can be purchased and licensed from <ulink
url="http://www.mathworks.com/products/matlab/">
MathWorks</ulink>. Consider letting the company know that
you would like a native &os; version of this software.</para>
<sect2>
<title>Installing &matlab;</title>
<para>To install <application>&matlab;</application>:</para>
<procedure>
<step>
<para>Become <username>root</username>, as recommended by
the installation script. Insert the installation CD and
mount it. To start the installation script type:</para>
<screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen>
<tip>
<para>The installer is graphical. If it is not able to
open a display, type <command>setenv HOME
~<replaceable>USER</replaceable></command>,
where <replaceable>USER</replaceable> is the user who
ran &man.su.1;.</para>
</tip>
</step>
<step>
<para>
When asked for the <application>&matlab;</application>
root directory, type:
<userinput>/compat/linux/usr/local/matlab</userinput>.</para>
<tip>
<para>For easier typing on the rest of the installation
process, type this at the shell prompt: <command>set
MATLAB=/compat/linux/usr/local/matlab</command>.</para>
</tip>
</step>
<step>
<para>Edit the license file as instructed when obtaining
the <application>&matlab;</application> license.</para>
<tip>
<para>This file can be prepared in advance using an
editor, and copied to
<filename>$MATLAB/license.dat</filename> before the
installer asks to edit it.</para>
</tip>
</step>
<step>
<para>Complete the installation process.</para>
</step>
</procedure>
<para>At this point the <application>&matlab;</application>
installation is complete. The following steps apply
<quote>glue</quote> to connect it to the &os; system.</para>
</sect2>
<sect2>
<title>License Manager Startup</title>
<procedure>
<step>
<para>Create symlinks for the license manager
scripts:</para>
<screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput>
&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen>
</step>
<step>
<para>Create a startup file named
<filename>/usr/local/etc/rc.d/flexlm</filename>. The
example below is a modified version of the distributed
<filename>$MATLAB/etc/rc.lm.glnx86</filename>. The
changes are file locations and startup of the license
manager under &linux; emulation.</para>
<programlisting>#!/bin/sh
case "$1" in
start)
if [ -f /usr/local/etc/lmboot_TMW ]; then
/compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> && echo 'MATLAB_lmgrd'
fi
;;
stop)
if [ -f /usr/local/etc/lmdown_TMW ]; then
/compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1
fi
;;
*)
echo "Usage: $0 {start|stop}"
exit 1
;;
esac
exit 0</programlisting>
<important>
<para>The file must be made executable:</para>
<screen>&prompt.root; <userinput>chmod +x /usr/local/etc/rc.d/flexlm</userinput></screen>
<para>Replace <replaceable>username</replaceable> with the
name of a valid user on the system which is not
<username>root</username>.</para>
</important>
</step>
<step>
<para>Start the license manager with the command:</para>
<screen>&prompt.root; <userinput>service flexlm start</userinput></screen>
</step>
</procedure>
</sect2>
<sect2 id="matlab-jre">
<title>Linking the &java; Runtime Environment</title>
<para>Change the <application>&java;</application> Runtime
Environment (<acronym>JRE</acronym>) link to one working under
&os;:</para>
<screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput>
&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen>
</sect2>
<sect2>
<title>Creating a &matlab; Startup Script</title>
<procedure>
<step>
<para>Place the following startup script in
<filename
class="directory">/usr/local/bin/matlab</filename>:</para>
<programlisting>#!/bin/sh
/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting>
</step>
<step>
<para>Then, type the command
<command>chmod +x /usr/local/bin/matlab</command>.</para>
</step>
</procedure>
<tip>
<para>Depending on the version of <filename
role="package">emulators/linux_base</filename>, running
this script may result in errors. To avoid errors, edit
<filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
and change the line that says:</para>
<programlisting>if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then</programlisting>
<para>to this line:</para>
<programlisting>if test -L $newbase; then</programlisting>
</tip>
</sect2>
<sect2>
<title>Creating a &matlab; Shutdown Script</title>
<para>The following is needed to solve a problem with &matlab;
not exiting correctly.</para>
<procedure>
<step>
<para>Create
<filename>$MATLAB/toolbox/local/finish.m</filename>
containing the single line:</para>
<programlisting>! $MATLAB/bin/finish.sh</programlisting>
<note><para>The <literal>$MATLAB</literal> is
literal.</para></note>
<tip>
<para>The same directory contains
<filename>finishsav.m</filename> and
<filename>finishdlg.m</filename>, which allow the
workspace to be saved before quitting. If either file
is used, insert the line above immediately after the
<literal>save</literal> command.</para></tip>
</step>
<step>
<para>Create
<filename>$MATLAB/bin/finish.sh</filename> which
contains the following:</para>
<programlisting>#!/compat/linux/bin/sh
(sleep 5; killall -1 matlab_helper) &
exit 0</programlisting>
</step>
<step>
<para>Make the file executable:</para>
<screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen>
</step>
</procedure>
</sect2>
<sect2 id="matlab-using">
<title>Using &matlab;</title>
<para>At this point, <command>matlab</command> is ready for
use.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-oracle">
<sect1info>
<authorgroup>
<author>
<firstname>Marcel</firstname>
<surname>Moolenaar</surname>
<contrib>Contributed by </contrib>
</author>
<!-- marcel@cup.hp.com -->
</authorgroup>
</sect1info>
<title>Installing &oracle;</title>
<indexterm>
<primary>applications</primary>
<secondary><application>Oracle</application></secondary>
</indexterm>
<para>This document describes the process of installing
<application>&oracle; 8.0.5</application> and
<application>&oracle; 8.0.5.1 Enterprise Edition</application>
for &linux; onto a &os; machine.</para>
<sect2>
<title>Installing the &linux; Environment</title>
<para>Make sure <filename
role='package'>emulators/linux_base</filename>
has been installed from the Ports Collection.</para>
<para>To run the intelligent agent, install the Red Hat Tcl
package: <filename>tcl-8.0.3-20.i386.rpm</filename>. The
general command for installing RPMs with the <filename
role='package'>archivers/rpm</filename> port is:</para>
<screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
<para>This command should not generate any errors.</para>
</sect2>
<sect2>
<title>Creating the &oracle; Environment</title>
<para>Before installing <application>&oracle;</application>, set
up a proper environment. This section only describes how to
install <application>&oracle;</application> for &linux; on
&os;, not what has been described in the
<application>&oracle;</application> installation guide.</para>
<sect3 id="linuxemu-kernel-tuning">
<title>Kernel Tuning</title>
<indexterm><primary>kernel tuning</primary></indexterm>
<para>As described in the <application>&oracle;</application>
installation guide, the maximum size of shared memory needs
to be set. Do not use <literal>SHMMAX</literal> under &os;
as it is calculated from <literal>SHMMAXPGS</literal> and
<literal>PGSIZE</literal>. Therefore, define
<literal>SHMMAXPGS</literal>. All other options can be
used as described in the guide. For example:</para>
<programlisting>options SHMMAXPGS=10000
options SHMMNI=100
options SHMSEG=10
options SEMMNS=200
options SEMMNI=70
options SEMMSL=61</programlisting>
<para>Set these options to suit the intended use of
<application>&oracle;</application>.</para>
<para>Also, make sure the following options are in the
kernel configuration file:</para>
<programlisting>options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communication</programlisting>
</sect3>
<sect3 id="linuxemu-oracle-account">
<title>&oracle; Account</title>
<para>Create a user account to be used as the
<username>oracle</username> account. Add
<literal>/compat/linux/bin/bash</literal> to
<filename>/etc/shells</filename> and set the shell for
the <username>oracle</username> account to
<filename>/compat/linux/bin/bash</filename>.</para>
</sect3>
<sect3 id="linuxemu-environment">
<title>Environment</title>
<para>Besides the normal <application>&oracle;</application>
variables, such as <envar>ORACLE_HOME</envar> and
<envar>ORACLE_SID</envar> set the following
environment variables:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Value</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>LD_LIBRARY_PATH</envar></entry>
<entry><literal>$ORACLE_HOME/lib</literal></entry>
</row>
<row>
<entry><envar>CLASSPATH</envar></entry>
<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
</row>
<row>
<entry><envar>PATH</envar></entry>
<entry><literal>/compat/linux/bin
/compat/linux/sbin
/compat/linux/usr/bin
/compat/linux/usr/sbin
/bin
/sbin
/usr/bin
/usr/sbin
/usr/local/bin
$ORACLE_HOME/bin</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>It is advised to set all the environment variables in
<filename>~/.profile</filename> as follows:</para>
<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
ORACLE_HOME=/oracle; export ORACLE_HOME
LD_LIBRARY_PATH=$ORACLE_HOME/lib
export LD_LIBRARY_PATH
ORACLE_SID=ORCL; export ORACLE_SID
ORACLE_TERM=386x; export ORACLE_TERM
CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
export CLASSPATH
PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
export PATH</programlisting>
</sect3>
</sect2>
<sect2>
<title>Installing &oracle;</title>
<para>Before starting the installer, create a directory named
<filename class="directory">/var/tmp/.oracle</filename> which
is owned by the <username>oracle</username> user. The
installation of <application>&oracle;</application> should
work without any problems. If errors are encountered, check
the <application>&oracle;</application> distribution and
configuration. Once <application>&oracle;</application> is
installed, apply the patches described in the next two
subsections.</para>
<para>A frequent error is that the TCP protocol adapter is not
installed correctly. As a consequence, no TCP listeners can
be started. The following actions help to solve this
problem:</para>
<screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>
<para>Do not forget to run <filename>root.sh</filename>
again.</para>
<sect3 id="linuxemu-patch-root">
<title>Patching <filename>root.sh</filename></title>
<para>When installing <application>&oracle;</application>,
some actions, which need to be performed as
<username>root</username>, are recorded in a shell script
called <filename>root.sh</filename>. This script is
found in <filename class="directory">orainst</filename>.
Apply the following patch to <filename>root.sh</filename>
so that it can find the &os; location of
<command>chown</command>. Alternatively, run the script
under a &linux; native shell.</para>
<programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
--- orainst/root.sh Mon Dec 28 15:58:53 1998
***************
*** 31,37 ****
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/bin/chown
#
# Define variables to be used in this script
--- 31,37 ----
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/usr/sbin/chown
#
# Define variables to be used in this script</programlisting>
<para>If <application>&oracle;</application> is not installed
from CD, patch the source for <filename>root.sh</filename>.
It is called <filename>rthd.sh</filename> and is located in
<filename class="directory">orainst</filename> in the source
tree.</para>
</sect3>
<sect3 id="linuxemu-patch-tcl">
<title>Patching <filename>genclntsh</filename></title>
<para>The script <command>genclntsh</command> is used to
create a single shared client library when building the
demos. Apply the following patch to comment out the
definition of <envar>PATH</envar>:</para>
<programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
--- bin/genclntsh Tue Dec 22 15:36:49 1998
***************
*** 32,38 ****
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! PATH=/usr/local/bin:/bin:/usr/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst
--- 32,38 ----
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! #PATH=/usr/local/bin:/bin:/usr/bin: export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
</sect3>
</sect2>
<sect2>
<title>Running &oracle;</title>
<para>After following these instructions,
<application>&oracle;</application> should run as if it was
running on &linux;.</para>
</sect2>
</sect1>
<sect1 id="linuxemu-advanced">
<title>Advanced Topics</title>
<para>This section describes how &linux; binary compatibility
works and is based on an email written to &a.chat; by
Terry Lambert <email>tlambert@primenet.com</email> (Message ID:
<literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para>
<indexterm><primary>execution class loader</primary></indexterm>
<para>&os; has an abstraction called an <quote>execution class
loader</quote>. This is a wedge into the &man.execve.2;
system call.</para>
<para>Historically, the &unix; loader examined the magic number
(generally the first 4 or 8 bytes of the file) to see if it was
a binary known to the system, and if so, invoked the binary
loader.</para>
<para>If it was not the binary type for the system, the
&man.execve.2; call returned a failure, and the shell
attempted to start executing it as shell commands. The
assumption was a default of <quote>whatever the current shell
is</quote>.</para>
<para>Later, a hack was made for &man.sh.1; to examine the first
two characters, and if they were <literal>:\n</literal>, it
invoked the &man.csh.1; shell instead.</para>
<para>&os; has a list of loaders, instead of a single loader, with
a fallback to the <literal>#!</literal> loader for running shell
interpreters or shell scripts.</para>
<indexterm><primary>ELF</primary></indexterm>
<indexterm><primary>Solaris</primary></indexterm>
<para>For the &linux; <acronym>ABI</acronym> support, &os; sees
the magic number as an ELF binary. The ELF loader looks for a
specialized <emphasis>brand</emphasis>, which is a comment
section in the ELF image, and which is not present on
SVR4/&solaris; ELF binaries.</para>
<para>For &linux; binaries to function, they must be
<emphasis>branded</emphasis> as type <literal>Linux</literal>
using &man.brandelf.1;:</para>
<screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
<indexterm>
<primary>ELF</primary>
<secondary>branding</secondary>
</indexterm>
<para>When the ELF loader sees the <literal>Linux</literal>
brand, the loader replaces a pointer in the
<literal>proc</literal> structure. All system calls are
indexed through this pointer. In addition, the process is
flagged for special handling of the trap vector for the signal
trampoline code, and several other (minor) fix-ups that are
handled by the &linux; kernel module.</para>
<para>The &linux; system call vector contains, among other
things, a list of <literal>sysent[]</literal> entries whose
addresses reside in the kernel module.</para>
<para>When a system call is called by the &linux; binary, the
trap code dereferences the system call function pointer off
the <literal>proc</literal> structure, and gets the &linux;,
not the &os;, system call entry points.</para>
<para>&linux; mode dynamically <emphasis>reroots</emphasis>
lookups. This is, in effect, equivalent to the
<option>union</option> option to file system mounts. First,
an attempt is made to lookup the file in <filename
class="directory">/compat/linux/<replaceable>original-path</replaceable></filename>.
If that fails, the lookup is done in
<filename
class="directory">/<replaceable>original-path</replaceable></filename>.
This makes sure that binaries that require other binaries can
run. For example, the &linux; toolchain can all run under
&linux; <acronym>ABI</acronym> support. It also means that
the &linux; binaries can load and execute &os; binaries, if
there are no corresponding &linux; binaries present, and that
a &man.uname.1; command can be placed in the
<filename class="directory">/compat/linux</filename> directory
tree to ensure that the &linux; binaries can not tell they are
not running on &linux;.</para>
<para>In effect, there is a &linux; kernel in the &os; kernel.
The various underlying functions that implement all of the
services provided by the kernel are identical to both the
&os; system call table entries, and the &linux; system call
table entries: file system operations, virtual memory
operations, signal delivery, and System V IPC. The only
difference is that &os; binaries get the &os;
<emphasis>glue</emphasis> functions, and &linux; binaries get
the &linux; <emphasis>glue</emphasis> functions. The &os;
<emphasis>glue</emphasis> functions are statically linked into
the kernel, and the &linux; <emphasis>glue</emphasis>
functions can be statically linked, or they can be accessed
via a kernel module.</para>
<para>Technically, this is not really emulation, it is an
<acronym>ABI</acronym> implementation. It is sometimes called
<quote>&linux; emulation</quote> because the implementation
was done at a time when there was no other word to describe
what was going on. Saying that &os; ran &linux; binaries was
not true, since the code was not compiled in.</para>
</sect1>
</chapter>