HTML source code, style-sheets, scripts, and images for deployment on mingw.osdn.io
| Revision | 1d89880b681082c16eec5639678e38300f24a722 (tree) |
|---|---|
| Zeit | 2022-01-01 04:45:39 |
| Autor |  Keith Marshall <keith@user...> |
| Commiter | Keith Marshall |
Publish MinGW linker's library search path HOWTO.
* libpath.html: New file; adapted from original Drupal content, this
describes the GCC/ld library search mechanism, and offers advice on
installation of third party libraries, to take best advantage of this
search mechanism.
libpath.html (diff)| @@ -0,0 +1,729 @@ | ||
| 1 | +<!DOCTYPE HTML><!-- | |
| 2 | + * | |
| 3 | + * libpath.html | |
| 4 | + * | |
| 5 | + * HOWTO establish the search path for libraries, which are to be made | |
| 6 | + * available for use with the MinGW GCC compiler suite. | |
| 7 | + * | |
| 8 | + * | |
| 9 | + * $Id$ | |
| 10 | + * | |
| 11 | + * Written by Keith Marshall <keith@users.osdn.me> | |
| 12 | + * Copyright (C) 2021, MinGW.OSDN Project | |
| 13 | + * | |
| 14 | + * | |
| 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: | |
| 18 | + * | |
| 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. | |
| 22 | + * | |
| 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. | |
| 28 | + * | |
| 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 | |
| 40 | + * DAMAGE. | |
| 41 | + * | |
| 42 | + * | |
| 43 | + * Note: this page assumes browser support for the following numeric | |
| 44 | + * HTML entity codes: | |
| 45 | + * | |
| 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 | |
| 52 | + * | |
| 53 | +--> | |
| 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. | |
| 59 | + */ | |
| 60 | + set_page("title", "MinGW Compiler Suite User Guide"); | |
| 61 | + set_page("subtitle", | |
| 62 | + "HOWTO Specify the MinGW Linker’s Search Path for Object Code Libraries" | |
| 63 | + ); | |
| 64 | +</script><!-- masthead --> | |
| 65 | +<div class="masthead" style="display: none"> | |
| 66 | +<p class="byline">Posted: 23-March-2009, by Keith; Last Update: 22-Nov-2021</p> | |
| 67 | +<p>FIXME: Page under construction; some value here now, but not yet complete. | |
| 68 | +</p> | |
| 69 | +<p>I will add to this as time permits; please bear with me. | |
| 70 | +My intent is to offer advice, complementing the information relating to | |
| 71 | +<a href="index.html?page=isystem.html">include file search paths</a>, | |
| 72 | +on circumventing the limitations of MinGW’s GCC when installing, | |
| 73 | +and subsequently linking with, user added function libraries. | |
| 74 | +</p> | |
| 75 | +<hr /> | |
| 76 | +</div><!-- masthead --> | |
| 77 | +<div class="overlapped" id="intro"> | |
| 78 | +<h3>Introduction</h3> | |
| 79 | +<p>This Mini‑HOWTO further develops the theme introduced by the | |
| 80 | +“<a href="index.html?page=isystem.html" | |
| 81 | +>Include File Search Path HOWTO</a>”, | |
| 82 | +progressing to a complementary consideration of where the MinGW implementation | |
| 83 | +of GCC, (or more accurately, of the linker, <code>ld</code>, which is actually | |
| 84 | +a component of the GNU <code>binutils</code> package), searches for object | |
| 85 | +code libraries. | |
| 86 | +In particular, it address the question: “<em>How do I ensure that the | |
| 87 | +MinGW linker will find my object libraries?</em> ” | |
| 88 | +</p> | |
| 89 | +<p>In the case of <em>header files</em>, | |
| 90 | +we observed that the <a rel="noopener noreferrer" target="_blank" | |
| 91 | + href="https://gcc.gnu.org/onlinedocs/index.html#dir">GCC Manual</a> | |
| 92 | +makes a <a rel="noopener noreferrer" target="_blank" | |
| 93 | + href="https://gcc.gnu.org/onlinedocs/gcc-3.4.5/cpp/Search-Path.html#Search-Path" | |
| 94 | +>definitive statement</a>, regarding the search path for header files, | |
| 95 | +(<em>although it became significantly less definitive, | |
| 96 | +<a rel="noopener noreferrer" target="_blank" | |
| 97 | + href="https://gcc.gnu.org/onlinedocs/cpp/Search-Path.html#Search-Path" | |
| 98 | +>in the documentation for GCC‑7 and later</a></em> ), | |
| 99 | +yet we also noted that this statement is not applicable to the MinGW | |
| 100 | +implementation of GCC. In the case of <em>libraries</em>, | |
| 101 | +the <a "noopener noreferrer" target="_blank" | |
| 102 | + href="https://gcc.gnu.org/onlinedocs/index.html#dir">GCC Manual</a> | |
| 103 | +makes a much <a "noopener noreferrer" target="_blank" | |
| 104 | + href="https://gcc.gnu.org/onlinedocs/gcc-3.4.5/gcc/Link-Options.html#Link-Options" | |
| 105 | +>less definitive statement</a>, | |
| 106 | +which is paradoxically more applicable to the MinGW implementation, | |
| 107 | +regarding the default search path: | |
| 108 | +</p> | |
| 109 | +<div class="box-out"> | |
| 110 | +<code>-llibrary</code><br /> | |
| 111 | +<code>-l</code> <code>library</code> | |
| 112 | +<p>Search the library named <code>library</code> when linking. | |
| 113 | +(The second alternative | |
| 114 | +with the <code>library</code> as a separate argument is only for POSIX compliance and | |
| 115 | +is not recommended.) | |
| 116 | +</p> | |
| 117 | +<p>It makes a difference where in the command you write this option; the | |
| 118 | +linker searches and processes libraries and object files in the order they | |
| 119 | +are specified. | |
| 120 | +Thus, | |
| 121 | +‘<code>foo.o -lz bar.o</code>’ | |
| 122 | +searches library ‘<code>z</code>’ after file <code>foo.o</code> | |
| 123 | +but before <code>bar.o</code>. | |
| 124 | +If <code>bar.o</code> refers to functions in ‘<code>z</code>’, | |
| 125 | +those functions may | |
| 126 | +not be loaded. | |
| 127 | +</p> | |
| 128 | +<p>The linker searches a standard list of directories for the library, which is | |
| 129 | +actually a file named <code>liblibrary.a</code>. The linker then uses this file as if it | |
| 130 | +had been specified precisely by name. | |
| 131 | +</p> | |
| 132 | +<p>The directories searched include several standard system directories plus | |
| 133 | +any that you specify with <code>-L</code>. | |
| 134 | +</p> | |
| 135 | +</div> | |
| 136 | +<p><em>Note:</em> | |
| 137 | +the second paragraph of the above extract is not strictly relevant to | |
| 138 | +the subject of this Mini‑HOWTO; I’ve chosen not to elide it, | |
| 139 | +because it answers another FAQ: “<em>Why do I get undefined reference | |
| 140 | +errors, when the symbols in question are definitely present in the libraries | |
| 141 | +I’ve specified with <code>-l</code> options?</em> ” — | |
| 142 | +the usual answer is that the <code>-l</code> options have been placed | |
| 143 | +too early in the command line argument sequence. | |
| 144 | +The remainder, and in particular the final paragraph, are pertinent, | |
| 145 | +vaguely indicating that libraries will be searched for in | |
| 146 | +<em>several standard system directories</em>; | |
| 147 | +these will be identified more explicitly in this Mini‑HOWTO. | |
| 148 | +</p> | |
| 149 | +</div><!-- intro --> | |
| 150 | + | |
| 151 | +<div class="overlapped" id="altref"> | |
| 152 | +<h3>Consulting an Alternative Reference Source<br /> | |
| 153 | +The GNU Binary File Utilities Manual’s Perspective</h3> | |
| 154 | +<p>We have observed that the | |
| 155 | +<a rel="noopener noreferrer" target="_blank" | |
| 156 | + href="https://gcc.gnu.org/onlinedocs/index.html#dir">GCC Manual</a> | |
| 157 | +makes no definitive statement, regarding the default directories | |
| 158 | +to be searched for libraries. | |
| 159 | +Since the actual library search is performed by the linker, | |
| 160 | +<code>ld</code>, which is a component of the <em>GNU Binary File Utilities</em>, | |
| 161 | +(more commonly known as <em>binutils</em>), we might hope to find a | |
| 162 | +more definitive statement in the | |
| 163 | +<a rel="noopener noreferrer" target="_blank" | |
| 164 | + href="https://sourceware.org/binutils/docs/ld/index.html" | |
| 165 | +>applicable section</a> of the | |
| 166 | +<a rel="noopener noreferrer" target="_blank" | |
| 167 | + href="https://sourceware.org/binutils/docs/index.html" | |
| 168 | +>Binutils Manual</a>. | |
| 169 | +Unfortunately, while obviously a useful reference for | |
| 170 | +the <em>GNU Binary File Utilities</em> in general, | |
| 171 | +<a rel="noopener noreferrer" target="_blank" | |
| 172 | + href="https://sourceware.org/binutils/docs/ld/index.html" | |
| 173 | +>this manual</a> appears to be equally noncommittal; | |
| 174 | +the only references to be found, to library search paths, | |
| 175 | +are in the | |
| 176 | +<a rel="noopener noreferrer" target="_blank" | |
| 177 | + href="https://sourceware.org/binutils/docs/ld/Options.html#index-search-directory_002c-from-cmd-line-55" | |
| 178 | +>Command Line Options</a> section: | |
| 179 | +</p> | |
| 180 | +<div class="box-out"> | |
| 181 | +<code>-Lsearchdir | |
| 182 | +<br />--library-path=searchdir | |
| 183 | +</code> | |
| 184 | +<p>Add path <code>searchdir</code> to the list of paths | |
| 185 | +that <code>ld</code> will search for archive | |
| 186 | +libraries and <code>ld</code> control scripts. | |
| 187 | +You may use this option any number of times. | |
| 188 | +The directories are searched in the order in which they are specified | |
| 189 | +on the command line. | |
| 190 | +Directories specified on the command line are searched | |
| 191 | +before the default directories. | |
| 192 | +All <code>-L</code> options apply to all <code>-l</code> options, | |
| 193 | +regardless of the order in which the options appear. | |
| 194 | +</p> | |
| 195 | +<p>If <code>searchdir</code> begins with <code>=</code>, | |
| 196 | +then the <code>=</code> will be replaced by the <code>sysroot</code> prefix, | |
| 197 | +a path specified when the linker is configured. | |
| 198 | +</p> | |
| 199 | +<p>The default set of paths searched (without being specified with | |
| 200 | +‘<code>-L</code>’) depends | |
| 201 | +on which emulation mode <code>ld</code> is using, | |
| 202 | +and in some cases also on how it was configured. | |
| 203 | +See <a rel="noopener noreferrer" target="_blank" | |
| 204 | + href="https://sourceware.org/binutils/docs/ld/Environment.html#Environment" | |
| 205 | +>Environment</a>. | |
| 206 | +</p> | |
| 207 | +<p>The paths can also be specified in a link script with | |
| 208 | +the <code>SEARCH_DIR</code> command. | |
| 209 | +Directories specified this way are searched at the point in which the linker | |
| 210 | +script appears in the command line. | |
| 211 | +</p></div> | |
| 212 | +<p>and in the <a rel="noopener noreferrer" target="_blank" | |
| 213 | + href="https://sourceware.org/binutils/docs/ld/File-Commands.html#index-search-path-in-linker-script-334" | |
| 214 | +>Linker Scripts / File Commands</a> section: | |
| 215 | +</p> | |
| 216 | +<div class="box-out"> | |
| 217 | +<code>SEARCH_DIR(path)</code> | |
| 218 | +<p>The <code>SEARCH_DIR</code> command adds path to the list of paths | |
| 219 | +where <code>ld</code> looks for archive libraries. | |
| 220 | +Using <code>SEARCH_DIR(path)</code> is exactly like using | |
| 221 | +‘<code>-L</code> <code>path</code>’ | |
| 222 | +on the command line (see <a rel="noopener noreferrer" target="_blank" | |
| 223 | + href="https://sourceware.org/binutils/docs/ld/Options.html#index-search-directory_002c-from-cmd-line-55" | |
| 224 | +>Command Line Options)</a>. | |
| 225 | +If both are used, then the linker will search both paths. | |
| 226 | +Paths specified using the command line option | |
| 227 | +are searched first. | |
| 228 | +</p></div> | |
| 229 | +<p>while the <a rel="noopener noreferrer" target="_blank" | |
| 230 | + href="https://sourceware.org/binutils/docs/ld/Environment.html#Environment" | |
| 231 | +>Environment</a> reference, appearing within the <a rel="noopener noreferrer" target="_blank" | |
| 232 | + href="https://sourceware.org/binutils/docs/ld/Options.html#index-search-directory_002c-from-cmd-line-55" | |
| 233 | +>Command Line Options</a> reference, apparently has nothing to say, | |
| 234 | +which is related to this subject. | |
| 235 | +</p> | |
| 236 | +</div><!-- altref --> | |
| 237 | + | |
| 238 | +<div class="overlapped" id="default-path"> | |
| 239 | +<h3>Determining MinGW’s Default Library Search Path</h3> | |
| 240 | +<p>So, if the applicable manuals don’t give us any definitive | |
| 241 | +indication of which directories will be searched for libraries, how | |
| 242 | +<em>can</em> we identify where the MinGW tools will search? | |
| 243 | +</p> | |
| 244 | +<p>The <a rel="noopener noreferrer" target="_blank" | |
| 245 | + href="https://sourceware.org/binutils/docs/ld/index.html" | |
| 246 | +><em>ld manual</em></a> tells us that the <a rel="noopener noreferrer" target="_blank" | |
| 247 | + href="https://sourceware.org/binutils/docs/ld/Options.html#index-search-directory_002c-from-cmd-line-55" | |
| 248 | +>directories searched</a> will be those specified on the command line, | |
| 249 | +using <code>-L</code> options, | |
| 250 | +followed by those specified in the effective <em>linker script</em>, | |
| 251 | +using the <code>SEARCH_DIR</code> script command. | |
| 252 | +We may identify the search directories specified within | |
| 253 | +the default <em>linker script</em>, | |
| 254 | +by running the command: | |
| 255 | +</p> | |
| 256 | +<pre class="vt box-out"> | |
| 257 | +$ <kbd>ld --verbose | grep SEARCH_DIR | tr -s ' ;' \\012</kbd> | |
| 258 | +</pre> | |
| 259 | +<p>which, with a standard MinGW installation, | |
| 260 | +might produce output similar to: | |
| 261 | +</p> | |
| 262 | +<pre class="vt box-out"> | |
| 263 | +$ <kbd>ld --verbose | grep SEARCH_DIR | tr -s ' ;' \\012</kbd> | |
| 264 | +SEARCH_DIR("/mingw/mingw32/lib") | |
| 265 | +SEARCH_DIR("/mingw/lib") | |
| 266 | +SEARCH_DIR("/usr/local/lib") | |
| 267 | +SEARCH_DIR("/lib") | |
| 268 | +SEARCH_DIR("/usr/lib") | |
| 269 | +</pre> | |
| 270 | +<p>The first thing we might notice about these | |
| 271 | +is that they are all specified in the style of POSIX paths; | |
| 272 | +however, since the MinGW tools are all native MS‑Windows applications, | |
| 273 | +the linker will be unable to resolve these paths, | |
| 274 | +in any manner other than as absolute with respect to | |
| 275 | +the <em>current drive</em>, | |
| 276 | +at the time when the linker is invoked. | |
| 277 | +Thus, even if these directories do exist, | |
| 278 | +(which is unlikely in a standard MS‑Windows installation), | |
| 279 | +they may represent <em>different</em> locations, | |
| 280 | +depending on whichever drive the user has made <em>current</em>, | |
| 281 | +at the time when the linker is invoked. | |
| 282 | +(For users of MSYS, | |
| 283 | +they will <em><strong>definitely not</strong></em> be resolved | |
| 284 | +relative to the root of the MSYS virtual file system, | |
| 285 | +even if that is what the user might like). | |
| 286 | +</p> | |
| 287 | +<p>Now, we have seen that none of its pre‑configured search paths | |
| 288 | +seem to be particularly useful as default search paths, | |
| 289 | +for use with the MinGW linker. | |
| 290 | +That may be considered to be a configuration error, | |
| 291 | +(which a future <em>binutils</em> package release may address); | |
| 292 | +nevertheless, it does not appear to present a significant obstacle | |
| 293 | +to operation in practice, | |
| 294 | +since suitable search paths may <em>always</em> be specified | |
| 295 | +using <code>-L</code> options. Of course, | |
| 296 | +any such options which <em><strong>we</strong></em> are required | |
| 297 | +to specify on the command line, | |
| 298 | +can hardly be described as <em><strong>default</strong></em> search paths; | |
| 299 | +however, | |
| 300 | +if we adopt the recommended practice of <em><strong>always</strong></em> | |
| 301 | +invoking <code>ld</code> via an appropriate GCC front‑end, | |
| 302 | +then the GCC driver has an opportunity to supply such options, | |
| 303 | +in a manner which may be so described, and in fact, | |
| 304 | +this is precisely what happens. | |
| 305 | +</p> | |
| 306 | +<p>Thus, we have established that the linker’s | |
| 307 | +default search paths have little value, in a standard MinGW installation, | |
| 308 | +but that GCC itself furnishes the effective defaults, | |
| 309 | +by supplying appropriate <code>-L</code> options. | |
| 310 | +To discover what these default <code>-L</code> options are, | |
| 311 | +we might use the command: | |
| 312 | +</p> | |
| 313 | +<pre class="vt box-out"> | |
| 314 | +$ <kbd>gcc -print-search-dirs</kbd> | |
| 315 | +</pre> | |
| 316 | +<p>If we run this, | |
| 317 | +we will see a sprawling mess of nigh incomprehensible output; | |
| 318 | +some judicious filtering, to extract only the library search paths, | |
| 319 | +normalize them to canonical forms, and present them one per line, | |
| 320 | +can reduce it to a form which is more readily interpreted, | |
| 321 | +(as in this example, with an old MinGW GCC‑3.4.5 system, | |
| 322 | +running under MSYS): | |
| 323 | +</p> | |
| 324 | +<pre class="vt box-out"> | |
| 325 | +$ <kbd>gcc -print-search-dirs | \</kbd> | |
| 326 | +> <kbd>sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,;s,;,; ,g' | \</kbd> | |
| 327 | +> <kbd>tr \; \\012</kbd> | |
| 328 | +libraries: | |
| 329 | +c:/mingw/lib/gcc/mingw32/3.4.5/ | |
| 330 | +c:/mingw/lib/gcc/ | |
| 331 | +/mingw/lib/gcc/mingw32/3.4.5/ | |
| 332 | +/usr/lib/gcc/mingw32/3.4.5/ | |
| 333 | +c:/mingw/mingw32/lib/mingw32/3.4.5/ | |
| 334 | +c:/mingw/mingw32/lib/ | |
| 335 | +/mingw/mingw32/lib/mingw32/3.4.5/ | |
| 336 | +/mingw/mingw32/lib/ | |
| 337 | +/mingw/lib/mingw32/3.4.5/ | |
| 338 | +/mingw/lib/ | |
| 339 | +c:/mingw/lib/mingw32/3.4.5/ | |
| 340 | +c:/mingw/lib/ | |
| 341 | +/mingw/lib/mingw32/3.4.5/ | |
| 342 | +/mingw/lib/ | |
| 343 | +/lib/mingw32/3.4.5/ | |
| 344 | +/lib/ | |
| 345 | +/usr/lib/mingw32/3.4.5/ | |
| 346 | +/usr/lib/ | |
| 347 | +</pre> | |
| 348 | +<p>Once again, | |
| 349 | +we may observe that this list includes a number of POSIX style paths, | |
| 350 | +which most likely are not relevant for a MinGW installation. | |
| 351 | +If we further filter, to remove the POSIX paths, | |
| 352 | +and keep only the MS‑Windows style paths, | |
| 353 | +this list reduces to: | |
| 354 | +</p> | |
| 355 | +<pre class="vt box-out"> | |
| 356 | +$ <kbd>gcc -print-search-dirs | \</kbd> | |
| 357 | +> <kbd>sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,;s,;,; ,g' | \</kbd> | |
| 358 | +> <kbd>tr \; \\012 | \</kbd> | |
| 359 | +> <kbd>grep -v '^ */'</kbd> | |
| 360 | +libraries: | |
| 361 | +c:/mingw/lib/gcc/mingw32/3.4.5/ | |
| 362 | +c:/mingw/lib/gcc/ | |
| 363 | +c:/mingw/mingw32/lib/mingw32/3.4.5/ | |
| 364 | +c:/mingw/mingw32/lib/ | |
| 365 | +c:/mingw/lib/mingw32/3.4.5/ | |
| 366 | +c:/mingw/lib/ | |
| 367 | +</pre> | |
| 368 | +<p>From this, | |
| 369 | +we might deduce that GCC will pass each of these paths to the linker, | |
| 370 | +using an appropriate <code>-L</code> option; to verify that deduction, | |
| 371 | +we might use GCC’s <code>-###</code> option, | |
| 372 | +in a command such as: | |
| 373 | +</p> | |
| 374 | +<pre class="vt box-out"> | |
| 375 | +gcc -### -o foo foo.c | |
| 376 | +</pre> | |
| 377 | +<p>to reveal <em>exactly</em> what command GCC will pass to the linker; (again, the output is not formatted for easy reading, but some judicious filtering will extract just the <code>-L</code> options, and present them in a form which can be more easily read by humans): | |
| 378 | +</p> | |
| 379 | +<pre class="vt box-out"> | |
| 380 | +$ <kbd>touch foo.c</kbd> | |
| 381 | +$ <kbd>gcc -### -o foo foo.c 2>&1 | \</kbd> | |
| 382 | +> <kbd>tr -s \\040 \\012 | \</kbd> | |
| 383 | +> <kbd>sed '/^"-L/!d;s,,,;s,"$,/,;:1;s,/[^/.][^/]*/\.\./,/,;t 1' | \</kbd> | |
| 384 | +> <kbd>sed 's,^, ,;1h;1s,.*,libraries:,;1G'</kbd> | |
| 385 | +libraries: | |
| 386 | +c:/mingw/lib/gcc/mingw32/3.4.5/ | |
| 387 | +c:/mingw/lib/gcc/ | |
| 388 | +c:/mingw/mingw32/lib/ | |
| 389 | +c:/mingw/lib/ | |
| 390 | +</pre> | |
| 391 | +<p>Oops! What happened there? In these examples, | |
| 392 | +GCC’s <code>‑print‑search‑dirs</code> | |
| 393 | +option tells us that there are <em>six</em> MS‑Windows paths | |
| 394 | +it will search, but <em>only four</em> of those are passed on | |
| 395 | +to the linker, as <code>-L</code> options. | |
| 396 | +Why are all six not passed on? | |
| 397 | +</p> | |
| 398 | +<p>Well, | |
| 399 | +recall that we arbitrarily chose to ignore | |
| 400 | +the POSIX style paths in GCC’s built‑in list, | |
| 401 | +when we formulated the list of MS‑Windows paths we expected | |
| 402 | +to be searched, but why would GCC itself make such an arbitrary choice? | |
| 403 | +In reality, it doesn’t. | |
| 404 | +Let’s re‑examine that full list of built‑in paths, | |
| 405 | +but this time we will filter it on an analytical basis, | |
| 406 | +selecting only those paths which represent | |
| 407 | +actual <em>physical</em> directories | |
| 408 | +on our host machine: | |
| 409 | +</p> | |
| 410 | +<pre class="vt box-out"> | |
| 411 | +$ <kbd>( echo libraries:</kbd> | |
| 412 | +> <kbd>drive=`pwd -W | sed 's,:.*,,'`</kbd> | |
| 413 | +> <kbd>for dir in `gcc -print-search-dirs \</kbd> | |
| 414 | +> <kbd>| sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,' \</kbd> | |
| 415 | +> <kbd>| tr \; '\012' \</kbd> | |
| 416 | +> <kbd>| sed "s,^/,$drive:/,"`</kbd> | |
| 417 | +> <kbd>do test -d $dir && echo " $dir"</kbd> | |
| 418 | +> <kbd>done</kbd> | |
| 419 | +> <kbd>)</kbd> | |
| 420 | +libraries: | |
| 421 | +c:/mingw/lib/gcc/mingw32/3.4.5/ | |
| 422 | +c:/mingw/lib/gcc/ | |
| 423 | +c:/mingw/mingw32/lib/ | |
| 424 | +c:/mingw/lib/ | |
| 425 | +</pre> | |
| 426 | +<p>which, we observe, | |
| 427 | +now exactly matches the list of <code>-L</code> options | |
| 428 | +we see passed to the linker, | |
| 429 | +when we invoke GCC with the <code>-###</code> option. | |
| 430 | +Thus, we may refine our previous deduction, | |
| 431 | +to conclude that GCC will examine its built‑in | |
| 432 | +list of pre‑configured library search directories, | |
| 433 | +passing on to the linker, in the form of <code>-L</code> options, | |
| 434 | +those which represent actual physical directories on the host machine; | |
| 435 | +therefore, this becomes the list of default library search | |
| 436 | +directories for MinGW. | |
| 437 | +</p> | |
| 438 | +</div><!-- default-path --> | |
| 439 | + | |
| 440 | +<div class="overlapped" id="install"> | |
| 441 | +<h3>Installation and Use of Supplementary Libraries with MinGW</h3> | |
| 442 | +<p>When a project uses only the standard core libraries, | |
| 443 | +either as provided by the MS‑Windows operating system itself, | |
| 444 | +or those provided as integral components of the MinGW distribution, | |
| 445 | +the user need take no action to ensure that those libraries | |
| 446 | +will be searched at link time; | |
| 447 | +the compiler driver will take care of it automatically. | |
| 448 | +Even in cases where the project relies on <em>optional</em> libraries | |
| 449 | +supplied as standard operating system components, | |
| 450 | +and for which MinGW provides <em>import libraries</em>, | |
| 451 | +the user need do no more than specify an appropriate | |
| 452 | +<code>-l<em>NAME</em></code> option to the compiler driver, | |
| 453 | +and the library will be linked, as required. | |
| 454 | +In either of these cases, | |
| 455 | +the necessary libraries are located within the default search path, | |
| 456 | +and no particular action is required of the user, | |
| 457 | +to specify where that might be. | |
| 458 | +</p> | |
| 459 | +<p>Conversely, | |
| 460 | +when a project supplements the standard libraries, | |
| 461 | +with one or more which it creates exclusively for its own use, | |
| 462 | +then those libraries will <em>not</em> be found | |
| 463 | +in the default search path, | |
| 464 | +so their location must be explicitly identified to the compiler driver, | |
| 465 | +to ensure that they can be found at link time. | |
| 466 | +In such cases, | |
| 467 | +in which the libraries are not installed for use by other projects, | |
| 468 | +the most common, and indeed the expected practice, | |
| 469 | +is for the project maintainer to specify the library locations explicitly, | |
| 470 | +by addition of appropriate <code>-L</code> options to the linking commands | |
| 471 | +within the project’s build system infrastructure. | |
| 472 | +When this is done correctly, | |
| 473 | +there is again no action required of the user, | |
| 474 | +to specify the location of such supplementary libraries. | |
| 475 | +</p> | |
| 476 | +<p>The situation becomes much more interesting, | |
| 477 | +when a project provides one or more supplementary libraries | |
| 478 | +for use by <em>other</em> projects. | |
| 479 | +In such cases, | |
| 480 | +there is an expectation that the libraries will be <em>installed</em> | |
| 481 | +in some central location, | |
| 482 | +whence they will become readily accessible | |
| 483 | +when <em>client</em> projects are linked, | |
| 484 | +<em>without</em> a need for any particular intervention by | |
| 485 | +the user building the client project, | |
| 486 | +to specify that location. | |
| 487 | +</p> | |
| 488 | +<p>On typical POSIX systems, | |
| 489 | +and in particular on those conforming to the GNU model, | |
| 490 | +it is common for the standard system libraries, | |
| 491 | +including those provided as standard components of the compiler suite, | |
| 492 | +to be installed in /<em>lib</em> or /<em>usr</em>/<em>lib</em>, | |
| 493 | +while supplementary libraries may be installed in | |
| 494 | +/<em>usr</em>/<em>local</em>/<em>lib</em>. | |
| 495 | +In fact, as we have already observed, | |
| 496 | +these three locations are already included, | |
| 497 | +by means of <code>SEARCH_DIR("...")</code> commands | |
| 498 | +in the default linker scripts, | |
| 499 | +as defaults to be searched by the MinGW linker; | |
| 500 | +unfortunately, they are specified exactly as such, | |
| 501 | +in the original POSIX format, | |
| 502 | +which cannot be readily interpreted in the file system context | |
| 503 | +in which the MinGW linker must operate! | |
| 504 | +This is a limitation of the MinGW linker, | |
| 505 | +which the user installing supplementary libraries must work around, | |
| 506 | +possibly by adopting one of the following strategies:– | |
| 507 | +</p> | |
| 508 | +<ol style="margin-left: -0.3em; list-style: lower-alpha"> | |
| 509 | +<li>Install in a <em>non‑default</em> location, | |
| 510 | +and require every user of the installed libraries to explicitly | |
| 511 | +add the requisite <code>-L</code> options to the linking commands, | |
| 512 | +for <em>every</em> subsequent project which requires any supplementary library. | |
| 513 | +This is inconvenient for subsequent use, | |
| 514 | +and is generally not recommended. | |
| 515 | +</li> | |
| 516 | +<li>Install in a location | |
| 517 | +which is already considered to be a default by the compiler driver. | |
| 518 | +This often recommended option is the simplest possible, | |
| 519 | +for <em>both</em> the user installing the libraries, | |
| 520 | +<em>and</em> for those using them. | |
| 521 | +If using MSYS as the command line environment | |
| 522 | +for building and installing the libraries, | |
| 523 | +and the libraries themselves are delivered as GNU standard source packages, | |
| 524 | +such installation may be readily accomplished by the command sequence: | |
| 525 | +<pre class="vt box-out"> | |
| 526 | +$ <kbd>../path/to/configure --prefix=`cd /mingw ; pwd -W` ... && make && make install</kbd> | |
| 527 | +</pre> | |
| 528 | +<p>(Note: | |
| 529 | +here we explicitly force the use of MS‑Windows <em>native</em> | |
| 530 | +path format for the <em>prefix</em>; this is normally necessary, | |
| 531 | +if the libraries being built hard code | |
| 532 | +the <em>prefix</em> within object files). | |
| 533 | +</p> | |
| 534 | +<p>It may be noted that, | |
| 535 | +in this example, we appear to have arbitrarily chosen the | |
| 536 | +top level <em>lib</em> sub‑directory, | |
| 537 | +within MinGW’s own installation directory, | |
| 538 | +as the preferred location for installation of supplementary libraries; | |
| 539 | +in reality, of the pre‑existing default search directories, | |
| 540 | +this is the only sane choice, | |
| 541 | +since the others are much more specifically associated with | |
| 542 | +the component libraries provided by the compiler suite itself, | |
| 543 | +and it is undesirable to pollute them with “foreign” libraries. | |
| 544 | +Indeed, many users also consider it undesirable to pollute the top level | |
| 545 | +MinGW library directory with such “foreign” libraries; | |
| 546 | +such users may prefer the following alternative installation strategy. | |
| 547 | +</p></li> | |
| 548 | +<li>Install in a <em>non‑default</em> location, | |
| 549 | +just as in the first option, but also customize the <em>linker scripts</em>, | |
| 550 | +or the <em>compiler driver specs</em>, | |
| 551 | +to <em>implicitly</em> add the requisite <code>-L</code> option, | |
| 552 | +such that this location becomes an additional default search path. | |
| 553 | +Available techniques for achieving such customization will be discussed, | |
| 554 | +in the following section. | |
| 555 | +</li> | |
| 556 | +</ol> | |
| 557 | +</div><!-- install --> | |
| 558 | + | |
| 559 | +<div class="overlapped" id="customize"> | |
| 560 | +<h3>Customizing MinGW’s Default Library Search Path</h3> | |
| 561 | +<p>So, you’ve decided you would prefer to segregate | |
| 562 | +your add‑on libraries from the core MinGW libraries? | |
| 563 | +The first issue to address, | |
| 564 | +is <em>where</em> you would like to install them. | |
| 565 | +</p> | |
| 566 | +<p>Here, you have two basic options: | |
| 567 | +<ol style="margin-left: -0.3em; list-style: lower-alpha"> | |
| 568 | +<li>Establish a set up, | |
| 569 | +analogous to the common /<em>usr</em>/<em>local</em> hierarchy | |
| 570 | +of typical Unix systems, with all additional libraries, | |
| 571 | +and their associated header files, collected into this one location. | |
| 572 | +</li> | |
| 573 | +<li>Provide a separate directory for each individual library package, | |
| 574 | +and customize the GCC search paths to consider <em>all</em> of them, | |
| 575 | +as appropriate, when looking for libraries and header files. | |
| 576 | +</li> | |
| 577 | +</ol> | |
| 578 | +</p> | |
| 579 | +<p>It should be fairly obvious that | |
| 580 | +the first of these will require less GCC customization than the second. | |
| 581 | +In fact, the principles are the same in both cases; | |
| 582 | +however, whereas the first requires the addition of only one include path, | |
| 583 | +(<code>-I</code> option), and one library path, (<code>-L</code> option), | |
| 584 | +the second will require one of each per library package installed, | |
| 585 | +which may be detrimental to GCC performance. | |
| 586 | +Thus, we will describe only the first option in detail; | |
| 587 | +users preferring the second may extend the principles described, | |
| 588 | +as necessary, to accommodate their preference. | |
| 589 | +</p> | |
| 590 | +<p>Having chosen to install all add‑on libraries in a common location, | |
| 591 | +the choice of that location is fairly arbitrary. | |
| 592 | +MSYS users may choose to simply use the conceptual /<em>usr</em>/<em>local</em> | |
| 593 | +of their existing MSYS installation, in which case, | |
| 594 | +they must ensure that that directory physically exists, | |
| 595 | +(it may not in a bare, standard MSYS installation), | |
| 596 | +and they must identify its true <em><strong>native</strong></em> Windows path, | |
| 597 | +for use in the GCC customization, as shown in the following example, | |
| 598 | +for a <em><strong>standard</strong></em> MSYS installation in its | |
| 599 | +<em><strong>default</strong></em> installation directory: | |
| 600 | +</p> | |
| 601 | +<pre class="vt box-out"> | |
| 602 | +$ <kbd>mkdir -p /usr/local</kbd> | |
| 603 | +$ <kbd>( cd /usr/local && pwd -W )</kbd> | |
| 604 | +c:/msys/1.0/local | |
| 605 | +</pre> | |
| 606 | +<p><em><strong>Caution:</strong> | |
| 607 | +Although this choice of directory may seem attractive, | |
| 608 | +particularly because it matches the default prefix assumed by | |
| 609 | +the majority of GNU packages, | |
| 610 | +it may <strong>not</strong> represent the <strong>best</strong> choice | |
| 611 | +for all MSYS users. | |
| 612 | +This is particularly true for those users | |
| 613 | +who may wish to develop MSYS applications. | |
| 614 | +The special MSYS build of <strong>GCC</strong> | |
| 615 | +used to compile such applications reserves </em>/usr/local<em> | |
| 616 | +for its own purposes; | |
| 617 | +in this case, | |
| 618 | +it <strong>must not</strong> be polluted by headers and libraries | |
| 619 | +intended for use with the MinGW build of <strong>GCC</strong>.</em> | |
| 620 | +</p> | |
| 621 | +<p>Alternatively, | |
| 622 | +masochists who prefer to persist with <code>cmd.exe</code>, | |
| 623 | +or MSYS users who prefer to keep MinGW related add‑ons more | |
| 624 | +closely associated with their MinGW installations, | |
| 625 | +might choose to create an installation directory | |
| 626 | +locally within their MinGW tree: | |
| 627 | +</p> | |
| 628 | +<pre class="vt box-out"> | |
| 629 | +C:\> <kbd>mkdir c:\mingw\local</kbd> | |
| 630 | +</pre> | |
| 631 | +<p>or adjacent to it: | |
| 632 | +</p> | |
| 633 | +<pre class="vt box-out"> | |
| 634 | +C:\> <kbd>mkdir c:\mingw-local</kbd> | |
| 635 | +</pre> | |
| 636 | +<p><em><strong>Caution:</strong> | |
| 637 | +Whichever of these options you choose, | |
| 638 | +<strong>please do not</strong> choose to create <strong>any directory | |
| 639 | +with white space</strong> appearing <strong>anywhere</strong> in | |
| 640 | +its absolute path name. | |
| 641 | +If you adopt this asinine practice, | |
| 642 | +do not be surprised if it turns around and bites. | |
| 643 | +When it does, please <strong>do not</strong> come here to complain; | |
| 644 | +you have been warned!</em> | |
| 645 | +</p> | |
| 646 | +<p>Once the tree into which supplementary libraries, | |
| 647 | +and their headers, are to be installed has been selected, | |
| 648 | +and created, the next step is to install the requisite | |
| 649 | +library packages into this tree. | |
| 650 | +In the case of standard GNU library packages, | |
| 651 | +and assuming you have chosen <em>C:\MinGW\local</em> as your | |
| 652 | +supplementary installation path, | |
| 653 | +(MSYS users may refer to it simply as <em>/mingw/local</em>), | |
| 654 | +this may be accomplished from the MSYS shell, by running: | |
| 655 | +</p> | |
| 656 | +<pre class="vt box-out"> | |
| 657 | +$ <kbd>../path/to/configure --prefix=/mingw/local ... && make && make install</kbd> | |
| 658 | +</pre> | |
| 659 | +<p>(or, if you suspect that the library may hard code | |
| 660 | +its installation path within itself): | |
| 661 | +</p> | |
| 662 | +<pre class="vt box-out"> | |
| 663 | +$ <kbd>../path/to/configure --prefix=`cd /mingw/local ; pwd -W` ... && make && make install</kbd> | |
| 664 | +</pre> | |
| 665 | +<p><em><strong>Note:</strong> | |
| 666 | +If the library package is <strong>not</strong> a standard GNU package, | |
| 667 | +you will need to adapt its installation procedure to achieve the effect | |
| 668 | +of the above. | |
| 669 | +Details of how this may be achieved are package specific, | |
| 670 | +and are beyond the scope of this HOWTO.</em> | |
| 671 | +</p> | |
| 672 | +<p>Finally, | |
| 673 | +having installed supplementary libraries and their headers | |
| 674 | +into the supplementary directory tree, | |
| 675 | +they must be made available to the GCC compilers. | |
| 676 | +Of course, | |
| 677 | +this may <em><strong>always</strong></em> be achieved by adding | |
| 678 | +appropriate <code>-I</code> <code>...</code>, | |
| 679 | +and <code>-L</code> <code>...</code> specifications to the commands, | |
| 680 | +when the compilers are invoked, | |
| 681 | +but that hardly seems consistent with the level of convenience | |
| 682 | +we are striving to achieve! | |
| 683 | +Obviously, the desired objective can best be met if it can be arranged | |
| 684 | +for the compilers to search in the supplementary tree by default; | |
| 685 | +this may be achieved by adding the path name for the supplementary | |
| 686 | +include file tree to the compilers’ default search paths, | |
| 687 | +as described in the | |
| 688 | +“<a href="index.html?page=isystem.html">Include Path HOWTO</a>”, | |
| 689 | +accompanied by <em>either</em> of: | |
| 690 | +</p> | |
| 691 | +<ol style="margin-left: -0.3em; list-style: lower-alpha"> | |
| 692 | +<li>Adding the path name for the supplementary library directory to | |
| 693 | +the <em>semicolon</em> separated list of library search directories specified | |
| 694 | +by the <code>LIBRARY_PATH</code> environment variable, | |
| 695 | +(which <em><strong>must</strong></em> be <em><strong>exported</strong></em>, | |
| 696 | +if it is assigned from within the MSYS shell): | |
| 697 | +<pre class="vt box-out"> | |
| 698 | +$ <kbd>export LIBRARY_PATH</kbd> | |
| 699 | +$ <kbd>LIBRARY_PATH="C:/mingw/local/lib;$LIBRARY_PATH"</kbd> | |
| 700 | +</pre> | |
| 701 | +<p><em><strong>Note:</strong> | |
| 702 | +The GCC manual states that this technique may be used | |
| 703 | +<strong>only</strong> | |
| 704 | +when GCC is configured as a <strong>native</strong> compiler; | |
| 705 | +thus, this method of specifying the supplementary library path | |
| 706 | +may not be used when your MinGW GCC is configured as a cross‑compiler. | |
| 707 | +Indeed, it would be illogical to use this technique with a cross‑compiler, | |
| 708 | +as it would lead to confusion between those libraries which are specific | |
| 709 | +to the native GCC compiler on the build platform, | |
| 710 | +and those which are specific to the cross‑compiler.</em> | |
| 711 | +</p> | |
| 712 | +</li> | |
| 713 | +<li>Follow the method, | |
| 714 | +as described in the | |
| 715 | +“<a href="index.html?page=gccspecs.html">GCC Customization HOWTO</a>”, | |
| 716 | +to add a supplementary path to the default library search path. | |
| 717 | +<p><em><strong>Note:</strong> | |
| 718 | +This method is applicable <strong>equally</strong> to MinGW GCC | |
| 719 | +configured as a native compiler <strong>or</strong> configured as | |
| 720 | +a cross‑compiler; | |
| 721 | +the additional search path applies <strong>only</strong> to | |
| 722 | +the specific instance of the compiler | |
| 723 | +with which the modified specs file is associated</em>. | |
| 724 | +</p></li> | |
| 725 | +</ol> | |
| 726 | +<!--p><em>TODO: additional text for this section to be added</em>.</p--> | |
| 727 | +</div><!-- customize --> | |
| 728 | + | |
| 729 | +<!-- $RCSfile$: end of file --> |
Fork