Freshening up of the Linux Emulation section, inspired by docs/2780:

- using &rel.current; instead of hardcoding release names
- removed redundant section on determining presence of Linux emulation
- corrected paths
- change 2.2-RELEASE to `2.2-RELEASE and later' in a couple of places
- added a small section on the use of `brandelf'
- removed a old comment about ELF support being new
- made the text a little more precise in a few places

PR: 2780
Reviewed and discussed with: jraynard

handbook/linuxemu.sgml

@@ -1,4 +1,4 @@
-<!-- $Id: linuxemu.sgml,v 1.22 1997-10-19 13:32:11 jraynard Exp $ -->
+<!-- $Id: linuxemu.sgml,v 1.23 1998-05-29 05:40:23 jkoshy Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <chapt><heading>Linux Emulation<label id="linuxemu"></heading>
@@ -11,7 +11,7 @@
 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
-FreeBSD-2.2-RELEASE is vastly more capable and runs all these as well as
+&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.
 
@@ -21,17 +21,6 @@ use the Linux /proc filesystem (which is different from the optional
 FreeBSD /proc filesystem) or i386-specific calls, such as enabling
 virtual 8086 mode.
 
-<p>To tell whether your kernel is configured for Linux
-compatibility simply run any Linux binary.  If it
-prints the error message
-<tscreen>
-<verb>
-linux-executable: Exec format error. Wrong Architecture.
-</verb>
-</tscreen>
-then you do not have linux compatibility support and
-you need to configure and install a new kernel.
-
 Depending on which version of FreeBSD you are running, how you get 
 Linux-emulation up will vary slightly:
 
@@ -113,7 +102,7 @@ two ways.  In FreeBSD 2.2.1-RELEASE and 2.1-STABLE enable it in
 linux=YES
 </verb>
 </tscreen>
-by changing it from NO to YES.  FreeBSD 2.1 RELEASE and earlier do not
+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 /etc/rc.local to
 add the following line.
 <tscreen>
@@ -178,7 +167,7 @@ this by hand, however, it is vastly simpler to just grab the
 linux_lib port:
 <tscreen>
 <verb>
-% cd /usr/ports-current/emulators/linux_lib
+% cd /usr/ports/emulators/linux_lib
 % make all install
 </verb>
 </tscreen>
@@ -187,10 +176,9 @@ and you should have a working linux emulator.  Legend (and the mail
 archives :-) 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.  As of this writing (March 1996) ELF emulation
-is still in the formulative stages but seems to work pretty well.  Also, 
-expect some programs to complain about incorrect minor versions.  In 
-general this does not seem to be a problem.
+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.
 
 <sect2><heading>Installing libraries manually</heading>
 
@@ -207,9 +195,9 @@ shadow tree /compat/linux/lib rather than the paths that the Linux
 ld.so reports.
 
 
-FreeBSD-2.2-RELEASE and later works slightly differently with respect to
-/compat/linux.  On -CURRENT, all files, not just libraries, are
-searched for from the ``shadow root'' /compat/linux.
+FreeBSD 2.2-RELEASE and later works slightly differently with respect to
+/compat/linux:  all files, not just libraries, are searched for from 
+the ``shadow root'' /compat/linux.
 
 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 
@@ -227,8 +215,8 @@ instructions: you will need to be root on your FreeBSD system to do
 the necessary installation steps).
 
 <p>If you have access to a Linux system, see what shared libraries
-it needs, and copy them to your FreeBSD system. Example: you have
-just ftp'ed the Linux binary of Doom. Put it on the Linux
+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 `ldd linuxxdoom':
 
@@ -295,7 +283,8 @@ 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.
 
-<sect2><heading>Configuring the ld.so -- for FreeBSD 2.2-RELEASE only</heading>
+<sect2><heading>Configuring the ld.so -- for FreeBSD 2.2-RELEASE and 
+later</heading>
 
 <p>This section applies only to FreeBSD 2.2-RELEASE and later.  Those running
 2.1-STABLE should skip this section.
@@ -397,6 +386,29 @@ system. The XXXX (name) and N (major revision number) should match;
 the minor number(s) mm are less important, though it is advised to
 take the most recent version.
 
+<sect1><heading>Installing Linux ELF binaries</heading>
+<p>ELF binaries sometimes require an extra step of ``branding''.
+If you attempt to run  an unbranded ELF binary, you will get an error 
+message like the following:
+
+<verb>
+% ./my-linux-elf-binary
+ELF binary type not known
+Abort
+%
+</verb>
+
+<p>To help the FreeBSD kernel distinguish between a FreeBSD ELF binary from a
+a Linux one, use the <htmlurl url="http://www.freebsd.org/cgi/man.cgi?brandelf"
+name="brandelf(1)"> utility:
+<verb>
+% brandelf -t Linux my-linux-elf-binary
+</verb>
+
+<p>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 the future.
+
 <sect1><heading>Configuring the host name resolver</heading>
 
 <p>If DNS does not work or you get the messages
@@ -425,8 +437,8 @@ complain about the incompatible FreeBSD syntax.  You should remove
 
 <p>Lastly, those who run 2.1-STABLE need to set an the
 RESOLV_HOST_CONF environment variable so that applications will know
-how to search the host tables.  If you run FreeBSD 2.2-RELEASE, you can
-skip this.  For the /bin/csh shell use:
+how to search the host tables.  If you run FreeBSD 2.2-RELEASE or later, 
+you can skip this.  For the /bin/csh shell use:
 <tscreen>
 <verb>
 setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf