5 * HOWTO establish the search path for system header files, which are
6 * to be included when compiling code using the MinGW GCC compilers.
11 * Written by Keith Marshall <keith@users.osdn.me>
12 * Copyright (C) 2008, 2021, MinGW.OSDN Project
15 * Redistribution and use in source and 'compiled' forms (SGML, HTML,
16 * PDF, PostScript, RTF, etc) with or without modification, are permitted
17 * provided that the following conditions are met:
19 * 1. Redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer as
21 * the first lines of this file, unmodified.
23 * 2. Redistributions in compiled form (transformed to other DTDs,
24 * converted to PDF, PostScript, RTF and other formats) must
25 * reproduce the above copyright notice, this list of conditions
26 * and the following disclaimer in the documentation and/or other
27 * materials provided with the distribution.
29 * THIS DOCUMENTATION IS PROVIDED BY THE MINGW.OSDN PROJECT "AS IS"
30 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
31 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
32 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MINGW.OSDN PROJECT, OR
33 * ITS CONTRIBUTORS, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39 * OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
43 * Note: this page assumes browser support for the following numeric
46 * ‑ non-breaking hyphen
47 * ‘ typographic left (opening) single quote
48 * ’ typographic apostrophe/right (closing) single quote
49 * “ typographic left (opening) double quote
50 * ” typographic right (closing) double quote
53 <script class="masthead">
54 /* Script fragment, to assign titles specific to this page; this is
55 * encapsulated within the "masthead", where such titles are displayed,
56 * to ensure that whatever page content may follow will be correctly
57 * positioned, relative to the masthead content.
59 set_page("title", "MinGW Compiler Suite User Guide");
61 "HOWTO Specify the Include File Search Path for use with MinGW Compilers"
63 </script><!-- masthead -->
64 <div class="masthead" style="display: none">
65 <p class="byline">Posted: 21-Nov-2008, by Keith; Last Update: 22-Nov-2021</p>
66 </div><!-- masthead -->
67 <div class="overlapped" id="introduction">
69 <p>This Mini‑HOWTO answers the question:
70 <em>“Why can’t the MinGW compilers find
71 my project’s header files?”</em>
73 <p>Prior to the publication of the <em>GCC‑7</em> documentation,
74 (when the wording changed, to provide only a brief outline of
75 <a href="#default-search">the identification method described below</a>),
76 the <a rel="noopener noreferrer" target="_blank"
77 href="https://gcc.gnu.org/onlinedocs/gcc-3.4.5/cpp/index.html#Top">CPP Section</a>
78 of the <a rel="noopener noreferrer" target="_blank"
79 href="https://gcc.gnu.org/onlinedocs/index.html#dir">GCC Manual</a>
80 indicated that header files may be located in
81 <a rel="noopener noreferrer" target="_blank"
82 href="https://gcc.gnu.org/onlinedocs/gcc-3.4.5/cpp/Search-Path.html#Search-Path"
83 >the following directories</a>:–
86 <p>On a normal Unix system, if you do not instruct it otherwise,
87 [GCC] will look for headers requested with
88 <code>#include</code> <code><file></code> in:
91 libdir/gcc/target/version/include
95 <p>For <code>C++</code> programs,
96 it will also look in <code>/usr/include/g++-v3</code>, first.
99 <a rel="noopener noreferrer" target="_blank"
100 href="https://osdn.net/projects/mingw/releases/p15691"
101 >MinGW ports of GCC</a>
102 target Microsoft’s Windows system,
103 which is <em><strong>not</strong></em>
104 a <em>“normal UNIX system”</em>.
105 Nevertheless, many users,
106 particularly those coming from a UNIX or GNU/Linux background,
107 and especially when they use MSYS to emulate a UNIX file system model
108 on their MS‑Windows hosts,
109 are surprised to find that MinGW,
110 using its default configuration,
111 does <em><strong>not</strong></em> automatically
112 search for header files in these directories.
114 </div><!-- introduction -->
115 <div class="overlapped" id="default-search">
116 <h3>Identifying MinGW’s Default Include Path</h3>
118 if MinGW compilers don’t search in these <em>“normal”</em> directories,
119 where <em><strong>do</strong></em> they search?
121 <p>Before answering this,
122 it may be useful to understand <em>why</em>
123 the MinGW compilers do not search in these directories.
124 Firstly, on a native MS‑Windows host,
125 these directories do not typically exist;
126 the nature of the file system,
127 with multiple distinct roots
128 distributed over multiple distinctly named devices,
129 means that such path names would be ambiguous.
130 Secondly, since MinGW itself is <em>not</em> a suite of MSYS applications,
131 even if such directories are created in the MSYS environment,
132 being <em>native MS‑Windows</em> applications,
133 the MinGW compilers would have no means to locate them.
136 to avoid imposing draconian restrictions on how users install MinGW,
137 the maintainers have chosen to adopt a restricted search paradigm,
138 which is determined on the basis of where MinGW is itself installed.
139 The actual search path,
140 for any specific installation of MinGW may be determined,
141 by running the compiler itself,
142 with the ‘<code>-v</code>’ option;
143 typically, for a MinGW‑GCC installation in <code>C:\MinGW</code>,
144 we might see something similar to the following,
145 from (the now dated, but nonetheless still typical)
146 MinGW‑GCC‑3.4.5:–
148 <pre class="vt box-out">
149 $ <kbd>touch foo.c bar.cpp</kbd>
150 $ <kbd>gcc -v -c foo.c</kbd>
152 #include "..." search starts here:
153 #include <...> search starts here:
154 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/../../../../include
155 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/include
159 $ <kbd>g++ -v -c bar.cpp</kbd>
161 #include "..." search starts here:
162 #include <...> search starts here:
163 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/../../../../include/c++/3.4.5
164 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/../../../../include/c++/3.4.5/mingw32
165 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/../../../../include/c++/3.4.5/backward
166 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/../../../../include
167 c:/mingw/bin/../lib/gcc/mingw32/3.4.5/include
171 <p>This raw‑format output, as displayed by the compilers,
172 may be difficult for human readers to interpret.
173 Thus, it may be helpful to reduce it to canonical path forms:–
175 <pre class="vt box-out">
176 $ <kbd>gcc -v -c foo.c 2>&1 | sed ':1;s,/[^/.][^/]*/\.\./,/,;t 1'</kbd>
178 #include "..." search starts here:
179 #include <...> search starts here:
181 c:/mingw/lib/gcc/mingw32/3.4.5/include
185 $ <kbd>g++ -v -c bar.cpp 2>&1 | sed ':1;s,/[^/.][^/]*/\.\./,/,;t 1'</kbd>
187 #include "..." search starts here:
188 #include <...> search starts here:
189 c:/mingw/include/c++/3.4.5
190 c:/mingw/include/c++/3.4.5/mingw32
191 c:/mingw/include/c++/3.4.5/backward
193 c:/mingw/lib/gcc/mingw32/3.4.5/include
197 </div><!-- default-search -->
198 <div class="overlapped" id="other-defaults">
199 <h3>Other Directories Searched by Default</h3>
200 <p>The minimal list of directories,
201 identified as described above,
202 specifies the <em><strong>only</strong></em> locations
203 which will be searched <em><strong>by default</strong></em>,
204 for system header files,
205 or for headers associated with user installed libraries;
206 however, there is <em><strong>one</strong></em> exception.
207 Astute readers may have noticed that
208 the include file search path is itemised in a pair of sequential lists,
209 with the second being concatenated to the first; however, the first,
211 <code>#include</code> <code>"..."</code> <code>search</code>
212 list appears to be empty.
213 In reality, this apparent emptiness may be misleading;
214 unless the user specifies the ‘<code>-I-</code>’ option
215 when invoking GCC, this list contains <em>exactly</em> one directory:
216 the directory in which the source file containing the
217 <code>#include</code> <code>"file"</code> directive resides.
219 <p>Notice that this one additional directory
220 is <em><strong>not</strong></em> searched for headers specified
221 with the <code>#include</code> <code><file></code> form of
222 the <code>#include</code> directive;
223 it applies only for those headers specified using
224 the <code>#include</code> <code>"file"</code> form of the directive.
225 Also note that the location of this additional directory is not fixed;
226 it is dependent on the location of the source file being compiled,
227 and, while unique for each individual source file,
228 it may vary even within the compilation scope for any project,
229 <em>and even within the scope of a single translation unit</em>,
230 if multiple source files are distributed among different directories
231 in the project’s source hierarchy.
233 <p>To clarify this point,
234 let us consider a trivial example.
235 Suppose that we have a small project,
236 which provides all of it’s sources in a single directory;
237 among them we might have:–
239 <pre class="box-out">
248 <p>Further suppose that the file, <code>foo.c</code>,
249 includes the project‑local header, <code>foo.h</code>:–
251 <pre class="box-out">
255 #include "foo.h"
258 <p>and that <code>foo.h</code>, in turn,
259 includes <code>bar.h</code>:–
261 <pre class="box-out">
265 #include "bar.h"
268 <p>With this arrangement,
269 we may create a build directory which is a sibling of <code>src</code>,
270 and with that as current directory,
271 we may compile <code>foo.c</code>:–
273 <pre class="vt box-out">
274 $ <kbd>mkdir ~/build</kbd>
275 $ <kbd>cd ~/build</kbd>
276 $ <kbd>gcc -c ../src/foo.c</kbd>
279 <p>and we might have every expectation that it will compile correctly;
280 it certainly should have no problem finding the pair of header files,
281 <code>foo.h</code> and <code>bar.h</code>.
283 <p>Now, suppose that the project grows
284 to such a size that we decide to separate our headers
285 into a subdirectory of <code>src</code>:–
287 <pre class="box-out">
298 <p>After making this rearrangement,
299 if we again try to compile <code>foo.c</code>,
300 we will likely see errors resulting from the failure
301 to locate the header file <code>foo.h</code>:–
303 <pre class="vt box-out">
304 $ <kbd>gcc -c ../src/foo.c</kbd>
305 ../src/foo.c:3:17: foo.h: No such file or directory
309 <p>To correct this, we must also modify <code>foo.c</code>,
310 to reflect the relocation of the header files:–
312 <pre class="box-out">
316 #include "hdr/foo.h"
319 <p>and this should be sufficient to again let us compile
320 <code>foo.c</code> successfully:–
322 <pre class="vt box-out">
323 $ <kbd>gcc -c ../src/foo.c</kbd>
327 that we did <em><strong>not</strong></em> make any corresponding change
328 in <code>bar.h</code>; that would have been wrong!
329 The rule is that, in any <code>#include</code> directive of the form:–
331 <pre class="box-out">#include "path/file"</pre>
332 <p><code>path</code> must be a <em><strong>relative</strong></em> path,
333 and it must be relative to the directory in which the file containing
334 the pertinent <code>#include</code> directive is itself located.
336 since <code>foo.h</code> and <code>bar.h</code> are still
337 in the same directory,
338 searches for files included by either will commence in that same directory.
339 If we had changed <code>foo.h</code>,
340 in a manner similar to the change we made in <code>foo.c</code>,
341 then <code>foo.h</code> would have attempted
342 to <code>#include</code> the file <code>~/src/hdr/hdr/bar.h</code>,
343 instead of the intended <code>~/src/hdr/bar.h</code>.
345 </div><!-- other-defaults -->
346 <div class="overlapped" id="extra-includes">
347 <h3>Including Headers from Directories which are Not Searched by Default</h3>
348 <p>While the default header search paths may suffice
349 for many simple projects,
350 as project complexity grows,
351 it will often become more convenient to collect header files into
352 a central directory which is <em><strong>not</strong></em> in
353 the default search path;
354 this is particularly true of projects which provide,
355 and possibly install,
356 one or more function libraries,
357 either exclusively for their own use,
358 or maybe even for general use by other projects.
360 GCC must be <em><strong>explicitly</strong></em> notified,
361 by specifying appropriate command line options,
362 to identify the additional directories in which to search.
364 <p>The relevant sections of
365 <a rel="noopener noreferrer" target="_blank"
366 href="https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html#Preprocessor-Options"
368 and its associated C preprocessor manual,
369 <a rel="noopener noreferrer" target="_blank"
370 href="https://gcc.gnu.org/onlinedocs/cpp/Invocation.html#Invocation"
371 >document several options</a>,
372 which may be used to specify directories to search for header files;
374 the most widely used is the
375 <code>-I</code> <code><em>dir</em></code> option.
376 As an example of its use, let us reconsider the previous example,
377 with the project source files organised within the hierarchy:–
379 <pre class="box-out">
391 we will <em><strong>not</strong></em> adapt <code>foo.c</code>
392 to locate <code>foo.h</code> using the default include file search path:–
394 <pre class="box-out">
398 #include "foo.h"
401 <p>As we saw previously,
402 if we try to compile this unmodified <code>foo.c</code>,
403 without explicitly specifying any header search path,
404 the compilation will fail:–
406 <pre class="vt box-out">
407 $ <kbd>gcc -c ../src/foo.c</kbd>
408 ../src/foo.c:3:17: foo.h: No such file or directory
413 we corrected this failure by modifying <code>foo.c</code>,
414 to bring <code>foo.h</code> into the
415 default <code>#include</code> <code>"..."</code> search path.
416 This time, we will correct it, not by modifying <code>foo.c</code>,
417 but by <em><strong>explicitly</strong></em> adding our project’s
418 local <code>hdr</code> directory to the search path,
419 when we invoke GCC to compile <code>foo.c</code>:–
421 <pre class="vt box-out">
422 $ <kbd>gcc -I ../src/hdr -c ../src/foo.c</kbd>
425 <p>which, we may observe, again results in successful compilation.
427 </div><!-- extra-includes -->
428 <div class="overlapped" id="third-party">
429 <h3>Using Headers Provided with Locally Installed External Libraries</h3>
430 <p>Many projects have dependencies on external libraries,
431 which are <em>not</em> provided by a standard MinGW installation.
432 Users who wish to build the applications provided by such projects
433 must first install the appropriate prerequisite libraries.
434 Such libraries are referred to as
435 <em>“locally installed libraries”</em>,
436 and they must be installed such that MinGW’s GCC can readily
437 locate both the libraries themselves,
438 <em>and</em> any header files installed as prerequisites
439 for specifying the interface to the library functions.
441 <p>The installation of
442 such external libraries may be viewed as a challenge,
445 and particularly in the case of library packages
446 originally developed for Unix‑like platforms,
447 such libraries would be installed into
448 the <code>/usr/local/...</code> directory hierarchy.
449 However, as we have seen above,
451 does not consider any such hierarchy in its default search paths,
452 either for header files, or for libraries.
453 Thus, the challenge is to choose an installation strategy
454 which achieves a satisfactory compromise between:–
457 <li>Installing directly into MinGW’s own standard
458 <code><mingw-root>/include</code>
459 and <code><mingw-root>/lib</code> directory hierarchies;
460 this offers the advantage that the libraries,
461 and their associated header files,
462 are placed directly into MinGW‑GCC’s default search paths,
463 so there is no additional burden placed on the user,
464 to add additional <code>-I</code> <code><em>dir</em></code> options,
465 throughout the build systems of any project using an external library.
466 However, while perhaps being the simplest option,
467 this strategy is not without its disadvantages:–
468 <ul style="margin: 0.3em 0 0 -1em; list-style: disc">
469 <li>The external library components are intermingled,
470 within the file system hierarchy,
471 with MinGW’s own standard components;
472 it may not be straightforward to segregate them later,
473 should this ever be necessary.
475 <li>Should the user wish to maintain <em>side‑by‑side</em>
476 MinGW installations, at differing release point versions, say,
477 then the external library installations will need to be duplicated,
478 within each of the separate MinGW installation hierarchies.
480 <li>If the MinGW installation hierarchy is purged,
481 in preparation for a clean re‑installation,
482 then any locally installed external libraries will also be purged,
483 and if subsequently needed, will have to be reinstalled.
486 <li>Creating a separate directory hierarchy,
487 into which all external library packages are installed;
488 this mitigates the disadvantages of option (1),
489 but introduces its own drawbacks:–
490 <ul style="margin: 0.3em 0 0 -1em; list-style: disc">
491 <li>The header files and libraries are no longer in
492 MinGW GCC’s default search paths;
493 thus the user <em><strong>must</strong></em> make provision
494 to pass the appropriate <code>-I</code> <code><em>dir</em></code>,
495 (and associated <code>-L</code> <code><em>dir</em></code>),
496 options to GCC, through his own projects’ build systems.
497 (This may be mitigated, in turn, by customising the
498 <a target="_blank" href="index.html?page=gccspecs.html"
499 ><em>GCC Specs File</em></a>,
500 to supply the necessary options <em>automatically</em>,
501 for <em>all</em> invocations of GCC,
502 or by appropriately defining GCC’s
503 <a rel="noopener noreferrer" target="_blank"
504 href="http://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html#Environment-Variables"
505 ><em>CPATH and related environment variables</em></a>).
507 <li>Although now segregated from the MinGW standard library
508 and header components, all external library packages are still intermixed,
509 one with another, in a common installation hierarchy; nonetheless,
510 this is often considered to be an acceptable compromise.
513 <li>As a variation on option (2),
514 create a separate directory hierarchy,
515 for <em>each</em> and <em>every individual</em> external library package
516 to be locally installed;
517 this mitigates all of the disadvantages of option (1),
518 and the package intermixing of option (2),
519 but it incurs an alternative penalty:–
520 <ul style="margin: 0.3em 0 0 -1em; list-style: disc">
521 <li>As with option (2),
522 appropriate <code>-I</code> <code><em>dir</em></code>
523 and <code>-L</code> <code><em>dir</em></code> options
524 <em>must</em> be added to each GCC invocation; however,
525 whereas option (2) requires only one additional path of each type,
526 this option requires an additional one of each type,
527 for <em>each</em> and <em>every</em> external library to be deployed.
528 (While this may still be achieved by appropriate customisation of the
529 <a target="_blank" href="index.html?page=gccspecs.html#isystem"
530 ><em>GCC Specs File</em></a>,
531 or by appropriately specifying the
532 <a rel="noopener noreferrer" target="_blank"
533 href="http://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html#Environment-Variables"
534 ><em>CPATH and related environment variables</em></a>,
535 the additional complexity, and maintenance overhead,
536 may be considered unacceptable to many users).
540 </div><!-- third-party -->
542 <!-- $RCSfile$: end of file -->