source: trunk/athena/bin/athdir/athdir.man @ 11254

Revision 11254, 7.2 KB checked in by cfields, 27 years ago (diff)
Add documentation for ATHENA_SYS_COMPAT.
Line 
1.TH ATHDIR 1 "7 March 1998"
2.ds ]W MIT Athena
3.SH NAME
4athdir \- find machine specific directories using Athena conventions
5.SH SYNOPSIS
6.nf
7athdir \fIlockerpath\fR [\fItype\fR]
8
9athdir [-t \fItype\fR] [-p \fIlockerpath\fR ...] [-e] [-c] [-l] [-i | -d]
10       [-r \fIrecsep\fR] [-f \fIformat\fR] [-s \fIsysname\fR] [-m \fImachtype\fR]
11.fi
12.SH DESCRIPTION
13\fIathdir\fR provides the most reliable way to determine the location
14in a locker of specific types of machine dependent files. While in C
15shell scripts the shell variable \fIbindir\fR is typically available,
16that information is not available in all environments (such as
17makefiles) and not necessarily as reliable, as it contains no
18intelligence. Similarly, while the environment variable
19\fIATHENA_SYS\fR is widely available, attempting to use it in
20makefiles or resource files may fail on older lockers that have not
21yet been upgraded to use the new conventions, or in lockers that have
22not been updated to support the latest operating system releases. (See
23\fIlockers\fR(7) for more information on locker directory
24conventions.)
25
26In the first invocation shown above, \fIathdir\fR does not accept
27command line options other than the two listed, and they must be in
28the listed order. If \fItype\fR is not specified, ``bin'' is assumed.
29
30In the second invocation above, no particular option is required,
31though at least one option is.  \fItype\fR has no default value, and
32the options may be specified in any order.
33.SH EXAMPLES
34\fIathdir\fR may be used to find directories for any sort of machine
35dependent or potentially machine dependent files. In its most common
36form, it should be used to replace \fImachtype\fR(1) (as in
37``/mit/locker/`machtype`bin''). For example,
38
39     set path=($path `athdir /mit/locker`)
40
41will append ``/mit/locker/arch/pmax_ul4/bin'' to the user's search
42path if the locker supports that as the machine specific binary
43directory, or ``/mit/locker/decmipsbin'' otherwise. Note that in this
44case, no type argument is specified, so ``bin'' is assumed. The
45example is shorthand for using `athdir /mit/locker bin`. Similarly,
46one might have in one's .twmrc file:
47
48    "meow"   f.exec "`athdir /mit/sipb`/oneko &"
49
50to replace:
51
52    "meow"   f.exec "/mit/sipb/`machtype`bin/oneko &"
53
54The rest of this manual page will probably not be of interest to most
55users, but may be of interest to developers.
56
57Another useful application for \fIathdir\fR is in makefiles. For
58example, suppose you wish to build a program against the x11 locker.
59You might start with
60
61     INCLUDES = `athdir /mit/x11 include`
62     LIBS = `athdir /mit/x11 lib`
63
64to find the appropriate directories in the locker. For dependencies
65on multiple lockers, you might have
66
67     INCLUDES = `athdir -t include -p /mit/motif /mit/x11`
68     LIBS = `athdir -t lib -p /mit/motif /mit/x11`
69
70which might resolve to
71
72     INCLUDES = /mit/motif/include /mit/x11/include
73     LIBS = /mit/motif/sun4lib /mit/x11/arch/sun4m_53/lib
74
75Note that this example allows for the possibility of machine dependent
76include files as well as libraries.
77
78In general, \fItype\fRs are treated as random strings by
79\fIathdir\fR. \fIathdir\fR checks the locker first for
80arch/$ATHENA_SYS/\fItype\fR. Next it checks for arch/COMPAT/\fitype\fR,
81where COMPAT iterates over the values in $ATHENA_SYS_COMPAT.
82Then it checks for `machtype`\fItype\fR. Finally it looks for \fItype\fR
83alone. Exceptions to this rule are cases where
84a convention is never expected to be used, or where a convention is
85explicitly discouraged and has never been supported. Note that if any
86future conventions arise, \fIathdir\fR will know about them and act
87accordingly. Thus, in theory, the usage of \fIathdir\fR should be
88forward compatible, and is encouraged.
89.SH OPTIONS
90\fIathdir\fR provides a few options for modifying its default behavior
91and providing other useful information.
92.TP 8
93.B \-e
94This option causes \fIathdir\fR to not engage in potentially annoying
95editorial behavior. It will not implement the above mentioned
96exceptions on conventions not expected or discouraged.
97.TP 8
98.B \-c
99This option causes \fIathdir\fR to not check for the usage of
100different possible conventions, and simply return output in the form
101of currently favored convention (arch). This is useful, for example,
102in makefiles that may wish to ``\fImkdir\fR -p'' target directories.
103.TP 8
104.B \-d
105This option, when used with \-c, tells \fIathdir\fR that you wish it
106to use the favored machine dependent directory convention when
107returning a pathname. \fIathdir\fR makes assumptions, based on
108\fItype\fR, what kind of directory should be returned. For example, if
109the \fItype\fR were ``include,'' \fIathdir\fR would ordinarily return
110something like ``/mit/locker/include.'' If you specify \-d, it would
111return ``/mit/locker/arch/$ATHENA_SYS/include'' instead.
112.TP 8
113.B \-i
114This option, when used with \-c, tells \fIathdir\fR that you wish it
115to use the favored machine independent directory convention when
116returning a pathname. This is basically the reverse of the \-d option.
117\fIathdir\fR, when it does not recognize a \fItype\fR, assumes the
118type to be machine dependent, so \-i may be used to override that.
119.TP 8
120.B \-l
121This option causes \fIathdir\fR to list the locations it would look
122for the \fItype\fR of directory requested, rather than looking in them
123and returning a single value. If a directory path is not specified,
124\fIathdir\fR will output a ``%p'' in its place; if a \fItype\fR is not
125specified, a ``%t'' will be output in its place, and all three above
126mentioned possibilities will be output.
127.TP 8
128.B \-f \fIformat\fR
129This option passes a format string to \fIathdir\fR to be used as a
130style for searching for directories. It is used as the preferred
131path style, with the built-in styles as fallbacks. It makes the following
132substitutions:
133
134        %p   path (as passed by -p)
135        %t   type (as passed by -t)
136        %s   sysname
137        %m   machtype value
138
139For example, the arch convention uses the string %p/arch/%s/%t. When
140making the substitution for %s, \fIATHENA_SYS_COMPAT\fR values will be
141substituted after the \fIATHENA_SYS\fR value as necessary.
142.TP 8
143.B \-r \fIrecsep\fR
144Specify the record separator when multiple paths are output. By default this
145is a newline. It may be useful to specify it to be a space or colon on
146various occasions.
147.TP 8
148.B \-s \fIsysname\fR
149This option allows a command line override for the \fIATHENA_SYS\fR
150value used in generating new style machine directories.
151.TP 8
152.B \-m \fImachtype\fR
153This option allows a command line override for the \fImachtype\fR
154value used in generating old style machine directories.
155.SH VARIABLES
156The environment variable \fIATHENA_SYS\fR is used to determine the
157sysname value when determining path names for new style paths, unless
158overridden by the \-s option.
159
160The environment variable \fIATHENA_SYS_COMPAT\fR is a colon-separated
161list of fallback sysname values which are known to be generally
162compatible with the current system. Thus, on a Solaris 2.6 machine,
163\fIATHENA_SYS\fR may be set to sun4x_56, with \fIATHENA_SYS_COMPAT\fR
164set to sun4x_55:sun4m_54. Then if there is no arch/sun4x_56 directory
165available, arch/sun4x_55 will be checked, etc.
166.SH SEE ALSO
167machtype(1), lockers(7), mkdir(1)
168.SH AUTHOR
169Craig Fields, MIT Information Systems
170.br
171Copyright (c) 1995, Massachusetts Institute of Technology
Note: See TracBrowser for help on using the repository browser.