1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META NAME=viewport CONTENT="width=device-width, initial-scale=1">
<TITLE>Porting the Icon Implementation</TITLE>
<LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css">
<LINK REL="SHORTCUT ICON" HREF="shortcut.gif">
</HEAD>
<BODY>
<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif"
ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A>
<H1>Porting the Icon Implementation</H1>
<P> Gregg M. Townsend
<BR> <SMALL> Department of Computer Science </SMALL>
<BR> <SMALL> The University of Arizona </SMALL>
<P> <SMALL> www.cs.arizona.edu/icon/uguide/port.htm
<BR> Last reviewed March 25, 2010
<BR> Minor update May 29, 2016
<BR> Minor update July 12, 2022
</SMALL>
<H2> Introduction </H2>
This document describes how to port a source release of Icon to a new platform.
It assumes familiarity with the process by which Icon is
<A HREF=build.htm>built from source</A>
using an existing configuration.
<H2>Requirements</H2>
Icon expects the underlying system to conform to certain standards
that are met by most modern systems.
These are not necessarily the latest standards but rather
versions that have already been widely implemented.
Newer standards maintain compatibility and present no problems.
<H3>POSIX Commands</H3>
Icon is built using Makefiles and shell scripts, as defined by
POSIX.2 (IEEE 1003.2-1992).
Additionally, Icon uses Makefile <DFN>includes</DFN>,
which were finally recognized by the standard in 2013.
<H3>C Compiler</H3>
Icon requires a production-quality compiler supporting C99 (ISO/IEC 9899:1999).
<EM>Production quality</EM> implies correctness, robustness,
and the ability to handle large files and complicated expressions.
<H3>C Data Sizes</H3>
Icon places the following requirements on C data sizes:
<UL>
<LI><I>chars</I> must be 8 bits.
<LI><I>ints</I> must be 16, 32, or 64 bits.
<LI><I>longs</I> and pointers must be 32 or 64 bits.
<LI>All pointers must be the same length.
<LI>Pointers and <I>longs</I> must be the same length.
</UL>
If your C data sizes do not meet these requirements,
do not attempt to configure Icon.
<H3>POSIX Library</H3>
In addition to the standard C library, Icon uses the library functions
specified by POSIX.1 (IEEE 1993.1-1996).
In particular, Icon uses <DFN>POSIX threads</DFN> and <DFN>semaphores</DFN>
to implement context switching for co-expressions.
<H2> The Porting Process </H2>
Every different Icon configuration has its own subdirectory in the
<CODE>config</CODE> directory of the Icon source tree.
To add a new configuration, create a new directory and copy in the
<CODE>define.h</CODE>, <CODE>Makedefs</CODE>, and <CODE>status</CODE> files
from the <CODE>posix</CODE> configuration directory.
<P> The porting process involves repeating these steps until
the system is working:
<OL>
<LI> Edit the configuration files as described below.
<LI> Configure:
<CODE>make Configure name=</CODE><VAR>newdirectory</VAR>
<LI> Build: <CODE>make</CODE>
<LI> Test: <CODE>make Test</CODE>
</OL>
If a configuration parameter is changed it is necessary to
reconfigure and rebuild from the beginning.
<P> The Icon source code has proven to be robust and portable.
Most porting problems are related to command options and library locations,
the things that are configured in the <CODE>Makedefs</CODE> file.
<P> If the system builds smoothly, but problems are revealed by
<CODE>make Test</CODE>, try removing any C optimization options.
New compilers are often stressed beyond their capabilities by Icon.
<P> It is best to start by building just the basic Icon system.
When that is working, repeat with <CODE>make X-Configure</CODE>
instead of <CODE>make Configure</CODE> to build Icon with graphics.
(Note that <CODE>make Test</CODE> does not test graphics, and so you
should also execute <CODE>bin/colrbook</CODE> as an additional manual test.)
Finally, when those configurations are working, you may wish to
enable dynamic loading as described in a later section.
<H2> Configuration Parameters </H2>
Icon is set up by editing three files in the configuration directory
of a particular platform.
You can examine the files in other directories to see working examples.
After a configuration file is changed, Icon must be reconfigured
and rebuilt from the beginning (step 2 above).
These instructions assume that you are starting from copies of
the <CODE>posix</CODE> configuration files.
<H3> <CODE>define.h</CODE> </H3>
Edit the comment at the beginning of <CODE>define.h</CODE>,
but otherwise leave this file alone.
Although some older configurations may define additional values,
they are not needed here.
<H3> <CODE>Makedefs</CODE> </H3>
The critical configuration work is done by editing the
<CODE>Makedefs</CODE> file.
The parameters set here are:
<BLOCKQUOTE><DL>
<DT><CODE>CC</CODE>
<DD>The command name for the C compiler. Typical values are
<CODE>cc</CODE>, <CODE>gcc</CODE>, or <CODE>c99</CODE>.
<DT><CODE>CFLAGS</CODE>
<DD>C compiler flags. A path specification for the X11 libraries
is usually needed.
Include <CODE>–O </CODE> to optimize the C code,
but remove it if it causes problems.
<DT><CODE>CFDYN</CODE>
<DD>C compiler flags for generating dynamic libraries,
usually a flag that generates position-independent code.
A typical value is <CODE>–fPIC</CODE>.
<DT><CODE>RLINK</CODE>
<DD>General runtime libraries.
Many systems require <CODE>–lm</CODE> to link
the math library.
Some systems also require <CODE>–ldl</CODE> to link
<CODE>dlopen()</CODE>.
<DT><CODE>TLIBS</CODE>
<DD>Thread library.
Some systems require <CODE>–lpthread</CODE> or other
values (see examples in other configurations) to link the
threads library.
<DT><CODE>XLIBS</CODE>
<DD>Linker specifications for the X Windows library.
Many systems need both a path and a library name here.
</DL></BLOCKQUOTE>
<H3> <CODE>status</CODE> </H3>
The <CODE>status</CODE> file is not used by the build process,
but it should be edited to document the target platform,
and it should be updated whenever the configuration changes.
<H2> Dynamic Loading </H2>
Icon's optional dynamic loading facility allows Icon programs
to call specially written user C code via the built-in
<CODE>loadfunc</CODE> procedure.
Dynamic loading is enabled by
<OL>
<LI> Editing <CODE>config/</CODE><VAR>name</VAR><CODE>/define.h</CODE>
to add <CODE>#define LoadFunc</CODE> at the end.
<LI> Editing <CODE>ipl/cfuncs/mklib.sh</CODE>
to add a new case to the shell script that builds
a shared library from a set of C object files.
<LI> Reconfiguring, rebuilding, and retesting as usual.
If dynamic loading is enabled in <CODE>define.h</CODE>,
it is tested by <CODE>make Test</CODE>.
</OL>
<P> The second step is the hardest; on many systems, documentation
that discusses shared libraries is scant or nonexistent.
<P> If problems are found while building, check especially the definitions
of the <CODE>Makedefs</CODE> parameters
<CODE>CFDYN</CODE> and <CODE>RLINK</CODE>.
<H2> Feedback </H2>
Please let us know if you complete a port to a new platform.
Review the <CODE>status</CODE> file one last time and make
sure it is correct.
Send the files from the new configuration directory
(and also <CODE>mklib.sh</CODE>, if changed) to
<A HREF="mailto:icon-project@cs.arizona.edu">icon-project@cs.arizona.edu</A>.
Please also tell us the values reported on that platform by the
<CODE>uname -p</CODE> and <CODE>uname -m</CODE> commands.
<HR>
</BODY>
</HTML>
|
