Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | <!DOCTYPE html>\r |
2 | <html lang="en">\r | |
3 | <head>\r | |
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r | |
5 | <meta name="generator" content="AsciiDoc 8.6.9">\r | |
6 | <title>PortingMLton</title>\r | |
7 | <link rel="stylesheet" href="./asciidoc.css" type="text/css">\r | |
8 | <link rel="stylesheet" href="./pygments.css" type="text/css">\r | |
9 | \r | |
10 | \r | |
11 | <script type="text/javascript" src="./asciidoc.js"></script>\r | |
12 | <script type="text/javascript">\r | |
13 | /*<![CDATA[*/\r | |
14 | asciidoc.install();\r | |
15 | /*]]>*/\r | |
16 | </script>\r | |
17 | <link rel="stylesheet" href="./mlton.css" type="text/css">\r | |
18 | </head>\r | |
19 | <body class="article">\r | |
20 | <div id="banner">\r | |
21 | <div id="banner-home">\r | |
22 | <a href="./Home">MLton 20180207</a>\r | |
23 | </div>\r | |
24 | </div>\r | |
25 | <div id="header">\r | |
26 | <h1>PortingMLton</h1>\r | |
27 | </div>\r | |
28 | <div id="content">\r | |
29 | <div id="preamble">\r | |
30 | <div class="sectionbody">\r | |
31 | <div class="paragraph"><p>Porting MLton to a new target platform (architecture or OS) involves\r | |
32 | the following steps.</p></div>\r | |
33 | <div class="olist arabic"><ol class="arabic">\r | |
34 | <li>\r | |
35 | <p>\r | |
36 | Make the necessary changes to the scripts, runtime system,\r | |
37 | <a href="BasisLibrary"> Basis Library</a> implementation, and compiler.\r | |
38 | </p>\r | |
39 | </li>\r | |
40 | <li>\r | |
41 | <p>\r | |
42 | Get the regressions working using a cross compiler.\r | |
43 | </p>\r | |
44 | </li>\r | |
45 | <li>\r | |
46 | <p>\r | |
47 | <a href="CrossCompiling"> Cross compile</a> MLton and bootstrap on the target.\r | |
48 | </p>\r | |
49 | </li>\r | |
50 | </ol></div>\r | |
51 | <div class="paragraph"><p>MLton has a native code generator only for AMD64 and X86, so, if you\r | |
52 | are porting to another architecture, you must use the C code\r | |
53 | generator. These notes do not cover building a new native code\r | |
54 | generator.</p></div>\r | |
55 | <div class="paragraph"><p>Some of the following steps will not be necessary if MLton already\r | |
56 | supports the architecture or operating system you are porting to.</p></div>\r | |
57 | </div>\r | |
58 | </div>\r | |
59 | <div class="sect1">\r | |
60 | <h2 id="_what_code_to_change">What code to change</h2>\r | |
61 | <div class="sectionbody">\r | |
62 | <div class="ulist"><ul>\r | |
63 | <li>\r | |
64 | <p>\r | |
65 | Scripts.\r | |
66 | </p>\r | |
67 | <div class="openblock">\r | |
68 | <div class="content">\r | |
69 | <div class="ulist"><ul>\r | |
70 | <li>\r | |
71 | <p>\r | |
72 | In <span class="monospaced">bin/platform</span>, add new cases to define <span class="monospaced">$HOST_OS</span> and <span class="monospaced">$HOST_ARCH</span>.\r | |
73 | </p>\r | |
74 | </li>\r | |
75 | </ul></div>\r | |
76 | </div></div>\r | |
77 | </li>\r | |
78 | <li>\r | |
79 | <p>\r | |
80 | Runtime system.\r | |
81 | </p>\r | |
82 | <div class="openblock">\r | |
83 | <div class="content">\r | |
84 | <div class="paragraph"><p>The goal of this step is to be able to successfully run <span class="monospaced">make</span> in the\r | |
85 | <span class="monospaced">runtime</span> directory on the target machine.</p></div>\r | |
86 | <div class="ulist"><ul>\r | |
87 | <li>\r | |
88 | <p>\r | |
89 | In <span class="monospaced">platform.h</span>, add a new case to include <span class="monospaced">platform/<arch>.h</span> and <span class="monospaced">platform/<os>.h</span>.\r | |
90 | </p>\r | |
91 | </li>\r | |
92 | <li>\r | |
93 | <p>\r | |
94 | In <span class="monospaced">platform/<arch>.h</span>:\r | |
95 | </p>\r | |
96 | <div class="ulist"><ul>\r | |
97 | <li>\r | |
98 | <p>\r | |
99 | define <span class="monospaced">MLton_Platform_Arch_host</span>.\r | |
100 | </p>\r | |
101 | </li>\r | |
102 | </ul></div>\r | |
103 | </li>\r | |
104 | <li>\r | |
105 | <p>\r | |
106 | In <span class="monospaced">platform/<os>.h</span>:\r | |
107 | </p>\r | |
108 | <div class="ulist"><ul>\r | |
109 | <li>\r | |
110 | <p>\r | |
111 | include platform-specific includes.\r | |
112 | </p>\r | |
113 | </li>\r | |
114 | <li>\r | |
115 | <p>\r | |
116 | define <span class="monospaced">MLton_Platform_OS_host</span>.\r | |
117 | </p>\r | |
118 | </li>\r | |
119 | <li>\r | |
120 | <p>\r | |
121 | define all of the <span class="monospaced">HAS_*</span> macros.\r | |
122 | </p>\r | |
123 | </li>\r | |
124 | </ul></div>\r | |
125 | </li>\r | |
126 | <li>\r | |
127 | <p>\r | |
128 | In <span class="monospaced">platform/<os>.c</span> implement any platform-dependent functions that the runtime needs.\r | |
129 | </p>\r | |
130 | </li>\r | |
131 | <li>\r | |
132 | <p>\r | |
133 | Add rounding mode control to <span class="monospaced">basis/Real/IEEEReal.c</span> for the new arch (if not <span class="monospaced">HAS_FEROUND</span>)\r | |
134 | </p>\r | |
135 | </li>\r | |
136 | <li>\r | |
137 | <p>\r | |
138 | Compile and install the <a href="GnuMP">GnuMP</a>. This varies from platform to platform. In <span class="monospaced">platform/<os>.h</span>, you need to include the appropriate <span class="monospaced">gmp.h</span>.\r | |
139 | </p>\r | |
140 | </li>\r | |
141 | </ul></div>\r | |
142 | </div></div>\r | |
143 | </li>\r | |
144 | <li>\r | |
145 | <p>\r | |
146 | Basis Library implementation (<span class="monospaced">basis-library/*</span>)\r | |
147 | </p>\r | |
148 | <div class="openblock">\r | |
149 | <div class="content">\r | |
150 | <div class="ulist"><ul>\r | |
151 | <li>\r | |
152 | <p>\r | |
153 | In <span class="monospaced">primitive/prim-mlton.sml</span>:\r | |
154 | </p>\r | |
155 | <div class="ulist"><ul>\r | |
156 | <li>\r | |
157 | <p>\r | |
158 | Add a new variant to the <span class="monospaced">MLton.Platform.Arch.t</span> datatype.\r | |
159 | </p>\r | |
160 | </li>\r | |
161 | <li>\r | |
162 | <p>\r | |
163 | modify the constants that define <span class="monospaced">MLton.Platform.Arch.host</span> to match with <span class="monospaced">MLton_Platform_Arch_host</span>, as set in <span class="monospaced">runtime/platform/<arch>.h</span>.\r | |
164 | </p>\r | |
165 | </li>\r | |
166 | <li>\r | |
167 | <p>\r | |
168 | Add a new variant to the <span class="monospaced">MLton.Platform.OS.t</span> datatype.\r | |
169 | </p>\r | |
170 | </li>\r | |
171 | <li>\r | |
172 | <p>\r | |
173 | modify the constants that define <span class="monospaced">MLton.Platform.OS.host</span> to match with <span class="monospaced">MLton_Platform_OS_host</span>, as set in <span class="monospaced">runtime/platform/<os>.h</span>.\r | |
174 | </p>\r | |
175 | </li>\r | |
176 | </ul></div>\r | |
177 | </li>\r | |
178 | <li>\r | |
179 | <p>\r | |
180 | In <span class="monospaced">mlton/platform.{sig,sml}</span> add a new variant.\r | |
181 | </p>\r | |
182 | </li>\r | |
183 | <li>\r | |
184 | <p>\r | |
185 | In <span class="monospaced">sml-nj/sml-nj.sml</span>, modify <span class="monospaced">getOSKind</span>.\r | |
186 | </p>\r | |
187 | </li>\r | |
188 | <li>\r | |
189 | <p>\r | |
190 | Look at all the uses of <span class="monospaced">MLton.Platform</span> in the Basis Library implementation and see if you need to do anything special. You might use the following command to see where to look.\r | |
191 | </p>\r | |
192 | <div class="listingblock">\r | |
193 | <div class="content monospaced">\r | |
194 | <pre>find basis-library -type f | xargs grep 'MLton\.Platform'</pre>\r | |
195 | </div></div>\r | |
196 | <div class="paragraph"><p>If in doubt, leave the code alone and wait to see what happens when you run the regression tests.</p></div>\r | |
197 | </li>\r | |
198 | </ul></div>\r | |
199 | </div></div>\r | |
200 | </li>\r | |
201 | <li>\r | |
202 | <p>\r | |
203 | Compiler.\r | |
204 | </p>\r | |
205 | <div class="openblock">\r | |
206 | <div class="content">\r | |
207 | <div class="ulist"><ul>\r | |
208 | <li>\r | |
209 | <p>\r | |
210 | In <span class="monospaced">lib/stubs/mlton-stubs/platform.sig</span> add any new variants, as was done in the Basis Library.\r | |
211 | </p>\r | |
212 | </li>\r | |
213 | <li>\r | |
214 | <p>\r | |
215 | In <span class="monospaced">lib/stubs/mlton-stubs/mlton.sml</span> add any new variants in <span class="monospaced">MLton.Platform</span>, as was done in the Basis Library.\r | |
216 | </p>\r | |
217 | </li>\r | |
218 | </ul></div>\r | |
219 | </div></div>\r | |
220 | </li>\r | |
221 | </ul></div>\r | |
222 | <div class="paragraph"><p>The string used to identify a particular architecture or operating\r | |
223 | system must be the same (except for possibly case of letters) in the\r | |
224 | scripts, runtime, Basis Library implementation, and compiler (stubs).\r | |
225 | In <span class="monospaced">mlton/main/main.fun</span>, MLton itself uses the conversions to and\r | |
226 | from strings:</p></div>\r | |
227 | <div class="listingblock">\r | |
228 | <div class="content monospaced">\r | |
229 | <pre>MLton.Platform.{Arch,OS}.{from,to}String</pre>\r | |
230 | </div></div>\r | |
231 | <div class="paragraph"><p>If the there is a mismatch, you may see the error message\r | |
232 | <span class="monospaced">strange arch</span> or <span class="monospaced">strange os</span>.</p></div>\r | |
233 | </div>\r | |
234 | </div>\r | |
235 | <div class="sect1">\r | |
236 | <h2 id="_running_the_regressions_with_a_cross_compiler">Running the regressions with a cross compiler</h2>\r | |
237 | <div class="sectionbody">\r | |
238 | <div class="paragraph"><p>When porting to a new platform, it is always best to get all (or as\r | |
239 | many as possible) of the regressions working before moving to a self\r | |
240 | compile. It is easiest to do this by modifying and rebuilding the\r | |
241 | compiler on a working machine and then running the regressions with a\r | |
242 | cross compiler. It is not easy to build a gcc cross compiler, so we\r | |
243 | recommend generating the C and assembly on a working machine (using\r | |
244 | MLton’s <span class="monospaced">-target</span> and <span class="monospaced">-stop g</span> flags, copying the generated files to\r | |
245 | the target machine, then compiling and linking there.</p></div>\r | |
246 | <div class="olist arabic"><ol class="arabic">\r | |
247 | <li>\r | |
248 | <p>\r | |
249 | Remake the compiler on a working machine.\r | |
250 | </p>\r | |
251 | </li>\r | |
252 | <li>\r | |
253 | <p>\r | |
254 | Use <span class="monospaced">bin/add-cross</span> to add support for the new target. In particular, this should create <span class="monospaced">build/lib/mlton/targets/<target>/</span> with the platform-specific necessary cross-compilation information.\r | |
255 | </p>\r | |
256 | </li>\r | |
257 | <li>\r | |
258 | <p>\r | |
259 | Run the regression tests with the cross-compiler. To cross-compile all the tests, do\r | |
260 | </p>\r | |
261 | <div class="listingblock">\r | |
262 | <div class="content monospaced">\r | |
263 | <pre>bin/regression -cross <target></pre>\r | |
264 | </div></div>\r | |
265 | <div class="paragraph"><p>This will create all the executables. Then, copy <span class="monospaced">bin/regression</span> and\r | |
266 | the <span class="monospaced">regression</span> directory to the target machine, and do</p></div>\r | |
267 | <div class="listingblock">\r | |
268 | <div class="content monospaced">\r | |
269 | <pre>bin/regression -run-only <target></pre>\r | |
270 | </div></div>\r | |
271 | <div class="paragraph"><p>This should run all the tests.</p></div>\r | |
272 | </li>\r | |
273 | </ol></div>\r | |
274 | <div class="paragraph"><p>Repeat this step, interleaved with appropriate compiler modifications,\r | |
275 | until all the regressions pass.</p></div>\r | |
276 | </div>\r | |
277 | </div>\r | |
278 | <div class="sect1">\r | |
279 | <h2 id="_bootstrap">Bootstrap</h2>\r | |
280 | <div class="sectionbody">\r | |
281 | <div class="paragraph"><p>Once you’ve got all the regressions working, you can build MLton for\r | |
282 | the new target. As with the regressions, the idea for bootstrapping\r | |
283 | is to generate the C and assembly on a working machine, copy it to the\r | |
284 | target machine, and then compile and link there. Here’s the sequence\r | |
285 | of steps.</p></div>\r | |
286 | <div class="olist arabic"><ol class="arabic">\r | |
287 | <li>\r | |
288 | <p>\r | |
289 | On a working machine, with the newly rebuilt compiler, in the <span class="monospaced">mlton</span> directory, do:\r | |
290 | </p>\r | |
291 | <div class="listingblock">\r | |
292 | <div class="content monospaced">\r | |
293 | <pre>mlton -stop g -target <target> mlton.mlb</pre>\r | |
294 | </div></div>\r | |
295 | </li>\r | |
296 | <li>\r | |
297 | <p>\r | |
298 | Copy to the target machine.\r | |
299 | </p>\r | |
300 | </li>\r | |
301 | <li>\r | |
302 | <p>\r | |
303 | On the target machine, move the libraries to the right place. That is, in <span class="monospaced">build/lib/mlton/targets</span>, do:\r | |
304 | </p>\r | |
305 | <div class="listingblock">\r | |
306 | <div class="content monospaced">\r | |
307 | <pre>rm -rf self\r | |
308 | mv <target> self</pre>\r | |
309 | </div></div>\r | |
310 | <div class="paragraph"><p>Also make sure you have all the header files in build/lib/mlton/include. You can copy them from a host machine that has run <span class="monospaced">make runtime</span>.</p></div>\r | |
311 | </li>\r | |
312 | <li>\r | |
313 | <p>\r | |
314 | On the target machine, compile and link MLton. That is, in the mlton directory, do something like:\r | |
315 | </p>\r | |
316 | <div class="listingblock">\r | |
317 | <div class="content monospaced">\r | |
318 | <pre>gcc -c -Ibuild/lib/mlton/include -Ibuild/lib/mlton/targets/self/include -O1 -w mlton/mlton.*.[cs]\r | |
319 | gcc -o build/lib/mlton/mlton-compile \\r | |
320 | -Lbuild/lib/mlton/targets/self \\r | |
321 | -L/usr/local/lib \\r | |
322 | mlton.*.o \\r | |
323 | -lmlton -lgmp -lgdtoa -lm</pre>\r | |
324 | </div></div>\r | |
325 | </li>\r | |
326 | <li>\r | |
327 | <p>\r | |
328 | At this point, MLton should be working and you can finish the rest of a usual make on the target machine.\r | |
329 | </p>\r | |
330 | <div class="listingblock">\r | |
331 | <div class="content monospaced">\r | |
332 | <pre>make basis-no-check script mlbpathmap constants libraries tools</pre>\r | |
333 | </div></div>\r | |
334 | </li>\r | |
335 | <li>\r | |
336 | <p>\r | |
337 | Making the last tool, mlyacc, will fail, because mlyacc cannot bootstrap its own yacc.grm.* files. On the host machine, run <span class="monospaced">make -C mlyacc src/yacc.grm.sml</span>. Then copy both files to the target machine, and compile mlyacc, making sure to supply the path to your newly compile mllex: <span class="monospaced">make -C mlyacc MLLEX=mllex/mllex</span>.\r | |
338 | </p>\r | |
339 | </li>\r | |
340 | </ol></div>\r | |
341 | <div class="paragraph"><p>There are other details to get right, like making sure that the tools\r | |
342 | directories were clean so that the tools are rebuilt on the new\r | |
343 | platform, but hopefully this structure works. Once you’ve got a\r | |
344 | compiler on the target machine, you should test it by running all the\r | |
345 | regressions normally (i.e. without the <span class="monospaced">-cross</span> flag) and by running a\r | |
346 | couple rounds of self compiles.</p></div>\r | |
347 | </div>\r | |
348 | </div>\r | |
349 | <div class="sect1">\r | |
350 | <h2 id="_also_see">Also see</h2>\r | |
351 | <div class="sectionbody">\r | |
352 | <div class="paragraph"><p>The above description is based on the following emails sent to the\r | |
353 | MLton list.</p></div>\r | |
354 | <div class="ulist"><ul>\r | |
355 | <li>\r | |
356 | <p>\r | |
357 | <a href="http://www.mlton.org/pipermail/mlton/2002-October/013110.html">http://www.mlton.org/pipermail/mlton/2002-October/013110.html</a>\r | |
358 | </p>\r | |
359 | </li>\r | |
360 | <li>\r | |
361 | <p>\r | |
362 | <a href="http://www.mlton.org/pipermail/mlton/2004-July/016029.html">http://www.mlton.org/pipermail/mlton/2004-July/016029.html</a>\r | |
363 | </p>\r | |
364 | </li>\r | |
365 | </ul></div>\r | |
366 | </div>\r | |
367 | </div>\r | |
368 | </div>\r | |
369 | <div id="footnotes"><hr></div>\r | |
370 | <div id="footer">\r | |
371 | <div id="footer-text">\r | |
372 | </div>\r | |
373 | <div id="footer-badges">\r | |
374 | </div>\r | |
375 | </div>\r | |
376 | </body>\r | |
377 | </html>\r |