libpath.html

   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  *    &#8197;   fixed width 1/4 em space
  47  *    &#8209;   non-breaking hyphen
  48  *    &#8216;   typographic left (opening) single quote
  49  *    &#8217;   typographic apostrophe/right (closing) single quote
  50  *    &#8220;   typographic left (opening) double quote
  51  *    &#8221;   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&#8217;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&#8217;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&#8209;HOWTO further develops the theme introduced by the
  80 &#8220;<a href="index.html?page=isystem.html"
  81 >Include&#8197;File&#8197;Search&#8197;Path&#8197;HOWTO</a>&#8221;,
  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: &#8220;<em>How do I ensure that the
  87 MinGW linker will find my object libraries?</em>&thinsp;&#8221;
  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&#8209;7 and later</a></em>&thinsp;),
  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>&nbsp;<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 &#8216;<code>foo.o&nbsp;-lz&nbsp;bar.o</code>&#8217;
 122 searches library &#8216;<code>z</code>&#8217; after file <code>foo.o</code>
 123 but before <code>bar.o</code>.
 124 If <code>bar.o</code> refers to functions in &#8216;<code>z</code>&#8217;,
 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&#8209;HOWTO; I&#8217;ve chosen not to elide it,
 139 because it answers another FAQ: &#8220;<em>Why do I get undefined reference
 140 errors, when the symbols in question are definitely present in the libraries
 141 I&#8217;ve specified with <code>-l</code> options?</em>&thinsp;&#8221; &mdash;
 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&#8209;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&#8217;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 &#8216;<code>-L</code>&#8217;) 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 &#8216;<code>-L</code>&nbsp;<code>path</code>&#8217;
 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&#8217;s Default Library Search Path</h3>
 240 <p>So, if the applicable manuals don&#8217;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(&quot;/mingw/mingw32/lib&quot;)
 265 SEARCH_DIR(&quot;/mingw/lib&quot;)
 266 SEARCH_DIR(&quot;/usr/local/lib&quot;)
 267 SEARCH_DIR(&quot;/lib&quot;)
 268 SEARCH_DIR(&quot;/usr/lib&quot;)
 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&#8209;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&#8209;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&#8209;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&#8209;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&#8217;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&#8209;3.4.5 system,
 322 running under MSYS):
 323 </p>
 324 <pre class="vt box-out">
 325 $ <kbd>gcc -print-search-dirs | \</kbd>
 326 &gt; <kbd>sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,;s,;,;  ,g' | \</kbd>
 327 &gt; <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&#8209;Windows style paths,
 353 this list reduces to:
 354 </p>
 355 <pre class="vt box-out">
 356 $ <kbd>gcc -print-search-dirs | \</kbd>
 357 &gt; <kbd>sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,;s,;,;  ,g' | \</kbd>
 358 &gt; <kbd>tr \; \\012 | \</kbd>
 359 &gt; <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&#8217;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&gt;&amp;1 | \</kbd>
 382 &gt; <kbd>tr -s \\040 \\012 | \</kbd>
 383 &gt; <kbd>sed '/^&quot;-L/!d;s,,,;s,&quot;$,/,;:1;s,/[^/.][^/]*/\.\./,/,;t 1' | \</kbd>
 384 &gt; <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&#8217;s <code>&#8209;print&#8209;search&#8209;dirs</code>
 393 option tells us that there are <em>six</em> MS&#8209;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&#8217;s built&#8209;in list,
 401 when we formulated the list of MS&#8209;Windows paths we expected
 402 to be searched, but why would GCC itself make such an arbitrary choice?
 403 In reality, it doesn&#8217;t.
 404 Let&#8217;s re&#8209;examine that full list of built&#8209;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 &gt;   <kbd>drive=`pwd -W | sed 's,:.*,,'`</kbd>
 413 &gt;   <kbd>for dir in `gcc -print-search-dirs \</kbd>
 414 &gt;     <kbd>| sed '/^lib/b 1;d;:1;s,/[^/.][^/]*/\.\./,/,;t 1;s,:[^=]*=,:;,' \</kbd>
 415 &gt;     <kbd>| tr \; '\012' \</kbd>
 416 &gt;     <kbd>| sed &quot;s,^/,$drive:/,&quot;`</kbd>
 417 &gt;     <kbd>do test -d $dir &amp;&amp; echo &quot;  $dir&quot;</kbd>
 418 &gt;     <kbd>done</kbd>
 419 &gt; <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&#8209;in
 432 list of pre&#8209;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&#8209;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&#8217;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(&quot;...&quot;)</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:&ndash;
 507 </p>
 508 <ol style="margin-left: -0.3em; list-style: lower-alpha">
 509 <li>Install in a <em>non&#8209;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` ... &amp;&amp; make &amp;&amp; make install</kbd>
 527 </pre>
 528 <p>(Note:
 529 here we explicitly force the use of MS&#8209;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&#8209;directory,
 537 within MinGW&#8217;s own installation directory,
 538 as the preferred location for installation of supplementary libraries;
 539 in reality, of the pre&#8209;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 &#8220;foreign&#8221; libraries.
 544 Indeed, many users also consider it undesirable to pollute the top level
 545 MinGW library directory with such &#8220;foreign&#8221; libraries;
 546 such users may prefer the following alternative installation strategy.
 547 </p></li>
 548 <li>Install in a <em>non&#8209;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&#8217;s Default Library Search Path</h3>
 561 <p>So, you&#8217;ve decided you would prefer to segregate
 562 your add&#8209;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&#8209;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 &amp;&amp; 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&#8209;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:\&gt; <kbd>mkdir c:\mingw\local</kbd>
 630 </pre>
 631 <p>or adjacent to it:
 632 </p>
 633 <pre class="vt box-out">
 634 C:\&gt; <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 ... &amp;&amp; make &amp;&amp; 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` ... &amp;&amp; make &amp;&amp; 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>&nbsp;<code>...</code>,
 679 and <code>-L</code>&nbsp;<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&#8217; default search paths,
 687 as described in the
 688 &#8220;<a href="index.html?page=isystem.html">Include Path HOWTO</a>&#8221;,
 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&#8209;compiler.
 707 Indeed, it would be illogical to use this technique with a cross&#8209;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&#8209;compiler.</em>
 711 </p>
 712 </li>
 713 <li>Follow the method,
 714 as described in the
 715 &#8220;<a href="index.html?page=gccspecs.html">GCC Customization HOWTO</a>&#8221;,
 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&#8209;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 -->