aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
blob: 1abb326aa5fd4493d3784f4fb89a2fa264060a75 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
<!--
     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>FreeBSD provides binary compatibility with several other
      &unix; like operating systems, including Linux.  At this point,
      you may be asking yourself why exactly, does
      FreeBSD need to be able to run Linux binaries?  The answer to that
      question is quite simple.  Many companies and developers develop
      only for Linux, since it is the latest <quote>hot thing</quote> in
      the computing world.  That leaves the rest of us FreeBSD users
      bugging these same companies and developers to put out native
      FreeBSD versions of their applications.  The problem is, that most
      of these companies do not really realize how many people would use
      their product if there were FreeBSD versions too, and most continue
      to only develop for Linux.  So what is a FreeBSD user to do?  This
      is where the Linux binary compatibility of FreeBSD comes into
      play.</para>

    <para>In a nutshell, the compatibility allows FreeBSD users to run
      about 90% of all Linux applications without modification.  This
      includes applications such as <application>&staroffice;</application>,
      the Linux version of <application>&netscape;</application>,
      <application>&adobe;&nbsp;&acrobat;</application>,
      <application>&realplayer;</application>,
      <application>&oracle;</application>,
      <application>&wordperfect;</application>, <application>Doom</application>,
      <application>Quake</application>, and more.  It is also reported
      that in some situations, Linux binaries perform better on FreeBSD
      than they do under Linux.</para>

    <para>There are, however, some Linux-specific operating system
      features that are not supported under FreeBSD.  Linux binaries will
      not work on FreeBSD 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 your system.</para>
      </listitem>

      <listitem>
	<para>How to install additional Linux shared
	  libraries.</para>
	</listitem>

      <listitem>
	<para>How to install Linux applications on your FreeBSD system.</para>
      </listitem>

      <listitem>
	<para>The implementation details of Linux compatibility in FreeBSD.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Know how to install additional third-party
        software (<xref linkend="ports">).</para>
      </listitem>
    </itemizedlist>

  </sect1>

  <sect1 id="linuxemu-lbc-install">
    <title>Installation</title>

    <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>

    <para>Linux binary compatibility is not turned on by default.  The
      easiest way to enable this functionality is to load the
      <literal>linux</literal> KLD object (<quote>Kernel LoaDable
      object</quote>).  You can load this module by typing the
      following as <username>root</username>:</para>

    <screen>&prompt.root; <userinput>kldload linux</userinput></screen>

    <para>If you would like Linux compatibility to always be enabled,
      then you should add the following line to
      <filename>/etc/rc.conf</filename>:</para>

    <programlisting>linux_enable="YES"</programlisting>

    <para>The &man.kldstat.8; command can be used to verify that the
      KLD is loaded:</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>If for some reason you do not want to or cannot load the KLD,
      then you may statically link Linux binary compatibility into the kernel
      by adding <literal>options COMPAT_LINUX</literal> to your kernel
      configuration file.  Then install your new kernel as described in
      <xref linkend="kernelconfig">.</para>

    <sect2>
      <title>Installing Linux Runtime Libraries</title>
      <indexterm>
	<primary>Linux</primary>
	<secondary>installing Linux libraries</secondary>
      </indexterm>

      <para>This can be done one of two ways, either by using the
	<link linkend="linuxemu-libs-port">linux_base</link> port, or
	by installing them <link
	linkend="linuxemu-libs-manually">manually</link>.</para>

      <sect3 id="linuxemu-libs-port">
	<title>Installing Using the linux_base Port</title>
	<indexterm><primary>Ports Collection</primary></indexterm>

	<para>This is by far the easiest method to use when installing the
	  runtime libraries.  It is just like installing any other port
	  from the <ulink type="html" url="file://localhost/usr/ports/">Ports Collection</ulink>.
	  Simply do the following:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base-f10</userinput>
&prompt.root; <userinput>make install distclean</userinput></screen>

	<note>
	  <para>On &os; systems prior to &os;&nbsp;8.0, you will have
	    to use the <filename
	    role="package">emulators/linux_base-fc4</filename> port
	    instead of <filename
	    role="package">emulators/linux_base-f10</filename>.</para>
	</note>

	<para>You should now have working Linux binary compatibility.
	  Some programs may complain about incorrect minor versions of the
	  system libraries.  In general, however, this does not seem to be
	  a problem.</para>

	<note><para>There may be multiple versions of the <filename
	  role="package">emulators/linux_base</filename> port available,
	  corresponding to different versions of various Linux distributions.
	  You should install the port most closely resembling the
	  requirements of the Linux applications you would like to
	  install.</para></note>

      </sect3>

      <sect3 id="linuxemu-libs-manually">
	<title>Installing Libraries Manually</title>

	<para>If you do not have the <quote>ports</quote> collection
	  installed, 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
	  <quote>shadow root</quote> 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, it will then 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>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>
	<indexterm><primary>shared libraries</primary></indexterm>

	<para>What if you install the <filename>linux_base</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 <username>root</username> on your FreeBSD system).</para>

	<para>If you have access to a Linux system, see what shared
	  libraries the application needs, and copy them to your FreeBSD
	  system.  Look at the following example:</para>

	<informalexample>
	  <para>Let us assume you used FTP to get the Linux binary of
	    <application>Doom</application>, and put it on a Linux system you have access to.  You
	    then can check which shared libraries it needs by running
	    <command>ldd linuxdoom</command>, like so:</para>

	  <screen>&prompt.user; <userinput>ldd linuxdoom</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>

	  <indexterm><primary>symbolic links</primary></indexterm>
	  <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>

	  <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>

	  <blockquote>
	    <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>

	      <screen>/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>

	      <para>and you find a new binary that claims to require a
		later version according to the output of
		<command>ldd</command>:</para>

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

	      <para>If it is only one or two versions out of date 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>

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

	  <blockquote>
	    <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>
	  </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 you attempt to run an unbranded ELF
	binary, you will get 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 FreeBSD kernel distinguish between a FreeBSD ELF
	binary and a Linux binary, use the &man.brandelf.1;
	utility.</para>

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

      <indexterm><primary>GNU toolchain</primary></indexterm>
      <para>The GNU toolchain now places the appropriate branding
	information into ELF binaries automatically, so this step
	should become increasingly unnecessary in the future.</para>
    </sect2>

    <sect2>
      <title>Installing a Random Linux RPM Based Application</title>

      <para>FreeBSD has its own package database and it is used to track
	all ports (&linux; ports as well).  So the &linux; RPM database is not
	used (not supported).</para>

      <para>However if you need to install a random &linux; RPM-based
	application it can be achieved by:</para>

      <screen>&prompt.root; <userinput>cd /compat/linux</userinput>
&prompt.root; <userinput>rpm2cpio -q &lt; /path/to/linux.archive.rpm | cpio -id</userinput></screen>

      <para>Then brandelf installed ELF binaries (not libraries!).
	You will not be able to do a clean uninstall, but it may help you
	to do tests.</para>
    </sect2>

    <sect2>
      <title>Configuring the Hostname Resolver</title>

      <para>If DNS does not work or you get this message:</para>

      <screen>resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keyword</screen>

      <para>You will need to configure a
	<filename>/compat/linux/etc/host.conf</filename> file
	containing:</para>

      <programlisting>order hosts, bind
multi on</programlisting>

      <para>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>
    </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 document describes the process of installing the Linux
      version of <application>&mathematica; 5.X</application> onto
      a FreeBSD system.</para>

    <para>The Linux version of <application>&mathematica;</application>
      or <application>&mathematica; for Students</application> can
      be ordered directly from Wolfram at
      <ulink url="http://www.wolfram.com/"></ulink>.</para>

    <sect2>
      <title>Running the &mathematica; Installer</title>

      <para>First, you have to tell &os; that
	<application>&mathematica;</application>'s Linux
	binaries use the Linux ABI.  The easiest way to do so 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>This will make &os; assume that unbranded ELF binaries
	use the Linux ABI and so you should be able to run the
	installer straight from the CDROM.</para>

      <para>Now, copy the file <filename>MathInstaller</filename> to
	your hard drive:</para>

      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen>

      <para>and in this file, replace <literal>/bin/sh</literal> in
	the first line by <literal>/compat/linux/bin/sh</literal>.
	This makes sure that the installer is executed by the Linux
	version of &man.sh.1;.  Next, replace all occurrences of
	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
	a text editor or the script below in the next section.  This
	tells the <application>&mathematica;</application> installer,
	who calls <command>uname -s</command> to determine the
	operating system, to treat &os; as a Linux-like operating
	system.  Invoking <command>MathInstaller</command> will 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 you can use them.  If
	you chose <filename class="directory">/usr/local/bin</filename>
	as the directory to place the
	<application>&mathematica;</application> executables in, you
	will find symlinks in this directory to files called
	<filename>math</filename>, <filename>mathematica</filename>,
	<filename>Mathematica</filename>, and
	<filename>MathKernel</filename>.  In each of these, replace
	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
	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 &gt; $i.tmp
  sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp &gt; $i
  rm $i.tmp
  chmod a+x $i
done</programlisting>
    </sect2>

    <sect2>
      <title>Obtaining Your &mathematica; Password</title>

      <indexterm>
	<primary>Ethernet</primary>
	<secondary>MAC address</secondary>
      </indexterm>

      <para>When you start <application>&mathematica;</application>
	for the first time, you will be asked for a password.  If you
	have not yet obtained a password from Wolfram, run the program
	<command>mathinfo</command> in the installation directory to
	obtain your <quote>machine ID</quote>.  This machine ID is
	based solely on the MAC address of your first Ethernet card,
	so you cannot run your copy of
	<application>&mathematica;</application> on different
	machines.</para>

      <para>When you register with Wolfram, either by email, phone or fax,
	you will give them 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 (integrals, sums, Greek
	letters, etc.).  The X protocol requires these fonts to be install
	<emphasis>locally</emphasis>.  This means you will have to copy
	these fonts from the CDROM or from a host with
	<application>&mathematica;</application>
	installed to your local machine.  These fonts are normally stored
	in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the
	CDROM, or
	<filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on
	your hard drive.  The actual fonts are in the subdirectories
	<filename>Type1</filename> and <filename>X</filename>.  There are
	several ways to use them, as described below.</para>

      <para>The first way is to copy them into one of the existing font
	directories in <filename>/usr/X11R6/lib/X11/fonts</filename>.
	This will require editing the <filename>fonts.dir</filename> file,
	adding the font names to it, and changing the number of fonts on
	the first line.  Alternatively, you should also just be able to
	run &man.mkfontdir.1; in the directory you have copied
	them to.</para>

      <para>The second way to do this is to copy the directories to
	<filename>/usr/X11R6/lib/X11/fonts</filename>:</para>

      <screen>&prompt.root; <userinput>cd /usr/X11R6/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/X11R6/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>cd /usr/X11R6/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 your font path:</para>

      <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>xset fp rehash</userinput></screen>

      <para>If you are using the <application>&xorg;</application> server, you can have these font
	directories loaded automatically by adding them to your
	<filename>xorg.conf</filename> file.</para>

      <indexterm><primary>fonts</primary></indexterm>

      <para>If you <emphasis>do not</emphasis> already have a directory
	called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
	can change the name of the <filename>MathType1</filename>
	directory in the example above to
	<filename>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>.  You must purchase this software from <ulink
      url="http://www.maplesoft.com/"></ulink> and then register there
      for a license file.  To install this software on FreeBSD, please
      follow these simple 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>If you have not done so, order a license for <application>&maple;</application>
	  from Maple Waterloo Software (<ulink url="http://register.maplesoft.com/"></ulink>)
	  and copy it 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 your machine for the license
	  server.</para></step>

        <step><para>Patch the
          <filename>/usr/local/maple/bin/maple.system.type</filename>
          file 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>Please note that after the <literal>"FreeBSD"|\</literal> no other
	  whitespace should be present.</para>

	<para>This patch instructs <application>&maple;</application> to
	  recognize <quote>FreeBSD</quote> 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/etc/rc.d/lmgrd.sh</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:/usr/X11R6/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&gt;&gt; ${LOG} 1&gt;&2
	echo -n " lmgrd"
	;;
stop)
	lmgrd -c ${LICENSE_FILE} -x lmdown 2&gt;&gt; ${LOG} 1&gt;&2
	;;
*)
	echo "Usage: `basename $0` {start|stop}" 1&gt;&2
	exit 64
	;;
esac

exit 0
   ----- snip ------------</programlisting></step>


      <step><para>Test-start <application>&maple;</application>:</para>
	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
&prompt.user; <userinput>./xmaple</userinput></screen>

	<para>You should be up and running. Make sure to write
	  Maplesoft to let them know you would like a native FreeBSD
	  version!</para></step>
    </procedure>

    <sect2>
      <title>Common Pitfalls</title>

      <itemizedlist>
	<listitem><para>The <application>FLEXlm</application> license manager can be a difficult
	  tool to work with.  Additional documentation on the subject
	  can be found at <ulink
	  url="http://www.globetrotter.com/"></ulink>.</para></listitem>

	<listitem><para><command>lmgrd</command> is known to be very picky
	  about the license file and to core dump 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>Serial number and key 'X''ed out. <hostid>chillig</hostid> is a
	    hostname.</para></note>

  	  <para>Editing the license file works as long as you do not
 	    touch the <quote>FEATURE</quote> line (which 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> (see
      <xref linkend="matlab-jre">).</para>

    <para>The Linux version of <application>&matlab;</application> can be
      ordered directly from The MathWorks at <ulink
      url="http://www.mathworks.com"></ulink>.  Make sure you also get
      the license file or instructions how to create it.  While you
      are there, let them know you would like a native &os;
      version of their software.</para>

    <sect2>
      <title>Installing &matlab;</title>

      <para>To install <application>&matlab;</application>, do the 
	following:</para>

      <procedure>
	<step>
	  <para>Insert the installation CD and mount it.
	    Become <username>root</username>, as recommended by the
	    installation script.  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 you get errors about
	      not being able to open a display, type
	      <command>setenv HOME ~<replaceable>USER</replaceable></command>,
	      where <replaceable>USER</replaceable> is the user you did a
	      &man.su.1; as.</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 your 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>You can prepare this file in advance using your
	      favorite editor, and copy it to
	      <filename>$MATLAB/license.dat</filename> before the
	      installer asks you to edit it.</para>
	  </tip>
	</step>

	<step>
	  <para>Complete the installation process.</para>
	</step>
      </procedure>

      <para>At this point your <application>&matlab;</application>
	installation is complete.  The following steps apply
	<quote>glue</quote> to connect it to your &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 at
	    <filename>/usr/local/etc/rc.d/flexlm.sh</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> &amp;&amp; echo 'MATLAB_lmgrd'
        fi
        ;;
  stop)
	if [ -f /usr/local/etc/lmdown_TMW ]; then
            /compat/linux/bin/sh /usr/local/etc/lmdown_TMW  &gt; /dev/null 2&gt;&amp;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.sh</userinput></screen>

	    <para>You must also replace
	      <replaceable>username</replaceable> above with the name
	      of a valid user on your system (and not
	      <username>root</username>).</para>
	  </important>
	</step>

	<step>
	  <para>Start the license manager with the command:</para>

	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/flexlm.sh 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 (JRE) 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>/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 your version of
	  <filename role="package">emulators/linux_base</filename>, you
	  may run into errors when running this script.  To avoid that,
	  edit the file
	  <filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
	  and change the line that says:</para>

	<programlisting>if [ `expr "$lscmd" : '.*-&gt;.*'` -ne 0 ]; then</programlisting>

	<para>(in version 13.0.1 it is on line 410) 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 a file
	    <filename>$MATLAB/toolbox/local/finish.m</filename>, and
	    in it put the single line:</para>

	  <programlisting>! $MATLAB/bin/finish.sh</programlisting>

	  <note><para>The <literal>$MATLAB</literal> is
	    literal.</para></note>

	  <tip>
	    <para>In the same directory, you will find the files
	      <filename>finishsav.m</filename> and
	      <filename>finishdlg.m</filename>, which let you save
	      your workspace before quitting.  If you use either of
	      them, insert the line above immediately after the
	      <literal>save</literal> command.</para></tip>
	</step>

	<step>
	  <para>Create a file
	    <filename>$MATLAB/bin/finish.sh</filename>, which will
	    contain 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 you are ready to type
	<command>matlab</command> and start using it.</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>

    <sect2>
      <title>Preface</title>
      <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 FreeBSD
	machine.</para>
    </sect2>

    <sect2>
      <title>Installing the Linux Environment</title>

      <para>Make sure you have both <filename role='package'>emulators/linux_base</filename> and
	<filename role='package'>devel/linux_devtools</filename> from the Ports Collection
	installed.  If you run into difficulties with these ports,
	you may have to use
	the packages or older versions available in the Ports Collection.</para>

      <para>If you want to run the intelligent agent, you will
	also need to install the Red Hat Tcl package:
	<filename>tcl-8.0.3-20.i386.rpm</filename>.  The general command
	for installing packages with the official <application>RPM</application> port (<filename role='package'>archivers/rpm</filename>) is:</para>

      <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>

      <para>Installation of the <replaceable>package</replaceable> should not generate any errors.</para>
    </sect2>

    <sect2>
      <title>Creating the &oracle; Environment</title>

      <para>Before you can install <application>&oracle;</application>, you need to set up a proper
	environment.  This document only describes what to do
	<emphasis>specially</emphasis> to run <application>&oracle;</application> for Linux on FreeBSD, 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, you need to set
	  the maximum size of shared memory.  Do not use
	  <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal>
	  is merely calculated out of <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 your intended use of <application>&oracle;</application>.</para>

	<para>Also, make sure you have the following options in your 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 an <username>oracle</username> account just as you would create any other
	  account. The  <username>oracle</username> account is special only that you need to give
	  it a Linux shell.  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> you must
	  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>.  A complete example is:</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>Due to a slight inconsistency in the Linux emulator, you need to
	create a directory named <filename>.oracle</filename> in
	<filename>/var/tmp</filename> before you start the installer.
	Let it be owned by the <username>oracle</username> user.  You
	should be able to install <application>&oracle;</application> without any problems.  If you have
	problems, check your <application>&oracle;</application> distribution and/or configuration first!
	After you have installed <application>&oracle;</application>, apply the patches described in the
	next two subsections.</para>

      <para>A frequent problem is that the TCP protocol adapter is not
	installed right. As a consequence, you cannot start any TCP listeners.
	The following actions help 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 root.sh</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
	  written in the <filename>orainst</filename> directory.  Apply the
	  following patch to <filename>root.sh</filename>, to have it use to proper location of
	  <command>chown</command> or 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>When you do not install <application>&oracle;</application> from CD, you can patch the source
	  for <filename>root.sh</filename>.  It is called
	  <filename>rthd.sh</filename> and is located in the
	  <filename>orainst</filename> directory in the source tree.</para>
      </sect3>

      <sect3 id="linuxemu-patch-tcl">
	<title>Patching genclntsh</title>

	<para>The script <command>genclntsh</command> is used to create
	  a single shared client
	  library.  It is used 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:/usr/X11R6/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:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Running &oracle;</title>

      <para>When you have followed the instructions, you should be able to run
	<application>&oracle;</application> as if it was run on Linux
	itself.</para>
    </sect2>
  </sect1>

  <sect1 id="linuxemu-advanced">
    <title>Advanced Topics</title>

    <para>If you are curious as to how the Linux binary compatibility
      works, this is the section you want to read.  Most of what follows
      is based heavily on an email written to &a.chat; by Terry Lambert
      <email>tlambert@primenet.com</email> (Message ID:
      <literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>

    <sect2>
      <title>How Does It Work?</title>
      <indexterm><primary>execution class loader</primary></indexterm>

      <para>FreeBSD has an abstraction called an <quote>execution class
	loader</quote>.  This is a wedge into the &man.execve.2; system
	call.</para>

      <para>What happens is that FreeBSD has a list of loaders, instead of
	a single loader with a fallback to the <literal>#!</literal>
	loader for running any shell interpreters or shell scripts.</para>

      <para>Historically, the only loader on the &unix; platform 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.</para>

      <para>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>, then it
	invoked the &man.csh.1; shell instead (we believe SCO first made
	this hack).</para>

      <para>What FreeBSD does now is go through a list of loaders, with a
	generic <literal>#!</literal> loader that knows about interpreters
	as the characters which follow to the next whitespace next to
	last, followed by a fallback to
	<filename>/bin/sh</filename>.</para>
      <indexterm><primary>ELF</primary></indexterm>

      <para>For the Linux ABI support, FreeBSD sees the magic number as an
	ELF binary (it makes no distinction between FreeBSD, &solaris;,
	Linux, or any other OS which has an ELF image type, at this
	point).</para>
      <indexterm><primary>Solaris</primary></indexterm>

      <para>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>
	from &man.brandelf.1;:</para>

      <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>

      <para>When this is done, the ELF loader will see the
	<literal>Linux</literal> brand on the file.</para>
      <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
	a traditional &unix; system, this would be the
	<literal>sysent[]</literal> structure array, containing the system
	calls).  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
	FreeBSD, system call entry points.</para>

      <para>In addition, the Linux mode dynamically
	<emphasis>reroots</emphasis> lookups; this is, in effect, what the
	<option>union</option> option to file system mounts
	(<emphasis>not</emphasis> the <literal>unionfs</literal> file system type!) does.  First, an attempt
	is made to lookup the file in the
	<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
	directory, <emphasis>then</emphasis> only if that fails, the
	lookup is done in the
	<filename>/<replaceable>original-path</replaceable></filename>
	directory.  This makes sure that binaries that require other
	binaries can run (e.g., the Linux toolchain can all run under
	Linux ABI support).  It also means that the Linux binaries can
	load and execute FreeBSD binaries, if there are no corresponding
	Linux binaries present, and that you could place a &man.uname.1;
	command in the <filename>/compat/linux</filename> directory tree
	to ensure that the Linux binaries could not tell they were not
	running on Linux.</para>

      <para>In effect, there is a Linux kernel in the FreeBSD kernel; the
	various underlying functions that implement all of the services
	provided by the kernel are identical to both the FreeBSD system
	call table entries, and the Linux system call table entries: file
	system operations, virtual memory operations, signal delivery,
	System V IPC, etc&hellip;  The only difference is that FreeBSD
	binaries get the FreeBSD <emphasis>glue</emphasis> functions, and
	Linux binaries get the Linux <emphasis>glue</emphasis> functions
	(most older OS's only had their own <emphasis>glue</emphasis>
	functions: addresses of functions in a static global
	<literal>sysent[]</literal> structure array, instead of addresses
	of functions dereferenced off a dynamically initialized pointer in
	the <literal>proc</literal> structure of the process making the
	call).</para>

      <para>Which one is the native FreeBSD ABI?  It does not matter.
	Basically the only difference is that (currently; this could
	easily be changed in a future release, and probably will be after
	this) the FreeBSD <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>Yeah, but is this really emulation?  No.  It is an ABI
	implementation, not an emulation.  There is no emulator (or
	simulator, to cut off the next question) involved.</para>

      <para>So why is it sometimes called <quote>Linux emulation</quote>?
	To make it hard to sell FreeBSD!  Really, it
	is because the historical implementation was done at a time when
	there was really no word other than that to describe what was
	going on; saying that FreeBSD ran Linux binaries was not true, if
	you did not compile the code in or load a module, and there needed
	to be a word to describe what was being loaded&mdash;hence
	<quote>the Linux emulator</quote>.</para>
    </sect2>
  </sect1>
</chapter>

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