aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml
blob: 8f9cc16e237a2c28c0b96b52018c44b71923dda4 (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
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="linuxemu">

  <info>
    <title>&linux; Binary Compatibility</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Jim</firstname>
	  <surname>Mock</surname>
	</personname>
	<contrib>Restructured and parts updated by </contrib>
      </author>
      <!-- 22 Mar 2000 -->
    </authorgroup>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Brian N.</firstname>
	  <surname>Handy</surname>
	</personname>
	<contrib>Originally contributed by </contrib>
      </author>

      <author>
	<personname>
	  <firstname>Rich</firstname>
	  <surname>Murphey</surname>
	</personname>
      </author>
    </authorgroup>
  </info>

  <sect1 xml:id="linuxemu-synopsis">
    <title>Synopsis</title>

    <indexterm>
      <primary>Linux binary compatibility</primary>
    </indexterm>
    <indexterm>
      <primary>binary compatibility</primary>
      <secondary>Linux</secondary>
    </indexterm>

    <para>&os; provides binary compatibility with &linux;,
      allowing users to install and run most &linux; binaries
      on a &os; system without having to first modify the binary.  It
      has even been reported that, in some situations, &linux;
      binaries perform better on &os; than they do on &linux;.</para>

    <para>However, some &linux;-specific operating system features
      are not supported under &os;.  For example, &linux; binaries
      will not work on &os; if they overly use &i386; specific calls,
      such as enabling virtual 8086 mode.</para>

    <note>
      <para>Support for 64-bit binary compatibility with &linux; was
	added in &os;&nbsp;10.3.</para>
    </note>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to enable &linux; binary compatibility on a &os;
	  system.</para>
      </listitem>

      <listitem>
	<para>How to install additional &linux; shared
	  libraries.</para>
      </listitem>

      <listitem>
	<para>How to install &linux; applications on a &os;
	  system.</para>
      </listitem>

      <listitem>
	<para>The implementation details of &linux; compatibility in
	  &os;.</para>
      </listitem>
    </itemizedlist>

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

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

  </sect1>

  <sect1 xml:id="linuxemu-lbc-install">
    <title>Configuring &linux; Binary Compatibility</title>

    <indexterm><primary>Ports Collection</primary></indexterm>

    <para>By default, &linux; libraries are not installed and &linux;
      binary compatibility is not enabled.  &linux; libraries can
      either be installed manually or from the &os; Ports
      Collection.</para>

    <para>Before attempting to build the port, load the &linux; kernel
      module, otherwise the build will fail:</para>

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

    <para>For 64-bit compatibility:</para>

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

    <para>To verify that the module 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>

    <para>The <package>emulators/linux_base-c7</package> package or
      port is the easiest way to install a base set of &linux;
      libraries and binaries on a &os; system.  To install the
      port:</para>

    <screen>&prompt.root; <userinput>pkg install emulators/linux_base-c7</userinput></screen>

    <para>For &linux; compatibility to be enabled at boot time,
      add this line to <filename>/etc/rc.conf</filename>:</para>

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

    <para>On 64-bit machines, <filename>/etc/rc.d/abi</filename> will
      automatically load the module for 64-bit emulation.</para>

    <indexterm>
      <primary>kernel options</primary>
      <secondary>COMPAT_LINUX</secondary>
    </indexterm>

    <para>Since the &linux; binary compatibility layer has gained
      support for running both 32- and 64-bit &linux; binaries (on
      64-bit x86 hosts), it is no longer possible to link the
      emulation functionality statically into a custom kernel.</para>

    <sect2 xml:id="linuxemu-libs-manually">
      <title>Installing Additional Libraries Manually</title>

      <indexterm>
	<primary>shared libraries</primary>
      </indexterm>

      <para>If a &linux; application complains about missing shared
	libraries after configuring &linux; binary compatibility,
	determine which shared libraries the &linux; binary needs and
	install them manually.</para>

      <para>From a &linux; system, <command>ldd</command> can be used
	to determine which shared libraries the application needs.
	For example, to check which shared libraries
	<command>linuxdoom</command> needs, run this command from a
	&linux; system that has <application>Doom</application>
	installed:</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>Then, copy all the files in the last column of the output
	from the &linux; system into
	<filename>/compat/linux</filename> on the &os; system.  Once
	copied, create symbolic links to the names in the first
	column.  This example will result in the following files on
	the &os; system:</para>

      <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -&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>

      <para>If a &linux; shared library already exists with a
	matching major revision number to the first column of the
	<command>ldd</command> output, it does not need to be copied
	to the file named in the last column, as the existing library
	should work.  It is advisable to copy the shared library if it
	is a newer version, though.  The old one can be removed, as
	long as the symbolic link points to the new one.</para>

      <para>For example, these libraries already exist on the &os;
	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 <command>ldd</command> indicates that a binary
	requires a later version:</para>

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

      <para>Since the existing library is only one or two versions out
	of date in the last digit, the program should still work with
	the slightly older version.  However, it is safe to replace
	the existing <filename>libc.so</filename> with the newer
	version:</para>

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

      <para>Generally, one will need to look for the shared libraries
	that &linux; binaries depend on only the first few times that
	a &linux; program is installed on &os;.  After a while, there
	will be a sufficient set of &linux; shared libraries on the
	system to be able to run newly installed &linux; binaries
	without any extra work.</para>
    </sect2>

    <sect2>
      <title>Installing &linux; <acronym>ELF</acronym>
	Binaries</title>

      <indexterm>
	<primary>Linux</primary>
	<secondary>ELF binaries</secondary>
      </indexterm>

      <para><acronym>ELF</acronym> binaries sometimes require an extra
	step.  When an unbranded <acronym>ELF</acronym> binary is
	executed, it will generate an error message:</para>

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

      <para>To help the &os; kernel distinguish between a &os;
	<acronym>ELF</acronym> binary and a &linux; binary, use
	&man.brandelf.1;:</para>

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

      <indexterm>
	<primary>GNU toolchain</primary>
      </indexterm>

      <para>Since the GNU toolchain places the appropriate branding
	information into <acronym>ELF</acronym> binaries
	automatically, this step is usually not necessary.</para>
    </sect2>

    <sect2>
      <title>Installing a &linux; <acronym>RPM</acronym> Based
	Application</title>

      <para>To install a &linux; <acronym>RPM</acronym>-based
	application, first install the
	<package>archivers/rpm4</package> package or port.  Once
	installed, <systemitem class="username">root</systemitem> can
	use this command to install a
	<filename>.rpm</filename>:</para>

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

      <para>If necessary, <command>brandelf</command> the installed
	<acronym>ELF</acronym> binaries.  Note that this will prevent
	a clean uninstall.</para>
    </sect2>

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

      <para>If <acronym>DNS</acronym> does not work or this error
	appears:</para>

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

      <para>configure <filename>/compat/linux/etc/host.conf</filename>
	as follows:</para>

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

      <para>This specifies that <filename>/etc/hosts</filename> is
	searched first and <acronym>DNS</acronym> is searched second.
	When <filename>/compat/linux/etc/host.conf</filename> does not
	exist, &linux; applications use
	<filename>/etc/host.conf</filename> and complain about the
	incompatible &os; syntax.  Remove <literal>bind</literal> if a
	name server is not configured using
	<filename>/etc/resolv.conf</filename>.</para>
    </sect2>
  </sect1>

  <?ignore

  While the installer works, the binaries do not.  As of Oct 2013,
  Linux emulation is 32-bit but the trial version of Mathematica is
  only available as 64-bit.  This section should be revisited if Linux
  emulation gets 64-bit binary support.

  <sect1 id="linuxemu-mathematica">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Boris</firstname>
	  <surname>Hollas</surname>
	  <contrib>Updated for Mathematica 5.X by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Installing &mathematica;</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>Mathematica</application></secondary>
    </indexterm>

    <para>This section describes the process of installing the &linux;
      version of <application>&mathematica; 9.X</application> onto a
      &os; system.  <application>&mathematica;</application> is a
      commercial, computational software program used in scientific,
      engineering, and mathematical fields.  A 30 day trial version is
      available for download from <ulink
	url="http://www.wolfram.com/mathematica/">wolfram.com/mathematica</ulink>.</para>

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

      <para>Before installing &mathematica;, make sure that the
	<filename role="package">textproc/linux-c7-aspell</filename>
	package or port is installed and that the &man.linprocfs.5;
	file system is mounted.</para>

      <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>

      <para>&os; will now assume that unbranded ELF binaries use the
	&linux; <acronym>ABI</acronym> which should allow the
	installer to execute from the CDROM.</para>

      <para>The downloaded file will be saved to
	<filename>/tmp/Mathematica_9.0.1_LINUX.sh</filename>.  Become
	the superuser and run this installer file:</para>

      <programlisting>&prompt.root; <userinput>sh /tmp/Mathematica_9.0.1_LINUX.sh</userinput>
Mathematica Secured 9.0.1 for LINUX Installer Archive

Verifying archive integrity.
Extracting installer. ...
                               Wolfram Mathematica 9 Installer
Copyright (c) 1988-2013 Wolfram Research, Inc. All rights reserved.

WARNING: Wolfram Mathematica is protected by copyright law and international treaties. Unauthorized
reproduction or distribution may result in severe civil and criminal
penalties and will be prosecuted to the maximum extent possible under law.

Enter the installation directory, or press ENTER to select /usr/local/Wolfram/Mathematica/9.0:
>
Now installing...
***********************
Installation complete.</programlisting>
    </sect2>

    <sect2>
      <title>Running the &mathematica; Frontend over a Network</title>

      <para><application>&mathematica;</application> uses some special
	fonts to display characters not present in any of the standard
	font sets.  <application>Xorg</application> requires these
	fonts to be installed locally.  This means that these fonts
	need to be copied from the CDROM or from a host with
	<application>&mathematica;</application> installed to the
	local machine.  These fonts are normally stored in <filename
	  >/cdrom/Unix/Files/SystemFiles/Fonts</filename>
	on the CDROM, or <filename
	  >/usr/local/mathematica/SystemFiles/Fonts</filename>
	on the 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 the fonts into one of the
	existing font directories in <filename
	  >/usr/local/lib/X11/fonts</filename> then
	running &man.mkfontdir.1; within the directory containing the
	new fonts.</para>

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

      <screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts</userinput>
&prompt.root; <userinput>mkdir X</userinput>
&prompt.root; <userinput>mkdir MathType1</userinput>
&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
&prompt.root; <userinput>cp X/* /usr/local/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>cp Type1/* /usr/local/lib/X11/fonts/MathType1</userinput>
&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/X</userinput>
&prompt.root; <userinput>mkfontdir</userinput>
&prompt.root; <userinput>cd ../MathType1</userinput>
&prompt.root; <userinput>mkfontdir</userinput></screen>

      <para>Now add the new font directories to the font path:</para>

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

      <para>When using the <application>&xorg;</application> server,
	these font directories can be loaded automatically by adding
	them to <filename>/etc/X11/xorg.conf</filename>.</para>

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

      <para>If <filename
	  >/usr/local/lib/X11/fonts/Type1</filename>
	does not already exist, change the name of the <filename
	  >MathType1</filename> directory in the
	example above to <filename
	  >Type1</filename>.</para>
    </sect2>
  </sect1>
  -->

  <!--
  As of October 2013, the trial version is only available in the
  Professional and Academic editions (not the Student or Personal
  editions) and requires a contact with a product specialist before
  the evaluation download link is made available.
  <sect1 id="linuxemu-maple">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Aaron</firstname>
	  <surname>Kaplan</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Robert</firstname>
	  <surname>Getschmann</surname>
	  <contrib>Thanks to </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Installing &maple;</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>Maple</application></secondary>
    </indexterm>

    <para><application>&maple;</application> is a commercial
      mathematics program similar to
      <application>&mathematica;</application>.  This software must be
      purchased and licensed from <ulink
	url="http://www.maplesoft.com/products/maple/">Maplesoft</ulink>.
      To install the &linux; version of this software on &os;, follow
      these steps.</para>

    <procedure>
      <step><para>Execute the <filename>INSTALL</filename> shell
	script from the product distribution.  Choose the
	<quote>RedHat</quote> option when prompted by the
	installation program.  A typical installation directory
	might be <filename
	  >/usr/local/maple</filename>.</para></step>

      <step>
	<para>Copy the license to
	  <filename>/usr/local/maple/license/license.dat</filename>.</para>
      </step>

      <step>
	<para>Install the <application>FLEXlm</application> license
	  manager by running the <filename>INSTALL_LIC</filename>
	  install shell script that comes with
	  <application>&maple;</application>.  Specify the primary
	  hostname for the machine for the license server.</para>
      </step>

      <step>
	<para>Patch
	  <filename>/usr/local/maple/bin/maple.system.type</filename>
	  with the following:</para>


	<programlisting>   ----- snip ------------------
*** maple.system.type.orig      Sun Jul  8 16:35:33 2001
-- - maple.system.type   Sun Jul  8 16:35:51 2001
***************
*** 72,77 ****
-- - 72,78 ----
          # the IBM RS/6000 AIX case
          MAPLE_BIN="bin.IBM_RISC_UNIX"
          ;;
+     "FreeBSD"|\
      "Linux")
          # the Linux/x86 case
        # We have two Linux implementations, one for Red Hat and
   ----- snip end of patch -----</programlisting>

	<para>Note that no whitespace should be present after
	  <literal>"FreeBSD"|\</literal>.</para>

	<para>This patch instructs <application>&maple;</application>
	  to recognize &os; as a type of &linux; system.  The
	  <filename>bin/maple</filename> shell script calls the
	  <filename>bin/maple.system.type</filename> shell script
	  which in turn calls <command>uname -a</command> to find out
	  the operating system name.  Depending on the OS name it will
	  find out which binaries to use.</para>
      </step>

      <step>
	<para>Start the license server.</para>

	<para>The following script, installed as
	  <filename>/usr/local/rtc/rc.d/lmgrd</filename> is a
	  convenient way to start up <command>lmgrd</command>:</para>

	<programlisting>   ----- snip ------------

#! /bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
export PATH

LICENSE_FILE=/usr/local/maple/license/license.dat
LOG=/var/log/lmgrd.log

case "$1" in
start)
	lmgrd -c ${LICENSE_FILE} 2&gt;&gt; ${LOG} 1&gt;&amp;2
	echo -n " lmgrd"
	;;
stop)
	lmgrd -c ${LICENSE_FILE} -x lmdown 2&gt;&gt; ${LOG} 1&gt;&amp;2
	;;
*)
	echo "Usage: `basename $0` {start|stop}" 1&gt;&amp;2
	exit 64
	;;
esac

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

      <step>
	<para>Test that <application>&maple;</application>
	  starts:</para>

	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
&prompt.user; <userinput>./xmaple</userinput></screen>

	<para>Once everything is working, consider writing Maplesoft
	  to let them know you would like a native &os;
	  version!</para>
      </step>
    </procedure>

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

      <itemizedlist>
	<listitem>
	  <para><command>lmgrd</command> is known to be picky about
	    the license file and to dump core if there are any
	    problems.  A correct license file should look like
	    this:</para>

	  <programlisting>#
=======================================================
# License File for UNIX Installations ("Pointer File")
# =======================================================
SERVER chillig ANY
#USE_SERVER
VENDOR maplelmg

FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
         PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
         ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
         SN=XXXXXXXXX</programlisting>

	  <note>
	    <para>In this example, the serial number and key were
	      replaced with <literal>X</literal>.
	      <hostid>chillig</hostid> is the hostname.</para>
	  </note>

	  <para>Editing the license file works as long as the
	    <quote>FEATURE</quote> line is not edited.  That line is
	    protected by the license key.</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  -->
  <!--
  As of October, 2013, the Linux version of Matlab is only available
  for 64-bit.

  <sect1 id="linuxemu-matlab">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Dan</firstname>
	  <surname>Pelleg</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Installing &matlab;</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>MATLAB</application></secondary>
    </indexterm>

    <para>This document describes the process of installing the
      &linux; version of
      <application>&matlab; version 6.5</application> onto a &os;
      system.  It works quite well, with the exception of the
      <application>&java.virtual.machine;</application> which is
      described further in <xref linkend="matlab-jre"/>.</para>

    <para>The &linux; version of <application>&matlab;</application>
      can be purchased and licensed from <ulink
	url="http://www.mathworks.com/products/matlab/">MathWorks</ulink>.
      Consider letting the company know that you would like a native
      &os; version of this software.</para>

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

      <para>To install <application>&matlab;</application>:</para>

      <procedure>
	<step>
	  <para>Become <username>root</username>, as recommended by
	    the installation script.  Insert the installation CD and
	    mount it.  To start the installation script type:</para>

	  <screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen>

	  <tip>
	    <para>The installer is graphical.  If it is not able to
	      open a display, type <command>setenv HOME
		~<replaceable>USER</replaceable></command>,
	      where <replaceable>USER</replaceable> is the user who
	      ran &man.su.1;.</para>
	  </tip>
	</step>

	<step>
	  <para>When asked for the <application>&matlab;</application>
	    root directory, type:
	    <userinput>/compat/linux/usr/local/matlab</userinput>.</para>

	  <tip>
	    <para>For easier typing on the rest of the installation
	      process, type this at the shell prompt: <command>set
		MATLAB=/compat/linux/usr/local/matlab</command>.</para>
	  </tip>
	</step>

	<step>
	  <para>Edit the license file as instructed when obtaining
	    the <application>&matlab;</application> license.</para>

	  <tip>
	    <para>This file can be prepared in advance using an
	      editor, and copied to
	      <filename>$MATLAB/license.dat</filename> before the
	      installer asks to edit it.</para>
	  </tip>
	</step>

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

      <para>At this point the <application>&matlab;</application>
	installation is complete.  The following steps apply
	<quote>glue</quote> to connect it to the &os; system.</para>
    </sect2>

    <sect2>
      <title>License Manager Startup</title>

      <procedure>
	<step>
	  <para>Create symlinks for the license manager
	    scripts:</para>

	  <screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput>
&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen>
	</step>

	<step>
	  <para>Create a startup file named
	    <filename>/usr/local/etc/rc.d/flexlm</filename>.  The
	    example below is a modified version of the distributed
	    <filename>$MATLAB/etc/rc.lm.glnx86</filename>.  The
	    changes are file locations and startup of the license
	    manager under &linux; emulation.</para>

	  <programlisting>#!/bin/sh
case "$1" in
  start)
        if [ -f /usr/local/etc/lmboot_TMW ]; then
              /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> &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</userinput></screen>

	    <para>Replace <replaceable>username</replaceable> with the
	      name of a valid user on the system which is not
	      <username>root</username>.</para>
	  </important>
	</step>

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

	  <screen>&prompt.root; <userinput>service flexlm start</userinput></screen>
	</step>
      </procedure>
    </sect2>

    <sect2 id="matlab-jre">
      <title>Linking the &java; Runtime Environment</title>

      <para>Change the <application>&java;</application> Runtime
	Environment (<acronym>JRE</acronym>) link to one working under
	&os;:</para>

      <screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput>
&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen>
    </sect2>

    <sect2>
      <title>Creating a &matlab; Startup Script</title>

      <procedure>
	<step>
	  <para>Place the following startup script in
	    <filename
	      >/usr/local/bin/matlab</filename>:</para>

	  <programlisting>#!/bin/sh
/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting>
	</step>

	<step>
	  <para>Then, type the command
	    <command>chmod +x /usr/local/bin/matlab</command>.</para>
	</step>
      </procedure>

      <tip>
	<para>Depending on the version of
	  <filename role="package">emulators/linux_base</filename>,
	  running this script may result in errors.  To avoid errors,
	  edit
	  <filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
	  and change the line that says:</para>

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

	<para>to this line:</para>

	<programlisting>if test -L $newbase; then</programlisting>
      </tip>
    </sect2>

    <sect2>
      <title>Creating a &matlab; Shutdown Script</title>

      <para>The following is needed to solve a problem with &matlab;
	not exiting correctly.</para>

      <procedure>
	<step>
	  <para>Create
	    <filename>$MATLAB/toolbox/local/finish.m</filename>
	    containing the single line:</para>

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

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

	  <tip>
	    <para>The same directory contains
	      <filename>finishsav.m</filename> and
	      <filename>finishdlg.m</filename>, which allow the
	      workspace to be saved before quitting.  If either file
	      is used, insert the line above immediately after the
	      <literal>save</literal> command.</para>
	  </tip>
	</step>

	<step>
	  <para>Create <filename>$MATLAB/bin/finish.sh</filename>
	    which contains the following:</para>

	  <programlisting>#!/compat/linux/bin/sh
(sleep 5; killall -1 matlab_helper) &amp;
exit 0</programlisting>
	</step>

	<step>
	  <para>Make the file executable:</para>

	  <screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen>
	</step>
      </procedure>
    </sect2>

    <sect2 id="matlab-using">
      <title>Using &matlab;</title>

      <para>At this point, <command>matlab</command> is ready for
	use.</para>
    </sect2>
  </sect1>

  <sect1 id="linuxemu-oracle">
    While the Oracle website is unclear, the installation script is:
    You are attempting to install 64-bit Oracle on a 32-bit operating
    system.  This is not supported and will not work.

    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Marcel</firstname>
	  <surname>Moolenaar</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Installing &oracle;</title>

    <indexterm>
      <primary>applications</primary>
      <secondary><application>Oracle</application></secondary>
    </indexterm>

    <para>This document describes the process of installing
      <application>&oracle; 8.0.5</application> and
      <application>&oracle; 8.0.5.1 Enterprise Edition</application>
      for &linux; onto a &os; machine.</para>

    <sect2>
      <title>Installing the &linux; Environment</title>

      <para>Make sure <filename
	  role='package'>emulators/linux_base</filename>
	has been installed from the Ports Collection.</para>

      <para>To run the intelligent agent, install the Red Hat Tcl
	package:  <filename>tcl-8.0.3-20.i386.rpm</filename>.  The
	general command for installing RPMs with the
	<filename role='package'>archivers/rpm</filename> port
	is:</para>

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

      <para>This command should not generate any errors.</para>
    </sect2>

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

      <para>Before installing <application>&oracle;</application>, set
	up a proper environment.  This section only describes how to
	install <application>&oracle;</application> for &linux; on
	&os;, not what has been described in the
	<application>&oracle;</application> installation guide.</para>

      <sect3 id="linuxemu-kernel-tuning">
	<title>Kernel Tuning</title>

	<indexterm>
	  <primary>kernel tuning</primary>
	</indexterm>

	<para>As described in the <application>&oracle;</application>
	  installation guide, the maximum size of shared memory needs
	  to be set.  Do not use <literal>SHMMAX</literal> under &os;
	  as it is calculated from <literal>SHMMAXPGS</literal> and
	  <literal>PGSIZE</literal>.  Therefore, define
	  <literal>SHMMAXPGS</literal>.  All other options can be
	  used as described in the guide.  For example:</para>

	<programlisting>options SHMMAXPGS=10000
options SHMMNI=100
options SHMSEG=10
options SEMMNS=200
options SEMMNI=70
options SEMMSL=61</programlisting>

	<para>Set these options to suit the intended use of
	  <application>&oracle;</application>.</para>

	<para>Also, make sure the following options are in the
	  kernel configuration file:</para>

	<programlisting>options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communication</programlisting>
      </sect3>

      <sect3 id="linuxemu-oracle-account">

	<title>&oracle; Account</title>

	<para>Create a user account to be used as the
	  <username>oracle</username> account.  Add
	  <literal>/compat/linux/bin/bash</literal> to
	  <filename>/etc/shells</filename> and set the shell for
	  the <username>oracle</username> account to
	  <filename>/compat/linux/bin/bash</filename>.</para>
      </sect3>

      <sect3 id="linuxemu-environment">
	<title>Environment</title>

	<para>Besides the normal <application>&oracle;</application>
	  variables, such as <envar>ORACLE_HOME</envar> and
	  <envar>ORACLE_SID</envar> set the following
	  environment variables:</para>

	<informaltable frame="none" pgwide="1">
	  <tgroup cols="2">
	    <colspec colwidth="1*"/>
	    <colspec colwidth="2*"/>
	    <thead>
	      <row>
		<entry>Variable</entry>
		<entry>Value</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><envar>LD_LIBRARY_PATH</envar></entry>
		<entry><literal>$ORACLE_HOME/lib</literal></entry>
	      </row>

	      <row>
		<entry><envar>CLASSPATH</envar></entry>
		<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
	      </row>

	      <row>
		<entry><envar>PATH</envar></entry>
		<entry><literal>/compat/linux/bin
		    /compat/linux/sbin
		    /compat/linux/usr/bin
		    /compat/linux/usr/sbin
		    /bin
		    /sbin
		    /usr/bin
		    /usr/sbin
		    /usr/local/bin
		    $ORACLE_HOME/bin</literal></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>It is advised to set all the environment variables in
	  <filename>~/.profile</filename> as follows:</para>

	<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
ORACLE_HOME=/oracle; export ORACLE_HOME
LD_LIBRARY_PATH=$ORACLE_HOME/lib
export LD_LIBRARY_PATH
ORACLE_SID=ORCL; export ORACLE_SID
ORACLE_TERM=386x; export ORACLE_TERM
CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
export CLASSPATH
PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
export PATH</programlisting>
      </sect3>
    </sect2>

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

      <para>Before starting the installer, create a directory named
	<filename>/var/tmp/.oracle</filename> which
	is owned by the <username>oracle</username> user.  The
	installation of <application>&oracle;</application> should
	work without any problems.  If errors are encountered, check
	the <application>&oracle;</application> distribution and
	configuration.  Once <application>&oracle;</application> is
	installed, apply the patches described in the next two
	subsections.</para>

      <para>A frequent error is that the TCP protocol adapter is not
	installed correctly.  As a consequence, no TCP listeners can
	be started.  The following actions help to solve this
	problem:</para>

      <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>

    <para>Do not forget to run <filename>root.sh</filename>
      again.</para>

    <sect3 id="linuxemu-patch-root">
      <title>Patching <filename>root.sh</filename></title>

      <para>When installing <application>&oracle;</application>,
	some actions, which need to be performed as
	<username>root</username>, are recorded in a shell script
	called <filename>root.sh</filename>.  This script is
	found in <filename>orainst</filename>.
	Apply the following patch to <filename>root.sh</filename>
	so that it can find the &os; location of
	<command>chown</command>.  Alternatively, run the script
	under a &linux; native shell.</para>

      <programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
--- orainst/root.sh Mon Dec 28 15:58:53 1998
***************
*** 31,37 ****
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/bin/chown
#
# Define variables to be used in this script
 --- 31,37 ----
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/usr/sbin/chown
#
# Define variables to be used in this script</programlisting>

      <para>If <application>&oracle;</application> is not installed
	from CD, patch the source for <filename>root.sh</filename>.
	It is called <filename>rthd.sh</filename> and is located in
	<filename>orainst</filename> in the source
	tree.</para>
    </sect3>

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

      <para>The script <command>genclntsh</command> is used to create
	a single shared client library when building the demos.  Apply
	the following patch to comment out the definition of
	<envar>PATH</envar>:</para>

      <programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
--- bin/genclntsh Tue Dec 22 15:36:49 1998
***************
*** 32,38 ****
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! PATH=/usr/local/bin:/bin:/usr/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst
--- 32,38 ----
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! #PATH=/usr/local/bin:/bin:/usr/bin: export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
      </sect3>
    </sect2>

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

      <para>After following these instructions,
	<application>&oracle;</application> should run as if it was
	running on &linux;.</para>
    </sect2>
  </sect1>
  ?>

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

    <para>This section describes how &linux; binary compatibility
      works and is based on an email written to &a.chat; by
      Terry Lambert <email>tlambert@primenet.com</email> (Message ID:
      <literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>

    <indexterm><primary>execution class loader</primary></indexterm>

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

    <para>Historically, the &unix; loader examined the magic number
      (generally the first 4 or 8 bytes of the file) to see if it was
      a binary known to the system, and if so, invoked the binary
      loader.</para>

    <para>If it was not the binary type for the system, the
      &man.execve.2; call returned a failure, and the shell
      attempted to start executing it as shell commands.  The
      assumption was a default of
      <quote>whatever the current shell is</quote>.</para>

    <para>Later, a hack was made for &man.sh.1; to examine the first
      two characters, and if they were <literal>:\n</literal>, it
      invoked the &man.csh.1; shell instead.</para>

    <para>&os; has a list of loaders, instead of a single loader, with
      a fallback to the <literal>#!</literal> loader for running shell
      interpreters or shell scripts.</para>

    <indexterm>
      <primary>ELF</primary>
    </indexterm>

    <indexterm>
      <primary>Solaris</primary>
    </indexterm>

    <para>For the &linux; <acronym>ABI</acronym> support, &os; sees
      the magic number as an ELF binary.  The ELF loader looks for a
      specialized <emphasis>brand</emphasis>, which is a comment
      section in the ELF image, and which is not present on
      SVR4/&solaris; ELF binaries.</para>

    <para>For &linux; binaries to function, they must be
      <emphasis>branded</emphasis> as type <literal>Linux</literal>
      using &man.brandelf.1;:</para>

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

    <indexterm>
      <primary>ELF</primary>
      <secondary>branding</secondary>
    </indexterm>

    <para>When the ELF loader sees the <literal>Linux</literal>
      brand, the loader replaces a pointer in the
      <literal>proc</literal> structure.  All system calls are indexed
      through this pointer.  In addition, the process is flagged for
      special handling of the trap vector for the signal trampoline
      code, and several other (minor) fix-ups that are handled by the
      &linux; kernel module.</para>

    <para>The &linux; system call vector contains, among other things,
      a list of <literal>sysent[]</literal> entries whose addresses
      reside in the kernel module.</para>

    <para>When a system call is called by the &linux; binary, the trap
      code dereferences the system call function pointer off the
      <literal>proc</literal> structure, and gets the &linux;, not the
      &os;, system call entry points.</para>

    <para>&linux; mode dynamically <emphasis>reroots</emphasis>
      lookups.  This is, in effect, equivalent to
      <option>union</option> to file system mounts.  First, an
      attempt is made to lookup the file in
      <filename>/compat/linux/<replaceable>original-path</replaceable></filename>.
      If that fails, the lookup is done in
      <filename>/<replaceable>original-path</replaceable></filename>.
      This makes sure that binaries that require other binaries can
      run.  For example, the &linux; toolchain can all run under
      &linux; <acronym>ABI</acronym> support.  It also means that the
      &linux; binaries can load and execute &os; binaries, if there
      are no corresponding &linux; binaries present, and that a
      &man.uname.1; command can be placed in the
      <filename>/compat/linux</filename> directory tree to ensure that
      the &linux; binaries cannot tell they are not running on
      &linux;.</para>

    <para>In effect, there is a &linux; kernel in the &os; kernel.
      The various underlying functions that implement all of the
      services provided by the kernel are identical to both the &os;
      system call table entries, and the &linux; system call table
      entries: file system operations, virtual memory operations,
      signal delivery, and System V IPC.  The only difference is that
      &os; binaries get the &os; <emphasis>glue</emphasis> functions,
      and &linux; binaries get the &linux; <emphasis>glue</emphasis>
      functions.  The &os; <emphasis>glue</emphasis> functions are
      statically linked into the kernel, and the &linux;
      <emphasis>glue</emphasis> functions can be statically linked, or
      they can be accessed via a kernel module.</para>

    <para>Technically, this is not really emulation, it is an
      <acronym>ABI</acronym> implementation.  It is sometimes called
      <quote>&linux; emulation</quote> because the implementation was
      done at a time when there was no other word to describe what was
      going on.  Saying that &os; ran &linux; binaries was not true,
      since the code was not compiled in.</para>
  </sect1>
</chapter>