Debian Codegraph @

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