doc/en/handbook/linuxemu/chapter.sgml

    <chapter id="linuxemu">
      <title>Linux Emulation</title>
      
      <para><emphasis>Contributed by &a.handy; and &a.rich;</emphasis></para>
      
      
      <sect1>
	<title>How to Install the Linux Emulator</title>
	
	<para>Linux emulation in FreeBSD has reached a point where it is
	  possible to run a large fraction of Linux binaries in both a.out and
	  ELF format. The linux emulation in the 2.1-STABLE branch is capable
	  of running Linux DOOM and Mathematica; the version present in
	  &rel.current;-RELEASE is vastly more capable and runs all these as
	  well as Quake, Abuse, IDL, netrek for Linux and a whole host of
	  other programs.</para>
	
	<para>There are some Linux-specific operating system features that are
	  not supported on FreeBSD. Linux binaries will not work on FreeBSD
	  if they use the Linux <filename>/proc</filename> filesystem (which
	  is different from the optional FreeBSD <filename>/proc</filename>
	  filesystem) or i386-specific calls, such as enabling virtual 8086
	  mode.</para>
	
	<para>Depending on which version of FreeBSD you are running, how you
	  get  Linux-emulation up will vary slightly:</para>
	
	
	<sect2>
	  <title>Installing Linux Emulation in 2.1-STABLE</title>
	  
	  <para>The <filename>GENERIC</filename> kernel in 2.1-STABLE is not
	    configured for linux compatibility so you must reconfigure your
	    kernel for it. There are two ways to do this: 1. linking the
	    emulator statically in the kernel itself and 2. configuring your
	    kernel to dynamically load the linux loadable kernel module
	    (LKM).</para>
	  
	  <para>To enable the emulator, add the following to your
	    configuration file (c.f.
	    <filename>/sys/i386/conf/LINT</filename>):</para>

	    <programlisting>
options COMPAT_LINUX</programlisting>

	  <para>If you want to run doom or other applications
	    that need shared memory, also add the following.</para>

	    <programlisting>
options SYSVSHM</programlisting>

	  <para>The linux system calls require 4.3BSD system
	    call compatibility. So make sure you have the following.</para>

	    <programlisting>
options "COMPAT_43"</programlisting>
	  
	  <para>If you prefer to statically link the emulator in the kernel
	    rather than use the loadable kernel module (LKM), then add</para>

	    <programlisting>
options  LINUX</programlisting>

	  <para>Then run config and install the new kernel as
	    described in the
	    <link linkend="kernelconfig">kernel configuration</link>
	    section.</para>
	  
	  <para>If you decide to use the LKM you must also install the
	    loadable module. A mismatch of versions between the kernel and
	    loadable module can cause the kernel to crash, so the safest thing
	    to do is to reinstall the LKM when you install the kernel.</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>cd /usr/src/lkm/linux</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
	    </informalexample>

	  <para>Once you have installed the kernel and the LKM,
	    you can invoke `linux' as root to load the LKM.</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>linux</userinput>
Linux emulator installed
Module loaded as ID 0</screen>
	    </informalexample>

	  <para>To see whether the LKM is loaded, run
	    <command>modstat</command>.</para>
	  
	    <informalexample>
	      <screen>&prompt.user; modstat
Type     Id Off Loadaddr Size Info     Rev
Module Name EXEC      0   3 f0baf000 0018 f0bb4000   1 linux_emulator</screen>
	    </informalexample>

	  <para>You can cause the LKM to be loaded when the
	    system boots in either of two ways. In FreeBSD 2.2.1-RELEASE and
	    2.1-STABLE enable it in <filename>/etc/sysconfig</filename>

	    <programlisting>
linux=YES</programlisting> by changing it from NO to YES. FreeBSD 2.1
	    RELEASE and earlier do not have such a line and on those you will
	    need to edit <filename>/etc/rc.local</filename> to add the following line.</para>

	    <programlisting>
linux</programlisting>
	  
	</sect2>
	
	<sect2>
	  <title>Installing Linux Emulation in 2.2.2-RELEASE and later</title>
	  
	  <para>It is no longer necessary to specify <literal>options LINUX</literal> or
	    <literal>options COMPAT_LINUX</literal>. Linux emulation is done with an LKM
	    (&ldquo;Loadable Kernel Module&rdquo;) so it can be installed on the fly
	    without having to reboot. You will need the following things in
	    your startup files, however:</para>
	    <orderedlist>
	      
	      <listitem>
		<para>In <filename>/etc/rc.conf</filename>, you need the
		  following line:</para>

		  <programlisting>
linux_enable=YES</programlisting>
	      </listitem>
	      
	      <listitem>
		<para>This, in turn, triggers the following action in
		  <filename>/etc/rc.i386</filename>:</para>

		  <programlisting>
# Start the Linux binary emulation if requested.
if [ "X${linux_enable}" = X"YES" ]; then echo -n '
        linux';               linux &gt; /dev/null 2&gt;&amp;1
fi</programlisting>
	      </listitem>
	      
	    </orderedlist>

	  
	  <para>If you want to verify it is running, modstat will do that:</para>

	    <informalexample>
	      <screen>&prompt.user; modstat
Type     Id Off Loadaddr Size Info     Rev Module Name
EXEC      0   4 f09e6000 001c f09ec010   1 linux_mod</screen>
	    </informalexample>

	  <para>However, there have been reports that this
	    fails on some 2.2-RELEASE and later systems. If for some reason
	    you cannot load the linux LKM, then statically link the emulator
	    in the kernel by adding

	    <programlisting>
options  LINUX</programlisting>

	    to your kernel config file. Then run config
	    and install the new kernel as described in the <link
	      linkend="kernelconfig">kernel configuration</link> section.</para>
	  
	</sect2>
	
	<sect2>
	  <title>Installing Linux Runtime Libraries</title>
	  
	  
	  <sect3>
	    <title>Installing using the linux_lib port</title>
	    
	    <para>Most linux applications use shared libraries, so you are
	      still not done until you install the shared libraries. It is
	      possible to do this by hand, however, it is vastly simpler to
	      just grab the linux_lib port:</para>

	      <informalexample>
		<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_lib</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
	      </informalexample>
	    
	    <para>and you should have a working linux emulator. Legend (and
	      the mail archives <!-- smiley -->:-) seems to hold that Linux emulation works
	      best with linux binaries linked against the ZMAGIC libraries;
	      QMAGIC libraries (such as those used in Slackware V2.0) may tend
	      to give the Linuxulator heartburn. Also, expect some programs to complain
	      about incorrect minor versions of the system libraries. In
	  general, however, this does not seem
	      to be a problem.</para>
	    
	  </sect3>
	  
	  <sect3>
	    <title>Installing libraries manually</title>
	    
	    <para>If you do not have the &ldquo;ports&rdquo; distribution, you can
	      install the libraries by hand instead. You will need the Linux
	      shared libraries that the program depends on and the runtime
	      linker. Also, you will need to create a "shadow root"
	      directory, <filename>/compat/linux</filename>, for Linux
	      libraries on your FreeBSD system. Any shared libraries opened
	      by Linux programs run under FreeBSD will look in this tree
	      first. So, if a Linux program loads, for example,
	      <filename>/lib/libc.so</filename>, FreeBSD will first try to
	      open <filename>/compat/linux/lib/libc.so</filename>, and if that
	      does not exist then it will try
	      <filename>/lib/libc.so</filename>. Shared libraries should be
	      installed in the shadow tree
	      <filename>/compat/linux/lib</filename> rather than the paths
	      that the Linux <command>ld.so</command> reports.</para>
	    
	    <para>FreeBSD-2.2-RELEASE and later works slightly differently
	      with respect to <filename>/compat/linux</filename>: all files, not just
	      libraries, are searched for from the &ldquo;shadow root&rdquo;
	      <filename>/compat/linux</filename>.</para>
	    
	    <para>Generally, you will need to look for the shared libraries
	      that Linux  binaries depend on only the first few times that you
	      install a Linux  program on your FreeBSD system. After a while,
	      you will have a sufficient set of Linux shared libraries on your
	      system to be able to run newly  imported Linux binaries without
	      any extra work.</para>
	    
	  </sect3>
	  
	  <sect3>
	    <title>How to install additional shared libraries</title>
	    
	    <para>What if you install the <filename>linux_lib</filename> port and your application
	      still complains about missing shared libraries? How do you know
	      which shared libraries Linux binaries need, and where to get
	      them? Basically, there are 2 possibilities (when following these
	      instructions: you will need to be root on your FreeBSD system to
	      do the necessary installation steps).</para>
	    
	    <para>If you have access to a Linux system, see what shared
	      libraries the application needs, and copy them to your FreeBSD system.
	      Example: you have just ftp'ed the Linux binary of Doom. Put it
	      on the Linux system you have access to, and check which shared
	      libraries it needs by running <command>ldd linuxxdoom</command>:</para>
	    
	    
	      <informalexample>
		<screen>&prompt.user; <userinput>ldd linuxxdoom</userinput>
libXt.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
	      </informalexample>
	    
	    <para>You would need to get all the files from the last column,
	      and put them under <filename>/compat/linux</filename>, with the
	      names in the first column as symbolic links pointing to them.
	      This means you eventually have these files on your FreeBSD
	      system:</para>
	      
	      <informalexample>
		<screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -&gt; libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
	      </informalexample>

	    <note>
	      <para>Note that if you already have a Linux shared library with
		a matching major revision number to the first column of the
		<command>ldd</command> output, you will not need to copy the file named in the
		last column to your system, the one you already have should
		work. It is advisable to copy the shared library anyway if it
		is a newer version, though. You can remove the old one, as
		long as you make the symbolic link point to the new one. So,
		if you have these libraries on your system:</para>

		<informalexample>
		  <screen>/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>
		</informalexample>
	    
	      <para>and you find a new binary that claims to require a later
		version according to the output of <command>ldd</command>:</para>

		<informalexample>
		  <screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
		</informalexample>

	      <para>If it is only one or two versions out of date in the in
		the trailing digit then do not worry about copying
		<filename>/lib/libc.so.4.6.29</filename> too, because the
		program should work fine with the slightly older version.
		However, if you like you can decide to replace the
		<filename>libc.so</filename> anyway, and that should leave you
		with:</para>

		<informalexample>
		  <screen>/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
		</informalexample>
	    </note>

	    <note>
	      <para>The symbolic link mechanism is <emphasis>only</emphasis>
		needed for Linux binaries. The FreeBSD runtime linker takes
		care of looking for matching major revision numbers itself and
		you do not need to worry about it.</para>
	    </note>
	  </sect3>
	  
	  <sect3>
	    <title>Configuring the <filename>ld.so</filename> &mdash; for FreeBSD
	      2.2-RELEASE and later</title>
	    
	    <para>This section applies only to FreeBSD 2.2-RELEASE and later.
	      Those running 2.1-STABLE should skip this section.</para>
	    
	    <para>Finally, if you run FreeBSD 2.2-RELEASE you must make sure
	      that you have the Linux runtime linker and its config files on
	      your system. You should copy these files from the Linux system
	      to their appropriate place on your FreeBSD system (to the
	      <filename>/compat/linux</filename> tree):</para>

	      <informalexample>
		<screen>/compat/linux/lib/ld.so
/compat/linux/etc/ld.so.config</screen>
	      </informalexample>
	    
	    <para>If you do not have access to a Linux system, you should get
	      the extra files you need from various ftp sites. Information on
	      where to look for the various files is appended below. For now,
	      let us assume you know where to get the files.</para>
	    
	    <para>Retrieve the following files (all from the same ftp site to
	      avoid any version mismatches), and install them under
	      <filename>/compat/linux</filename> (i.e.
	      <filename>/foo/bar</filename> is installed as
	      <filename>/compat/linux/foo/bar</filename>):</para>

	      <informalexample>
		<screen>/sbin/ldconfig
/usr/bin/ldd
/lib/libc.so.x.y.z
/lib/ld.so</screen>
	      </informalexample>
	    
	    <para><command>ldconfig</command> and <command>ldd</command> do not necessarily need to be under
	      <filename>/compat/linux</filename>; you can install them
	      elsewhere in the system too. Just make sure they do not conflict
	      with their FreeBSD counterparts. A good idea would be to install
	      them in <filename>/usr/local/bin</filename> as <command>ldconfig-linux</command>
	      and <command>ldd-linux</command>.</para>
	    
	    <para>Create the file
	      <filename>/compat/linux/etc/ld.so.conf</filename>, containing
	      the directories in which the Linux runtime linker should look
	      for shared libs. It is a plain text file, containing a directory
	      name on each line. <filename>/lib</filename> and
	      <filename>/usr/lib</filename> are standard, you could add the
	      following:</para>

	      <programlisting>
/usr/X11/lib
/usr/local/lib</programlisting>
	    
	    <para>When a linux binary opens a library such as
	      <filename>/lib/libc.so</filename> the emulator maps the name to
	      <filename>/compat/linux/lib/libc.so</filename> internally. All
	      linux libraries should be installed under /compat/linux (e.g.
	      <filename>/compat/linux/lib/libc.so</filename>,
	      <filename>/compat/linux/usr/X11/lib/libX11.so</filename>, etc.)
	      in order for the emulator to find them.</para>
	    
	    <para>Those running FreeBSD 2.2-RELEASE should run the Linux
	      ldconfig program.</para>

	      <informalexample>
		<screen>&prompt.root <userinput>cd /compat/linux/lib</userinput>
&prompt.root; <userinput>/compat/linux/sbin/ldconfig</userinput>
		</screen>
	      </informalexample>
	    
	    <para><command>ldconfig</command> is statically linked, so it does not need any
	      shared libraries to run. It creates the file
	      <filename>/compat/linux/etc/ld.so.cache</filename> which
	      contains the names of all the shared libraries and should be
	      rerun to recreate this file whenever you install additional
	      shared libraries.</para>
	    
	    <para>On 2.1-STABLE do not install
	      <filename>/compat/linux/etc/ld.so.cache</filename> or run
	      <command>ldconfig</command>; in 2.1-STABLE the syscalls are implemented differently
	      and <command>ldconfig</command> is not needed or used.</para>
	    
	    <para>You should now be set up for Linux binaries which only need
	      a shared libc. You can test this by running the Linux <command>ldd</command> on
	      itself. Supposing that you have it installed as <command>ldd-linux</command>, it
	      should produce something like:</para>

	      <informalexample>
		<screen>&prompt.root; <userinput>ldd-linux `which ldd-linux`</userinput>
libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
	      </informalexample>
	    
	    <para>This being done, you are ready to install new Linux
	      binaries. Whenever you install a new Linux program, you should
	      check if it needs shared libraries, and if so, whether you have
	      them installed in the <filename>/compat/linux</filename> tree.
	      To do this, you run the Linux version <command>ldd</command> on the new program,
	      and watch its output. <command>ldd</command> (see also the manual page for <citerefentry><refentrytitle>ldd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
	      will print a list of shared libraries that the program depends
	      on, in the form <literal><replaceable>majorname</replaceable> (<replaceable>jumpversion</replaceable>) =&gt; <replaceable>fullname</replaceable></literal>.</para>
	    
	    <para>If it prints <literal>not found</literal> instead of <replaceable>fullname</replaceable> it means that
	      you need an extra library. The library needed is shown in
	      majorname and will be of the form <literal>lib<replaceable>XXXX</replaceable>.so.<replaceable>N</replaceable></literal>. You will need to
	      find a <filename>lib<replaceable>XXXX</replaceable>.so.N.mm</filename> on a Linux ftp site, and install it on
	      your system. The <replaceable>XXXX</replaceable> (name) and <replaceable>N</replaceable> (major revision number)
	      should match; the minor number(s) <replaceable>mm</replaceable> are less important, though
	      it is advised to take the most recent version.</para>
	    
	  </sect3>
	</sect2>

    <sect2>
      <title>Installing Linux ELF binaries</title>

      <para>ELF binaries sometimes require an extra step of
	&ldquo;branding&rdquo;. If you attempt to run an unbranded ELF binary,
	you will get an error message like the following;</para>

      <informalexample>
	<screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
ELF binary type not known
Abort</screen>
      </informalexample>

      <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
	binary from a Linux one, use the <citerefentry>
	  <refentrytitle>brandelf</refentrytitle>
	  <manvolnum>1</manvolnum>
	</citerefentry> utility.</para>

      <informalexample>
	<screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
      </informalexample>

      <para>The GNU toolchain now places the appropriate branding information
	into ELF binaries automatically, so you should be needing to do this
	step increasingly rarely in future.</para>
    </sect2>
    
	<sect2>
	  <title>Configuring the host name resolver</title>
	  
	  <para>If DNS does not work or you get the messages

	    <informalexample>
	      <screen>resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keyword</screen>
	    </informalexample>
	  
	  then you need to configure a
	    <filename>/compat/linux/etc/host.conf</filename> file containing:

	    <programlisting>
order hosts, bind
multi on</programlisting>
	  
	  where the order here specifies that
	    <filename>/etc/hosts</filename> is searched first and DNS is
	    searched second. When
	    <filename>/compat/linux/etc/host.conf</filename> is not installed
	    linux applications find FreeBSD's
	    <filename>/etc/host.conf</filename> and complain about the
	    incompatible FreeBSD syntax. You should remove <literal>bind</literal> if you
	    have not configured a name-server using the
	    <filename>/etc/resolv.conf</filename> file.</para>
	  
	  <para>Lastly, those who run 2.1-STABLE need to set an the
	    <envar>RESOLV_HOST_CONF</envar> environment variable so that applications will
	    know how to search the host tables. If you run FreeBSD
	    2.2-RELEASE or later, you can skip this. For the
	    <filename>/bin/csh</filename> shell use:</para>

	    <informalexample>
	      <screen>&prompt.user; <userinput>setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf</userinput></screen>
	    </informalexample>
	  
	  <para>For <filename>/bin/sh</filename> use:</para>

	    <informalexample>
	      <screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen>
	    </informalexample>
	  
	</sect2>
	
	<sect2>
	  <title>Finding the necessary files</title>

	  <note>
	    <para>The information below is valid as of the time this document
	      was written, but certain details such as names of ftp sites,
	      directories and distribution names may have changed by the time
	      you read this.</para>
	  </note>
	  
	  <para>Linux is distributed by several groups that make their own set
	    of binaries that they distribute. Each distribution has its own
	    name, like &ldquo;Slackware&rdquo; or &ldquo;Yggdrasil&rdquo;. The distributions are
	    available on a lot of ftp sites. Sometimes the files are unpacked,
	    and you can get the individual files you need, but mostly they are
	    stored in distribution sets, usually consisting of subdirectories
	    with gzipped tar files in them. The primary ftp sites for the
	    distributions are:</para>

	    <orderedlist>
	      <listitem>
		<para>sunsite.unc.edu:/pub/Linux/distributions</para>
	      </listitem>

	      <listitem>
		<para>tsx-11.mit.edu:/pub/linux/distributions</para>
	      </listitem>
	    </orderedlist>
	  
	  <para>Some European mirrors:</para>

	    <orderedlist>
	      <listitem>
		<para>ftp.luth.se:/pub/linux/distributions</para>
	      </listitem>

	      <listitem>
		<para>ftp.demon.co.uk:/pub/unix/linux</para>
	      </listitem>

	      <listitem>
		<para>src.doc.ic.ac.uk:/packages/linux/distributions</para>
	      </listitem>
	    </orderedlist>
	  
	  
	  <para>For simplicity, let us concentrate on Slackware here. This
	    distribution consists of a number of subdirectories, containing
	    separate packages. Normally, they are controlled by an install
	    program, but you can retrieve files &ldquo;by hand&rdquo; too. First of all,
	    you will need to look in the <filename>contents</filename> subdir of the
	    distribution. You will find a lot of small text files here
	    describing the contents of the separate packages. The fastest way
	    to look something up is to retrieve all the files in the contents
	    subdirectory, and grep through them for the file you need. Here is
	    an example of a list of files that you might need, and in which
	    contents-file you will find it by grepping through them:</para>

	    <informaltable frame="none">
	      <tgroup cols="2">
		<thead>
		  <row>
		    <entry>Library</entry>
		    <entry>Package</entry>
		  </row>
		</thead>

		<tbody>
		  <row><entry><filename>ld.so</filename> </entry><entry>ldso
		    </entry></row>
		  <row><entry><filename>ldconfig</filename>
		    </entry><entry>ldso </entry></row>
		  <row><entry><filename>ldd</filename> </entry><entry>ldso
		    </entry></row>
		  <row><entry><filename>libc.so.4</filename>
		    </entry><entry>shlibs </entry></row>
		  <row><entry><filename>libX11.so.6.0</filename>
		    </entry><entry>xf_lib
		    </entry></row>
		  <row><entry><filename>libXt.so.6.0</filename>
		    </entry><entry>xf_lib
		    </entry></row>
		  <row><entry><filename>libX11.so.3</filename>
		    </entry><entry>oldlibs
		    </entry></row>
		  <row><entry><filename>libXt.so.3</filename>
		    </entry><entry>oldlibs
		    </entry></row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  
	  <para>So, in this case, you will need the packages ldso, shlibs,
	    xf_lib and oldlibs. In each of the contents-files for these
	    packages, look for a line saying <literal>PACKAGE LOCATION</literal>, it will
	    tell you on which &ldquo;disk&rdquo; the package is, in our case it will tell
	    us in which subdirectory we need to look. For our example, we
	    would find the following locations:</para>

	    <informaltable frame="none">
	      <tgroup cols="2">
		<thead
		  <row>
		    <entry>Package</entry>
		    <entry>Location</entry>
		  </row>
		</thead>
		
		<tbody>
		  <row><entry>ldso </entry><entry>diska2 </entry></row>
		  <row><entry>shlibs </entry><entry>diska2 </entry></row>
		  <row><entry>oldlibs </entry><entry>diskx6 </entry></row>
		  <row><entry>xf_lib </entry><entry>diskx9 </entry></row>
		</tbody>
	      </tgroup>
	    </informaltable>
	  
	  <para>The locations called &ldquo;disk<replaceable>XX</replaceable>&rdquo; refer to the <filename>slakware/<replaceable>XX</replaceable></filename>
	    subdirectories of the distribution, others may be found in the
	    <filename>contrib</filename> subdirectory. In this case, we
	    could now retrieve the packages we need by retrieving the
	    following files (relative to the root of the Slackware
	    distribution tree):</para>
	  
	    <itemizedlist>
	      <listitem>
		<para><filename>slakware/a2/ldso.tgz</filename></para>
	      </listitem>

	      <listitem>
		<para><filename>slakware/a2/shlibs.tgz</filename></para>
	      </listitem>

	      <listitem>
		<para><filename>slakware/x6/oldlibs/tgz</filename></para>
	      </listitem>

	      <listitem>
		<para><filename>slakware/x9/xf_lib.tgz</filename></para>
	      </listitem>
	    </itemizedlist>
	  
	  
	  <para>Extract the files from these gzipped tarfiles in your
	    <filename>/compat/linux</filename> directory (possibly omitting or
	    afterwards removing files you do not need), and you are
	    done.</para>
	  
	  <para><emphasis>See also:</emphasis>
	    <filename>ftp.freebsd.org:pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README</filename> and <filename>/usr/src/sys/i386/ibcs2/README.iBCS2</filename></para>
	  
	</sect2>
      </sect1>
      
      <sect1 id="mathematica">
	<title>How to Install Mathematica on FreeBSD</title>
	
	<para><emphasis>Contributed by &a.rich; and
	    &a.chuck;</emphasis></para>
	
	<para>This document shows how to install the Linux binary distribution
	  of Mathematica 2.2 on FreeBSD 2.1.</para>
	
	<para>Mathematica supports Linux but not FreeBSD as it stands. So
	  once you have configured your system for Linux compatibility you
	  have most of what you need to run Mathematica.</para>
	
	<para>For those who already have the student edition of Mathematica
	  for DOS the cost of upgrading to the Linux version at the time this
	  was written, March 1996, was &#36;45.00. It can be ordered directly
	  from Wolfram at (217) 398-6500 and paid for by credit card.</para>
	
	
	<sect2>
	  <title>Unpacking the Mathematica distribution</title>
	  
	  <para>The binaries are currently distributed by Wolfram on CDROM.
	    The CDROM has about a dozen tar files, each of which is a binary
	    distribution for one of the supported architectures. The one for
	    Linux is named <filename>LINUX.TAR</filename>. You can, for
	    example, unpack this into
	    <filename>/usr/local/Mathematica</filename>:</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>cd /usr/local</userinput>
&prompt.root; <userinput>mkdir Mathematica</userinput>
&prompt.root; <userinput>cd Mathematica</userinput>
&prompt.root; <userinput>tar -xvf /cdrom/LINUX.TAR</userinput></screen>
	    </informalexample>
	  
	</sect2>
	
	<sect2>
	  <title>Obtaining your Mathematica Password</title>
	  
	  <para>Before you can run Mathematica you will have to obtain a
	    password from Wolfram that corresponds to your &ldquo;machine
	    ID&rdquo;.</para>
	  
	  <para>Once you have installed the linux compatibility runtime
	    libraries and unpacked the mathematica you can obtain the &ldquo;machine
	      ID&rdquo; by running the program <command>mathinfo</command> in the Install directory.</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput>
&prompt.root; <userinput>mathinfo</userinput>
LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented
richc.isdn.bcm.tmc.edu   9845-03452-90255</screen>
	    </informalexample>

	  <para>So, for example, the &ldquo;machine ID&rdquo; of <hostid>richc</hostid> is
	    <literal>9845-03452-90255</literal>. You can ignore the message about the ioctl
	    that is not implemented. It will not prevent Mathematica from
	    running in any way and you can safely ignore it, though you will
	    see the message every time you run Mathematica.</para>
	  
	  <para>When you register with Wolfram, either by email, phone or fax,
	    you will give them the &ldquo;machine ID&rdquo; and they will respond with a
	    corresponding password consisting of groups of numbers. You need
	    to add them both along with the machine name and license number in
	    your mathpass file.</para>
	  
	  <para>You can do this by invoking:</para>

	    <informalexample>
	      <screen>&prompt.root; <userinput>cd /usr/local/Mathematica/Install</userinput>
&prompt.root; <userinput>math.install</userinput></screen>
	    </informalexample>

	  <para>It will ask you to enter your license number
	    and the Wolfram supplied password. If you get them mixed up or
	    for some reason the math.install fails, that is OK; you can simply
	    edit the file <filename>mathpass</filename> in this same directory to correct the
	    info manually.</para>
	  
	  <para>After getting past the password, math.install will ask you if
	    you accept the install defaults provided, or if you want to use
	    your own. If you are like us and distrust all install programs,
	    you probably want to specify the actual directories. Beware.
	    Although the math.install program asks you to specify directories,
	    it will not create them for you, so you should perhaps have a
	    second window open with another shell so that you can create them
	    before you give them to the install program. Or, if it fails, you
	    can create the directories and then restart the <command>math.install</command>
	    program. The directories we chose to create beforehand and
	    specify to <command>math.install</command> were:</para>

	    <informaltable frame="none">
	      <tgroup cols="2">
		<tbody>
		  <row>
		    <entry><filename>/usr/local/Mathematica/bin</filename></entry>
		    <entry>for binaries</entry>
		  </row>

		  <row>
		    <entry><filename>/usr/local/Mathematica/man/man1</filename></entry>
		    <entry>for man pages</entry>
		  </row>

		  <row>
		    <entry>/usr/local/Mathematica/lib/X11</entry>
		    <entry>for the XKeysymb file</entry>
		  </row>
		</tbody>
	      </tgroup>
	    </informaltable>

	  <para>You can also tell it to use
	    <filename>/tmp/math.record</filename> for the system record file,
	    where it puts logs of sessions. After this <command>math.install</command> will
	    continue on to unpacking things and placing everything where it
	    should go.</para>
	  
	  <para>The Mathematica Notebook feature is included separately, as
	    the X Front End, and you have to install it separately. To get the
	    X Front End stuff correctly installed, cd into the
	    <filename>/usr/local/Mathematica/FrontEnd</filename> directory and
	    execute the <command>xfe.install</command> shell script. You will have to tell it
	    where to put things, but you do not have to create any directories
	    because it will use the same directories that had been created for
	    math.install. When it finishes, there should be a new shell script
	    in <filename>/usr/local/Mathematica/bin</filename> called
	    <filename>mathematica</filename>.</para>
	  
	  <para>Lastly, you need to modify each of the shell scripts that
	    Mathematica has installed. At the beginning of every shell script
	    in <filename>/usr/local/Mathematica/bin</filename> add the
	    following line:</para>

	    <informalexample>
	      <screen>&prompt.user; <userinput>XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB</userinput></screen>
	    </informalexample>

	  <para>This tells Mathematica were to find its own
	    version of the key mapping file <filename>XKeysymDB</filename>.
	    Without this you will get pages of error messages about missing
	    key mappings.</para>
	  
	  <para>On 2.1-STABLE you need to add the following as well:</para>

	    <informalexample>
	      <screen>&prompt.user; <userinput>RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF</userinput></screen>
	    </informalexample>

	  <para>This tells Mathematica to use the linux version
	    of host.conf. This file has a different syntax from FreeBSD's
	    host.conf, so you will get an error message about
	    <filename>/etc/host.conf</filename> if you leave this out.</para>
	  
	  <para>You might also want to modify your
	    <filename>/etc/manpath.config</filename> file to read the new man
	    directory, and you may need to edit your
	    <filename>~/.cshrc</filename> file to add
	    <filename>/usr/local/Mathematica/bin</filename> to your
	    path.</para>
	  
	  <para>That is about all it takes. With this you should be able to
	    type <command>mathematica</command> and get a really slick looking Mathematica
	    Notebook screen up. Mathematica has included the Motif user
	    interfaces, but it is compiled in statically, so you do not need
	    the Motif libraries. Good luck doing this yourself!</para>
	  
	</sect2>
	
	<sect2>
	  <title>Bugs</title>
	  
	  <para>The Notebook front end is known to hang sometimes when reading
	    notebook files with an error messages similar to:</para>
	  
	    <informalexample>
	      <screen><errorname>File .../Untitled-1.mb appears to be broken for OMPR.257.0</errorname></screen>
	    </informalexample>
	  
	  <para>We have not found the cause for this, but it only affects the
	    Notebook's X Window front end, not the mathematica engine itself.
	    So the command line interface invoked by 'math' is unaffected by
	    this bug.</para>
	  
	</sect2>
	
	<sect2>
	  <title>Acknowledgments</title>
	  
	  <para>A well-deserved thanks should go to &a.sos; and &a.peter; who
	    made linux emulation what it is today, and Michael Smith who drove
	    these two guys like dogs to get it to the point where it runs
	    Linux binaries better than linux! <!-- smiley -->:-)</para>
	  
	</sect2>
      </sect1>
    </chapter>
    

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-shorttag: nil
     sgml-always-quote-attributes: t
     sgml-minimize-attributes: max
     sgml-parent-document: ("../handbook.sgml" "part" "chapter")
     End:
-->