.nr :a 0 1 .nr :b 0 .nr :c 0 .nr :d 0 .nr :e 0 .nr :f 0 .nr :g 0 1 .nr :h 1 .nr :u 0 .nr ;p 1 .nr !0 0 .nr !1 0 .nr !2 0 .nr !3 0 .nr !N 0 .nr ;F 0 .nr !V 0 .nr !Y 0 .nr !6 0 .nr !8 0 .nr !9 0 .nr !M 0 .ds F \v'-.4m'\s-3\\n+(:p\s0\v'.4m' .ds HF 2 2 2 2 2 2 2 .ds Rf \v'-.4m'\s-3[\\n+(:R]\s0\v'.4m' .nr Au 1 .nr Cp 0 .nr Cl 2 .nr Ds 1v .nr Ec 0 1 .nr Eq 0 .nr Ex 0 1 .nr De 0 .nr Df 5 .nr Fg 0 1 .nr Fs 1 .nr H1 0 1 .nr H2 0 1 .nr H3 0 1 .nr H4 0 1 .nr H5 0 1 .nr H6 0 1 .nr H7 0 1 .nr Hb 2 .nr Hi 1 .nr Hs 2 .nr Hu 2 .nr Hy 0 .nr Le 0 .nr Lf 1 .nr Li 5 .nr Ls 6 .nr Lt 1 .nr Lx 1 .nr Np 0 .nr Oc 0 .nr Of 0 .nr !4 0 1 .af !4 01 .nr Pi 3 .nr Ps 1 .nr Pt 0 .nr Pv 0 .nr Rf 0 .nr Si 3 .nr Tb 0 1 .de B .ie \\n(.$ .nr ;G \\n(.f .el.ft 3 .if \\n(.$ .if !\\n(.$-2 \&\f3\\$1\fP\\$2 .if \\n(.$-2 \{.ds }i .if \\n(.f2 .ds }i \^ .ds }I \&\f3\\$1\fP\\$2\\*(}i 'br\} .if \\n(.$-2 .if !\\n(.$-4 \\*(}I\f3\\$3\fP\\$4 .if \\n(.$-4 .if !\\n(.$-6 \\*(}I\f3\\$3\fP\\$4\\*(}i\f3\\$5\fP\\$6 .if \\n(.$ .ft \\n(;G .. .de I .ie \\n(.$ .nr ;G \\n(.f .el.ft 2 .if \\n(.$ .if !\\n(.$-1 \&\f2\\$1 .if \\n(.$-1 \{.ds }i \^ .if \\n(.f2 .ds }i .ds }I \& .if \w\\$1 .ds }I \&\f2\\$1\fP\\*(}i 'br\} .if \\n(.$-1 .if !\\n(.$-3 \\*(}I\\$2\f2\\$3 .if \\n(.$-3 .if !\\n(.$-5 \\*(}I\\$2\f2\\$3\fP\\*(}i\\$4\f2\\$5 .if \\n(.$-5 \\*(}I\\$2\f2\\$3\fP\\*(}i\\$4\f2\\$5\fP\\*(}i\\$6 .if \\n(.$ .ft \\n(;G .. .de R .ft1 .ul0 .. .de XS .if !\\n(1T .BG .ds XL \\n(PN .if \\n(.$ .ds XL \\$1 .nr SJ \\n(.j .nr PF \\n(.f .nr PX \\n(.s .nr SL \\n(.l .ls 1 .br .da XT .if \\n(.$-1 \{\ . nr XI 1 . in \\$2n .\} .ft 1 .ps \\n(PS .ll \\n(LLu-8n .na .sp \\n(PDu .. . \" XA - add index entry .de XA .if !\\*(XLno \\a\\t\\*(XL .if \\n(.$ .ds XL \\$1 .sp \\n(PDu .if \\n(.$-1 \{\ . nr XI 1 . in \\$2n .\} .. . \" XE - end index entry .de XE .if !\\*(XLno \\a\\t\\*(XL .br .da .ls .ad \\n(SJ .ft \\n(PF .ps \\n(PX .ll \\n(SLu .if \\n(XI \{\ . nr XI 0 . in 0 .\} .. . \" PX - print index (table of contents) .de PX .if \\n(VS>=40 .vs \\n(VSu .if \\n(VS<=39 .vs \\n(VSp .ll \\n(LLu .lt \\n(LTu .ta \\n(LLu-5n \\n(LLuR .in 0 .nf .rs .if !\\$1no \{\ . sp .5i . tl ''\f3\s+2Table of Contents\s-2\f1'' . sp .5i .\} .XT .. .de TC .bp 1 .af PN i .ds RF \\$1 - \\\\n(PN .ps 14 .ce .B CONTENTS .sp 2 .LP .ps 14 \fBChapter \\$1\fP - \\$2 .ps 11 .sp 2 .PX no .. .de MT .bp 1 .ev 1 .bp 1 .af PN i .ps 14 .ev .ds RF \\$1 - \\\\n(PN .ps 14 .ce .B CONTENTS .sp 2 .LP .ps 14 \fBChapter \\$1\fP - \\$2 .ps 11 .sp 2 .PX no .. .de NH .if \\n(:F .)D "H:missing FE" .if \\n(:y .)D "H:missing DE" .if !\\n(.$ .)D "H:missing arg" .nr ;0 0 .if \\$1-7 .nr ;0 1 .if \w\\$1-\w'0'u .nr ;0 1 .if \\n(;0 .)D "H:bad arg:\\$1" .LC 0 .br .)R .nr ;1 0\\$1 .if !0\\$1 .nr ;1 \\n(Hu .if !\\n(;1 .)D "H:bad arg:\\$1" .if 2-\\n(;1 .nr H2 0 1 .if 3-\\n(;1 .nr H3 0 1 .if 4-\\n(;1 .nr H4 0 1 .if 5-\\n(;1 .nr H5 0 1 .if 6-\\n(;1 .nr H6 0 1 .if 7-\\n(;1 .nr H7 0 1 .if 2-\\n(;1 \{.if \\n(:S .)w .if \\n(:C .nr :p 0 1 \} .SP .5 .nr :u 0 .if \\n(;1-1 .nr H\\n(;1 +1 .if !\\n(;1-1 \{.nr :u 1 .SP 1 \} .if \\n(;1-1 .if (\\n(Ej+1-\\n(;1)&(\\n(;L\{\ .bp .nr ;L 0\} .if \\n(;1-1 .if (\\n(Ej+1-\\n(;1)&(\\n(nl-\\n(:J) \{.if \\n(;C .nr ;C 2 .bp\} .if !\\n(;1-1 \{.if (\\n(Ej+\\n(:S)&(\\n(nl-\\n(:J) \{.if \\n(;C .nr ;C 2 .bp\} .if !\\n(:u-1 .nr H1 +1 .if (\\n(:u=1)&(\\n(:S=1) .nr P 1 \} .nr :u 0 .ds }0 \\n(H1. .if 0\\$1-1 .as }0 \\n(H2 .if 0\\$1-2 .as }0 .\\n(H3 .if 0\\$1-3 .as }0 .\\n(H4 .if 0\\$1-4 .as }0 .\\n(H5 .if 0\\$1-5 .as }0 .\\n(H6 .if 0\\$1-6 .as }0 .\\n(H7 .ds SN \\n(H1. .if 0\\$1-1 .as SN \\n(H2 .if 0\\$1-2 .as SN .\\n(H3 .if 0\\$1-3 .as SN .\\n(H4 .if 0\\$1-4 .as SN .\\n(H5 .if 0\\$1-5 .as SN .\\n(H6 .if 0\\$1-6 .as SN .\\n(H7 \\*(SN .if \\n(Ht \{.)I \\n(;1 \\n(H1 \\n(H2 \\n(H3 \\n(H4 \\n(H5 \\n(H6 \\n(H7 .ds }0 \\*(}3. 'br\} .as}0 \ \ .if !0\\$1 .ds }0 .nr ;0 0 .if !\\n(;1-\\n(Hb .nr ;0 1 .if !\\n(;1-\\n(Hs .nr ;0 2 .ds }2 .if !\\n(;0 .if \w\\$2 .ds }2 " .nr ;3 2v .HX \\n(;1 0\\$1 "\\$2\\$3" .if \\$1<3 .nr !5 0 1 .af !5 01 .if (\\$1=1)&(\\n(Np=1) .nr !4 0 .di>A \&\\*(}0\\$2\\$3\\*(}2 .br .di .rm>A .if \\n(;0-1 .nr ;3 +.5v .ne\\n(;3u+\\n(dnu+.5p-1v .HY \\n(;1 0\\$1 "\\$2\\$3" .if \\n(;0 .na .)I \\n(;1 \\*(HF .nr ;3 1 .nr ;3 \\*(}3 .ft\\n(;3 .nr :I \\n(.s .)I \\n(;1 \\*(HP .if ((\\*(}3=0):(\w\\*(}3=0))&(\\n(;3=3)&(\\n(;0>0) .ps -1 .if !\\*(}3 .if !\\*(}30 .ps \\*(}3 .nr ;2 \w\\*(}0 .if \\n(;0 \{.in +\\n(;2u .ti-\\n(;2u \} .nr ;2 \\n(.i .if !\\n(;1-\\n(Hc .if \\n(;0 .ce \\*(}0\&\c .if \\n(;0 \&\\$2\\$3 .if !\\n(;0 \&\\$2\\$3\\*(}2\&\c .ft1 .ps \\n(:Ip .if \\n(;0 'in .if !\\n(;1-\\n(Cl .if \w\\$2 .)E \\$1 "\\$2" .SA .if \\n(;0 .br .if \\n(;0-1 .SP .5 .if \\n(;0*\\n(Hi*\\n(Pt .if !\\n(Hi-1+\\n(Pt-1 .ti+\\n(Pin .if 0\\$1*\\n(;0 .if \\n(Hi-1 .ti\\n(;2u .nr :I 1 .nr !D \\n(nl .nr !Z \\n(.k .if (\\$1=1)&(\\nN=5) \{\ .nr Fg 0 .nr Tb 0 .nr Ec 0 .nr Ex 0 \} .HZ \\n(;1 0\\$1 "\\$2\\$3" .. .de HH .af H1 \\$1 1 .af H2 \\$2 1 .af H3 \\$3 1 .af H4 \\$4 1 .af H5 \\$5 1 .af H6 \\$6 1 .af H7 \\$7 1 .. .de HU .if !\\n(.$ .)D "HU:missing arg" .H 0 "\\$1" "\\$2" .. .de LC .if \\n(:g-0\\$1 .)B .if \\n(:g-0\\$1 .LC 0\\$1 .. .de S .if !\\n(:Q .nr :Q \\nS .if !\\n(.$ .nr ;0 \\n(:Q .if \\n(.$ .if !\w\\$1 \{\ .nr ;J 2 .nr ;0 \\n(:P \} .if \w\\$1 \{\ .ie \\$1D \{\ .nr ;J 1 .nr ;0 \\nS \} .el\{\ .ie \\$1C \{\ .nr ;J 2 .nr ;0 \\n(:P \} .el\{\ .ie \\$1P \{\ .nr ;J 3 .nr ;0 \\n(:Q \} .el\{.if !\\n(;J \{\ .nr ;0 \\n(:P .nr ;0 \\$1 \}\}\}\}\} .if 0\\$1-99 .nr ;0 \\nS .if !\\n(;0 .)D "S:bad arg \\$1" .nr :Q \\n(:P .nr :P \\n(;0 .ps \\n(:Pp .nr ;J 0 .if !\\n(!Q .nr !Q \\nS+2 .if !\\n(.$-1 \{\ .ie \\n(.$ \{\ .nr ;K 1 .nr ;7 \\n(.s+2 \} .el\{\ .nr ;K 3 .nr ;7 \\n(!Q \}\} .if \\n(.$-1 .if !\w\\$2 \{\ .nr ;K 2 .nr ;7 \\n(!P \} .if \w\\$2 \{\ .ie \\$2D \{\ .nr ;K 1 .nr ;7 \\n(.s+2 \} .el\{\ .ie \\$2C \{\ .nr ;K 2 .nr ;7 \\n(!P \} .el\{\ .ie \\$2P \{\ .nr ;K 3 .nr ;7 \\n(!Q \} .el\{.if !\\n(;K \{\ .nr ;7 \\n(!P .nr ;7 \\$2 \}\}\}\}\} .if 0\\$2-99 .nr ;7 \\n(.s+2 .if !\\n(;7 .)D "S:bad arg \\$2" .nr !Q \\n(!P .nr !P \\n(;7 .vs \\n(!Pp .nr ;K 0 .. .de SA .if \\n(.$ \{.if \\$1-1 .)D "SA:bad arg:\\$1" .nr :h 0\\$1 \} 'na .if \\n(:h 'ad .. .de SP .br .el.ie !'\\n(.z'' .)S \\$1 .el\{.rr ;D ;E .nr ;4 1v .if \\n(.$ .nr ;4 \\$1v .if !(\\n(nl=\\n(:N) .nr :A 0 .nr ;4 -\\n(:Au .if \\n(;4 \{.sp\\n(;4u .nr :A +\\n(;4u \} .nr :N \\n(nl \} .. .de )S .br .if !'\\n(.z'\\*(}D' .rr ;D ;E .nr ;4 1v .if \\n(.$ .nr ;4 \\$1v .if !(\\n(.d=\\n(;D) .nr ;E 0 .nr ;4 -\\n(;Eu .if \\n(;4 \{.sp\\n(;4u .nr ;E +\\n(;4u \} .nr ;D \\n(.d .ds }D \\n(.z .. .de )B .br .nr :g -1 .)C nr :a ]a \\*(]a .[b ]b \\*(]b .)C nr :b ]b \\*(]b 'in\\n(:bu 'ti\\n(:bu .)C nr :c ]c \\*(]c .)C nr :d ]d \\*(]d .)C nr :e ]e \\*(]e .)C nr :f ]f \\*(]f .)C ds ]g ]h \\*(]h .af :a 1 .if \\n(:e .af :a \\*(]g .. .de [b .ds \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 .. .de )C .\\$1 \\$2 \\$4 .ds \\$3 \\$5 \\$6 \\$7 \\$8 \\$9 .. .de )D 'di 'di .nr :D 0 .fl ******************** .br ERROR:(\\n(.F)input line \\n(.c:\\$1 .br ******************** .tm******************** .tmERROR:(\\n(.F)input line \\n(.c:\\$1 .tm******************** .if !\\nD .ab Processing has been terminated. .. .de )I .nr ;9 0\\$1+1 .ds }3 \\$\\n(;9 .rr;9 .. .de )E .ds }3 .if \\n(:S .ds }3 \\n(H1 .am>C .)T \\n(;1 \\$1 "\\*(}0" "\\$2" \\nP \\*(}3 \\.. .. .de )T .nr ;0 \w\\$5 .if \w\\$6 .nr ;0 +\w'-'u+\w\\$6u .if \\n(;0-\\n(:a .nr :a \\n(;0 .)I \\$1 \\n(H1 \\n(H2 \\n(H3 \\n(H4 \\n(H5 \\n(H6 \\n(H7 .if \w\\$3-\\*(}3 .nr H\\$1 \w\\$3 .. .de )U .if !0\\$1-\\n(:b .sp\\n(:cu*.5v .)I \\$1 \\*(}0 .nr ;0 \\*(}3 .)I \\$1 \\*(Ci .nr ;1 \\*(}3 .)I \\$1 \\*(}2 .nr ;2 \\*(}3 .ds }3 \\$5 .if \\n(.$-5 .ds }3 \\$6\(hy\\$5 .nr :e \\n(:au-\w\\*(}3u+2n .ds }3 \h\\n(:eu\\*(}3 .ds }y .nr ;0 -\w\\$3 .if \\n(;0 .as }y \h\\n(;0u .if 2-0\\$1 .as }y "\\$3 .if 0\\$1-1 .ds }y "\\$3\\*(}y .if !0\\$2 .ds }y .ll \\nWu-\\n(:au-3n .in \\n(;2u .if !0\\$2 .in \\n(;1u .ti\\n(;1u .fi .di>A \!.cs 3 48 .if !0\\$1-\\n(:d .if !\\n(:f \\*(}y\\$4\\\\f3\\a\\\\fP\\*(}3 .if !0\\$1-\\n(:d .if \\n(:f \\*(}y\\$4\\t\\*(}3 .if 0\\$1-\\n(:d \\*(}y\\$4\\*(}3 .br \!.br \!.cs 3 .di .br .ll \\nWu .ne\\n(dnu+.5p-1v .ta \\nWu-\\n(:au-2n .nf .in 0 .na .>A .. .de )b 'ev2 .nf .?1 .?2 .?3 .?4 .br .)R .af ;P \\gP .af P 1 .nr ;P \\nP .af P \\g(;P .af ;P 1 .ie !\\n(;P%2 .tl \\*(}f .el.tl \\*(}p .ie \\n(;P=1 \{\ .ie \\nN=1 .tl \\*(}t .el.tl \\*(}b \} .el.tl \\*(}b .if \\nC .tl \\*(]C .nf .?5 .)R 'ev .. .de >W .if \\n(;C \{\ .ev1 .ll \\n(:Lu .lt\\n(:Lu .ev .nr W \\n(:Lu .nr ;W 1 \} .. .de >N .if (\\n(;l>0)&(\\n(;C=0) \{\ .ev1 .ll \\n(;lu .lt\\n(;lu .ev .nr W \\n(;lu .nr ;W 2 \} .. .de >R .ie \\n(;W=1 .nr W \\n(;lu .el.if \\n(;W=2 .nr W \\n(:Lu .if \\n(;W \{\ .ev1 .ll \\nWu .lt\\nWu .ev .nr ;W 0 \} .. .de )Q .ch )Q 200v .rs 'sp70 .. .de BS .(B .. .de BE .(E 4 .. .de (B .ev1 .)R .di>K .. .de (E .br .di .)R .ev .ie (\\n(dn=0)&(0\\$2=0) \{\ .nr ?\\$1 0 .rm>K ?\\$1 'br\} .el\{\ .ie 0\\$2>0 .nr ?\\$1 0\\$2 .el.nr ?\\$1 \\n(dn \} .nr ?0 \\n(:Uu .nr :U \\n(?1+\\n(?2+\\n(?3+\\n(?4+\\n(?5 .if (\\n(:Uu+\\n(:Mu)>(\\n(.pu-\\n(nlu-.5v) .SK .rn>K ?\\$1 .nr :o +(\\n(:Uu-\\n(?0u) .ch )n -\\n(:ou .ch )f -\\n(:ou .nr :m \\n(:Mu+\\n(:Uu .ch )b -(\\n(:ru+\\n(:Uu) .. .de )x 'nr:v \\n(:z ')y 'if\\n(:v=\\n(:z \{\ 'nr;d 1 \&\c 'SP \\n(.tu+1v 'nr;d 0 ')z \} .. .de )w 'if\\n(:z \{\ ')x ')w \} .. .de )t .br .nr !L \\n(.L .ls 1 .)r .ti\\n(.iu .nf .if \\n(:t>1 .in -\\n(;iu .rs .nr ;d 1 .>0 .)R .nr ;d 0 .ie \\n(:I>1 \{\ .if \\n(nl>\\n(:J .nr :I 0 \} .el.nr :I 0 .ls \\n(!L .in \\n(;iu .if !\\n(;q .nf .if \\n(Ds .SP .5 .nr :J \\n(nl .. .de )r .if \\n(Ds .SP .5 .if (\\n(:0>=\\n(.t)&((\\n(:0<(\\n(.p-\\n(;r-\\n(:m)):\ (\\n(nl>(\\n(.p-\\n(;r-\\n(:o/2u+\\n(;r))) \{\ .if \\n(;e \&\c .ne\\n(.tu+1v .if \\n(:I<2 .)r \} .. .de )R 'fi 'na .if \\n(:h 'ad 'nh 'if\\n(Hy 'hy 14 'in0 'ti0 'ps\\n(:Pp 'vs\\n(!Pp .. .ig .de )k .po0 .lt7.5i .ps 10 .vs 10p .ft1 .tl'--''--' .ft .vs .po .ps .lt .. . \" Macro for headers for Volume I of Khoros Manual .de J1 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIVolume I - User's Manual\fP .ds RF \\$1 - % .ds RH Chapter \\$1 - \\$2 .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" Macro for headers for Volume II of Khoros Manual .de J2 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIVolume II - Programmer's Manual\fP .ds RF \\$1 - % .ds RH Chapter \\$1 - \\$2 .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" Macro for headers for Volume III of Khoros Manual .de J3 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIVolume III - Reference Manual\fP .ds RF \\$1 - % .ds RH Chapter \\$1 - \\$2 .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" Macro for headers for Changes Document .de J5 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIAppendix C - Khoros Changes Document\fP .ds RH Changes .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" fIAppendix B header and footer .de J7 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIAppendix B - Khoros Imake Document\fP .ds RH Imake .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" Macro for headers for Glossary Document .de J6 .ds CF Release: 1.0 .ds CH .ds LF KHOROS .ds LH \fIAppendix A - Khoros Glossary\fP .ds RH Glossary .ds HF 2 3 3 3 .ds HP 16 14 14 12 .HH A 1 1 1 .nr FM 1.0i .nr HM 1.0i .nr LL 6i .nr PO 0.85i .nr PS 11 .nr VS 13 .. . \" Macro for chapter title page for Volume I of Khoros Manual .de K1 .RP .KS .B .ps 18 .sp 0.5i .ce \fIVolume I\fP .sp 2 .ce \fIKhoros User's Manual\fP .sp 6 .ce Chapter \\$1 .sp 6 .ce \s22\\$2\s0 .sp 4 .ce \s16\\$3\s0 .sp 6 .ce \s16Primary Author(s):\s0 .sp .ce \s16 \fI\\$4\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for chapter title page for Volume II of Khoros Manual .de K2 .RP .KS .B .ps 18 .sp 0.5i .ce \fIVolume II\fP .sp 2 .ce \fIKhoros Programmer's Manual\fP .sp 6 .ce Chapter \\$1 .sp 6 .ce \s22\\$2\s0 .sp 4 .ce \s16\\$3\s0 .sp 6 .ce \s16Primary Author(s):\s0 .sp .ce \s16 \fI\\$4\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for Chapter 8 title page for Volume II of Khoros Manual .de K4 .RP .KS .B .ps 18 .sp 0.5i .ce \fIVolume II\fP .sp 2 .ce \fIKhoros Programmer's Manual\fP .sp 6 .ce The \fI\\$1\fP Library .sp 4 .ce \s16\\$2\s0 .sp 6 .ce \s16Primary Author(s):\s0 .sp .ce \s16\fI\\$3\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for chapter title page for Volume III of Khoros Manual .de K3 .RP .KS .B .ps 18 .sp 0.5i .ce \fIVolume III\fP .sp 2 .ce \fIKhoros Reference Manual\fP .sp 2i .ce Chapter \\$1 .sp 6 .ce \s22\\$2\s0 .sp 4 .ce \s16\\$3\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for title page of Changes Document .de K5 .RP .KS .B .ps 18 .sp 0.5i .ce \fBAPPENDIX B\fP .sp 2 .ce 2 \s22Changes to the Khoros Programs & Libraries\s0 .sp 2 \s22since the Beta Release of Khoros 0.9\s0 .sp 2i .ce \fIKhoros Changes Document\fP .sp 1.6i .ce \s16Compiled By:\s0 .sp .ce \s16 \fI\\$1\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for glossary of Khoros Manual .de K6 .RP .KS .B .ps 18 .sp 0.5i .ce \fBAPPENDIX A\fP .sp 2 .ce \fBGLOSSARY\fP .sp 2i .ce \fIGlossary for Khoros System\fP .sp 2i .ce \s16Primary Author(s):\s0 .sp .ce \s16 \fI\\$1\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" appendix C imake .de K7 .RP .KS .B .ps 18 .sp 0.5i .ce \fBAPPENDIX B\fP .sp 2 .ce 2 \s22Khoros \fBImake\fP Symbols and Variables\s0 .sp 2i .ce \fIKhoros Imake Document\fP .sp 1.6i .ce \s16Compiled By:\s0 .sp .ce \s16 \fI\\$1\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp 1 .. . \" Macro for top of first page (of chapter) of Khoros Manual .de K0 .KS .sp .KE .ce .B \s18\\$1\s0 .R .sp 3 .. . \" Macro for chapter 1 VIFF for Volume II of Khoros Manual .de K8 .RP .KS .B .ps 18 .sp 0.5i .ce \fIVolume II\fP .sp 2 .ce \fIKhoros Programmer's Manual\fP .sp 6 .ce Chapter \\$1 .sp 6 .ce \s22\\$2\s0 .sp 4 .ce \s16\\$3\s0 .sp 6 .ce \s16Primary Author(s):\s0 .sp .ce \s16 \fI\\$4\fP\s0 .ps 11 .R .sp 2i .ce Copyright \(co\ 1992 University of New Mexico. All rights reserved. .sp 2 .ce Printed: \*(MO \n(dy, 19\n(yr .KE .P1 \ .bp .. .if !\nS .nr S 10 .if !\nW .nr W 6i .S D D .J2 9 "Configuration Management" .K2 9 "CONFIGURATION MANAGEMENT" "Configuration Management for the Khoros System" "Tom Sauer & Charlie Gage" .K0 "CONFIGURATION MANAGEMENT" .NH 1 "INTRODUCTION" .XS \s12\*(SN INTRODUCTION\s0 .XE .sp 2 .PP This chapter of the manual describes the source configuration of the Khoros system and how it is managed in a development environment. An important goal in the design of Khoros has been to create an environment that can change on a daily basis but yet not fall apart. (Surprisingly, it works most of the time.) The manager of the Khoros system will find this chapter useful, as it provides information about the organization of the Khoros system and on the utilities for installing and compiling the system. .PP Khoros is designed to work well in either a stand-alone environment or in a distributed environment. Several tools are provided to help manage the Khoros system more efficiently. Information is provided in this chapter on how to use the tools for different site configurations. .PP This chapter is organized into three sections. Section A describes the organization of the Khoros directory structure, and gives a brief explanation of the contents of each of the main directories in Khoros. Section B provides an overview of the Imake system necessary for installing and compiling Khoros, including explanations on the use of the \fBimkmf\fP, \fBmakemake\fP, and \fBmake\fP programs. This is followed by section C, which provides information on building and maintaining the Khoros srcmach tree for the support of multiple machine architectures. .sp 3 .NH 2 "ORGANIZATION OF THE KHOROS DIRECTORIES" .XS \*(SN ORGANIZATION OF THE KHOROS DIRECTORIES .XE .sp .PP An environment variable is used to define the path to the top level of the Khoros directory. This environment variable is termed \fBKHOROS_HOME\fP. The Khoros directory structure is relatively complex because it is designed to support both the development of new code (i.e. a working environment) and the distribution of the system. The addition of new routines to Khoros is done in separate directory structure called a \fItoolbox\fP. The directory structure of a toolbox is similar to the directory structure of KHOROS_HOME. The \fItoolbox\fP area is designed for the addition of new routines provided by various users of Khoros outside of the main development team. Therefore all installation of new routines for Khoros should take place in the \fItoolbox\fP source tree, and not in the KHOROS_HOME source tree. For more information on creating and installing new routines in your own \fItoolbox\fP, see Volume II, Chapter 1, specifically you should read about \fIkraftsman, composer and kinstall\fP.. .PP Please note that ANY ADDITIONS OR MODIFICATIONS TO THE KHOROS_HOME SOURCE DIRECTORY WILL NOT ALLOW REVISIONS OR PATCHES TO BE MADE TO THE KHOROS SYSTEM. THE KHOROS_HOME SOURCE TREE SHOULD NOT BE CHANGED! .PP While not imperative for those who simply intend to utilize the Khoros programs, it is most helpful for anyone who intends to add new programs to Khoros to acquire an understanding of the Khoros system directory structure. .bp .LP The following table provides a brief description of the Khoros system directory structure. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). KHOROS SYSTEM DIRECTORY STRUCTURE bin *:T{ .na Location of Khoros binaries. It may be set up as a symbolic link to binmach. .ad T} binmach:T{ .na Location of Khoros binaries if multiple machine architectures are supported. For example, in binmach/ there may be directories of bindecmips, binsun4, etc. .ad T} data:T{ .na This directory contains sample data, plots and images. .ad T} doc *:T{ .na This directory contains "pop-up" help for xvroutines. The files in doc are also used for creating the manual sections located in manual/. .ad T} dotfiles:T{ .na The dotfiles directory provides the configuration files to run Khoros applications in a proper environment. .ad T} include *:T{ .na System include files are located in this directory. See the descriptions in README.h for a brief description of each file. .ad T} lib *:T{ .na Location of compiled libraries (.a's). It may be set up as a symbolic link to libmach. .ad T} libmach:T{ .na Location of compiled libraries (.a's) if multiple machine architectures are supported. For example, in libmach/ there may be directories of libdecmips, libsun4, etc. .ad T} man *:T{ .na Contains the man1 and man3 directories for "on-line" documentation on how to execute a program. (Accessed using \fBvman\fP.) .ad T} manual:T{ .na This directory contains the documentation that is intended to be printed. .ad T} repos *:T{ .na A repository of all Khoros default files, UIS files, configuration mach files, and all template files for the Imake system. .ad T} src *:T{ .na The Khoros source tree is located here. .ad T} srcmach:T{ .na This directory is used for symbolically linked source trees if multiple machine architectures are supported. For example, in srcmach/ there may be directories of srcdecmips, srcsun4, etc. .ad T} .TE .sp 1 .LP * These directories also present under {toolbox name}. .sp 1 .PP To run Khoros, a \fIminimal\fP system requires the contents of bin, repos, man, and doc. It is likely that you will also want a data directory for examples. If you plan on doing development within Khoros, you will also need the contents of lib, include, and src. More detailed information about the contents and organization of the data, repos, and src directories are provided in the sections that follow. .bp .NH 3 "The Data Directory" .XS \*(SN The Data Directory .XE .sp .PP The \fIdata\fP directory contains images, kernels, look up tables, masks, and overlays that may be used as sample input data. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). THE DATA DIRECTORY annotate:T{ .na Annotation files for \fBeditimage\fP, \fBxprism2\fP and \fBxprism3\fP. .ad T} bitmaps:T{ .na A couple of X bitmaps created with \fBviff2xbm\fP, suitable for icons. .ad T} images:T{ .na An assortment of VIFF (visualization/image file format) files. .ad T} kernels:T{ .na VIFF images appropriate for convolution. .ad T} lut:T{ .na An assortment of VIFF (visualization/image file format) files that have interesting color maps. .ad T} masks:T{ .na Masks that can be used for the shape, clip and overlay functions in the interactive display programs. .ad T} morphokernel:T{ .na VIFF images appropriate for morphology routines. .ad T} plot_functions:T{ .na Equations and data that can be used in \fBxprism2\fP and \fBxprism3\fP. .ad T} sequences:T{ .na Image time sequences in VIFF format. .ad T} signals:T{ .na One dimensional real and complex VIFF format signals. .ad T} warp_coeffs:T{ .na Example VIFF images that contain warping coefficients for \fBvwarp\fP. .ad T} .TE .sp 2 .NH 3 "The Repos Directory" .XS \*(SN The Repos Directory .XE .sp .PP The repos directory is a repository of required files. Primarily it contains the User Interface Specification (UIS) files for xvroutines. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). THE REPOSITORY DIRECTORY Conventions:T{ .na This directory contains template pane files for \fBcantata\fP and guidelines for creating a .pane file. .ad T} animate:T{ .na The UIS file for \fBanimate\fP. .ad T} annotation:T{ .na The UIS file for annotation subforms that are used by \fBeditimage\fP, \fBxprism2\fP and \fBxprism3\fP. .ad T} cantata:T{ .na The UIS file for \fBcantata\fP is broken into subforms. Each subform file (.sub) refers to pane files (.pane). The cantata/subform subdirectory structure mimics that of the source directory structure. .ad T} composer:T{ .na The UIS file for \fBcomposer\fP, and an example .prog file. .ad T} config:T{ .na This directory contains the machine configuration and template files for the Imake system, OS and compiler specific installation scripts, and site specific mach files. .ad T} .TE .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). THE REPOSITORY DIRECTORY editimage:T{ .na The UIS file for \fBeditimage\fP. .ad T} fonts:T{ .na Includes the various vector fonts used by \fBxprism2\fP and \fBxprism3\fP. These are required because the X fonts can not be resized or rotated. .ad T} preview:T{ .na The UIS file for \fBpreview\fP. .ad T} utils:T{ .na This contains copyright templates and module header templates. \fBGhostwriter\fP uses several of the files. .ad T} viewimage:T{ .na The UIS file for \fBviewimage\fP. .ad T} warpimage:T{ .na The UIS file for \fBwarpimage\fP. .ad T} workspace:T{ .na Several demo and test workspaces illustrating some of \fBcantata's\fP visual programming capabilities. .ad T} xprism:T{ .na The UIS files for \fBxprism2\fP and \fBxprism3\fP. .ad T} journal:T{ .na Journal playback files for demos of xvroutines. .ad T} .TE .sp 3 .NH 3 "The Source Directory" .XS \*(SN The Source Directory .XE .sp .PP Within the \fIsrc\fP directory there are many levels of subdirectories. These subdirectories were chosen to categorize functions with similar functionality. For instance, you will find a \fILib\fP directory at the top of source and also in dspl, file_formats, num_analysis, remote_gis, vipl and xvroutines. The top level \fILib\fP contains libraries that are needed across the system. The lower level \fILib\fP directories contain source for libraries local to that functional category. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). THE SOURCE DIRECTORY Lib:T{ .na This directory contains several libraries that are required by the entire system. .ad T} dspl:T{ .na Similar to vipl, except it contains one dimensional signal processing algorithms. .ad T} file_formats:T{ .na This directory contains a collection of programs for converting to and from VIFF format. .ad T} num_analysis:T{ .na This directory contains programs for matrix manipulations. .ad T} public_domain:T{ .na This directory contains subdirectories which contain the public domain software which are used by Khoros. .ad T} remote_gis:T{ .na This directory contains routines specific to remote sensing and GIS applications. .ad T} scripts:T{ .na This directory contains subdirectories of csh script files used by Khoros. .ad T} .TE .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). THE SOURCE DIRECTORY tools:T{ .na This directory contains subdirectories of programs used to manage the Khoros source tree. .ad T} vipl:T{ .na This directory contains all the image processing driver programs. Within this directory, each subdirectory is dedicated to a a specific area of image processing. Below each of these is a subdirectory named for a specific program. .ad T} xvroutines:T{ .na This directory contains all source for xvroutines. Below this is a Lib directory and a subdirectory for each program. .ad T} bootstrap:T{ .na Programs necessary to boot the Khoros system. The programs in this directory must be compiled before anything else can be compiled. .ad T} .TE .sp 1 .LP To get a better understanding of how the \fIsrc\fP directory is arranged, the following diagram is provided to graphically illustrate the src directories and some of their subdirectories. Under \fIsrc\fP we have several subdirectories containing 1D and 2D data processing algorithms, file format conversion routines, and remote sensing/GIS routines. The categories were chosen to accommodate the broad spectrum of algorithms that exist in Khoros. .bp .DS .ps 9 .vs 11 \f(CW |-ghost---------- |-verror--------- |-Lib-----------|-vexpr---------- | |-vgparm--------- | |-* | | |-Lib------------ | |-filter_1Dfreq-- |-dspl----------|-filter_1Dtime-- | |-info----------- | |-* | | |-Lib------------ |-file_formats--|-no_format------ | |-remote_gis----- | |-standard------- | |-num_analysis--|-Lib------------ | |-matrix_algebra- | | |-eispack-------- | |-imake---------- |-public_domain-|-linpack-------- | |-makedepend----- | |-tiff----------- |-src-| | |-Lib------------ |-remote_gis----|-surface-------- | |-vector--------- | |-warp----------- | |-scripts-------|-cantata-------- | |-tools---------- | | |-formatdoc------ | |-ghostcheck----- |-tools---------|-helppage------- | |-imkmf---------- | |-* | | |-Lib------------ | |-arith_binary--- |-vipl----------|-arith_logical-- | |-arith_unary---- | |-* | | |-Lib------------ | |-animate-------- |-xvroutines----|-cantata-------- |-composer------- |-* * - more directories follow \fP .DE .bp .sp 2 .NH 4 "The \f(BIsrc/dspl\fP Directory" .XS \*(SN The \fIsrc/dspl\fP Directory .XE .sp .PP The table below describes the taxonomy for the 1D data processing algorithms. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). 1D DATA PROCESSING ORGANIZATION filter_1Dfreq:T{ .na These routines operate on signals in the frequency domain. .ad T} filter_1Dtime:T{ .na These routines operate on signals in the time domain. .ad T} info:T{ .na These routines are designed to provide the user with information about a signal. .ad T} input_create1D:T{ .na These routines generate a signal based on functions or user specifications. .ad T} linearop1D:T{ .na A collection of routines that provide "classical" linear theory operations. They include convolution, correlation, etc. .ad T} modify_seq1D:T{ .na A collection of routines designed to manipulate signals or portions of signals. .ad T} spectest1D:T{ .na These routines provide several methods for estimating the spectral content of a signal. .ad T} transform1D:T{ .na These routines are used to go to and from the Fourier Domain and perform operations in the Fourier Domain. .ad T} .TE .sp 2 .NH 4 "The \f(BIsrc/vipl\fP Directory" .XS \*(SN The \fIsrc/vipl\fP Directory .XE .sp 1 .PP Because of historical reasons, \fIvipl\fP forms the base set of the data processing programs in Khoros. The categories of num_analysis, remote_gis, dspl, and file_formats have some dependencies on \fIvipl\fP. .PP The table below describes the taxonomy for the 2D data processing algorithms. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). 2D DATA PROCESSING ALGORITHM ORGANIZATION arith_binary:T{ .na These routines use two images to produce a single output image. They also may use a masking image to gate what is used from one of the input images. The operations are arithmetic operations performed on a pixel by pixel basis from the two images or signals. .ad T} arith_logical:T{ .na These routines perform logic operations on a pixel by pixel basis. .ad T} arith_unary:T{ .na These routines use one image to produce a single output image. The operations performed are arithmetic point operations done on a pixel by pixel basis. Several of the operations may be used with an optional masking image or signal. .ad T} classify:T{ .na These routines are used to perform supervised or unsupervised classification. .ad T} .TE .br .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). 2D DATA PROCESSING ORGANIZATION convert_color:T{ .na These routines use images with multiple bands representing a specific color to create images which are mapped into other color spaces. .ad T} convert_compr:T{ .na Currently includes only a driver for existing compression algorithms. The purpose is to reduce the amount of data needed to store an image. .ad T} convert_data:T{ .na These routines change the data storage size/type of VIFF image. .ad T} feature:T{ .na These routines calculate various feature measurements of images. .ad T} filter_2Dfreq:T{ .na These routines operate on images in the frequency domain. .ad T} filter_2Dspatl:T{ .na These routines operate on images in the time domain. .ad T} filter_morph:T{ .na These routines operate in the spatial domain using morphology filters. .ad T} geomanip:T{ .na These routines alter the location of pixels in an image or signal by expanding, shrinking, rotating, etc. .ad T} histogram:T{ .na These routines modify the histogram of an image or display the current histogram of an image. .ad T} info:T{ .na A collection of routines designed to provide the user with information about an image. .ad T} input_create2D:T{ .na These routines generate an image based on functions or user specifications. .ad T} map:T{ .na These routines manipulate the color maps of an image. .ad T} output_dither:T{ .na These routines convert images to a black pixel/white pixel image for use on monochrome screens or printers without pre-dithering algorithms. .ad T} output_print:T{ .na These routines are used to format and send an image to a printer. .ad T} segment:T{ .na These routines are intended to define regions of an image as a function of grey level pixel values. .ad T} subregion:T{ .na These routines are designed to extract and manipulate subimages. .ad T} transform2D:T{ .na These routines are used to go to and from the Fourier Domain and perform operations in the Fourier Domain. .ad T} .TE .sp 2 .NH 4 "The \f(BIsrc/file_formats\fP Directory" .XS \*(SN The \fIsrc/file_formats\fP Directory .XE .sp .PP The following table describes the taxonomy for the file format conversion algorithms. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). FILE FORMAT ORGANIZATION no_format:T{ .na These routines are for converting ascii and raw images to VIFF format, and from raw to VIFF format. .ad T} remote_gis:T{ .na These routines are for converting to and from the VIFF format to remote sensing and GIS file formats. .ad T} standard:T{ .na These routines are for converting to and from the VIFF format to several other popular file formats. .ad T} .TE .sp 3 .NH 4 "The \f(BIsrc/remote_gis\fP Directory" .XS \*(SN The \fIsrc/remote_gis\fP Directory .XE .sp 2 .PP The table below describes the taxonomy for the remote sensing and GIS algorithms. .sp .TS tab(:) allbox; c s lw(1.0i) lw(4.5i). REMOTE SENSING AND GIS ALGORITHM ORGANIZATION surface:T{ .na A collection of routines designed to compute surface normals and correct the illumination gradient in an image. .ad T} vector:T{ .na These routines manipulate the color maps and bands of dlg images. .ad T} warp:T{ .na These routines are for performing image registration of images. .ad T} .TE .br .bp .NH 1 "THE KHOROS IMAKE SYSTEM .XS \s12\*(SN THE KHOROS IMAKE SYSTEM .XE .sp 2 .PP .nh The Khoros system is designed to be run on a variety of platforms and as such needs a common method which allows Khoros to be compiled and installed on different architectures. The method that was chosen uses \fIImakefiles\fR and the utility \fBimake\fR, the same utility used by MIT with the X11 source. \fBImake\fP allows architecture dependent \fIMakefiles\fP to be automatically generated from an \fIImakefile\fP specification. .PP Khoros uses a series of \fIImakefiles\fR which are created from a set of template files. Each \fIImakefile\fR in turn includes a ``specification file'', that defines which \fBimake\fR rules are applied for making the resulting \fIMakefile\fP. The resulting architecture dependent \fIMakefile\fP is then used to compile and install programs, libraries, and shell scripts. .sp 2 .NH 2 "BACKGROUND" .XS \*(SN BACKGROUND .XE .sp .PP .nh The \fBimake\fR and \fIImakefile\fR environment created for MIT X11 was not intended for software development. It was primarily set up to help compile and install a `final product', on many different hardware architectures. Khoros, on the other hand, uses \fBimake\fR and \fIImakefiles\fR while in the development of the `final product' allowing users and developers to extend Khoros. As a result, many modifications were necessary to allow Khoros to be able to use \fIImakefiles\fR. These modifications necessitated the creation of a set of files similar in nature to the `normal' \fBimake\fR definition and configuration files, but allow Khoros to use \fBimake\fR other ways To help manage the growth of Khoros during its development, \fBimkmf\fR and \fBmakemake\fR were built to aid in the creation of \fIImakefiles\fR and \fIMakefiles\fR in a consistent and easy manner. These tools allow a software developer to easily add to a `final product' without having to spend an inordinate amount of time learning about \fBimake\fR and \fIImakefiles\fR. .PP This manual section covers various aspects of how Khoros uses \fIImakefiles\fR using the utility \fBimkmf\fR, how to install Khoros using the existing \fIImakefiles\fR, and how to integrate new sources into Khoros or to move/rename existing sources. .PP This document does not go into any details on the specifics of how \fBimake\fR works, but enough information is given to compile and manage the Khoros \fBimake\fP system. For more details, it is suggested that the reader consult the following references. .sp .IP "Configuration Management in the X Window System," Fulton, Jim (found in MIT X.V11R4 source in mit/doc/config/usenixws/paper.ms) .sp .IP "An \fIImake\fR Tutorial," Moraes, Mark, November 24, 1989 (found in MIT X.V11R4 source in contrib/doc/imake/imake.tex) .sp 2 .NH 2 "KHOROS IMAKE TOOLS: imake, makemake, imkmf, makedepend" .XS \*(SN KHOROS IMAKE TOOLS: imake, makemake, imkmf, makedepend .XE .PP Four main utility programs are used to manage the Khoros \fBimake\fP system. These programs include \fBimake\fP, \fBmakemake\fP, \fBimkmf\fP, and \fBmakedepend\fP. \fBImake\fP and \fBmakedepend\fP are low-level tools called by \fBmakemake\fP and/or \fBimkmf\fP. \fBMakemake\fP and \fBimkmf\fP are used frequently to update and build both \fIMakefiles\fP and \fIImakefiles\fP. For specific information on how to use these tools, consult the Khoros manpages makemake(1), imkmf(1), imake(1) and makedepend(1). The following paragraphs provide a brief introduction to each of these utility programs. .PP The utility \fBimake\fP is a low level configuration tool. \fBImake\fP takes an Imakefile with a set of specifications defined in \fIKHOROS_HOME/repos/config/imake_conf\fP and generates a architecture specific \fIMakefile\fP. \fBImake\fP uses the C preprocessor (cpp), taking advantage of its include-file and macro-processing facilities for the purpose of generating \fIMakefiles\fP suitable for \fBmake\fP. .PP The Khoros utility \fBmakemake\fR is a shell script that calls \fBimake\fR with all of the necessary arguments to successfully \fBmake\fR or update a \fIMakefile\fR from an \fIImakefile\fR. Currently, the \fBmakemake\fR script contains the following command: .in +1i .nf \f(CW imake \\ -DKHOROS_TEMPLATE=\\"Khoros.tmpl\\" \\ -DKHOROS_HOME=$KHOROS_HOME \\ -D{toolbox_defines} \\ -T$KHOROS_HOME/repos/config/imake_conf/Khoros.tmpl \\ -I$KHOROS_HOME/repos/config/imake_conf \\ -I{toolbox_includes} \\ -I$KHOROS_HOME/repos/config/imake_tmpls \fR .in -1i .fi .sp 1 These arguments to \fBimake\fR specify \fI$KHOROS_HOME/repos/config/imake_conf/Khoros.tmpl\fR as the basic startup file which in turn includes all of the other necessary files, including the current directory's \fIImakefile\fP (\fI./Imakefile\fR). \fBImake\fR will first look in the directory \fI$KHOROS_HOME/repos/config/imake_conf\fR for the \fBimake\fR specification files. It will then search all the toolbox \fIrepos/config/imake_conf\fR directories for the toolbox definition file. Figure 1 Section B.3.1 shows the files that \fBimake\fR includes in the process of making a \fIMakefile\fR. .PP The \fBimkmf\fP utility automatically generates an \fIImakefile\fP, assuming that one does not already exist, or updates an already existing one to contain information sufficient to compare the files contained in the directory. If an \fIImakefile\fP does not exist, \fBimkmf\fP copies a template, specified on the command line with `-type', into the current directory and then proceeds to update it. Revision is accomplished by reviewing of all the files in the current directory and updating any existing "definition" that \fBimkmf\fP uses. \fBimkmf\fP uses the template \fIImakefiles\fP that can be found in $KHOROS_HOME/repos/config/imake_tmpls/. These template files include different specifications to compile a program (independent or dependent of X11, independent or dependent on Fortran), to create a library, to continue making in sub-directories, and to install shell scripts. All of these templates contain empty \fBmake\fR definitions which are filled in by \fBimkmf\fR. The templates available are: .sp .in +1i .nf Imakefile.p \(em for programs which are independent of X11 Imakefile.pf \(em for programs which are dependent on Fortran and independent of X11 Imakefile.x \(em for programs which are dependent on X11 Imakefile.xf \(em for programs which are dependent on Fortran and X11 Imakefile.l \(em for libraries Imakefile.d \(em for directories Imakefile.s \(em for scripts .in -1i .fi .PP Finally, the \fBmakedepend\fP utility is used to generate file dependencies for C source files in each directory after the \fIMakefile\fP has been built. Dependencies of C files upon objects can be statically listed in the \fIImakefile\fP, but dependencies for header files (.h files) can not. Since different architectures organize dependencies for header files differently, these dependencies must be generated dynamically for each architecture. \fBMakedepend\fP is called automatically when a \fIMakefile\fP is generated or updated using \fBmakemake\fP. .sp 2 .NH 2 "CONFIGURING THE KHOROS IMAKE SYSTEM" .XS \*(SN CONFIGURING THE KHOROS IMAKE SYSTEM .XE .PP Before Khoros can be compiled on a platform, the \fIimake\fP system must be configured. The configuration consists of editing some of the \fIimake\fP include-macro files. Before discussing the specifics required to compile Khoros, an overview of the \fIimake\fP symbol and macro construct and the include-macro files is given. This will, hopefully, give one a clearer idea of how \fIimake\fP gathers the information necessary to build a \fIMakefile\fP. Finally, information specific to configuring the imake system is discussed. .sp 2 .NH 3 "\fBImake\fP Symbol and Macro Construct" .XS \*(SN \fBImake\fP Symbol and Macro Construct .XE .PP The \fBimake\fP system uses symbol and macro constructs to gather information necessary to generate a \fIMakefile\fP. The symbol and macro constructs are defined in the Khoros \fBimake\fP configuration files. The configuration files are discussed in the next subsection. .PP \fBImake\fP passes its input through the C preprocessor (cpp) so that the definitions in the configuration files can take advantage of several features not present in \fBmake\fP. The features include parameterized macros (using #define), file inclusion (using #include) and conditional testing (using #if, #ifdef and #ifndef). .PP The flexibility of the Khoros configuration files is achieved through the following construct, which defines a \fIsymbol\fP only if it has not previously been defined: .in +1i .nf \f(CW#ifndef symbol #define symbol #endif\fP .fi .in -1i .PP This construct allows any system, library, or build symbol to be given a default definition if none has previously supplied. This definition construct along with support for inclusion of platform, site and library specific files prior to the section in which the default symbols are defined, provides the ability to build a hierarchy for defining symbols. For example, the default C compiler symbol, \fICcCmd\fP, occurs in the build section of the \fIKhoros.tmpl\fP file and is defined as: .in +1i .nf \f(CW#ifndef CcCmd #define CcCmd cc #endif\fP .fi .in -1i However, suppose you want to use \fIgcc\fP as the C compiler rather than \fIcc\fP. The \fICcCmd\fP can be overridden by putting the following symbol definition in either the \fISite.def\fP or \fIplatform.cf\fP file. .in +1i .nf \f(CW#ifndef CcCmd #define CcCmd gcc #endif\fP .fi .in -1i .PP The pattern followed in the the system/build section of the \fIKhoros.tmpl\fP file is that definitions for \fIcpp\fP symbols are listed first, followed by definitions for \fImake\fP variables. The strategy adopted is to associate a \fIcpp\fP symbol with a given \fImake\fP variable by equating the \fImake\fP variable to a given \fIcpp\fP symbol. The example below illustrates this concept: .in +1i .nf \f(CW#ifndef CcCmd #define CcCmd gcc #endif . . . CC=CcCmd\fP .fi .in -1i .PP For a listing of all \fIcpp\fP symbols and \fBimake\fP rules, consult Vol 2, Appendix C, Imake Symbols and Variables. This appendix is helpful when either determining which \fIcpp\fP symbol to change/set for a correct compile and when porting to a new architecture. .sp 2 .NH 3 "\fIImake\fP Configuration Files" .XS \*(SN \fIImake\fP Configuration Files .XE .PP To produce a \fIMakefile\fP from an \fPImakefile\fP, the \fBimake\fP utility uses configuration files located in \fI$KHOROS_HOME/repos/config/imake_conf\fP. The following list briefly describes each configuration file: .in +1i .nf Khoros.tmpl \(em Master template file used to generate the Makefile \fIplatform\fP.cf \(em Platform-specific definitions (the filename varies) Site.def \(em Site-specific definitions Library.def \(em Library specific definitions Khoros.rules \(em \fIcpp\fR macros to generate \fImake\fR rules \fItoolbox\fP.def \(em Toolbox-specific definitions (the filename varies) .in -1i .fi .PP Figure 1 below shows how the configuration files are included and processed by \fBimake\fP to produce a Makefile. The \fIKhoros.tmpl\fP file contains a #include line for each of the other four configuration files and for the \fIImakefile\fP, and the \fIImakefile\fP contains a #include line for the \fItoolbox\fP.def file. The \fIKhoros.tmpl\fP file also contains in-line sections for a header block section, a description of system characteristics, build definitions and \fIextra make\fP rules. .PP The \fIKhoros.tmpl\fP file contains all the default symbol definitions for the Khoros \fBimake\fP system. Symbols defined in the \fIplatform.cf\fP file will override the same symbols in the \fISite.def\fP, \fILibrary.def\fP and \fIKhoros.tmpl\fP files. Subsequently, symbols defined in the \fISite.def\fP file, which have not previously been defined in the \fIplatform.cf\fP file will override the same symbols in the \fILibrary.def\fP and \fIKhoros.tmpl\fP files. Any symbols defined in the \fItoolbox\fP.def file will override the same symbols in all the previously included imake configuration files. Note: the \fIImakefile\fP should only contain \fBmake\fP variables; it should not contain \fIcpp\fP symbols. A \fBmake\fP variable defined in the \fIImakefile\fP will override all previous declarations of that variable since the variable is made by assignment rather than defined. .bp .KF .sp 2 .TS center box tab (%) ; l s s l l l l l l l _ l l | l | l l _ l l _ l l | l | l l _ l l l l l _ l l | l | l l _ l l _ l l | l | l l _ l l _ l l | l | l l _ l l _ l l | l | l l | l | l l _ l l l l l l l l l . \fIKhoros.tmpl\fR % %Header Blocks % %#include \fI"Platform.cf"\fR % % %#include \fI"Site.def"\fR % %System description and build definitions % %#include \fI"Library.def"\fR % % %#include \fI"Khoros.rules"\fR % % %#include \fI"{Toolbox_name}"\fR % % %#include \fI"./Imakefile"\fR %T{ .in +.1i .sp .B1 .sp .5 #include \fI"*.template"\fR\ \ \ \s-4(Specific to Imakefile used)\s+4 .sp .5 .B2 .in -.1i T} % %Extra \fImake\fP rules .TE .sp .ce Figure 1. Khoros \fBimake\fR template structure .sp 3 .KE .sp 2 .NH 4 "Header Block" .XS \*(SN Header Block .XE .PP The header block section of \fIKhoros.tmpl\fP determines the type of machine on which \fBimake\fP is being run. This will allow \fBimake\fP to include the proper \fIplatform.cf\fP file when creating \fIMakefiles\fP. Most C preprocessors have unique symbols that indicate a given platform. For example, a SUN4's preprocessor defines the symbol "sun", where as the Apollo defines the symbol "apollo". If the C preprocessor does not define any such symbol, one can use the BOOTSTRAPFLAGS option with \fBimake\fP to define a unique C preprocessor symbol. \fBimake\fP is designed to pass the BOOTSTRAPFLAGS symbol to the C preprocessor for use. This is important for those trying to port Khoros to a new platform. .sp 2 .NH 4 "Platform.cf File" .XS \*(SN Platform.cf File .XE .PP After the header block section has determined which platform-specific file to use, That file is then included by \fIKhoros.tmpl\fP. The platform-specific file includes symbol definitions necessary to build Khoros on a particular system. Overall these files are usually a conglomeration of symbol definitions, make variables and imake rules. This file must be edited before attempting to compile Khoros. Appendix C, Vol 2, "Imake Symbols and Variables" will aid in determining which symbol definitions need to be changed or added. .sp 2 .NH 4 "Site.def File" .XS \*(SN Site.def File .XE .PP This file contains site-specific definitions. This file should reflect site-wide conventions. The \fISite.def\fP file is a good place to override symbol defaults defined in the \fIKhoros.tmpl\fP file, at least in theory. This file works fine if Khoros is going to be installed and maintained on only one platform. If Khoros is going to be installed and/or maintained on multiple platforms, it is best make changes in the \fIplatform.cf\fP file rather than the \fISite.def\fP file. This \fISite.def\fP is, in a sense, global; symbol defines for one platform might not be correct for a different platform. .sp 2 .NH 4 "System Description and Build Definitions" .XS \*(SN System Description and Build Definitions .XE .PP The inclusion of platform-specific and site-specific files in the \fIKhoros.tmpl\fP are followed by a section containing some default symbol definitions. This section will make sure that symbols, such as CcCmd, get defined that have not previously been defined. This section is also where \fBmake\fP variables get equated to \fIcpp\fP symbols. This section of the \fIKhoros.tmpl\fP should not be modified; definitions should be overridden in the platform-specific and site-specific files. .sp 2 .NH 4 "Library.def File" .XS \*(SN Library.def File .XE .PP The \fILibrary.def\fP file contains symbol definitions and \fBmake\fP variable equates for the Khoros libraries and programs. This file defines the system libraries, X11R4 libraries, Fortran libraries and Khoros libraries necessary to build Khoros. Most of the symbol definitions and \fBmake\fP variables in this file do not have defaults in the \fIKhoros.tmpl\fP file. The \fILibrary.def\fP file is included after the \fISite.def\fP and \fIplatform.cf\fP files. .sp 2 .NH 4 "Khoros.rules File" .XS \*(SN Khoros.rules File .XE .PP This file contains the \fIcpp\fP macros used to generate \fBmake\fP rules for the \fIMakefiles\fP. This file should not be modified. If rule changes need to be made, the \fIplatform.cf\fP file is the place to make changes. Consult the \fIsgi.cf\fP file for an example. .sp 2 .NH 4 "toolbox.def File" .XS \*(SN toolbox.def File .XE .PP This file contains the symbol definitions for a particular toolbox. All the symbol definitions specified in this file will override the same symbol definition that was previously defined. This file exists in each toolbox in the repos/config/imake_conf directory. The \fBimkmf\fP program will automatically include this file. If the "-toolbox" \fBimkmf\fP option is not used on the command line, the default toolbox definition file for KHOROS_HOME will be used. It is located in $KHOROS_HOME/repos/config/imake_conf/Toolbox.def. If the "-toolbox {toolbox_name}" option is specified, the $TOOLBOX_NAME/repos/config/imake_conf/{toolbox_name}.def file will be used. For more information on setting up and managing toolboxes, consult Vol 2, Chapter 1, specifically read about \fBkraftsman, composer and kinstall\fP. .sp 2 .NH 4 "./Imakefile File" .XS \*(SN ./Imakefile File .XE .PP The last file included in the \fIKhoros.tmpl\fP file is the \fIImakefile\fP from the current directory. The Khoros \fIImakefiles\fP define the sources, objects, header files and necessary libraries needed to compile. \fIImakefiles\fP should always be generated using the progarm \fBimkmf\fP. .sp 2 .NH 4 "Extra Make Rules" .XS \*(SN Extra Make Rules .XE .PP The last section of the \fIKhoros.tmpl\fP file defines some of the common \fBmake\fP targets such as "clean", "tags", etc. These definitions should not be modified. .sp 2 .NH 3 "Khoros \fIImakefile\fP Templates" .XS \*(SN Khoros \fIImakefile\fP Templates .XE .PP The Khoros \fBimake\fP system uses template \fIImakefiles\fP when generating \fIImakefiles\fP. The utility \fBimkmf\fP uses the template files in \fI$KHOROS_HOME/repos/config/imake_tmpls\fP to make an \fIImakefile\fP. .PP All of the \fIImakefile\fR templates, besides containing the \fBmake\fR definitions to be filled in by \fBimkmf\fR, contain ``include'' references to other files that contain specifications which are common to all of the \fIImakefile\fR templates. Templates \fIImakefile.p\fR and \fIImakefile.x\fR include the file \fIProg.template\fR; \fIImakefile.pf\fR and \fIImakefile.xf\fR include the file \fIFProg.template\fR; \fIImakefile.l\fR includes the file \fILib.template\fR; \fIImakefile.d\fR includes the file \fIDir.template\fR and \fIImakefile.s\fR includes the file \fIScrpt.template\fR. Note, these files should never have to be touched, changes to the imake system should be made through the \fIplatform.cf\fP files, the \fISite.def\fP file and the \fILibrary.def\fP file located in \fI$KHOROS_HOME/repos/config/imake_conf\fP. .PP .nh The \fI*.template\fR files contain the \fBimake\fR specifications instead of the \fIImakefile\fR templates themselves because if a ``rule'' needs to be added or modified which changes the way \fIImakefiles\fR work, for example compiling a library, then only a single file, in this case \fILib.template\fR, needs to be updated instead of all library \fIImakefiles\fR. .sp 2 .NH 2 "KHOROS INSTALLATION CONFIGURATION" .XS \*(SN KHOROS INSTALLATION CONFIGURATION .XE .sp .PP Before the installation can begin, there are three files that need to be checked for correctness to insure proper installation of Khoros. All three files are located in \fI$KHOROS_HOME/repos/config/imake_conf\fR and contain symbol definitions to override default specifications. .PP The first file, \fIplatform.cf\fR, where \fIplatform\fP is the architecture of your machine. For example, use the file "sun.cf" if you are on a Sun, use the file "ultrix.cf" if you are on a Decmips, use the file "sgi.cf" if you are on a SGI machine. The \fIplatform.cf\fR file contains machine specific symbol defines. If is important to set the symbols to the correct value. For example, if your system does not have a Fortran compiler, then set the symbol "HasFortran" to NO, if your system does not support Saber-C, set the symbol HasSaberC to NO. .PP The next file that needs to be modified is the \fISite.def\fP file. It is suggested that the file not be changed. It is better to copy the symbols that need changing into the \fIplatform.cf\fR file, and make the changes in the \fIplatform.cf\fR file. The reason for this is because if you are going to support Khoros on more than one architecture the \fIplatform.cf\fR will override the \fISite.def\fP file. The \fISite.def\fP file is a "global" file where as the \fIplatform.cf\fR is local to a particular platform. .PP The symbols in the \fISite.def\fP file define where the Khoros binaries, libraries, man pages, and source directories exist. Also, this file contains some of the common symbols that need to be overridden from the defaults. Note, many of the symbols in the \fISite.def\fP file will appear in the \fIplatform.cf\fR file. .PP The last file that needs to be modified is the \fILibrary.def\fR file. This file contains the symbol defines for which libraries are necessary to link against. The only symbols that should be changed in this file are \fILibDir, SysLibs, XLibs, ForSysLibs, and ExtraLibs\fP. .sp 2 .NH 3 "Multiple Architectures" .XS \*(SN Multiple Architectures .XE .PP If you plan to support Khoros on multiple architectures, then all changes to the \fBimake\fP system should be made in the \fIplatform.cf\fR file. The \fISite.def\fP and \fILibrary.def\fR file act as "global" files for symbol defines, whereas the \fIplatform.cf\fR file is local to a particular architecture. Again, any symbol that is defined in the \fIplatform.cf\fR file will override the same symbol in the \fISite.def\fP and \fILibrary.def\fR file. .sp 2 .NH 3 "Commonly Asked Questions" .XS \*(SN Commonly Asked Questions .XE .PP Below are a few commonly asked questions about the \fBimake\fP configuration files. We suggest that the symbol defines discussed below are put in the \fIplatform.cf\fR file. .RS .IP Q: X11 directories are not in the "standard" place on my machine, how do I specify where the X11 directories exist? .IP A: define the symbol "XLibDir" to the directory where the X11 libraries exist .br .nf \f(CW#define XLibDir /usr/local/lib/X11\fP .fi .sp define the symbol "XIncludes" to the directory where the X11 include directory exists. .br .nf \f(CW#define XIncludes -I/usr/local/include\fP .fi .RE .RS .IP Q: Fortran libraries are in /usr/lang rather than in /usr/lib, how do I change where to look for Fortran libraries? .IP A: define the symbol "FortranLibDir" to the directory where the Fortran libraries exist .br .nf \f(CW#define FortranLibDir /usr/lang\fP .fi .RE .RS .IP Q: I need to add some other libraries to compile against, how do I add these extra libraries? .IP A: define the symbol "ExtraLibs" to the directory where the libraries exist .br .nf \f(CW#define ExtraLibs /myhome/foobar\fP .fi .RE .RS .IP Q: How do I make the libraries load with a different option than the C programs load with? .IP A: define the symbol "LibraryLdCmd" to the command that you want the libraries to load with and the "LdCmd" to the command that you want the C programs to load with. .br .nf \f(CW#define LibraryLdCmd ld\fP \f(CW#define LdCmd cc\fP .fi .RE .RS .IP Q: How do I specify different compile options for libraries and C programs. .IP A: define the symbol "LibraryCCOptions" to the options that you want the libraries to compile with and the "DefaultCCOptions" to the options that you want the C programs to compile with. .br .nf \f(CW#define LibraryCCOptions -q -P\fP \f(CW#define DefaultCCOptions -float\fP .fi .RE .IP Q: How do I specify different compile options for Fortan libraries and Fortran object files. .IP A: define the symbol "LibraryFCOptions" to the options that you want the libraries or other Fortran object files to compile with. .br .nf \f(CW#define LibraryFCOptions -O\fP .fi .RE .PP Although many more questions about configuring the \fBimake\fP system have been asked, this set of questions and answers should give one the feel of how to make changes to the \fBimake\fP configuration files. It is strongly suggested that the document Vol 2, Appendix C, "Imake Symbols and Variables" be consulted when making changes to the \fBimake\fP symbols. .sp 2 .NH 2 "ADDING FILES TO KHOROS" .XS \*(SN ADDING FILES TO KHOROS .XE .sp .PP .nh At this point it is assumed that Khoros has already been successfully installed, and now other data processing programs or applications are to be added to enhance it. These enhancements may range from simply adding a new algorithm to an existing library, to something a little more difficult, such as adding a new library, program or shell script. NOTE, KHOROS SOURCE SHOULD NOT BE MODIFIED. MODIFICATION OF KHOROS SOURCE WILL PREVENT THE ABILITY TO UPDATE THE SOURCE WITH LATER PATCHES. New routines, libraries and scripts should be installed in a Khoros toolbox, or kept in the users local area. .PP .nh In all cases the \fIImakefiles\fR are managed by the \fBimkmf\fR utility which either creates \fIImakefiles\fR if none exist, or updates them to contain current information concerning the files in existence in the current directory. .PP It is strongly suggested that the Khoros utilities for installing and managing the Khoros source tree and the Khoros toolboxes be used rather than performing the tasks manually, as outlined below. Please consult the "Writing Programs" documentation Vol 2, Chapter 1, and the Configuration Management documentation Vol 2, Chapter 9, Section A before installing a new routine. The utilities that may be helpful for managing Khoros and Khoros toolbox source include: \fBkraftsman, kmakeall, kinstall, kdinstall, krmprog, ksrcconf, and klnfile\fP. Use \fBvman\fP to obtain more information on these tools. .sp 2 .NH 2 "UPDATING \f(BIImakefiles\fP" .XS \*(SN UPDATING \fIImakefiles\fP .XE .sp .PP .nh .PP .nh If all the \fIImakefiles\fR in a subdirectory need to be updated or changed to reflect changes made to the \fIImakefile\fR templates, probably as a result of adding a new library (see EXAMPLE 2), then all that needs to be done is to cd into the directory and run \fBmake AllImakefiles\fR. The \fIImakefiles\fR have built into them the necessary information so that \fBimkmf\fR gets called with the correct arguments. .PP If the \fIImakefiles\fP need to be completely regenerated, the command \fBmake GenAllImakefiles\fP, will remove the existing \fIImakefiles\fR and recreate them. The difference between \fBmake AllImakefiles\fR and \fBmake GenAllImakefiles\fP is \fBmake AllImakefiles\fR just updates existing \fIImakefiles\fR while \fBmake GenAllImakefiles\fP recreates them. Normally \fBmake GenAllImakefiles\fP is not needed. .sp 2 .NH 2 "WORKING WITH \f(BIMakefiles\fP" .XS \*(SN WORKING WITH \fIMakefiles\fP .XE .sp .PP .nh A user should never have to edit a \fIMakefile\fR to change a \fBmake\fR definition (for example to change the `-O' option to `-g'). Changes can be made by either modifying the \fIImakefile\fR and then remaking the \fIMakefile\fR, by running \fBmake Makefile\fR, or by using \fBmake CDEBUGFLAGS=-g\fR. The user has access to several \fBmake\fR definitions to help accomplish this task. Some of the more common definitions are listed in Table 1. .KS .ps 10 .nr PS 10 .vs 12 .nr VS 12 .TS center box tab(%); l | l | lw55 . \fBmake\fP definitions%Default%comments _ CDEBUGFLAGS%-O%T{ Passed to all compiles. If a `debug' compile is needed, just change this to be `-g'. This definition is used in defining CFLAGS, which is used when compiling C files, and LDOPTIONS, which is used when loading (linking) a program, \fIa.out\fR for example. T} _ STD_INCLUDES%-I.%T{ \fI$KHOROS_HOME/include\fR is already included elsewhere. This field should only be added to in the rare case where an include file is needed and is not in either of `.' or \fI$KHOROS_HOME/include\fR. This definition is used in defining CFLAGS which is used when compiling C files. T} _ YFLAGS%%Flags passed to \fByacc\fR _ LFLAGS%%Flags passed to \fBlex\fR _ EXTRA_LOAD_FLAGS%%T{ When compiling a program, this field can be used to pass additional flags to the loader during the program load phase, for example any additional libraries that need to be linked in. This definition is used when loading (linking) a program, \fIa.out\fR for example. T} .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .sp .ce Table 1. Some common \fBmake\fR definitions the user may change in the \fIImakefile\fR or on the \fBmake\fR command line. .KE .bp .NH 2 "EXAMPLES" .XS \*(SN EXAMPLES .XE .sp .PP .nh In this section, several references are made to Khoros utilities which are used to help manage the system. For a complete description of these utilities and their exact use consult Section A of this chapter. \fBkmakeall\fR is basically equivalent to \fBmake\fR except that \fBkmakeall\fR \fBrsh\fRes to other systems to \fBmake\fR Khoros on different architectures. \fBksrcconf\fR creates symbolically linked source trees allowing different architectures to be compiled using the same source without having to have multiple copies of the source. It is strongly suggested that the Khoros manual pages for these utilities be consulted to provide a detailed description of what these utilities do. .PP .nh There are also references made to `srcmach' trees which are what \fBksrcconf\fR creates. For example, in $KHOROS_HOME/srcmach there might contain directories \fBsrcdecmips\fR and \fBsrcsun4\fR which are source trees, symbolic links to the real source, created to allow compiles on DEC Mips and Sun 4 based machines respectively. .PP .nh The rest of this section contains examples of how to add new routines or programs into a Khoros \fItoolbox\fP (see Volume 2, Chapter 1 for instructions on using \fBkraftsman\fP to create and maintain a toolbox). The examples that follow will assume that a toolbox has been previously created and the name of the toolbox is CONTRIB_TOOLBOX. .sp 2 .NH 3 "Adding a New Routine to an Existing Library" .XS \*(SN Adding a New Routine to an Existing Library .XE .PP .nh The following steps show how to install a new routine, source file, into an already existing library. For example, assume that a routine called \fIvfoo\fR (file \fIvfoo.c\fR) is to be added to the library \fIlibcontrib.a\fR which is located in the toolbox called CONTRIB_TOOLBOX. Do not forget to specify the -toolbox option when using \fBksrcconf\fR and \fBkmakeall\fR. .in +.5i .IP 1) Install the new file, \fIvfoo.c\fR, in the library directory, with either the \fBmv\fR or \fBcp\fR command. .IP 2) Run \fBimkmf\fR in the library directory, to update the \fIImakefile\fR so that it contains a reference to the newly added file \fIvfoo.c\fR. .IP 3) Run \fBmakemake\fR to update the \fIMakefile\fR to reflect the changes made to the \fIImakefile\fR in step 2 above. .IP 4) If there are no `srcmach' trees, go to step 5b else continue with step 5a. .sp .IP 5a) Run \fBksrcconf -toolbox contrib_toolbox\fR to create the symbolic links for the new file in the `srcmach' trees. .IP 6a) Run \fBkmakeall -toolbox contrib_toolbox Makefile\fR to update the \fIMakefiles\fR in the `srcmach' trees. .IP 7a) Run \fBkmakeall -toolbox contrib_toolbox depend\fR to add the file dependencies to the \fIMakefiles\fR in the `srcmach' trees. Do not combine this step with step 6a above, i.e. \fBkmakeall -toolbox contrib_toolbox Makefile depend\fR, because the \fIMakefile\fR that is used for the `depend' would be the old one and not the new one which contains a reference to the newly added file \fIvfoo.c\fR. .IP 8a) Run \fBkmakeall -toolbox contrib_toolbox install\fR to compile the new file in the `srcmach' trees and to install the library in the library directory. Do not combine this step with step 7a above, i.e. \fBkmakeall -toolbox contrib_toolbox depend install\fR, because the \fIMakefile\fR that would be used for the `install' is the old one and not the one with the dependencies added. .LP Adding the routine \fIvfoo\fR to the library is finished. .sp .IP 5b) Run \fBmake depend\fR to add the file dependencies to the \fIMakefile\fR. Do not combine this step with step 3 above, i.e. \fBmake Makefile depend\fR, because the \fIMakefile\fR that is used for the `depend' would be the old one and not the new one which contains a reference to the newly added file \fIvfoo.c\fR. .IP 6b) Run \fBmake install\fR to compile the new file into the library and to install the library in the library directory. Do not combine this step with step 5b above, i.e. \fBmake depend install\fR, because the \fIMakefile\fR that is used for the `install' would be the old one and not the one with the dependencies added. .LP Adding the routine \fIvfoo\fR to the library is finished. .in -.5i .sp 2 .NH 3 "Creating a New Library" .XS \*(SN Creating a New Library .XE .PP .nh The following steps show how to install a new library into the "CONTRIB_TOOLBOX" toolbox. For example, assume that the library \fIlibfubar.a\fR is to be added to your toolbox and is to be placed in \fI$CONTRIB_TOOLBOX/src/Lib\fR. For clarity, the directory name should be the same as the library name. For this example since the library will be \fIlibfubar.a\fR, the directory name should be \fIfubar\fR. .in +.5i .IP 1) Make a directory \fIfubar\fR in \fI$CONTRIB_TOOLBOX/src/Lib\fR. .IP 2) Install the files that will make up the new library into the \fIfubar\fR directory with either the \fBmv\fR or \fBcp\fR command. .IP 3) cd into the new directory, \fIfubar\fR. .IP 4) Run \fBimkmf -type lib -name fubar -toolbox contrib_toolbox\fR to create the \fIImakefile\fR. The \fIlibname\fR argument should be the name of the library, which in this example is \fIfubar\fR. .IP 5) Run \fBmakemake\fR to create the first \fIMakefile\fR. .IP 6) cd .. (into \fI$CONTRIB_TOOLBOX/src/Lib\fR). .IP 7) Run \fBimkmf\fR to update the \fIImakefile\fR in \fI$CONTRIB_TOOLBOX/src/Lib\fR so that it contains a reference to the new directory \fIfubar\fR. .IP 8) Run \fBmake Makefile\fR to update the \fIMakefile\fR to reflect changes made to the \fIImakefile\fR in step 7 above. .IP 9) If there are no `srcmach' trees, go to step 11b else continue with step 11a. .sp .IP 10a) Run \fBksrcconf -toolbox contrib_toolbox\fR to create the symbolic links for the new directory in the `srcmach' trees. .IP 11a) Run \fBkmakeall -toolbox contrib_toolbox Makefile\fR to update the \fIMakefile\fR in the `srcmach' trees. .IP 12a) cd into the new directory, \fIfubar\fR. .IP 13a) Run \fBkmakeall -toolbox contrib_toolbox install\fR to make, in any `srcmach' tree, the new library and to install it. .IP 14a) Go to step 15. .sp .IP 10b) cd into the new directory, \fIfubar\fR. .IP 11b) Run \fBmake install\fR to make the new library and to install it. Do not combine this step with step 11b above, i.e. \fBmake depend install\fR, because the \fIMakefile\fR that is used for the `install' is the old one and not the one with the dependencies added. .sp .5 Continue with step 15. .sp .IP 15) Now that the library has been compiled and installed, the toolbox imake definition file needs to be updated so that programs will know about the new library. .sp cd into \fI$CONTRIB_TOOLBOX/repos/config/imake_conf\fR. .sp Edit the file \fIcontrib_toolbox.def\fP adding \f(CW-lfoobar\fP to the \f(CWTOOLBOX_LIBRARIES\fP line, and \f(CW$(LIBDIR)/libfoobar.a\fP to the \f(CWTOOLBOX_DEP_LIBRARIES\fP line. .br Note, if the \fIfubar\fR library is a fortran library then modify the \f(CWFOR_TOOLBOX_LIBRARIES\fP and \f(CWFOR_TOOLBOX_DEP_LIBRARIES\fP lines rather than the \f(CWTOOLBOX_LIBRARIES\fP and \f(CWTOOLBOX_DEP_LIBRARIES\fP lines. If the \fIfubar\fR library makes calls or references any of the X11 libraries then modify the \f(CWX_TOOLBOX_LIBRARIES\fP and \f(CWX_TOOLBOX_DEP_LIBRARIES\fP lines rather than the \f(CWTOOLBOX_LIBRARIES\fP and \f(CWTOOLBOX_DEP_LIBRARIES\fP lines. .IP 17) At this point, the addition of library \fIfubar\fR to the toolbox is complete; allowing programs to know about it. Before compiling a program which needs to link against the new library, the \fImake Makefile\fP command must be run on the programs \fIMakefile\fP. .in -.5i .sp 2 .NH 3 "Creating a New Program (independent of X11)" .XS \*(SN Creating a New Program (independent of X11) .XE .PP .nh The following steps show how to install a new program, independent of X11, into a Khoros toolbox. For example, assume that the program, \fIvbar\fR, is a routine and falls under the \fIarith\fR category. Also assume that this program needs to call the library routine \fIlvbar\fR. For clarity, the directory name should be the same as the program name. Note, Khoros provides a tool, \fBkinstall\fP, for installing new routines. For more information on \fBkinstall\fP consult kinstall(1) and Volume 2, Chapter 1 - Writing Programs. The method outlined below is for manual installation of a routine, we recommend that you use \fBkinstall\fP. .PP .nh There are two parts to installing a program. The first is adding the routine \fIlvbar\fR to the library located in \fI$CONTRIB_TOOLBOX/src/Lib/bar\fR and then installing the modified library. The procedure for doing this is described above in the above example. The second part is installing the ``main'' part of the program. The procedure for doing this is described in the steps below. .PP .nh It should be noted that it is very likely that the library module source will be located in the same directory with the ``main'' source of the program, requiring that steps 1, 2 and 3 below be completed before the library module can be added to the library, as described in the above example. .sp .in +.5i .IP 1) Create the directory \fIvbar\fR in \fI$CONTRIB_TOOLBOX/src/arith\fR. Note, if the \fIarith\fR directory does not exist, you must first create the \fIarith\fR directory then create the \fIvbar\fR directory. In the \fIarith\fR directory you must create an Imakefile using \fBimkmf -type dir -toolbox contrib_toolbox\fP and a Makefile using \fBmakemake\fP. If you created the \fIarith\fR directory, then \f(CWcd ..\fP and run Run \fBimkmf\fR to update the \fIImakefile\fR in \fI$CONTRIB_TOOLBOX/src\fR and \fBmake Makefile\fR to update the \fIMakefile\fR. .IP 2) Install the files for the new program in the \fIvbar\fR directory with either the \fBmv\fR or \fBcp\fR command. .IP 3) cd into the new directory, \fIvbar\fR. .sp If there is a library module associated with the ``main'' source, then it needs to be installed in the required library as described in the above example before continueing. In our example, the source for \fIlvbar\fR needs to be installed in library \fI$CONTRIB_TOOLBOX/src/Lib/bar\fR. .IP 4) Run \fBimkmf -type prog -name vbar -toolbox contrib_toolbox\fR to create the \fIImakefile\fR. Note, if the program makes a call to Fortran or any Fortran function is used, use \fBimkmf -type fprog -name vbar -toolbox contrib_toolbox\fR to create a Fortran \fIImakefile\fR. The \fIprogname\fR argument should be the name of the program, which in this example is \fIvbar\fR. .IP 5) Run \fBmakemake\fR to create the \fIMakefile\fR. .IP 6) cd .. (in \fI$CONTRIB_TOOLBOX/src/arith\fR). .IP 7) Run \fBimkmf\fR to update the \fIImakefile\fR in \fI$CONTRIB_TOOLBOX/src/arith\fR so that it contains a reference to the new directory \fIvbar\fR. .IP 8) Run \fBmake Makefile\fR to update the \fIMakefile\fR to reflect changes made to the \fIImakefile\fR. .IP 9) If there are no `srcmach' trees, go to step 10b else continue with step 10a. .sp .IP 10a) Run \fBksrcconf -toolbox contrib_toolbox\fR to create the symbolic links for the new directory in the `srcmach' trees. .IP 11a) Run \fBkmakeall -toolbox contrib_toolbox Makefile\fR to update the \fIMakefile\fR in the `srcmach' trees. .IP 12a) cd into the new directory, \fIvbar\fR. .IP 13a) Run \fBkmakeall -toolbox contrib_toolbox install\fR to make, in any `srcmach' tree, the new program and to install it. .LP Adding the routine \fIvbar\fR to \fIarith\fR is finished. .sp .IP 10b) cd into the new directory, \fIvbar\fR. .IP 11b) Run \fBmake depend\fR to create the file dependences in the \fIMakefile\fR. .IP 12b) Run \fBmake install\fR to compile the new files and to install the new program. Do not combine this step with step 11b above, i.e. \fBmake depend install\fR, because the \fIMakefile\fR used for the `install' would be the old one and not the one with the dependencies added. .LP Adding the routine \fIvbar\fR to \fIarith\fR is finished. .in -.5i .sp 2 .NH 3 "Creating a New Program (dependent on X11)" .XS \*(SN Creating a New Program (dependent on X11) .XE .PP .nh The steps involved in adding a new program, dependent on X11, is exactly the same as described in the above example with the exception that step 4) needs to be: .in +.5i .IP 4) Run \fBimkmf -type xprog -name vbar -toolbox contrib_toolbox\fR to create the \fIImakefile\fR. The \fIxprogname\fR argument should be the name of the X11 program. If the routine is dependent on Fortran then use \fBimkmf -type fxprog -name xprogname -toolbox contrib_toolbox\fR. .in -.5i .sp 2 .NH 3 "Creating a New Shell Script" .XS \*(SN Creating a New Shell Script .XE .PP .nh The steps involved in adding a new shell script are exactly the same as described above in the "Creating a New Program" section with the exception that step 4) needs to be: .in +.5i .IP 4) Run \fBimkmf -type script -toolbox contrib_toolbox -name\fR \fIscriptname\fR to create the \fIImakefile\fR. The \fIscriptname\fR argument should be the name of the `main' script, assuming that several scripts are needed to help the `main' script. .in -.5i .PP All script files should end with the suffix ".csh". .sp 2 .NH 3 "Moving Files within a Khoros Toolbox" .XS \*(SN Moving Files within a Khoros Toolbox .XE .PP .nh If the only things being moved are files, no directories, then the following steps need to be taken to insure that the \fIImakefiles\f located in the `original' and `destination' directories are up to date. For example, assume that files \fIlvclip.c\fR and \fIlvtranslat.c\fR need to be moved from \fI$CONTRIB_TOOLBOX/src/vipl/Lib\fR to \fI$CONTRIB_TOOLBOX/src/dspl/Lib\fR. .PP .nh In the steps below, if there are no `srcmach' trees, then just use \fBmake\fR for the make command otherwise use \fBmake\fP followed by \fBkmakeall -toolbox contrib_toolbox\fR. .in +.5i .IP 1) cd into the `original' directory, in our example \fI$CONTRIB_TOOLBOX/src/vipl/Lib\fR. .IP 2) Move the required files from the current directory to \fI$CONTRIB_TOOLBOX/src/dspl/Lib\fR, for example: \f(CWmv lvclip.c lvtranslat.c $CONTRIB_TOOLBOX/src/dspl/Lib\fR. .IP 3) Remove the object files (\fIlvclip.o\fR and \fIlvtranslat.o\fR) associated with the files that were moved. This can be done either running \fBmake clean\fR, which removes all objects, or they can be removed by hand, for example: \f(CWrm lvclip.o lvtranslat.o\fR. .IP 4) Run \fBimkmf\fR to update the \fIImakefile\fR (to remove references to the moved files, \fIlvclip.c\fR, \fIlvtranslat.c\fR, \fIlvclip.o\fR, and \fIlvtranslat.o\fR, from the SRCS, OBJS, FSRCS, FOBJS, HEADERS lists). .IP 5) Run \fBmake Makefile\fR to update the \fIMakefile\fR to reflect the changes made to the \fIImakefile\fR in step 4 above. .IP 6) Run \fBmake depend\fR to add the file dependencies to the \fIMakefile\fR. Do not combine this step with step 5 above, i.e. \fBmake Makefile depend\fR, because the \fIMakefile\fR that is used for the `depend' would be the old one and not the new one which has the references to the moved files removed. .IP 7) Run \fBmake install\fR to make sure moving the files did not cause any \fBmake\fR problems. Do not combine this step with step 6 above, i.e. \fBmake depend install\fR, because the \fIMakefile\fR that is used for the `install' would be the old one and not the one with the dependencies added. .IP 8) cd into the `destination' directory, in our example \fI$CONTRIB_TOOLBOX/src/dspl/Lib\fR. .IP 9) Run \fBimkmf\fR to update the \fIImakefile\fR (to add references to the moved files, \fIlvclip.c\fR, \fIlvtranslat.c\fR, \fIlvclip.o\fR, and \fIlvtranslat.o\fR, to the SRCS, OBJS, FSRCS, FOBJS, HEADERS lists). .IP 10) Run \fBmake Makefile\fR to update the \fIMakefile\fR to reflect the changes made to the \fIImakefile\fR in step 9 above. .IP 11) Run \fBmake depend\fR to add the file dependencies to the \fIMakefile\fR. Do not combine this step with step 10 above, i.e. \fBmake Makefile depend\fR, because the \fIMakefile\fR that is used for the `depend' would be the old one and not the new one which has references to the moved files inserted. .IP 12) Run \fBmake install\fR to make sure moving the files did not create any unresolved dependencies. Do not combine this step with step 11 above, i.e. \fBmake depend install\fR, because the \fIMakefile\fR that is used for the `install' would be the old one and not the one with the dependencies added. .IP 13) Moving the files, \fIlvclip.c\fR and \fIlvtranslat.c\fR, is finished. .in -.5i .sp 2 .NH 3 "Moving a Directory within a Khoros Toolbox" .XS \*(SN Moving a Directory within a Khoros Toolbox .XE .PP .nh If a directory is all that is being moved, no individual files, then the following steps need to be taken to insure that the \fIImakefile\f located in the `original' and `destination' directories are up to date. For example, assume that the directory \fIvadd\fR needs to be moved from \fI$CONTRIB_TOOLBOX/src/vipl/arith_binary\fR to \fI$CONTRIB_TOOLBOX/src/vipl/arith_unary\fR. .PP .nh In the steps below, if there are no `srcmach' trees, then just use \fBmake\fR for the make command otherwise use both \fBmake\fP and \fBkmakeall -toolbox contrib_toolbox\fR. Again, it is best to use the Khoros utilities, \fBkdinstall\fP, \fBkrmprog\fP, and \fBkinstall\fP to remove or move either programs within the Khoros environment. The method outlined below should be followed when directories are being moved manually. .in +.5i .IP 1) cd into the `original' directory, \fI$CONTRIB_TOOLBOX/src/vipl/arith_binary\fR. .IP 2) Move the required directory, \fIvadd\fR from the current directory to \fI$CONTRIB_TOOLBOX/src/vipl/arith_unary\fR, for example: .IP \f(CWmv vadd $CONTRIB_TOOLBOX/src/vipl/arith_unary\fR. .IP 3) Edit the configuration file, \fIvadd.conf\fR, to reflect the change of location of the sources. .IP 4) Run \fBimkmf\fR to update the \fIImakefile\fR (to remove the reference to the moved directory, \fIarith_binary\fR, from the SUBDIRS list). .IP 5) Run \fBmake Makefile\fR to update the `original' directory \fIMakefile\fR to reflect the changes made to the \fIImakefile\fR in step 3 above. .IP 6) cd into the `destination' directory, \fI$CONTRIB_TOOLBOX/src/vipl/arith_unary\fR. .IP 7) Run \fBimkmf\fR to update the \fIImakefile\fR (to add a reference to the moved directory, \fIarith_unary\fR, to the SUBDIRS list). .IP 8) Run \fBmake Makefile\fR to update the \fIMakefile\fR to reflect the changes made to the \fIImakefile\fR in step 6 above. .IP 9) Run \fBmake install\fR to make sure moving the directory did not create any unresolved dependencies. .IP 10) If the name of the directory moved was changed, for example from \fIvadd\fR to \fIaddition\fR, then all files associated with the old name need to be removed by hand; i.e. remove \fI$CONTRIB_TOOLBOX/bin/vadd\fR. If the directory moved was a library, for example \fI$CONTRIB_TOOLBOX/src/Lib/vrast\fR, and the name was changed from \fIlibvrast.a \fR to \fIlibvraster.a\fR, then the old library would need to be removed by hand; i.e. remove \fI$CONTRIB_TOOLBOX/lib/libvrast.a\fR. .IP 11) Moving a directory is finished. .in -.5i .bp .NH 1 "MAINTAINING THE KHOROS SRCMACH TREE FOR MULTIPLE ARCHITECTURES" .XS \s12\*(SN MAINTAINING THE KHOROS SRCMACH TREE FOR MULTIPLE ARCHITECTURES .XE .sp .PP This section of the manual provides information for setting up and maintaining Khoros for multiple architectures. Information in this section applies to both KHOROS_HOME and Khoros toolboxes. Briefly, the steps necessary for configuring Khoros for multiple architectures includes the following: .sp .IP "(1) - " Create the libmach directories for each architecture to be supported. .sp .IP "(2) - " Create the binmach directories for each architecture to be supported. .sp .IP "(3) - " Modify or create the mach file(s) in KHOROS_HOME/repos/config/src_conf or in {toolbox}/repos/config/src_conf for the appropriate paths and machine names for each architecture. .sp .IP "(4) - " Create the srcmach tree for each architecture. This consists of creating a directory structure that mimics that of the Khoros source tree, and making symbolic links from the srcmach tree to the Khoros source tree. .sp .IP "(5) - " Compile the system for each architecture. .sp .PP The remainder of this document provides more detailed information on each step outlined above. Several tool programs are provided, which help in creating directories and making links to files in source. The use of these programs is explained in the sections that follow. .PP Khoros should be installed for a single architecture prior to establishing a multiple architecture system. This will ensure that all programs compile clean and that there are no configuration problems. The \fIInstallation Guide\fP provides the user with the necessary information for setting up Khoros for a single architecture. .PP Before proceeding to set up a system for multiple architectures, the user should be aware of some of the possible configurations that may arise on a networked system of machines. As described in Section A of this chapter, the directory structure of Khoros includes src, repos, lib, include, bin, and data. To support multiple architectures, you would also have srcmach, libmach, and binmach directories which would contain subdirectories for each architecture. Because disk storage is a precious commodity, you might choose to store the Khoros source directories on a different disk from that of the binaries and libraries. Note that the environment variable, \fIKHOROS_HOME\fP, points to the top level of the Khoros src directory. .PP There are three common scenarios for setting up Khoros for multiple architectures on a networked system. One scenario is to have the srcmach, bins, and libs on a local partition and the src directory on another machine that is mounted on the local partition. Another scenario is to have the binaries and libraries on a local partition, and the src and srcmach on a remote disk that is mounted on the local partition. The last scenario is to have the src, srcmach, binaries, and libraries on a remote disk that is mounted locally. The following diagram depicts these three scenarios: .sp .DS .ps 9 .vs 11 \f(CW Scenario 1 - src located on a remote disk Machine A Machine B (local) (remote) ---------- mounted ---------- | |<---------------| khoros | |--------| | | | srcmach| | | | bins | | | | libs | | | ---------- ---------- Scenario 2 - src and srcmach located on a remote disk Machine A Machine B (local) (remote) ---------- mounted ---------- | |<---------------| khoros | | |<---------------| srcmach| |--------| | | | bins | | | | libs | | | ---------- ---------- Scenario 3 - src, srcmach, bins, and libs located on a remote disk Machine A Machine B (local) (remote) ---------- mounted ---------- | |<---------------| khoros | | |<---------------| srcmach| | |<---------------| bins | | |<---------------| libs | | | | | ---------- ---------- * khoros - includes the directories of src, include, repos, and data. \fP .DE .PP After it is determined which scenario best fits a particular site, the next step is to create the directories for the \fIlibmach\fP and \fIbinmach\fP. We will now provide a procedure for doing this. .PP The first step in setting up Khoros for multiple architectures is to create a \fIlibmach\fP directory that will have a separate subdirectory for each architecture to be supported. For example, if both dec and sun architectures are supported, then \fIlibdecmips\fP and \fIlibsun4\fP directories are created beneath the \fIlibmach\fP directory. Each of these directories will contain the compiled libraries for each supported architecture. The directory \fIlib\fP is just a symbolic link to the libmach directory for the local host machine architecture. This is accomplished by creating a \fI/localhost/khoros\fP directory and creating a link between the \fIlib\fP directory and the libmach directory on each machine. Thus, accessing the directory \fIlib\fP on a sun4 machine will actually get you the libmach directory for the sun4 architecture, \fIlibsun4\fP. This step must be performed for each machine architecture to be supported. .LP This step can best be illustrated by an example: (on a sun4 machine) .sp .nf \f(CW% mkdir /localhost/khoros % ln -s ~khoros/libmach/libsun4 lib % cd khoros % ln -s /localhost/khoros/lib lib \fP .fi .PP The next step is to create a \fIbinmach\fP directory that will contain the compiled libraries for each architecture. Similar to the \fIlibmach\fP directory discussed above, a \fIbinmach\fP directory is created with a separate subdirectory for each architecture. Using the same example as above, separate subdirectories will be created for \fIbindecmips\fP and \fIbinsun4\fP. Each of these directories will contain the compiled binaries for each supported architecture. Similar to the \fIlib\fP directory discussed above, the \fIbin\fP directory is just a symbolic link to the local host libmach for that machine architecture. This step must be performed for each machine architecture to be supported. A symbolic link can be set up for the local host in the following manner: .sp .nf \f(CW% mkdir /localhost/khoros % ln -s ~khoros/binmach/binsun4 bin % cd khoros % ln -s /localhost/khoros/bin bin \fP .fi .PP The following diagram shows a portion of the Khoros directory structure for support of multiple architectures. It illustrates the organization of the \fIlibmach\fP and \fIbinmach\fP directories as described above would appear if the local host machine is a decmips. .sp .DS .ps 9 .vs 11 \f(CW /localhost/khoros/bin@ -> binmach/bindecmips /localhost/khoros/lib@ -> libmach/libdecmips |--bin@ -> /localhost/khoros/bin | | |-bindecmips---- |--binmach---------| | |-binsun4------- | ../khoros---| | | |-libdecmips---- |--libmach---------| | |-libsun4------- | |--lib@ -> /localhost/khoros/lib \fP .DE .PP This is followed by creating a srcmach tree for each architecture, creating symbolic links to the files in the Khoros source tree, and compiling for each architecture. Creating a srcmach tree consists of creating a directory structure that mimics the directory structure of the Khoros source tree. This is followed by creating symbolic links from the srcmach tree to each of the files in the Khoros source tree. The final step is to compile the system for each of the architectures. .PP There are several programs that can be used to help create symbolically linked source trees when your site supports multiple machine architectures. Two programs that can be used to create a symbolically linked source tree are \fBklndir\fP and \fBksrcconf\fP. \fBKlndir\fP is a low level tool used to create a symbolically linked source tree for a particular architecture, whereas \fBksrcconf\fP can be used to create multiple source trees at once. \fBKsrcconf\fP will take care of creating the source tree directories for each architecture and make the links to the source files. \fBKmakeall\fP is a tool to ease the process of compiling the source for each architecture. \fBKsrcconf\fP and \fBkmakeall\fP both depend on \fImach\fP files, whereas \fBklndir\fP does not. Each of these tools will be discussed in the sections that follow. .PP The concepts described above were applied to KHOROS_HOME. These same concepts can be applied to Khoros toolboxes. Since many of the tool programs in Khoros make use of \fImach\fP files, we will begin by discussing the creation and use of mach files. .sp 2 .NH 2 "MACH FILES AND MULTIPLE ARCHITECTURES" .XS \*(SN MACH FILES AND MULTIPLE ARCHITECTURES .XE .sp .PP \fBKsrcconf\fP and \fBkmakeall\fP use a \fImach\fP file to sort out the correct paths to the top level of source for each machine. A mach file contains information specific for a particular installation site. It contains the name of the Khoros user, the names of the machines, and the proper paths to the source and srcmach directories for each of the machine architectures that source will be compiled on. These routines also require that an ".rhosts.bk" file be located in the top level directory of KHOROS_USER, for access to the machine names and login IDs. .PP Note that a mach file must be setup even if you are not going to support multiple architectures. That is you need a mach file even if you are working with a single architectures. .PP The five entries in the mach file are described below: .sp .IP KHOROS_USER 24 specifies the name of the user. This is used to ensure proper ownership and permissions of files, required for rsh's, and will mail to the user the results of compilations and installations. NOTE, This is a required field. .sp .IP LOCAL_SRC_TOP 24 specifies the complete path to the top of source for the machine that is used in the development of the Khoros system. (See explanation below). NOTE, this is a required field. .sp .IP KHOROS_MACHINES 24 specifies the name of the machines that source will be compiled on. This field only needs to be specified if multiple architectures are to be supported. .sp .IP KHOROS_MACH_DIR 24 specifies the complete paths to the srcmach directories for each machine named in the KHOROS_MACHINES entry. This field only needs to be specified if multiple architectures are to be supported. .sp .IP KHOROS_SRC_TOP 24 specifies the complete paths to the top of source for each machine named in the KHOROS_MACHINES entry. This field only needs to be specified if multiple architectures are to be supported. .sp .PP \f(CW$KHOROS_HOME/repos/config/src_conf\fP is the location for KHOROS_HOME mach files. If your site has one or more machines with the same paths to the Khoros source tree, then one mach file may be used to specify the machine information for Khoros home. A mach file must also be created for those sites supporting Khoros toolboxes. Each toolbox will contain its own mach file(s), located in \f(CW{toolbox}/repos/config/src_conf\fP. Consult Volume 2, Chapter 1 for information on creating and managing toolboxes using \fBkraftsman\fP. Several examples of different mach files are presented in the examples that follow. .PP The paths for $KHOROS_HOME and and the top level of toolboxes must be correct for your site. The user should be aware of aliases for "pwd". For example, if you have "pwd" aliased to "cwd", then you may get an incomplete path if your site is using \fIautomount\fP or if your partitions are symbolically linked so that Khoros is available in a different location on your disk. To avoid this problem, the user may want to unalias the "pwd" command, or use "\pwd" to get the correct path to the top of source. .PP One other problem that may occur, is that the hostnames for the machines at your site may not be qualified with an extension. For example, if your site has a machine name of "mymachine", it may be qualified with an extension, such as "mymachine.xyz.edu". You should verify the correct hostname of all machines at your site by logging on to the machine and entering the command, \f(CWhostname\fP. This will return the correct hostname for that machine, and this is what should be entered in KHOROS_MACHINES field of the mach file. .PP The following is an example of a mach file for Khoros that supports two different machine architectures: .nf set KHOROS_USER = (khoros) set KHOROS_MACHINES = (dec.xyz.edu sun.xyz.edu) set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips $KHOROS_HOME/src mach/srcsun4) set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src) set LOCAL_SRC_TOP = (/local/khoros/src) .fi .sp .PP If the full paths to the top of the Khoros source tree are different for each of the machines at a site, then a mach file must be created for each of the machines. To create a mach file for a particular site, one needs to list the machine names for each of the architectures that are supported. The path to the srcmach directories for each machine must also be provided in the KHOROS_MACH_DIR field. In addition, the path to the top of the source for each of the machines must also be provided. Note that there is a one-to-one correspondence for each entry in the fields, KHOROS_MACHINES, KHOROS_MACH_DIR, and KHOROS_SRC_TOP. .PP The field LOCAL_SRC_TOP specifies the path to the top of source. For some sites, this path may be different for each of the machines that source will be compiled on. If the paths to source are different for each machine, then it is necessary to create a mach file for each machine. For example, if your site supports two machine architectures with different paths to the top of source, then a mach file should be created for each architecture. In addition, the paths to the top of the Khoros source tree must be checked for any networked machine that is used for developing or managing Khoros. If the path to the top of the Khoros source tree is different, then a separate mach file must also be created for use with that particular machine. .PP The programs that use mach files check the current machine name and will use the appropriate mach file, if one exists for that machine. For example, if your current machine name is sun.xyz.edu, a search is made in the repos/config/src_conf directory for a mach file named "default_mach.sun.xyz.edu" for KHOROS_HOME and "{toolbox}_mf.sun.xyz.edu" for a toolbox. If the mach file is not found, then the search will continue in the repos/config/src_conf directory for "default_mach" for KHOROS_HOME and "{toolbox}_mf for a toolbox. If a mach file is not found, the program will terminate and a mach file will have to be created. .PP The next example illustrates a site supporting two architectures when the paths to the top of Khoros source are different for each of the machines. In this case two mach files are required. The two mach files are named using the machine name as the extension. If the machine names are dec.xyz.edu and sun.xyz.edu, then the mach files would be named, default_mach.dec.xyz.edu and default_mach.sun.xyz.edu. Note, this example applies to the mach files in KHOROS_HOME, however this concept can be applied to the mach files in a Khoros Toolbox. Examples of these two files are presented below: .nf # default_mach.dec.xyz.edu set KHOROS_USER = (khoros) set KHOROS_MACHINES = (dec.xyz.edu sun.xyz.edu) set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips $KHOROS_HOME/src mach/srcsun4) set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src) set LOCAL_SRC_TOP = (/local/khoros/src) .fi .nf # default_mach.sun.xyz.edu set KHOROS_USER = (khoros) set KHOROS_MACHINES = (dec.xyz.edu sun.xyz.edu) set KHOROS_MACH_DIR = ($KHOROS_HOME/srcmach/srcdecmips $KHOROS_HOME/src mach/srcsun4) set KHOROS_SRC_TOP = ($KHOROS_HOME/src $KHOROS_HOME/src) set LOCAL_SRC_TOP = (/foo/local/khoros/src) .fi .PP Notice that the paths for the two machines are different for LOCAL_SRC_TOP. Since the tools make use of these paths to install and configure srcmach trees, it is important to recognize these differences for successful maintenance of the Khoros source tree. .PP The next example shows how a mach file may be set up for support of a Khoros toolbox srcmach for two different architectures. In this example, let's assume that the paths to the top of Khoros source are the same. This enables the use of one mach file to define the paths for both architectures. We will call the Khoros toolbox "CONTRIB_TOOLBOX." An example of a mach file for a Khoros toolbox is presented below: .nf # contrib_toolbox_mf set KHOROS_USER = (spanky) set KHOROS_MACHINES = (dec.xyz.edu sun.xyz.edu) set KHOROS_MACH_DIR = ($CONTRIB_TOOLBOX/srcmach/srcdecmips $CONTRIB_TOOLBOX RIB/srcmach/srcsun4) set KHOROS_SRC_TOP = ($CONTRIB_TOOLBOX/src $CONTRIB_TOOLBOX/src) set LOCAL_SRC_TOP = (/usr/users/spanky/contrib_toolbox/src) .fi .PP The following sections discuss each of the tool programs involved in building and maintaining the Khoros srcmach tree for multiple architectures. .sp 2 .NH 2 "CREATE A SYMBOLIC LINKED SOURCE TREE - KLNDIR" .XS \*(SN CREATE A SYMBOLIC LINKED SOURCE TREE - KLNDIR .XE .sp .PP \fBKlndir\fP is a program for creating directories in a srcmach tree and creating symbolic links to the files in the corresponding directories in the Khoros source tree. \fBKlndir\fP first checks to see if the destination directories in the srcmach tree exist. If they do not exist, then it creates the directories and makes the symbolic links to the *.c, *.h, *.f source files. It copies over the source Makefiles, and makes symbolic links to the Imakefiles. .sp .PP The usage for \fBklndir\fP is as follows: .nf \f(CW % klndir -source xxxx -dest yyyy\fP where, xxxx is the absolute path to a directory in source from /. yyyy is the absolute path to a directory in the srcmach from /. .fi The user specifies the FULL directory path to the Khoros source tree and the destination srcmach tree. The Khoros source tree is the location of the source files for Khoros. The destination source tree is a new source tree containing symbolic links to the source (*.c, *.h, and *.f files), and is referred to as a srcmach tree. The user may retrieve the man page for \fBklndir\fP for a complete description and usage information. .PP The following example demonstrates the usage for \fBklndir\fP: .sp .nf \f(CW% klndir -source /foo/khoros/src -dest /foo/khoros/srcmach/foomach\fP .fi .sp This will make links from the khoros source tree to the foomachine source tree. .sp 2 .NH 2 "CREATE MULTIPLE SYMBOLIC LINKED SOURCE TREES - KSRCCONF" .XS \*(SN CREATE MULTIPLE SYMBOLIC LINKED SOURCE TREES - KSRCCONF .XE .sp .PP \fBKsrcconf\fP is a more powerful and higher level tool than \fBklndir\fP, since it can create multiple srcmach trees at once. Since \fBKsrcconf\fP calls \fBklndir\fP for each directory in the srcmach directory, it is the preferred tool to use when creating srcmach trees for multiple machine architectures. By default, \fBksrcconf\fP will attempt to create symbolic links relative to the present working directory. \fBKsrcconf\fP assumes that there is a directory called srcmach. In the srcmach directory are subdirectories for each machine architecture, and for each of these subdirectories it will update and create the symbolic links. The paths to each subdirectory of the srcmach directory are specified in the \fImach file\fP. .LP The usage for \fBksrcconf\fP is as follows: .nf \f(CW % ksrcconf [-source xxxx] [-toolbox yyyy]\fP where, xxxx is the source directory yyyy is the name of the toolbox you are working in. If you you are working in KHOROS_HOME, do not specify the the -toolbox option. .fi A complete description and program usage may be obtained by retrieving the man page for \fBksrcconf\fP. .LP The following examples may be helpful: .sp .nf \f(CW% cd $KHOROS_HOME/src/vipl/arith_binary % ksrcconf\fP .fi .sp \fBOR\fP .sp \f(CW% ksrcconf -source $KHOROS_HOME/src/vipl/arith_binary\fP .sp Here is an example of setting up the symbolic links for all of $KHOROS_HOME/src: .sp .nf \f(CW% cd $KHOROS_HOME/src % ksrcconf\fP .fi .sp The next example shows how to configure the srcmach directory for a Khoros toolbox. We will call the toolbox "contrib_toolbox". .sp .nf cd to the source directory in the "contrib_toolbox" toolbox. Execute: .br \f(CW% ksrcconf -toolbox contrib_toolbox\fP .fi .sp ksrcconf will look in $CONTRIB_TOOLBOX/repos/config/src_conf for the mach file. .sp 2 .NH 2 "COMPILING MULTIPLE ARCHITECTURES - KMAKEALL" .XS \*(SN COMPILING MULTIPLE ARCHITECTURES - KMAKEALL .XE .sp .PP Once the srcmach trees are in place and the bin and lib directories for the multiple architectures have been created, \fBkmakeall\fP can be used to compile all of the architectures at once. \fBKmakeall\fP is a shell script to assist in the use of \fBmake\fP on a distributed computer system. By default, \fBkmakeall\fP will attempt to make source relative to the present working directory. .PP The usage for \fBkmakeall\fP is as follows: .sp .nf \f(CW% kmakeall [-toolbox] [-f full_path | -r relative_path] [make options]\fP where, [-toolbox] the Toolbox name [-f] is the full path [-r] is relative path to the top level src directory .fi The user can specify the FULL directory path name (-f) to the source, or the relative path name (-r) to the src directory. A complete description and usage of \fBkmakeall\fP can be obtained at any time by retrieving the man page for \fBkmakeall\fP. .PP After getting the defined make objects and options, \fBkmakeall\fP attempts to call \fIrsh\fP to each machine and call \fBmake\fP in the appropriate $KHOROS_HOME/srcmach/ directory. \fBKmakeall\fP uses \fIrsh\fP, and since ".rhosts" files should not be left lying around, \fBkmakeall\fP copies the $KHOROS_USER/.rhosts.bk to $KHOROS_USER/.rhosts before calling \fIrsh\fP and then removes the ".rhosts" file before exiting. Since the \fIrsh\fP's are put in the background, \fBkmakeall\fP needs to sleep for about a minute to allow \fIrsh\fP's to be connected before removing the ".rhosts" file. .PP Here is an example of making and installing \fBvadd\fP $KHOROS_HOME on all machines: .sp .nf \f(CW% cd $KHOROS_HOME/src/vipl/arith_binary/vadd % kmakeall install\fP .fi .PP Here is an example of making and installing all of $KHOROS_HOME/src/file_formats on all machines: .sp .nf \f(CW% cd $KHOROS_HOME/src/file_formats % ksrcconf % kmakeall install\fP .fi .PP Note that on a busy network and/or a slow server, you may experience timeout problems. Therefore one should be cognizant of the network load when compiling. .PP The following example illustrates how to compile all of the source in a Khoros toolbox. We will call the toolbox CONTRIB_TOOLBOX .sp .nf \f(CW% cd CONTRIB_TOOLBOX/src % kmakeall install -toolbox contrib_toolbox\fP .fi .sp .TC 9 "CONFIGURATION MANAGEMENT"