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