• R/O
  • HTTP
  • SSH
  • HTTPS

website: Commit

HTML source code, style-sheets, scripts, and images for deployment on mingw.osdn.io


Commit MetaInfo

Revision1d89880b681082c16eec5639678e38300f24a722 (tree)
Zeit2022-01-01 04:45:39
AutorKeith Marshall <keith@user...>
CommiterKeith Marshall

Log Message

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.

Ändern Zusammenfassung

Diff

--- /dev/null
+++ b/libpath.html
@@ -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+ * &#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 -->
Show on old repository browser