| 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>–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>–fPIC</CODE>. |
| 156 |
|
| 157 |
<DT><CODE>RLINK</CODE> |
| 158 |
<DD>General runtime libraries. |
| 159 |
Many systems require <CODE>–lm</CODE> to link |
| 160 |
the math library. |
| 161 |
Some systems also require <CODE>–ldl</CODE> to link |
| 162 |
<CODE>dlopen()</CODE>. |
| 163 |
|
| 164 |
<DT><CODE>TLIBS</CODE> |
| 165 |
<DD>Thread library. |
| 166 |
Some systems require <CODE>–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> |