5 * HOWTO customize GCC behaviour, by modification of an external
11 * Written by Keith Marshall <keith@users.osdn.me>
12 * Copyright (C) 2021, MinGW.OSDN Project
15 * Redistribution and use in source and 'compiled' forms (SGML, HTML,
16 * PDF, PostScript, RTF, etc) with or without modification, are permitted
17 * provided that the following conditions are met:
19 * 1. Redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer as
21 * the first lines of this file, unmodified.
23 * 2. Redistributions in compiled form (transformed to other DTDs,
24 * converted to PDF, PostScript, RTF and other formats) must
25 * reproduce the above copyright notice, this list of conditions
26 * and the following disclaimer in the documentation and/or other
27 * materials provided with the distribution.
29 * THIS DOCUMENTATION IS PROVIDED BY THE MINGW.OSDN PROJECT "AS IS"
30 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
31 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
32 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MINGW.OSDN PROJECT, OR
33 * ITS CONTRIBUTORS, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39 * OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
43 * Note: this page assumes browser support for the following numeric
46 *   fixed width 1/4 em space
47 * ‑ non-breaking hyphen
48 * ‘ typographic left (opening) single quote
49 * ’ typographic apostrophe/right (closing) single quote
50 * “ typographic left (opening) double quote
51 * ” typographic right (closing) double quote
54 <script class="masthead">
55 /* Script fragment, to assign titles specific to this page; this is
56 * encapsulated within the "masthead", where such titles are displayed,
57 * to ensure that whatever page content may follow will be correctly
58 * positioned, relative to the masthead content.
60 set_page("title", "MinGW Compiler Suite User Guide");
61 set_page("subtitle", "HOWTO Customize the Default Behaviour of the MinGW Compiler");
62 </script><!-- masthead -->
63 <!--<p class="byline">Posted: 2021-07-03, by Keith; Last Update: 2021-07-03</p>-->
65 <div class="overlapped" id="intro">
67 <p>The MinGW compiler comprises a comprehensive suite of separate programs,
68 intended for deployment as a native compiler, on the Microsoft Windows platform,
69 or alternatively, as a cross‑compiler for use on some other platform,
70 to create applications for deployment on the native Windows platform.
71 In either case, the compiler suite consists of, at least:–
73 <li>The GNU Compiler Collection (GCC),
74 built either as a fully native suite, or as a cross‑compiler suite,
75 with Microsoft Windows as the code‑generator target.
77 <li>The GNU Binutils suite; this comprises, primarily,
78 the GNU assembler, the GNU linker, and the GNU archive librarian,
79 accompanied by a small collection of other utility programs,
80 also built with Microsoft Windows as the code‑generator target.
82 <li>The MinGW C runtime libraries,
83 (which integrate with Microsoft’s C runtime library),
84 and the MinGW Windows API suite,
85 (which integrates with Microsoft’s core Windows system DLLs).
87 <p>In addition to the above,
88 a native MinGW compiler deployment is accompanied by several other GNU DLLs,
89 which are required to support the operation of the compiler itself;
90 in the case of a cross‑compiler,
91 the function of these additional DLLs is served by equivalents,
92 which are native to the platform on which the cross‑compiler is run.
94 <p>Regardless of whether it is deployed as a native compiler,
95 or as a cross‑compiler suite,
96 the MinGW compiler, assembler, and linker are normally invoked
97 by means of a common <em>driver</em>  program;
98 in the case of a native compiler,
99 this driver program is normally <code>gcc</code>,
100 (or <code>g++</code>, when compiling C++ code);
101 in the case of a cross‑compiler,
102 the corresponding driver programs may be <code>mingw32‑gcc</code>,
103 and <code>mingw32‑g++</code>,
104 (possibly qualified by an additional prefix,
105 to identify the target CPU).
107 the driver program determines the sequence of auxiliary programs,
108 which are to be executed,
109 and the options and file names which are to be passed to them,
110 on the basis of:–
112 <li>The options, and file names,
113 which are specified on the command line
114 which invokes the driver program itself.
116 <li>A collection of ‘specs’ strings,
117 such as those which are identified in
118 <a rel="noopener noreferrer" target="_blank"
119 href="http://gcc.gnu.org/onlinedocs/gcc/Spec-Files.html"
120 >the relevant section of the GCC on‑line manual</a>;
121 a default set of such ‘specs’ strings is
122 compiled into the driver programs,
123 but the user is permitted to modify, and even add to these,
124 and so modify the default behaviour of the compiler.
127 we explore the capabilities afforded by ‘specs’ string
128 modifications, illustrating these capabilities by examples of:–
130 <li><a href="#isystem">Adding directories to the include file search path</a>,
131 as recommended in the
132 “<a target="_blank" href="index.html?page=isystem.html#third-party"
133 >Include File Search Path HOWTO</a>”,
134 as it relates to the use of third‑party libraries with MinGW.
136 <li><a href="#libpath">Adding directories to the library search path</a>,
137 as recommended in the
138 “<a target="_blank" href="index.html?page=libpath.html#customize"
139 >Library Search Path HOWTO</a>”,
140 as it relates to the customization of the default library search path.
142 <li><a href="#msvcrt">Adding support for linking with
143 Microsoft’s non‑free C runtime libraries</a>,
144 such as those which are distributed with the
145 Microsoft Visual C Compiler suite.
149 <div class="overlapped" id="prep">
150 <h3>Preparing the GCC ‘specs’ for Customization</h3>
152 the behaviour of GCC is controlled by
153 a collection of ‘specs’ strings,
154 which are defined at the time when GCC itself is built,
155 and are built‑in to the driver program;
156 such built‑in ‘specs’ strings
157 are <em>internally immutable</em>, 
158 but any of them may be redefined in <em>external</em> 
159 ‘specs’ files,
160 thus allowing them to be <em>effectively modified</em> 
161 at GCC run‑time.
162 Thus, it should be evident
163 that customization of GCC behaviour will require
164 the use of <em>external</em> 
165 ‘specs’ files.
167 <p>Before we embark on the customization process,
168 it may be helpful to clarify some aspects of how GCC interprets,
169 ‘specs’ files ... an area in which the GCC documentation,
170 and its built‑in help are ambiguously vague!
172 within the built‑in help:
174 <pre class="vt box-out">
175 $ <kbd>gcc --help</kbd>
177 -specs=<file> Override built-in specs with the contents of <file>.
180 <p>this terse description of the <code>-specs</code> option,
181 while technically accurate,
182 may lead to a misconception that,
183 when this option is specified,
184 GCC will ignore its built‑in ‘specs’
185 <em>in their entirety</em> ;
188 <li><em>Before</em>  reading <em>any</em>  file,
189 which has been nominated with the <code>-specs=<file></code> option,
190 GCC <em>will</em>,  with <em>just one exception</em>, 
191 initialize its <em>default ‘specs’</em>  state
192 to that which is directed by its built‑in ‘specs’.
194 <li>The <em>one exception</em>  to the preceding initialization
195 arises when an <em>external</em>  ‘specs’ file,
196 <em>explicitly</em>  named “specs”,
197 is present: in this case,
198 GCC <em>will</em>  ignore its built‑in ‘specs’,
199 and will read its default ‘specs’ state from this file instead.
200 This explicitly named ‘specs’ file need <em>not</em>  be
201 invoked by means of a <code>-specs=specs</code> option; (indeed,
202 if it is, it will be read <em>twice</em>, 
203 the effect of which is unlikely to be desired).
205 <li>Only <em>after</em> 
206 its default ‘specs’ state has been initialized,
207 will GCC read <em>any</em>  ‘specs’ file
208 which has been nominated by means of
209 a <code>-specs=<file></code> option.
210 Each ‘specs’ file so nominated,
211 (more than one is permitted, in which case they will be read
212 in strictly left‑to‑right order, as nominated),
213 will <em>augment</em>  the prevailing ‘specs’ state,
214 (as it has been established at the time when each file is read);
216 <ol style="list-style: lower-roman">
217 <li><em>Add</em> 
218 new <em>custom</em>  ‘specs’ strings.
220 <li><em>Redefine</em> 
221 any <em>existing</em>  ‘specs’ string,
222 <em>in its entirety</em> ;
223 (such redefinition <em>does</em>  have the effect of
224 <em>overriding</em>  each redefined ‘specs’ string,
225 but the effect is <em>selective</em> ).
227 <li><em>Append</em>  additional text
228 to any <em>existing</em>  ‘specs’ string;
229 (this <em>modifies</em>  the affected ‘specs’ string,
230 but does not, strictly speaking, <em>override</em>  it).
232 <li><em>Delete</em> 
233 any <em>existing</em>  ‘specs’ string.
235 <li>Compilation ultimately proceeds
236 with whatever ‘specs’ state prevails,
237 after all applicable customizations have been processed.
239 <p>Having established an understanding of
240 how GCC processes ‘specs’ files,
241 we may now progress to development of our customization strategy.
242 First we must decide, in the case of each planned customization,
243 whether we would like it to affect <em>every</em>  GCC invocation,
244 or if it should be subject to selection,
245 by specification of a <code>-specs=<file></code> option.
247 the customization should be applied in a ‘specs’ file
248 which overrides all of the built‑in ‘specs’,
249 (i.e. in a file named “specs”);
250 in the latter, a selective customization
251 (in a file with any user-chosen name other than “specs”)
252 may be more appropriate.
254 <p>Regardless of how any required ‘specs’ files are to be named,
255 they <em>must</em>  be installed at an appropriate location within the
256 GCC installation directory hierarchy;
257 the appropriate directory path name may be identified,
258 (as in this example for a MinGW installation of GCC-3.4.5),
259 by running the command:
261 <pre class="vt box-out">
262 $ <kbd>gcc -print-libgcc-file-name</kbd>
263 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/libgcc.a
265 <p>and discarding the final file name component of the path name,
266 to obtain a directory path name resembling
267 <code>c:/mingw/bin/../lib/gcc/mingw32/3.4.5</code>.
269 <p>Note: if you are running this
270 in an MSYS (or other POSIX‑compatible) shell,
271 and assuming that the <code>sed</code> utility program is installed,
272 you may wish to use it, in an adaptation of the preceding command,
273 to obtain the requisite directory path name directly,
274 expressing it in canonical form):
276 <pre class="vt box-out">
277 $ <kbd>gcc -print-libgcc-file-name | sed 's!/[^/]*$!!;:1;s![^/][^/]*/\.\./!/!;t 1'</kbd>
278 c:/mingw/lib/gcc/mingw32/3.4.5
280 <p>Alternatively, in Microsoft’s <code>cmd.exe</code> shell,
281 with a suitable POSIX‑compatible <code>sed</code> utility program available,
282 you may use the same adaptation of the command,
283 <em>except</em>  that you <em>must</em> substitute double quotes,
284 in place of the single quotes:
286 <pre class="vt box-out">
287 C:\> <kbd>gcc -print-libgcc-file-name | sed "s!/[^/]*$!!;:1;s![^/][^/]*/\.\./!/!;t 1"</kbd>
288 c:/mingw/lib/gcc/mingw32/3.4.5
290 <p>If you plan to apply any customizations
291 which you wish to take effect <em>every</em>  time you run GCC,
292 (i.e. <em>without</em>  requiring
293 a <code>-specs=<file></code> option),
294 then you <em>must</em>  apply those customizations
295 within a ‘specs’ file which is
296 <em>explicitly</em>  named “specs”,
297 in the directory which you have just identified,
299 If such a ‘specs’ file already exists,
300 then you are good to go;
302 (in case you need to revert it ... a mistake in customization
303 could break GCC in some “interesting” way),
304 then proceed to edit it,
305 to apply your chosen customizations.
306 Conversely, if no file named “specs” yet exists,
307 in the appropriate directory,
309 Ideally, you should start from a baseline which <em>exactly</em> reproduces
310 GCC’s built‑in ‘specs’;
311 you may create, (or subsequently revert to), such a baseline,
312 by running the command:
314 <pre class="vt box-out">
315 $ <kbd>gcc -dumpspecs > c:/path/to/libgcc/dir/specs</kbd>
317 <p>where <code>/path/to/libgcc/dir</code> represents the path
318 to the directory in which <code>libgcc.a</code> is installed,
319 as you have identified previously, from the output of the
320 <span class="nowrap"><code>gcc -print-libgcc-file-name</code></span> command;
321 (thus, by extension of the earlier example, you would execute):
323 <pre class="vt box-out">
324 $ <kbd>gcc -dumpspecs > c:/mingw/lib/gcc/mingw32/3.4.5/specs</kbd>
328 <div class="overlapped" id="isystem">
329 <h3>Defining a Custom Include File Search Path</h3>
331 “<a target="_blank" href="index.html?page=isystem.html"
332 >Include File Search Path HOWTO</a>”,
333 if a <code>mingw32</code> build of GCC had been
334 configured to run on a typical Unix system,
335 it might be expected to search for include files
336 in <code>/usr/local/include</code>,
337 some GCC and <code>mingw32</code> specific directories,
338 and <code>/usr/include</code>.
340 <p>On its native MS‑Windows host,
341 when installed at its default file system location of <code>C:/MinGW</code>,
342 it may seem reasonable to consider that <code>C:/MinGW</code> could be used
343 as a representative equivalent of the <code>/usr</code> directory
344 of the typical Unix system; thus,
345 <code>C:/MinGW/local/include</code> would be equivalent to
346 the Unix system’s <code>/usr/local/include</code> directory.
347 However, in a standard <code>mingw32</code> build of GCC,
348 <code>C:/MinGW/local/include</code> is conspicuously <em>omitted</em> 
349 from the configured include file search path.
352 the <code>/usr/local/lib</code> file system hierarchy
353 would typically be used to segregate third‑party,
354 locally installed libraries, from the core system libraries,
355 with the corresponding header files,
356 associated with such locally installed libraries,
357 being placed into the file system hierarchy
358 below <code>/usr/local/include</code>.
359 From a system management perspective,
360 this segregation is very convenient;
361 the absence of a similar file system infrastructure,
362 in a standard MinGW installation,
363 introduces an inconvenience which we would like to mitigate.
366 having created a supporting directory structure,
367 and installed our third‑party header files within it,
368 we can <em>always</em>  instruct GCC to search for them by specifying
369 <code>-I...</code>, <code>-isystem</code> <code>...</code>,
370 or even <code>-iquote</code> <code>...</code> options to GCC commands,
371 or by specifying <code>CPATH=...</code>, <code>C_INCLUDE_PATH=...</code>,
372 <code>CPLUS_INCLUDE_PATH=...</code>, or <code>OBJC_INCLUDE_PATH=...</code>
373 <em>environment variables</em>,  as appropriate;
374 of more interest here, however,
375 is the development of an inconvenience mitigating configuration,
376 by means of ‘specs’ file customization.
378 <p>Let us assume that we have created a suitable
379 file system hierarchy at <code class="nowrap">C:/MinGW/local</code>,
380 and we have installed our third‑party header files
381 into <code class="nowrap">C:/MinGW/local/include</code>;
382 (we could just as well have chosen a path outside
383 the default MinGW installation hierarchy
384 . . . say <code class="nowrap">C:/Local/MinGW</code>,
386 <code class="nowrap">C:/Local/MinGW/include</code> . . .
387 but the principle remains the same;
388 we would simply substitute <code class="nowrap">C:/Local/MinGW</code>
389 for <code class="nowrap">C:/MinGW/local</code>,
390 in ‘specs’ file references).
391 Given this assumption, as stated,
392 our objective will be to customize the GCC ‘specs’ state,
393 such that <code class="nowrap">C:/MinGW/local/include</code> will be searched,
394 as if specified by <code class="nowrap">-isystem C:/MinGW/local/include</code>,
395 <em>every</em>  time GCC is invoked.
397 <p>Since we would like this customization to apply for every GCC invocation,
398 the most appropriate place to make the necessary changes is in the external
399 ‘specs’ file which is explicitly named “specs”,
400 rather than in any which needs to be nominated by specification of
401 a <code>-specs=<file></code> option.
402 If this file already exists, make a backup copy of it,
403 (in case you mess it up, and need to revert it);
404 if it does not yet exist, create it.
405 (Please refer to <a href="#prep">the preceding section, within this document</a>,
406 for advice on how to locate, or how to create, this “specs” file,
407 if you do not already know).
409 <p>Next, open this “specs” file
410 in your favourite text‑file editor, and add:
412 <pre class="box-out">
417 -I %(local_prefix)include
420 <p>at (or near) the top of the file,
421 taking care to ensure that each of
422 these new custom ‘specs’ string definitions,
423 (while also taking care to preserve the same structure
424 for <em>all existing</em>,  adjacent definitions),
425 comprises <em>exactly</em> :
427 <li>One line, beginning with an asterisk and ending with a colon,
428 specifying the <em>name</em>  of of the custom ‘specs’
429 string, between these punctuation marks.
431 <li>One (or more) non‑blank lines,
432 specifying the <em>value</em>  of the named ‘specs’ string.
434 <li>One final line, to terminate the ‘specs’ string definition;
435 (this line <em>must</em>  be <em>completely empty</em> ;
436 take care that no white space is accidentally inserted).
439 to make GCC actually <em>use</em> 
440 our <code>local_includes</code> definition,
441 we must append it to each of GCC's own (existing) <code>ccp</code>,
442 and <code>cc1plus</code> definitions.
443 While the “specs” file is still open,
444 in your text‑file editor,
445 move to the end of the file,
448 <pre class="box-out">
457 taking care to leave the <em>two empty lines</em>, 
459 before saving the file,
460 and quitting from the text‑editor,
461 to complete the modification.
463 <p>Astute readers may have noticed that,
464 to the extent to which this ‘specs’ file modification uses it,
465 our definition of <code>local_prefix</code> is effectively redundant;
466 we could just as well have specified the value of
467 <code>local_includes</code> <em>directly</em>, 
468 to be <code class="nowrap">-isystem c:/mingw/local/include</code>,
469 and the effect would be the same.
470 We have chosen to define <code>local_prefix</code> separately,
471 because, as we will see in <a href="#libpath">the next section</a>,
472 we will want to define a <code>local_libpath</code> specification,
473 relative to the same file system prefix.
474 Of course, we could also specify <code>local_libpath</code>
475 <em>entirely</em>  within a single ‘specs’ string,
476 (including a duplicate of the prefix from <code>local_includes</code>);
477 the advantage of defining <code>local_prefix</code> separately,
478 and then relating both <code>local_includes</code>
479 and <code>local_libpath</code> to it,
480 is that it offers us an option,
481 at some unspecified future time,
482 to relocate the <em>entire</em>  local file system hierarchy,
483 (from <code>C:/MinGW/local</code> to <code>C:/Local/MinGW</code>,
484 for example), by redefining, or by <em>overriding</em>, 
485 just the one <code>local_prefix</code> ‘specs’ string.
487 </div><!-- isystem -->
489 <div class="overlapped" id="libpath">
490 <h3>Defining a Custom Library Search Path</h3>
491 <p>Further building on the underlying principles of,
492 and complementing the customized include file search path configuration,
493 as described in <a href="#isystem">the preceding section</a>,
494 GCC also needs to be instructed where to search for the associated
495 third‑party library files.
497 <p>By analogy with the customized local include file search path,
498 which we have configured as <code>c:/mingw/local/include</code>,
499 the logically corresponding local library search path would be
500 <code>c:/mingw/local/lib</code>.
501 While the “<a target="_blank" href="index.html?page=libpath.html#customize"
502 >Library Search Path HOWTO</a>” indicates how
503 this search path may be specified,
504 without recourse to ‘specs’ file customization,
505 for the additional convenience which it will ultimately afford,
506 we are more interested, here, in how to specify this custom search path
507 <em>using</em>  ‘specs’ file customization.
509 <p>Like the local include file search path configuration,
510 this ‘specs’ file customization will be most convenient
511 if its deployment does <em>not</em>  require the use of
512 a <code>-specs=<file></code> command line option.
513 So, assuming that you have already followed the preceding procedures,
514 to <a href="#prep">provision a primary ‘specs’ file</a>,
515 (explicitly named “specs”),
516 and to <a href="#isystem">configure the custom include file search path</a>,
517 open this ‘specs’ file once again,
518 in your favourite text‑file editor;
519 locate the definition for <code>local_includes</code>,
520 which you added previously, and below it,
523 <pre class="box-out">
525 -L %(local_prefix)lib
528 <p>once again, taking care to maintain correct structure,
529 both within this new definition, and those adjacent to it.
532 to complete the configuration,
533 and instruct GCC to <em>use</em>  this new custom search path,
534 go to the end of the file, and add:
536 <pre class="box-out">
541 <p>before saving the ‘specs’ file,
542 and quitting the editor.
544 </div><!-- libpath -->
546 <div class="overlapped" id="msvcrt">
547 <h3>Supporting Microsoft’s Non‑Free ‘C’ Runtime Libraries</h3>
548 <p>By default, the MinGW compiler/linker combination will link applications,
549 such that they depend on Microsoft’s <code>MSVCRT.DLL</code>
550 ‘C’ runtime library;
551 while not strictly “free”,
552 in the sense defined by the GNU General Public Licence,
553 this <em>does</em>,  qualify for the GPL linking exemption
554 for integration with non‑free software components,
555 on the basis that it is distributed, by Microsoft,
556 as a standard Windows operating system component.
558 <p>In addition to <code>MSVCRT.DLL</code>,
559 Microsoft also distribute various alternative ‘C’ runtime libraries,
560 as components of their “Visual Studio”, or “Visual C”
561 software development suites.
562 Bearing names such as <span class="nowrap">
563 <code>MSVCR70.DLL</code> <code>..</code> <code>MSVCR120.DLL</code>,
564 </span>these are <em>not</em>  distributed as standard components
565 of the Windows operating system;
566 thus, they do <em>not</em>  qualify for the GPL linking exemption,
567 and MinGW.OSDN is <em>not</em>  licensed to distribute them.
569 <p>Notwithstanding the foregoing licensing restrictions on their use,
570 the non‑free Microsoft ‘C’ runtime libraries
571 <em>do</em>  introduce a small number of functions,
572 which Microsoft have never incorporated into
573 <code>MSVCRT.DLL</code>;
574 consequently, there may be occasions when users will
575 wish to link their MinGW applications with one of these
576 non‑free ‘C’ runtime libraries.
577 While MinGW.OSDN is not licensed to distribute these
578 ‘C’ runtime libraries,
580 we <em>can</em>,  and <em>do</em>, 
581 distribute <em>import libraries</em>  which map their entry points,
582 (at least for <span class="nowrap"><code>MSVCR70.DLL</code> <code
583 >..</code> <code>MSVCR100.DLL</code>),</span>
584 so that any users who are prepared to handle the licensing implications,
585 and the provisioning of the DLLs for themselves,
586 may link their MinGW applications with these libraries,
589 <p>Some users may assume, naïvely,
590 that linking with, for example <code>MSVCR80.DLL</code>, would be
591 as simple as adding the <code>-lmsvcr80</code> library specification
592 to the <code>gcc</code> command line;
593 unfortunately, it is <em>not</em>  as simple as this!
594 The problem with this naïve approach is twofold:–
595 </p><ol style="list-style: lower-roman">
596 <li>When linking with <code>-lmsvcr80</code>,
597 it is <em>also necessary</em>  to link with <code>-lmoldname80</code>;
598 while it may appear that this would be as simple as
599 also adding <code>-lmoldname80</code>,
600 this is also the wrong way to accomplish the objective!
602 <li>The fundamental reason why it is <em>wrong</em>  to simply add
603 <code class="nowrap">-lmoldname80 -lmsvcr80</code>
604 to the <code>gcc</code> command line
605 is that the default GCC ‘specs’ strings <em>already add</em> 
606 <code class="nowrap">-lmoldname -lmsvcrt</code>
607 to the <em>effective</em>  <code>gcc</code> command.
608 Thus, by <em>also</em>  adding
609 <code class="nowrap">-lmoldname80 -lmsvcr80</code>,
610 we are asking the linker to search <em>both</em> 
611 <code>libmoldname80.a</code> <em>and</em>  <code>libmoldname.a</code>,
612 to resolve <code>OLDNAME</code> symbols,
613 <em>and ultimately both</em>  <code>libmsvcr80.a</code>
614 <em>and</em>  <code>libmsvcrt.a</code>,
615 to resolve ‘C’ runtime DLL references.
616 This introduces potential for the linked application to depend on
617 <em>both</em>  <code>MSVCR80.DLL</code>
618 <em>and</em>  <code>MSVCRT.DLL</code>,
619 which is <em>definitively unsupported</em> ;
620 at best, you <em>may</em>  be lucky, and get away with it;
621 more likely, your application will be unstable,
622 and may crash and burn at run time,
623 with unpredictable side effects.
625 <p>Thus, we should <em>not</em> simply specify <code>-lmsvcr80</code>,
626 (either free‑standing, or accompanied by <code>-lmoldname80</code>),
627 to the <code>gcc</code> command line, when our intent is to link with
628 <code>MSVCR80.DLL</code>, in preference to <code>MSVCRT.DLL</code>.
629 (Nor, following similar reasoning, should we attempt to substitute
630 any of Microsoft’s other non‑free ‘C’
631 runtime DLLs, in this manner).
632 Rather, we <em>must</em>  modify the GCC ‘specs’ strings,
633 such that <em>all</em>  existing references to <code>-lmsvcrt</code>,
634 and to <code>-lmoldname</code>, are <em>replaced</em>  by
635 <code>-lmsvcr80</code> and <code>-lmoldname80</code>, respectively,
636 (or whatever alternative references are appropriate,
637 for the intended substitute ‘C’ runtime DLL).
638 Below, we will explore some methods for achieving this objective.
640 <h4>Identifying the Required ‘specs’ String Modifications</h4>
641 <p>As we’ve seen above,
642 when we wish to link with any of Microsoft’s non‑free
643 ‘C’ runtime libraries,
644 we <em>really</em>  ought to modify the GCC ‘specs’ strings,
645 to avoid any conflicting application dependencies on <em>both</em> 
646 <code>MSVCRT.DLL</code>,
647 and the chosen non‑free DLL.
648 The default libraries specification,
649 for linking with <code>MSVCRT.DLL</code>,
650 is <code class="nowrap">-lmoldname -lmsvcrt</code>;
651 for linking with any of the non‑free ‘C’ runtime DLLs,
652 this couplet <em>must</em>  be replaced,
653 in any ‘specs’ string which includes it,
654 by an alternative couplet selected from the following table:–
656 <table class="borderless">
658 <th>To Use</th><th>Preprocessor Identification</th><th>Link With Libraries</th>
662 <td><code>MSVCRT.DLL</code></td>
663 <td /><td><code class="nowrap">-lmoldname -lmsvcrt</code></td>
665 no preprocessor identification or ‘specs’ changes required
668 <tr><td><code>MSVCR70.DLL</code></td>
669 <td><code>-D__MSVCRT_VERSION__=0x0700</code></td>
670 <td><code class="nowrap">-lmoldname70 -lmsvcr70</code></td>
672 <tr><td><code>MSVCR71.DLL</code></td>
673 <td><code>-D__MSVCRT_VERSION__=0x0710</code></td>
674 <td><code class="nowrap">-lmoldname71 -lmsvcr71</code></td>
676 <tr><td><code>MSVCR80.DLL</code></td>
677 <td><code>-D__MSVCRT_VERSION__=0x0800</code></td>
678 <td><code class="nowrap">-lmoldname80 -lmsvcr80</code></td>
680 <tr><td><code>MSVCR90.DLL</code></td>
681 <td><code>-D__MSVCRT_VERSION__=0x0900</code></td>
682 <td><code class="nowrap">-lmoldname90 -lmsvcr90</code></td>
684 <tr><td><code>MSVCR100.DLL</code></td>
685 <td><code>-D__MSVCRT_VERSION__=0x1000</code></td>
686 <td><code class="nowrap">-lmoldname100 -lmsvcr100</code></td>
688 <tr style="display: none"><td><code>MSVCR110.DLL</code></td>
689 <td><code>-D__MSVCRT_VERSION__=0x1100</code></td>
690 <td><code class="nowrap">-lmoldname110 -lmsvcr110</code></td>
692 <tr style="display: none"><td><code>MSVCR120.DLL</code></td>
693 <td><code>-D__MSVCRT_VERSION__=0x1200</code></td>
694 <td><code class="nowrap">-lmoldname120 -lmsvcr120</code></td>
698 in addition to the alternative libraries couplet,
699 the foregoing table also specifies a “<em>preprocessor
700 identification</em> ”,
701 for all but the default <code>MSVCRT.DLL</code> case.
702 This should be <em>added</em> to the
703 <code>cpp</code> ‘specs’ string,
705 to ensure that definitions associated with the selected non‑free
706 runtime library are made visible,
707 when the compiler parses the appropriate ‘C’ header files.
709 <h4>A Simplistic Approach to Implementing the ‘specs’ Strings Modifications</h4>
711 although rather naïve,
712 method of implementing the necessary ‘specs’ string modifications,
713 might be to create a separate copy of the ‘specs’ file,
714 specific to each non‑free runtime DLL
715 which we wish to support.
717 to support linking with <code>MSVCR80.DLL</code>,
718 we might create a copy of an existing external ‘specs’ file,
719 (in the appropriate ‘specs’ file directory),
720 naming the copy as <code>msvcr80</code>,
721 (or, if we don’t have an external ‘specs’ file,
722 use the <code>gcc -dumpspecs</code> command to create <code>msvcr80</code>,
723 as described under the heading “<a href="#prep">Preparing the GCC
724 ‘specs’ for Customization</a>”, above).
726 <p>Once we have created a copy of the ‘specs’ file,
727 (which we’ve called <code>msvcr80</code>, in our example case),
728 we may edit it, to implement the required customizations.
729 First, we should locate the <code>cpp</code> string definition ...
730 it should look something like this:
732 <pre class="box-out">
734 %{posix:-D_POSIX_SOURCE} %{mthreads:-D_MT} %{pthread:-D_REENTRANT} %{!no-pthread: }
737 <p>or, if we’ve already added an additional include file search path:
739 <pre class="box-out">
741 %{posix:-D_POSIX_SOURCE} %{mthreads:-D_MT} %{pthread:-D_REENTRANT} %{!no-pthread: }
745 <p>to which we must add
746 the appropriate <em>preprocessor identification</em>,  string,
747 selected from the table above,
748 (which, in the <code>MSVCR80.DLL</code> case,
749 is <code>-D__MSVCRT_VERSION__=0x0800</code>).
750 Thus, the modified definition becomes:
752 <pre class="box-out">
754 %{posix:-D_POSIX_SOURCE} %{mthreads:-D_MT} %{pthread:-D_REENTRANT} %{!no-pthread: }
755 -D__MSVCRT_VERSION__=0x0800
759 <pre class="box-out">
761 %{posix:-D_POSIX_SOURCE} %{mthreads:-D_MT} %{pthread:-D_REENTRANT} %{!no-pthread: }
762 %(local_includes) -D__MSVCRT_VERSION__=0x0800
765 <p style="margin-top: 0.8em">Second,
766 we must locate all occurrences of <code>-lmsvcrt</code>,
767 and of <code>-lmoldname</code>,
768 and replace each with the corresponding equivalents from the table above,
769 (<span class="nowrap">i.e. <code>-lmsvcr80</code></span>
770 and <code>-lmoldname80</code>, respectively,
771 in the case of the <code>MSVCR80.DLL</code> example).
772 Typically, each will appear just once,
773 with both in the <code>libgcc</code> string definition,
774 which initially, should look something like:
776 <pre class="box-out">
778 %{mthreads:-lmingwthrd} -lmingw32 -lmingwex -lmingw32 -lmingwex
779 %{static|static-libgcc:-lgcc -lgcc_eh} %{!static:%{!static-libgcc:%{!shared:%{!shared-libgcc:-lgcc -lgcc_eh}
780 %{shared-libgcc:-lgcc_s -lgcc}} %{shared:-lgcc_s -lgcc}}} -lmoldname -lmsvcrt
783 <p>and, after modification, should look like this:
785 <pre class="box-out">
787 %{mthreads:-lmingwthrd} -lmingw32 -lmingwex -lmingw32 -lmingwex
788 %{static|static-libgcc:-lgcc -lgcc_eh} %{!static:%{!static-libgcc:%{!shared:%{!shared-libgcc:-lgcc -lgcc_eh}
789 %{shared-libgcc:-lgcc_s -lgcc}} %{shared:-lgcc_s -lgcc}}} -lmoldname80 -lmsvcr80
792 <p style="margin-top: 0.8em">Finally,
793 while these two modifications are sufficient for <code>gcc</code>,
794 they will <em>not</em>  pass the correct <code>__MSVCRT_VERSION__</code>
795 definition for compilation with <code>g++</code>;
796 to correct this deficiency,
797 we must also modify the <code>cc1plus</code> ‘specs’ string,
798 (which, unless we've already added anything to it,
799 appears to be initially empty, by default), so we define it as:
800 <pre class="box-out">
802 -D__MSVCRT_VERSION__=0x0800
805 <p>or, if we had already added, e.g. an additional include files search path:
807 <pre class="box-out">
809 %(local_includes) -D__MSVCRT_VERSION__=0x0800
812 <p style="margin-top: 0.8em">
813 With all three of the above modifications in place,
814 in the <code>msvcr80</code> ‘specs’ file,
815 we may invoke <code>gcc</code>, (or <code>g++</code>), like this:
817 <pre class="vt box-out">
818 $ <kbd>gcc -specs=msvcr80 foo.c -o foo.exe</kbd>
820 <p>to compile, and link <code>foo.exe</code> with <code>MSVCR80.DLL</code>,
821 <em>without</em>  incurring any dependency on <code>MSVCRT.DLL</code>.
822 However, the naïve simplicity of this ‘specs’ strings
823 modification technique <em>does</em>  make it sub‑optimal,
824 and may create potential problems;
825 in the following section,
826 we will discuss possible improvements to this simple modification technique.
828 <h4>Improving on the Simplistic ‘specs’ Strings Modification Technique</h4>
829 <p>The simplistic ‘specs’ strings modification technique,
830 as described in the preceding section,
831 for supporting the use of Microsoft’s non‑free
832 ‘C’ runtime DLLs,
833 exhibits the following potential disadvantages:–
835 <li>Each custom ‘specs’ file,
836 which relates to any one specific non‑free ‘C’ runtime DLL,
837 reproduces a redundant copy of <em>every</em>  ‘specs’ string
838 which appears in the set of built‑in ‘specs’,
839 (or in an external <code>specs</code> file copy thereof),
840 but modifies <em>only two</em>  of them.
841 An implication of this is that <em>every one</em>  of those
842 <em>unmodified</em>  ‘specs’ strings <em>must</em> 
843 be parsed <em>twice</em> ;
844 this is <em>grossly inefficient</em>.
846 <li>The duplication of all of those <em>unmodified</em> 
847 ‘specs’ strings is a possible impediment to <em>other</em> 
848 (<em>unrelated</em> ) customizations;
849 <em>each</em>  and <em>every</em>  subsequent modification
850 to <em>any</em>  of the ‘specs’ strings,
851 which are orthogonal to the changes needed to support
852 the non‑free runtime DLLs,
853 <em>must</em>  be <em>faithfully reproduced</em>, 
854 not only in an external <code>specs</code> file,
855 but <em>also</em>  in <em>every</em> 
856 non‑free runtime specific auxiliary ‘specs’ file;
857 not only is this an undesirable maintenance burden ...
858 it is potentially error‑prone!
861 these disadvantages may be mitigated by elimination of
862 <em>all</em>  unmodified ‘specs’ strings from
863 each of the auxiliary ‘specs’ files,
864 leaving the <em>entire</em>  content of,
865 for example, the <code>msvcr80</code> ‘specs’ file,
866 (incorporating the additional include file search path modification),
867 as <em>exactly</em> :
869 <pre class="box-out">
871 %{posix:-D_POSIX_SOURCE} %{mthreads:-D_MT} %{pthread:-D_REENTRANT} %{!no-pthread: }
872 %(local_includes) -D__MSVCRT_VERSION__=0x0800
875 %(local_includes) -D__MSVCRT_VERSION__=0x0800
878 %{mthreads:-lmingwthrd} -lmingw32 -lmingwex -lmingw32 -lmingwex
879 %{static|static-libgcc:-lgcc -lgcc_eh} %{!static:%{!static-libgcc:%{!shared:%{!shared-libgcc:-lgcc -lgcc_eh}
880 %{shared-libgcc:-lgcc_s -lgcc}} %{shared:-lgcc_s -lgcc}}} -lmoldname80 -lmsvcr80
883 <p>(and similarly, for other auxiliary ‘specs’ files
884 relating to other non‑free ‘C’ runtime DLLs).
887 but it still leaves a significant degree of redundancy,
888 in the three definitions which <em>do</em>  need to be modified.
889 A simple way to remove some of this redundancy,
890 <em>without</em>  requiring any pyhsical change to
891 the originating definition,
892 as it appears in the built‑in ‘specs‘,
893 is by reformulating the amended <code>cpp</code>
894 and <code>cc1plus</code> definitions as:
896 <pre class="box-out">
898 + -D__MSVCRT_VERSION__=0x0800
901 + -D__MSVCRT_VERSION__=0x0800
904 <p>but, unfortunately,
905 we cannot adopt a similar adjustment to remove the redundancy
906 in the modified <code>libgcc</code> definition.
908 <p>If we do wish to eliminate the redundancies <em>entirely</em>, 
909 then we <em>must</em>  modify the <code>libgcc</code> ‘specs’
910 string at its point of origin;
911 this implies that we <em>must</em>  use an <em>external</em> 
912 <code>specs</code> file,
913 in which we can make the necessary modification.
914 Thus, if we don't already have an external ‘specs’ file,
915 we should follow the procedure described above,
916 under the heading “<a href="#prep">Preparing the GCC
917 ‘specs’ for Customization</a>”,
920 <p>Once we have set up an external ‘specs’ file,
921 such that <code>gcc</code>, and <code>g++</code>, will read it
922 instead of using their built‑in ‘specs’,
924 splitting the original <code>libgcc</code> definition
925 into a modified <code>libgcc</code>,
926 and a supplementary <code>libmsvcrt</code> definition, thus:
930 %{mthreads:-lmingwthrd} -lmingw32 -lmingwex -lmingw32 -lmingwex
931 %{static|static-libgcc:-lgcc -lgcc_eh} %{!static:%{!static-libgcc:%{!shared:%{!shared-libgcc:-lgcc -lgcc_eh}
932 %{shared-libgcc:-lgcc_s -lgcc}} %{shared:-lgcc_s -lgcc}}} %(libmsvcrt)
938 <p>(noting the use of <em>parentheses</em>  in the
939 <code>%(libmsvcrt)</code> substitution field,
940 whereas <em>braces</em> are used elsewhere,
941 throughout the <code>libgcc</code> definition).
944 with that single modification in place,
945 within the external <code>specs</code> file,
946 the supplementary <code>msvcr80</code> ‘specs’ file
947 may be condensed, to nothing more than:
949 <pre class="box-out">
951 + -D__MSVCRT_VERSION__=0x0800
954 + -D__MSVCRT_VERSION__=0x0800
957 -lmoldname80 -lmsvcr80
960 <p>and Microsoft’s other non‑free ‘C’ runtime DLLs
961 may be similarly supported,
962 with suitably named copies of this supplementary ‘specs’ file,
963 each with appropriate changes to the <code>__MSVCRT_VERSION__</code> assignment,
964 and the import libraries named in the <code>libmsvcrt</code> definition.
966 <div style="display: none">
967 <!-- Seemed like a good idea, but doesn't work for C++ -->
968 <h4>Consolidating Support for Non‑Free Runtime Libraries</h4>
969 <p>In the preceding section,
970 we began with a naïve collection of supplementary ‘specs’ files,
971 each of which was a mostly redundant copy of GCC’s built‑in
972 ‘specs’, and each incorporating a minimal set of modifications,
973 specific to supporting <em>one</em>  particular version of
974 Microsoft’s non‑free ‘C’ runtime DLLs.
975 We observed that the redundancy in this naïvely constructed collection
976 of ‘specs’ files created an undesirable maintenance burden,
977 and we further developed the concept to eliminate the redundancy.
979 we significantly reduced the size of each ‘specs’ file,
980 while introducing a trivial dependency on a minimally‑modified
981 (non‑redundant) external <code>specs</code> file.
984 we will develop this concept further,
985 with a view to consolidating the entire collection of separate
986 ‘specs’ files into the fewest practicable number,
987 while retaining the capability to arbitrarily select any one
988 of Microsoft’s non‑free ‘C’ runtime DLLs,
989 with which to link any application.
992 we would like to consolidate all of the necessary ‘specs’
993 string modifications into a single,
994 <em>implicitly</em>  loaded external <code>specs</code> file,
995 and to use a command line option to specify the particular
996 version of the ‘C’ runtime library,
997 with which the application should be linked.
999 of all the predefined option keywords which <code>gcc</code> will accept,
1000 only the <code>-lfoo</code> class,
1001 (which, strictly speaking, aren’t really options anyway),
1002 seem suitable for alternative runtime library selection,
1003 and these do not appear to participate in conditional
1004 ‘specs’ string processing.
1006 we will require custom option keywords,
1007 which <code>gcc</code> will accept <em>only</em>  if invoked
1008 with an <em>explicitly</em>  loaded external ‘specs’ file,
1009 so we will be unable to realize our ideal objective;
1010 the best we are likely to achieve will be <em>one</em>  small,
1011 <em>explicitly</em>  loaded external ‘specs’ file,
1012 to enable the use of custom options,
1013 (and to handle at least some of their interpretation),
1014 in conjunction with an implicitly loaded external <code>specs</code> file,
1015 modified as in the preceding section, to avoid redundancy.
1018 the latter best practicable objective is entirely achievable.
1019 If we keep the external <code>specs</code> file <em>exactly</em> 
1020 in the state as we developed it in the preceding section, but,
1021 instead of the collection of supplementary ‘specs’ files,
1022 (one for each non‑free runtime DLL),
1023 we create just <em>one</em>, 
1024 (let’s call it <code>opt</code>),
1027 <pre class="box-out">
1029 + %{msvcr*:-D__MSVCRT_VERSION__=0x0%*0}%<msvcr*
1032 + %{msvcr*:-D__MSVCRT_VERSION__=0x0%*0}%<msvcr*
1035 -lmoldname%{msvcr*:%* -lmsvcr%*}%{!msvcr*: -lmsvcrt}
1038 <p>then we may link our applications with <em>any</em> 
1039 of Microsoft’s non‑free ‘C’ runtime DLLs,
1040 simply by invoking <code>gcc</code>, (or <code>g++</code>), like this:
1042 <pre class="vt box-out">
1043 $ <kbd>gcc -specs=opt -msvcr<N> foo.c -o foo.exe</kbd>
1045 <p>(where “<code><N></code> represents the numeric identifier,
1046 within the runtime DLL name);
1049 <pre class="vt box-out">
1050 $ <kbd>gcc -specs=opt -msvcr80 foo.c -o foo.exe</kbd>
1052 <p>would result in <code>foo.exe</code> being
1053 linked with <code>MSVCR80.DLL</code>, while:
1055 <pre class="vt box-out">
1056 $ <kbd>gcc -specs=opt -msvcr120 foo.c -o foo.exe</kbd>
1058 <p>would result in linking with <code>MSVCR120.DLL</code>,
1059 and the system will automatically adapt,
1060 to accommodate linking with any other numerically identified runtime DLL,
1061 which may be available, (or may become available in the future),
1062 <em>without</em>  requiring a separate ‘specs’ file
1063 for each distinct DLL.
1065 </div><!-- undisplayed -->
1066 </div><!-- msvcrt -->
1068 <!-- $RCSfile$: end of file -->
OSDN Git Service
