Debian Codegraph @

doc/files.htm

raw
1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <HTML>
3 <HEAD>
4 <META NAME=viewport CONTENT="width=device-width, initial-scale=1">
5 <TITLE>File Organization in Versions Icon Installations</TITLE>
6 <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css">
7 <LINK REL="SHORTCUT ICON" HREF="shortcut.gif">
8 </HEAD>
9 <BODY>
10
11 <P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif"
12 ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A>
13
14 <H1> File Organization in Icon Installations</H1>
15
16 <P> Gregg M. Townsend
17 <BR> <SMALL> Department of Computer Science </SMALL>
18 <BR> <SMALL> The University of Arizona </SMALL>
19
20 <P> <SMALL> www.cs.arizona.edu/icon/uguide/files.htm
21 <BR> Last updated November 16, 2009 </SMALL>
22
23 <H2> Introduction </H2>
24
25 <P> Version 9.4 of Icon introduced several changes to the organization
26 of Icon's files under Unix and the methods for finding them.
27 These changes, which are described below, simplify the installation
28 and use of Icon.
29
30 <H2> Library procedure inclusion </H2>
31
32 <P> As Icon evolved, the procedures from the Icon program library
33 became more important to basic Icon programs, and vital to graphics
34 programs; yet the IPL had been treated as a separate product.
35 A complete Icon system required two downloads and two installation
36 efforts, with proper coordination.
37
38 <P> Now, the complete set of basic and graphics library
39 procedures is included with every binary Icon distribution.
40 Also present are the associated <CODE>$include</CODE> files
41 and a selected few programs from the library &mdash;
42 notably VIB, the visual interface builder.
43
44 <P> Source distributions of Icon include the full library,
45 which also continues to be available separately.
46
47 <H2> Installation directory structure </H2>
48
49 <P> An Icon binary distribution unpacks to produce an <CODE>icon</CODE>
50 directory containing <CODE>bin</CODE>, <CODE>lib</CODE>, <CODE>man</CODE>,
51 and <CODE>doc</CODE> subdirectories.
52 Building Icon from source produces these same directories.
53
54 <P> The <CODE>bin</CODE> directory contains executables of
55 <CODE>icont</CODE>, the Icon translator;
56 <CODE>iconx</CODE>, the Icon interpreter;
57 a few library programs including <CODE>vib</CODE>;
58 and <CODE>libcfunc.so</CODE>, the loadable C functions.
59 There is a symbolic link from <CODE>icon</CODE> to <CODE>icont</CODE>.
60 Files in this directory are system dependent.
61
62 <P> The <CODE>lib</CODE> directory holds <CODE>$include</CODE> files
63 and "ucode" (<CODE>.u1</CODE>/<CODE>.u2</CODE>) files of
64 program library procedures.
65 This directory is system independent.
66
67 <P> The <CODE>man</CODE> directory holds the Unix <CODE>man</CODE> pages
68 for <CODE>icon</CODE> and <CODE>icont</CODE>, and the <CODE>doc</CODE>
69 directory holds HTML (<CODE>.htm</CODE>) documentation files.
70 These directories are also system independent.
71
72 <P> This structure is similar to that of binary distributions of Icon 9.3.
73 The main difference is that the <CODE>lib</CODE> directory no longer holds
74 just a subset of the procedure collection, and the few files from
75 the former <CODE>include</CODE> directory have moved into <CODE>lib</CODE>.
76
77 <H2> Installation location </H2>
78
79 <P> The <CODE>icon</CODE> directory can be installed in any public or
80 private area as long as its internal structure is preserved.
81 When upgrading an existing Icon installation, replacing the previous
82 Icon directory with the new one may provide the smoothest transition.
83 Old Icon binaries will continue to function correctly with the new
84 interpreter.
85
86 <P> In order to consider packaging Icon binaries in Linux RPM files,
87 or other similar packages, it is necessary to define a "canonical"
88 location for installing Icon.
89 The suggested canonical system installation location for Icon is
90 <CODE>/opt/icon</CODE>.
91 The <CODE>/opt</CODE> directory is present today on most Unix systems and is
92 the location recommended by the emerging File Hierarchy Standard (FHS),
93 <A HREF="http://www.pathname.com/fhs/">www.pathname.com/fhs</A>.
94
95 <P> For convenience of use it may be desirable to provide symbolic
96 links from a directory such as /opt/bin or /usr/local/bin
97 to programs in the Icon <CODE>bin</CODE> directory.
98 If this is done, the list should include at least <CODE>icon</CODE>,
99 <CODE>icont</CODE>, <CODE>iconx</CODE>, and <CODE>vib</CODE>.
100
101 <H2> Automatic inference of <CODE>iconx</CODE> location </H2>
102
103 <P> Past versions of <CODE>icont</CODE> were configured to know
104 the location of <CODE>iconx</CODE> in order to embed this in
105 generated binaries.
106 The <CODE>iconx</CODE> location was configured by editing
107 <CODE>src/h/path.h</CODE> in source builds or by using the
108 <CODE>patchstr</CODE> utility to edit the <CODE>icont</CODE>
109 executable when installing a binary distribution.
110
111 <P> Now, <CODE>icont</CODE> deduces its own location,
112 and from this it infers the location of <CODE>iconx</CODE>
113 in the same directory.
114 No configuration of <CODE>icont</CODE> is needed, and the correct
115 path is embedded automatically, requiring only that
116 <CODE>icont</CODE> and <CODE>iconx</CODE> reside in the same directory.
117
118 <P> It is still possible to configure a fixed path in
119 <CODE>icont</CODE> using the <CODE>patchstr</CODE> utility.
120 If this is done, the configured path is used instead of the
121 inferred path.
122
123 <H2> Automatic search for iconx at execution </H2>
124
125 <P> The path that <CODE>icont</CODE> embeds in an Icon executable makes
126 binary distributions of Icon programs difficult because the embedded
127 path must be edited to match the installed location of <CODE>iconx</CODE>.
128 The <CODE>ipatch</CODE> utility performed this task when installing
129 binary distributions of Icon 9.3.
130
131 <P> Icon implements a simple search in the shell script that
132 heads each generated Icon executable.
133 The new header script searches for <CODE>iconx</CODE>
134 in these places:
135
136 <OL>
137 <LI> in the location specified by the ICONX environment variable
138 <LI> in the same directory as executing binary
139 <LI> in a location specified in the script itself
140 (as generated by <CODE>icont</CODE> or as patched later)
141 <LI> in the command search path ($PATH)
142 </OL>
143
144 <P> The second item is the key: If there is a copy of <CODE>iconx</CODE>
145 in the same directory as the executing program, it is found automatically
146 and used as the interpreter.
147 An Icon program can now be distributed in binary form
148 simply by including an <CODE>iconx</CODE> executable
149 in the same directory as the program executable.
150
151 <P> The <CODE>ipatch</CODE> utility has been modified to recognize
152 both old and new headers, and can still be used to edit the path
153 embedded in an Icon executable.
154
155 <H2> Automatic library access </H2>
156
157 <P> The ability to figure out its own location also lets
158 <CODE>icont</CODE> provide automatic access to library procedures.
159 The inferred location of the <CODE>lib</CODE> directory is implicitly
160 appended to the paths, if any, specified by LPATH and IPATH
161 environment variables.
162 To use only the standard library files, no environment variables
163 need be set.
164
165 <P> In a similar manner, <CODE>iconx</CODE> creates or alters the
166 FPATH environment variable before beginning execution of an Icon
167 program. This provides transparent access to the library's
168 loadable C functions without requiring explicit user action.
169
170 <H2> No Setup step </H2>
171
172 <P> With the changes above, the executable files in an Icon binary
173 distribution are ready for use without modification.
174 The annoying and error-prone Setup step that was necessary
175 with previous versions is no longer required.
176 Now, installation can be as simple as just unpacking the
177 tar file and adding its <CODE>bin</CODE> directory to the search path.
178
179 <HR>
180
181 </BODY>
182 </HTML>