OSDN Git Service

Publish MinGW installation and maintenance guidelines.
[mingw/website.git] / setup.html
2  *
3  * setup.html
4  *
5  * A guide to managed MinGW installation, for new users.
6  *
7  *
8  * $Id$
9  *
10 --><meta author="Julien Lecomte" /><!--
11  * Copyright (C) 2007, 2021, MinGW.org Project
12  *
13  *
14  * Redistribution and use in source and 'compiled' forms (SGML, HTML,
15  * PDF, PostScript, RTF, etc) with or without modification, are permitted
16  * provided that the following conditions are met:
17  *
18  * 1. Redistributions of source code must retain the above copyright
19  *    notice, this list of conditions and the following disclaimer as
20  *    the first lines of this file, unmodified.
21  *
22  * 2. Redistributions in compiled form (transformed to other DTDs,
23  *    converted to PDF, PostScript, RTF and other formats) must
24  *    reproduce the above copyright notice, this list of conditions
25  *    and the following disclaimer in the documentation and/or other
26  *    materials provided with the distribution.
27  *
39  * DAMAGE.
40  *
41  *
42  * Note: this page assumes browser support for the following numeric
43  * HTML entity codes:
44  *
45  *    &#8209;   non-breaking hyphen
46  *    &#8216;   typographic left (opening) single quote
47  *    &#8217;   typographic apostrophe/right (closing) single quote
48  *    &#8220;   typographic left (opening) double quote
49  *    &#8221;   typographic right (closing) double quote
50  *
51 -->
52 <style>
53 div.h3-numbered ul { margin-left: -0.7em; }
54 div.h3-numbered li > p + ul { margin-top: -0.3em; }
55 div.h3-numbered p + ul { margin-top: 0.1em; }
57 span.smaller { font-size: 0.9em; }
58 pre.vt em::after { content: "&nbsp;"; font-size: 0.4pt; }
60 ol.setup-steps { list-style: lower-roman; }
61 ol.setup-steps > li:first-child { margin-top: 0; }
62 ol.setup-steps div.desc { width: calc( 65% - 2em ); }
63 ol.setup-steps > li { clear: both; margin-top: 1.0em; }
64 ol.setup-steps img { width: 35%; float: right; margin: 0.2em 0 0 2em; }
65 ol.setup-steps ol { list-style: number; margin: 0 0 0 -0.85em; }
66 ol.setup-steps ul { list-style: disc; margin: 0 0 0 -0.7em; }
67 ol.setup-steps ol > li::marker { font-size: 0.75em; }
68 ol.setup-steps div.desc li { margin-right: 0; }
69 ol.setup-steps p { margin-top: 0.4em; }
71 ol.config-options { margin-left: -0.5em; }
72 ol.config-options > li { margin-top: 0.4em; }
73 ol.config-options > li::marker { font-size: 0.85em; }
74 ol.config-options ul + p { margin-top: 0.3em; }
75 ol.config-options ul { list-style: disc; }
77 div.step-ref { clear: both; position: relative; top: -70px; height: 70px; }
78 div.step-ref + li { margin-top: calc( 1.0em - 70px ); }
79 </style>
80 <script class="masthead">
81 /* Script fragment, to assign titles specific to this page; this is
82  * encapsulated within the "masthead", where such titles are displayed,
83  * to ensure that whatever page content may follow will be correctly
84  * positioned, relative to the masthead content.
85  */
86  set_page("title", "Getting Started with MinGW");
87  set_page("subtitle",
88     "HOWTO Set Up the MinGW Compiler Suite &mdash; a Guide for New Users"
89   );
90 </script><!-- masthead -->
92 <p>This HOWTO document provides instructions,
93 and recommendations, both for first&#8209;time installation,
94 and subsequent maintenance of the MinGW (GCC) compiler suite,
95 and ancillary MinGW applications and/or tools;
96 the recommended method of installation is suitable
97 for <em>all</em>&hairsp; users,
98 regardless of experience,
99 or level of expertise.
100 </p>
101 <p><strong><em>Caution</em></strong>&hairsp;:
102 MinGW may have problems with paths containing spaces, and if not,
103 other programs used with MinGW may often experience problems with such paths.
104 Thus, we <strong><em>strongly recommend</em></strong>&hairsp; that you
105 <strong><em>do not install MinGW in any location
106 with spaces in the absolute path name</em></strong>&hairsp;;
107 you should avoid installing into any directory or subdirectory
108 having names like <code>&quot;Program</code>&#8197;<code>Files&quot;</code>
109 or <code>&quot;My</code>&#8197;<code>Documents&quot;</code>, etc.
110 </p>
111 <p>The preferred installation target directory,
112 its path name having been chosen to comply with the preceding recommendation,
113 is <code><strong>C:\MinGW</strong></code>
114 </p>
115 <p>The preferred installation method is using
116 the <code>mingw-get</code> &#8220;Installation Manager&#8221; tool,
117 <a href="#start-here">as described below</a>.
118 While a manual installation is possible,
119 we recommend it only for expert users,
120 unless you have a very old version of MS&#8209;Windows,
121 which is unable to run the GUI variant of <code>mingw&#8209;get</code>.
122 If you really want (or need) to resort to it,
123 instructions for manual installation are provided in
124 <a target="_blank" href="index.html?page=install.html"
125 >this alternative HOWTO document</a>.
126 </p>
127 <p>After installation,
128 you may need to perform some additional system configuration tasks yourself,
129 to ensure your MinGW applications will run.
130 Most importantly,
131 you may need to set up <code>Start</code>&#8197;<code>Menu</code>,
132 or <code>Desktop</code> &#8220;short&#8209;cuts&#8221;,
133 to launch a suitable command line interpreter session,
134 with appropriate environment variable settings,
135 (notably, the <code>PATH</code> setting),
136 for running MinGW applications;
137 further details may be found in the
138 <a href="#post-install">post&#8209;installation section</a>,
139 below.
140 </p>
141 <p>Ultimately,
142 having completed installation and configuration,
143 you will wish to perform occasional maintenance tasks,
144 perhaps to install additional packages,
145 and certainly to install software updates,
146 and so keep your installation up&#8209;to&#8209;date;
147 suitable maintenance procedures are discussed in
148 <a href="#maintenance">the final section</a>
149 of this document.
150 </p>
152 <div class="h3-numbered">
153 <div class="overlapped" id="start-here">
154 <h3>Setting Up the MinGW Installation Manager for First&#8209;Time Use</h3>
155 <p>The first step,
156 in the recommended procedure for creating a new MinGW installation,
157 is to install the <code>mingw-get</code> installer itself;
158 this can be most readily accomplished by downloading,
159 and subsequently running,
160 <a rel="noopener noreferrer" target="_blank"
161  href="https://osdn.net/dl/mingw/mingw-get-setup.exe"
162 >the GUI <code>mingw&#8209;get&#8209;setup.exe</code> tool</a>.
163 </p>
164 <p>If you have previously installed <code>mingw&#8209;get</code>,
165 and your objective is to upgrade, or to extend,
166 its associated (existing) MinGW installation,
167 then you should <em>not</em> run <code>mingw&#8209;get&#8209;setup.exe</code> again;
168 you <em>should</em> simply run <code>mingw&#8209;get.exe</code>, and
169 <a href="#install-packages">proceed directly to the next installation phase</a>.
170 </p>
171 <p>If do wish to run <code>mingw&#8209;get&#8209;setup.exe</code>,
172 and you already have a local copy,
173 we <em>strongly</em> recommend that you check its publication date,
174 to ensure that it is no older than the current release,
175 <a rel="noopener noreferrer"
176  target="_blank" href="https://osdn.net/projects/mingw"
177 >as identified at https://osdn.net/projects/mingw</a>;
178 you should <em>always</em> run the most recent release of
179 <code>mingw&#8209;get&#8209;setup.exe</code>,
180 so please download a replacement copy,
181 if yours is out of date.
182 </p>
183 <p>When you <em>do</em> choose to run
184 <code>mingw&#8209;get&#8209;setup.exe</code>,
185 you should follow this sequence of steps:&ndash;
186 </p>
187 <ol class="setup-steps">
188 <li><img src="https://static-cdn.osdn.net/thumb/g/5/213/800x600_0.png"
189  alt="Installer Setup &mdash; Opening Dialogue"
190 /><div class="desc">
191 Depending on your MS&#8209;Windows version,
192 and its system security policy configuration,
193 you may be able to invoke <code>mingw&#8209;get&#8209;setup.exe</code>
194 directly from the <a rel="noopener noreferrer"
195  target="_blank" href="https://osdn.net/dl/mingw/mingw-get-setup.exe"
196 >download link specified above</a>;
197 alternatively, you may need to save a local copy,
198 locate it in the file&#8209;system explorer,
199 and double&#8209;click to invoke it.
200 In either case, and again depending on Windows version,
201 and security policy configuration,
202 you may need to authorize execution of
203 <code>mingw&#8209;get&#8209;setup.exe</code>,
204 and the changes it will make to your system,
205 after which you should see a dialogue similar
206 to that depicted to the right.
207 <p>When you see this dialogue,
208 we advise you to acquaint yourself with the content
209 of the warranty disclaimer, and additional &#8220;blurb&#8221;,
210 which appears below the copyright notice;
211 you may also wish to review the licensing terms,
212 which will be displayed in a web browser window,
213 if you click the <code>View</code>&#8197;<code>Licence</code> button.
214 </p>
215 <p>When you are ready to proceed,
216 click the <code>Install</code> button to move on to the next step;
217 alternatively, you may click the <code>Cancel</code> button
218 to abandon the installation process.
219 </p>
220 </div><!-- ol.setup-steps desc -->
221 </li>
222 <div class="step-ref" id="step-1-ii"></div>
223 <li><img src="https://static-cdn.osdn.net/thumb/g/5/214/800x600_0.png"
224  alt="Installer Setup &mdash; Preferences Dialogue"
225 /><div class="desc">
226 On progressing from the opening dialogue,
227 by clicking on the <code>Install</code> button
228 as stipulated in the preceding step,
229 you will be presented with a new dialogue,
230 as depicted to the right.
231 Here, you have the opportunity to select from
232 a set of optional configuration attributes for
233 your <code>mingw&#8209;get</code> installation,
234 and for the associated MinGW installation,
235 which you will use it to manage.
236 <p>You may observe, when this dialogue is opened,
237 that the installation directory is specified, by default,
238 to be <code>C:\MinGW</code>.
239 We <em>strongly</em> recommend that you leave this
240 at its default setting,
241 <em>except</em> in the particular cases where:&ndash;
242 <ul><li>Your system policy forbids installation into a directory
243 at this level within the file&#8209;system hierarchy,
244 and you are unable to obtain authorization for an exception
245 to such a policy.
246 </li>
247 <li>You require an alternative installation root directory,
248 for the purpose of creating <em>side&#8209;by&#8209;side</em>
249 MinGW sandbox installations.
250 </li></ul>
251 <p>If you do choose to change the installation directory,
252 you may click the <code>Change</code> button to open
253 a standard file&#8209;system navigation dialogue,
254 whence you may select, or create, an alternative directory;
255 <em>do</em> please heed the warning about avoiding any
256 directory name, which introduces white&#8209;space into
257 its absolute path name.
258 </p>
259 <p>Other installation options, which you may select via this dialogue,
260 include:&ndash;
261 </p>
262 <ul><li>Installation of the <code>mingw&#8209;get</code> GUI application,
263 in addition to the CLI version, (which is <em>always</em> installed).
264 </li>
265 <li>Installation of Windows &#8220;shortcuts&#8221;,
266 either on the desktop,
267 or in the Windows <code>Start</code>&nbsp;<code>Menu</code>, (or both),
268 for either the current user only (<em>strongly</em> recommended),
269 or for all users;
270 (if installed, these will launch the <code>mingw&#8209;get</code>
271 GUI client, and thus are effective only if that is installed).
272 </li></ul>
273 <p>Once you have specified your choice of installation root directory,
274 and completed your selection of installation options,
275 you may click the <code>Continue</code> button,
276 to proceed to the next step &mdash; the actual installation
277 of <code>mingw&#8209;get</code>.
278 </p>
279 </div><!-- ol.setup-steps desc -->
280 </li>
281 <li><img src="https://static-cdn.osdn.net/thumb/g/5/215/800x600_0.png"
282  alt="Installer Setup &mdash; Download Dialogue"
283 /><div class="desc">
284 Your computer <em>must</em> remain actively connected to the internet,
285 throughout this step, which should proceed <em>without</em> user intervention.
286 <p>While the process proceeds, you should observe a dialogue similar to
287 that depicted to the right; the data displayed will be dynamically
288 updated, as the constituent packages of <code>mingw&#8209;get</code>
289 are downloaded from the MinGW.org on&#8209;line file store,
290 and installed locally, into your designated installation directory tree.
291 </p>
292 <p>You may observe that,
293 while download and installation are in progress,
294 the <code>Continue</code> and <code>Quit</code>
295 buttons are <em>disabled</em>;
296 they will be <em>enabled</em>, only when the process completes.
297 </p>
298 <p>If errors occur, during the download and installation process,
299 only the <code>Quit</code> button will be <em>enabled</em>,
300 allowing you to terminate <code>mingw&#8209;get&#8209;setup.exe</code>;
301 please <a target="_blank"
302  href="index.html?page=faq.html#troubleshoot-installation"
303 >consult the FAQ</a>, or <a target="_blank"
304  href="index.html?page=mailing.html#mingw-users"
305 >seek advice via the mailing list</a>,
306 for assistance to troubleshoot, and resolve the errors,
307 <em>before</em> running <code>mingw&#8209;get&#8209;setup.exe</code> again.
308 </p>
309 <p>When the download and installation of <code>mingw&#8209;get</code>
310 completes successfully, <em>both</em> the <code>Continue</code>,
311 <em>and</em> the <code>Quit</code> buttons will be <em>enabled</em>.
312 At this point, you may choose to:&ndash;
313 </p>
314 <ul><li>Click the <code>Continue</code> button,
315 to terminate <code>mingw&#8209;get&#8209;setup.exe</code>,
316 and <em>immediately</em> start <code>mingw&#8209;get</code> in GUI mode;
317 (note that the <code>mingw&#8209;get</code> GUI is available at this point,
318 at least temporarily, even if you chose not to install it permanently).
319 </li>
320 <li>Click the <code>Quit</code> button,
321 to terminate <code>mingw&#8209;get&#8209;setup.exe</code>
322 <em>without</em> starting <code>mingw&#8209;get</code>;
323 (you may resume installation of MinGW later,
324 by running stand&#8209;alone <code>mingw&#8209;get</code>,
325 either in CLI mode,
326 or &mdash; if you chose to install it as a permanent capability &mdash;
327 in GUI mode).
328 </li></ul>
329 <p>Regardless of which of the preceding options you choose,
330 <code>mingw&#8209;get&#8209;setup.exe</code> has completed its task;
331 when you proceed to the next stage of the installation process,
332 you will be running <code>mingw&#8209;get</code>,
333 <em>not</em>&hairsp; <code>mingw&#8209;get&#8209;setup.exe</code>.
334 </p>
335 </div><!-- ol.setup-steps desc -->
336 </li></ol>
337 </div><!-- start-here -->
339 <div style="clear: both"></div>
340 <div class="overlapped" id="install-packages">
341 <h3>Using the MinGW Installation Manager to Install Packages</h3>
342 <p>Once you have completed the installation of
343 <code><strong>mingw&#8209;get</strong></code>,
344 (which is also known,
345 particularly in its GUI guise,
346 as the &#8220;MinGW Installation Manager&#8221;),
347 you may use it to proceed with the installation of your choice of packages,
348 to complete (or subsequently extend) your MinGW installation.
349 Assuming that you have started the GUI variant of <code>mingw&#8209;get</code>,
350 either (having chosen to install it
351 at <a href="#step-1-ii">step ii of the set up procedure</a>)
352 as a free&#8209;standing application,
353 or by continuation from within <code>mingw&#8209;get&#8209;setup.exe</code>,
354 you will be presented with a three&#8209;paned window display,
355 whence you may proceed as follows:&ndash;
356 </p>
357 <ol class="setup-steps">
358 <li><img src="https://static-cdn.osdn.net/thumb/g/7/709/800x600_0.png"
359  alt="Installer &mdash; Basic Package View"
360 /><div class="desc">
361 When <code>mingw&#8209;get</code> is invoked as a continuation
362 of <code>mingw&#8209;get&#8209;setup.exe</code>,
363 the initial three&#8209;paned view will appear as on the right;
364 (alternatively,
365 this view may be accessed by selecting
366 the <code>Basic</code>&#8197;<code>Setup</code>
367 option in the left&#8209;hand window pane,
368 at any time,
369 regardless of whether <code>mingw&#8209;get</code> is running
370 as a continuation of <code>mingw&#8209;get&#8209;setup.exe</code>,
371 or as a free&#8209;standing application).
372 <p>Within this view,
373 you will see a list (in the upper right&#8209;hand pane) of those packages
374 which are likely to be of most interest to first&#8209;time MinGW users;
375 you may select any one of these packages,
376 to see related package information on the tabs of
377 the lower right&#8209;hand pane,
378 and,
379 by clicking on the small square button,
380 to the left of any selected package entry,
381 you may choose (from its context menu) to mark one (or more) packages,
382 which you would like to install ...
383 for first&#8209;time users,
384 we recommend that you elect to install,
385 at least,
386 the <code>mingw32&#8209;base&#8209;bin</code> package,
387 (which comprises the C compiler and essential ancillary tools);
388 if you require a C++ compiler,
389 in addition to the C compiler,
390 you should also elect to install
391 the <code>mingw32&#8209;g++&#8209;bin</code> package.
392 </div><!-- ol.setup-steps desc -->
393 </li>
394 <div style="clear: both"></div>
395 <li><img src="https://static-cdn.osdn.net/thumb/g/7/710/800x600_0.png"
396  alt="Installer &mdash; All Package View"
397 /><div class="desc">
398 Conversely,
399 when the GUI variant of <code>mingw&#8209;get</code> is invoked
400 as a free&#8209;standing application,
401 the initial three&#8209;paned view will appear as on the right;
402 (alternatively,
403 this view may be accessed by selecting the
404 <span class="nowrap"><code>All</code>&#8197;<code>Packages</code></span> option,
405 in the left&#8209;hand pane,
406 regardless of how <code>mingw&#8209;get</code> has been started).
407 <p>You may observe that,
408 in comparison with the
409 <span class="nowrap"><code>Basic</code>&#8197;<code>Setup</code></span> view,
410 this view offers a selection of many more packages,
411 from which you may choose those which you would like to install
412 ... so many more that,
413 to see the entire selection,
414 you will need to scroll the list in the upper right window pane;
415 if you find this extensive package list to be too confusing,
416 you may refine the visible selection by clicking on
417 any of the subsidiary package categories,
418 as shown in the package category tree view,
419 in the left hand pane.
420 </p>
421 <p>As with selection of packages from the
422 <span class="nowrap"><code>Basic</code>&#8197;<code>Setup</code></span> view,
423 you may elect to install any packages which are visible in the
424 <span class="nowrap"><code>All</code>&#8197;<code>Packages</code></span> view,
425 making your selection by clicking on the small square button,
426 to the left of the name of each chosen package,
427 in turn,
428 and choosing the <span class="nowrap">
429 <code>Mark</code>&#8197;<code>for</code>&#8197;<code>Installation</code></span>
430 option from the associated context menu.
431 </p>
432 </div><!-- ol.setup-steps desc -->
433 </li>
434 <div class="step-ref" id="step-2-iii"></div>
435 <li><img src="https://static-cdn.osdn.net/thumb/g/7/714/800x600_0.png"
436  alt="Installer &mdash; Apply Changes View"
437 /><div class="desc">
438 Once you have made a selection of packages to be installed,
439 from either the
440 <span class="nowrap"><code>Basic</code>&#8197;<code>Setup</code></span> view,
441 or the
442 <span class="nowrap"><code>All</code>&#8197;<code>Packages</code></span> view,
443 as described above,
444 you must commit this selection,
445 to complete your installation,
446 by proceeding as follows:&ndash;
447 <ol>
448 <li>Open the <code>Installation</code> menu,
449 (on the menu bar),
450 and select the
451 <span class="nowrap"><code>Apply</code>&#8197;<code>Changes</code></span> option;
452 (this will open a dialogue,
453 similar to that shown to the right).</li>
454 <li>Review the schedule of pending installation actions,
455 (noting that you may need to scroll the lists of packages for which deletion,
456 upgrade, or installation actions have been scheduled,
457 for any of these lists which includes more than six package entries),
458 then choose <em>one</em>&hairsp; of:&ndash;
459 <ul>
460 <li>Click the <code>Apply</code> button,
461 to complete <em>all</em> scheduled actions,
462 update indicated installation status,
463 clear the schedule of pending actions,
464 and return to the selection phase of installation,
465 to allow initiation of a further package selection.</li>
466 <li>Click the <code>Defer</code> button,
467 if you would like to modify your package selection;
468 this will take you back to the package selection phase of installation,
469 to allow you to make your desired changes.</li>
470 <li>Click the <code>Discard</code> button,
471 if you do <em>not</em>&hairsp; wish to commit <em>any</em>&hairsp;
472 of the scheduled changes;
473 this will clear your active package selection,
474 then return you to the package selection phase of installation,
475 whence you may start the installation process again.</li>
476 </ul></ol>
477 </div><!-- ol.setup-steps desc -->
478 </li>
479 <li><div class="desc">
480 After you have completed your selection of packages,
481 and you have committed all of the changes which are needed to install them,
482 you may quit from <code>mingw&#8209;get</code>,
483 either by selecting the <code>Quit</code> option
484 from the <code>Installation</code> menu,
485 or by simply closing the <span class="nowrap">
486 &#8220;MinGW&#8197;Installation&#8197;Manager&#8221;</span> GUI window.
487 Having done so,
488 and in particular,
489 if you have just completed a first&#8209;time installation,
490 you may need to perform some post&#8209;installation system configuration,
491 as described in the following section,
492 to make your installation work.
493 <p style="display: none">
494 At this point,
495 if you plan to use the MSYS command line interpreter system,
496 your MinGW installation should be ready to use;
497 however,
498 if you choose to use MinGW from Microsoft&#8217;s
499 <span class="nowrap">&#8220;command&#8197;prompt&#8221;</span>
500 console subsystem,
501 then you may need to complete the
502 <a href="#post-install">MinGW post&#8209;installation steps</a>
503 as <a href="#post-install">described below</a>.
504 </p>
505 </div><!-- ol.setup-steps desc -->
506 </li></ol>
507 </div><!-- install-packages -->
509 <div style="clear: both"></div>
510 <div class="overlapped" id="post-install">
511 <h3>Post&#8209;Installation Requirements for Use of the MinGW Compiler Suite</h3>
512 <p>As noted above,
513 the process of installation alone
514 is likely to be insufficient to acquire a working MinGW system:
515 some additional one&#8209;time system configuration is usually required.
516 </p>
517 <p>Although some users may choose
518 to use an integrated development environment (IDE),
519 it is important to understand that, fundamentally,
520 MinGW applications are intended for deployment
521 using a command line interface (CLI);
522 the scope of the necessary system configuration
523 is dependent on <em>your</em>&hairsp; choice of infrastructure,
524 for provision of a suitable CLI,
525 or IDE.
526 Some choices,
527 which you may wish to consider,
528 include:&ndash;
529 </p>
530 <ol class="config-options">
531 <li>Run the MinGW tools <em>directly</em>,&hairsp;
532 using Microsoft&#8217;s <code>cmd.exe</code> interpreter,
533 within the MS&#8209;Windows default <span class="nowrap">
534 &#8220;<code>Command</code>&#8197;<code>Prompt</code>&#8221;
535 </span> console host.
536 If you choose this option,
537 (which may <em>not</em>&hairsp; be the most appropriate choice),
538 you will, at least, need to ensure that the MinGW tools can be found
539 in the <code>cmd.exe</code> executable search <code>PATH</code>,
540 as configured in the process environment.
541 The default system configuration will not normally support
542 this capability, without making an appropriate <code>PATH</code> adjustment;
543 to check if any such adjustment is necessary:&ndash;
544 <ul>
545 <li>Open a <code>Command</code>&#8197;<code>Prompt</code> console,
546 and run the command:
547 <pre class="vt box-out">
548 C:\Users\me&gt; <kbd>gcc --version</kbd>
549 </pre>
550 If this results in output similar to:
551 <pre class="vt box-out">
552 C:\Users\me&gt; <kbd>gcc --version</kbd>
553 gcc (MinGW GCC Build-2) 9.2.0
554 Copyright (C) 2019 Free Software Foundation, Inc.
555 This is free software; see the source for copying conditions.  There is NO
557 </pre>
558 then it appears that your process <code>PATH</code> setting
559 <em>is already</em>&hairsp; suitably configured,
560 and <em>no further</em>&hairsp; configuration is needed;
561 however, if the output resembles:
562 <pre class="vt box-out">
563 C:\Users\me&gt; <kbd>gcc --version</kbd>
564 'gcc' is not recognized as an internal or external command,
565 operable program or batch file.
566 </pre>
567 this, then the <code>PATH</code> setting in the process environment
568 <em>is not</em>&hairsp; suitably configured;
569 you <em>should</em>&hairsp; modify the environment configuration,
570 as advised below.
571 </li></ul>
572 <p>If the preceding check indicates that
573 the <code>PATH</code> configuration needs to be adjusted,
574 then you should proceed as follows:&ndash;
575 </p><ul>
576 <li>From the system <span class="nowrap">
577 <code>Control</code>&#8197;<code>Panel</code></span>,
578 open the <code>System</code> tab,
579 access the <span class="nowrap">
580 <code>Advanced</code>&#8197;<code>system</code>&#8197;<code>settings</code>
581 </span> dialogue,
582 and click the <span class="nowrap">
583 <code>Environment</code>&#8197;<code>Variables</code></span> button.
584 </li>
585 <li>In the dialogue,
586 which should now have become active,
587 observe that there are two categories of environment variables,
588 viz. a category for user&#8209;specific variables,
589 and another for system (global) variables.
590 Please note that any environment variables,
591 which you either add, or modify, in either of these categories,
592 will be recorded in the system registry,
593 and will become visible to <em>all</em>&hairsp; processes
594 which are subsequently invoked on the system,
595 (although visibility of those in the user&#8209;specific category
596 will be restricted to processes owned by the currently&#8209;logged&#8209;in
597 user), and that changes to the <code>PATH</code> variable have potential
598 to introduce system security vulnerabilities;
599 thus, you should exercise caution,
600 when making such changes, and,
601 unless it is your intention that your changes should affect
602 <em>all users</em>&hairsp; of the system,
603 you should prefer to make the change <em>only</em>&hairsp;
604 in the user&#8209;specific category,
605 in order to limit the potential of any vulnerability.
606 </li>
607 <li>Note that <code>mingw&#8209;get</code> will have installed
608 MinGW applications into <code>C:\MinGW\bin</code>,
609 (with substitution of any alternative installation&#8209;root path name,
610 which you may have chosen at installation time,
611 for the <code>C:\MinGW</code> prefix);
612 it is this equivalent for the <code>C:\MinGW\bin</code> path name,
613 (with prefix substitution as may be appropriate),
614 which you must now incorporate into the <code>PATH</code> variable,
615 to be passed in the environment,
616 to your <span class="nowrap">
617 <code>Command</code>&#8197;<code>Prompt</code></span> process.
618 </li>
619 <li>Within the environment variables category
620 in which you have decided to adjust the <code>PATH</code> setting,
621 identify the entry (matching the variable name
622 <em>case&#8209;insensitively</em>&hairsp;),
623 if it exists, for the <code>PATH</code> variable definition.
624 </li>
625 <li>If the <code>PATH</code> variable definition <em>does</em>&hairsp;
626 already exist, select it, and click the <code>Edit</code> button;
627 move the input cursor to the <em>end</em>&hairsp; of the
628 <code>Value</code> field,
629 and append a semicolon (&#8220;<code>;</code>&#8221;),
630 followed by your equivalent for <code>C:\MinGW\bin</code>,
631 with prefix substitution as required.
632 </li>
633 <li>Conversely, if no such <code>PATH</code> variable exists,
634 click the <code>New</code> button, and create a new entry for it;
635 assign your equivalent for <code>C:\MinGW\bin</code>,
636 with prefix substitution as required,
637 as its value.
638 </li>
639 <li>Click the <code>OK</code> button on each nested dialogue box,
640 as you walk focus back to the top level of the <span class="nowrap">
641 <code>Control</code>&#8197;<code>Panel</code></span>,
642 so saving your environment variable changes,
643 then dismiss the <span class="nowrap">
644 <code>Control</code>&#8197;<code>Panel</code></span> itself.
645 </li></ul>
646 <p>After you have completed the above system configuration steps,
647 you may open a standard MS&#8209;Windows <span class="nowrap">
648 <code>Command</code>&#8197;<code>Prompt</code></span> console session,
649 and you <em>should</em>&hairsp; find that your MinGW tools will work,
650 without further ado.
651 </p></li>
652 <li>As a (possibly better) alternative to option
653 <span class="smaller">1</span>,
654 you may still choose to run the MinGW tools directly from
655 Microsoft&#8217;s <code>cmd.exe</code> command line interpreter,
656 but with this interpreter hosted within a console session which has
657 been started from a customized &#8220;shortcut&#8221;,
658 which itself addresses the issue of adding the equivalent of
659 <code>C:\MinGW\bin</code> to the <code>PATH</code>
660 environment variable setting;
661 this ensures that the modified <code>PATH</code> setting is visible
662 <em>only</em>&hairsp; to processes which are invoked from within
663 the hosting console session itself, and thus
664 <em>significantly</em>&hairsp; reduces any associated potential
665 for exposure to system security vulnerability exploits.
666 <p>To implement this <code>PATH</code> configuration technique:&ndash;
667 </p><ul>
668 <li>Create a new &#8220;shortcut&#8221;,
669 ideally within the <code>MinGW</code> subdirectory
670 (folder) of your user&#8209;specific
671 <span class="nowrap"><code>Start</code>&#8197;<code>Menu</code></span>,
672 (or, if preferred, in the <code>MinGW</code> subdirectory of the
673 <span class="nowrap"><code>All</code>&#8197;<code>Users</code></span>
674 <span class="nowrap"><code>Start</code>&#8197;<code>Menu</code></span>,
675 noting that you may need to create the respective <span class="nowrap">
676 <code>"Start</code>&#8197;<code>Menu\MinGW"</code></span> subdirectory,
677 if it does not already exist);
678 you should name this new &#8220;shortcut&#8221; as
679 <span class="nowrap"><code>"MinGW</code>&#8197;<code>Prompt.lnk"</code>,</span>
680 <span class="nowrap"><code>"MinGW</code>&#8197;<code>Console.lnk"</code>,</span>
681 or any similar alternative name of your own choice.
682 <li>Set the <code>Target</code> of your new &#8220;shortcut&#8221; to:
683 <pre class="vt box-out">
684 <kbd>%comspec% /k path %PATH%;C:\MinGW\bin</kbd>
685 </pre>
686 (with substitution for <code>C:\MinGW</code>, as appropriate,
687 if you chose an alternative prefix at installation time).
688 Alternatively, create a new MS&#8209;Windows batch file,
689 (called <span class="nowrap"><code>C:\MinGW\mingw.bat</code>,</span>
690 for example), within which the:
691 <pre class="vt box-out">
692 <kbd>path %PATH%;C:\MinGW\bin</kbd>
693 </pre>
694 <code>PATH</code> augmentation command is executed,
695 and set the &#8220;shortcut&#8221; <code>Target</code> to:
696 <pre class="vt box-out">
697 <kbd>%comspec% /k C:\MinGW\mingw.bat</kbd>
698 </pre>
699 (This latter alternative offers greater flexibility than the former,
700 insofar as the batch file may be modified to accommodate configuration
701 options beyond the minimally required <code>PATH</code> augmentation).
702 </li>
703 <li>Access the properties of the new &#8220;shortcut&#8221;,
704 and set the start&#8209;up directory path name, within the
705 <span class="nowrap"><code>Start</code>&#8197;<code>in</code></span>
706 field, to select any appropriate directory of your choice;
707 if you wish to reproduce the behaviour of the standard MS&#8209;Windows
708 <span class="nowrap"><code>Command</code>&#8197;<code>Prompt</code>,</span>
709 the appropriate assignment is:
710 <pre class="vt box-out">
711 <kbd>%HOMEDRIVE%%HOMEPATH%</kbd>
712 </pre>
713 At the same time,
714 you may wish to take the opportunity to tweak &#8220;shortcut&#8221;
715 properties on the <code>Font</code>, <code>Layout</code>,
716 and <code>Colors</code> tabs.
717 </li></ul></li>
718 <li>If you chose to install MSYS,
719 and you would like to use it as your working MinGW development environment,
720 in preference to the rather more limited capabilities of the MS&#8209;Windows
721 <span class="nowrap"><code>Command</code>&#8197;<code>Prompt</code>,</span>
722 then some associated configuration checks are recommended:&ndash;
723 <ul>
724 <li>Firstly,
725 you may need to create a &#8220;shortcut&#8221;,
726 ideally within your user&#8209;specific
727 <span class="nowrap"><code>Start</code>&#8197;<code>Menu</code>,</span>
728 or within the
729 <span class="nowrap"><code>All</code>&#8197;<code>Users</code>,</span>
730 <span class="nowrap"><code>Start</code>&#8197;<code>Menu</code>;</span>
731 the recommended name for this &#8220;shortcut&#8221; is
732 <span class="nowrap"><code>MinGW</code>&#8197;<code>Shell</code>,</span>
733 and its <code>Target</code> should be set to invoke:
734 <pre class="vt box-out">
735 <kbd>C:\MinGW\MSYS\1.0\msys.bat</kbd>
736 </pre>
737 (with the path name adjusted, as may be required,
738 to represent the actual installed location of <code>msys.bat</code>).
739 </li>
740 <li>Secondly,
741 your MSYS installation <em>must</em>&hairsp; be given an appropriate
742 hint to the base location of your MinGW tools.
743 This is established by means of a &#8220;mount&nbsp;point&#8221;
744 specification, within the <span class="nowrap">
745 <code>C:\MinGW\MSYS\1.0\etc\fstab</code></span> file,
746 (again, with the <span class="nowrap"><code>C:\MinGW\MSYS\1.0</code></span>
747 path name adjusted to match the prefix,
748 in the actual location of the <code>msys.bat</code> file);
749 if this file does not exist, you should create it,
750 but in any case, you <em>must</em>&hairsp; ensure that it
751 includes (at least) a line of the form:
752 <pre class="vt box-out">
753 <kbd>C:/MinGW   /mingw</kbd>
754 </pre>
755 (again noting that the <code>C:/MinGW</code> prefix should be adjusted
756 to match any alternative, which you may have chosen at installation time,
757 and furthermore, &#8220;<code>/</code>&#8221; characters should be used
758 as directory name separators, in preference to &#8220;<code>\</code>&#8221;
759 characters, within the <code>etc/fstab</code> file).
760 </li></ul>
761 <p>You may be wondering why these post&#8209;installation instructions,
762 for MSYS, do not refer to <code>PATH</code> configuration.
763 In practice, no specific configuration is necessary, because,
764 provided the <code>/mingw</code> &#8220;mount&#8209;point&#8221;
765 is correctly specified in the <code>fstab</code> file,
766 MSYS will correctly deduce the required <code>PATH</code> setting,
767 when any shell session is started.
768 However, it <em>is</em>&hairsp; important to note that it is
769 <em>imperative</em>&hairsp; that <em>no white&#8209;space</em>&hairsp;
770 is present, within the absolute path name specification for the
771 &#8220;mount&#8209;point&#8221;;
772 thus, since this <em>must</em>&hairsp; be specified as
773 an <em>absolute</em>&hairsp; path name, if,
774 contrary to offered advice,
775 you have chosen an installation directory with white&#8209;space
776 in its absolute path name,
777 you will need to determine the short (8.3) form of your
778 installation path name,
779 and use that in the &#8220;mount&#8209;point&#8221; specification.
780 </p></li>
781 <li>Regardless of whether you choose to run the MinGW tools
782 within an MSYS session, or within a <code>cmd.exe</code> session, by default,
783 either of these will run within an MS&#8209;Windows console host
784 container.
785 If you prefer, you may choose an alternative container, such as
786 <a target="_blank" rel="noopener noreferrer" href="https://conemu.github.io">
787 ConEmu</a>,
788 <a target="_blank" rel="noopener noreferrer" href="https://github.com/bozho/console">
789 Console2</a>, or
790 <a target="_blank" rel="noopener noreferrer" href="https://github.com/cbucher/console">
791 ConsoleZ</a>.
792 While it should be feasible to use any of these,
793 each will have its own configuration considerations,
794 which are beyond the scope of this HOWTO document.
795 </li>
796 <li>Alternatively,
797 you may decide that you would prefer to deploy MinGW within an IDE.
798 Please be aware that MinGW.OSDN offers no formal support for any such
799 deployment; however, users have reported success with
800 <a target="_blank" rel="noopener noreferrer" href="https://www.codeblocks.org">
801 Code::Blocks</a>, and with
802 <a target="_blank" rel="noopener noreferrer" href="https://www.eclipse.org">
803 Eclipse</a>,
804 (but be advised that these third&#8209;party websites may
805 may exhibit out&#8209;of&#8209;date references to MinGW download sites;
806 the most up&#8209;to&#8209;date downloads of MinGW are <em>always</em>&hairsp;
807 available from <a target="_blank" rel="noopener noreferrer"
808 href="https://osdn.net/projects/mingw/">OSDN.net</a>).
809 As with option <span class="smaller">4</span>,
810 each of these IDEs will be subject to its own configuration considerations,
811 which, once again, are beyond the scope of this HOWTO document.
812 </li></ol>
813 </div><!-- post-install -->
815 <div style="clear: both"></div>
816 <div class="overlapped" id="maintenance">
817 <h3>Maintaining Currency of your MinGW Installation</h3>
818 <p>After you have installed your initial choice of MinGW,
819 and/or MSYS packages,
820 you will eventually discover that you need to perform some degree
821 of maintenance of your installation;
822 this need may be prompted by:&ndash;
823 </p><ul>
824 <li>A desire to install additional packages,
825 which you had not chosen to include within your original installation.
826 </li>
827 <li>Availability of newer releases of those packages,
828 which you have previously installed;
829 you will wish to upgrade your existing installation,
830 to take advantage of any such newer package releases.
831 </li>
832 </ul>
833 <p>Regardless of your motivation
834 for performing maintenance on your MinGW installation,
835 it is recommended that you use <code>mingw&#8209;get</code>,
836 either in its GUI, or in its CLI mode of operation,
837 to achieve your objective.
838 </p>
839 <p>Whether your intention is to install a new package,
840 or simply to upgrade an installed package to a newer release,
841 you should ensure that the package information records, within
842 your locally installed copy of <code>mingw&#8209;get</code>,
843 are kept up&#8209;to&#8209;date with respect to the state of
844 the online package repositories.
845 To achieve this,
846 you are advised to periodically,
847 (say, if it has been more than a week since your update),
848 request an update of your local copy of the package catalogue,
849 <em>before</em>&hairsp; you embark on any package installation,
850 or package upgrade activity.
851 You may accomplish this, either:&ndash;
852 </p><ul>
853 <li>From the <code>mingw&#8209;get</code> GUI,
854 by selecting the <span class="nowrap">
855 <code>Update</code>&#8197;<code>Catalogue</code></span> option
856 from the <code>Installation</code> menu.
857 <li>From the MinGW CLI, simply by running the command:
858 <pre class="vt box-out">
859 C:\Users\me&gt; <kbd>mingw-get update</kbd>
860 </pre>
861 </li></ul>
862 <p>After updating your package catalogue,
863 to synchronize with the online package repository state,
864 you may install further packages:&ndash;
865 </p><ul>
866 <li>From the <code>mingw&#8209;get</code> GUI,
867 by following the procedure described in <a href="#install-packages">
868 section <span class="smaller">2</span>, above</a>.
869 </li>
870 <li>From the MinGW CLI, by running the command:
871 <pre class="vt box-out">
872 C:\Users\me&gt; <kbd>mingw-get install</kbd> &lt;<em>package-name</em>&gt;
873 </pre>
874 </li></ul>
875 <p>When a new version of any package,
876 which you have already installed, is released,
877 you will want to upgrade your installation,
878 to incorporate the package changes.
879 Once again, you can perform the upgrade from either
880 the <code>mingw&#8209;get</code> GUI,
881 or the MinGW CLI;
882 the simplest procedure,
883 which will upgrade <em>all</em>&hairsp; installed packages,
884 for which new releases are available,
885 <em>en masse</em>,&hairsp; is&ndash;
886 </p><ul>
887 <li>From the <code>Installation</code> menu of
888 the <code>mingw&#8209;get</code> GUI,
889 select the <span class="nowrap">
890 <code>Mark</code>&#8197;<code>All</code>&#8197;<code>Upgrades</code>
891 </span> option, followed by the <span class="nowrap">
892 <code>Apply</code>&#8197;<code>Changes</code>,</span>
893 then review, and commit the changes,
894 following the procedure described in
895 <a href="#step-2-iii">section <span class="smaller">2</span>, step iii</a>,
896 above.
897 </li>
898 <li>From the MinGW CLI, execute the command:
899 <pre class="vt box-out">
900 C:\Users\me&gt; <kbd>mingw-get upgrade</kbd>
901 </pre>
902 (without <em>any</em>&hairsp; <span class="nowrap">
903 <code>&lt;<em>package-name</em>&gt;</code></span> argument);
904 this CLI method performs <em>identically</em>&hairsp; the same
905 <em>en masse</em>&#8209; upgrade as the GUI method, <em>except</em>&hairsp;
906 that it offers <em>no opportunity</em>&hairsp; for review of the scheduled
907 changes, prior to <em>unconditionally</em>&hairsp; committing them.
908 </li></ul>
909 <p>Alternatively,
910 you may choose to perform a <em>selective</em>&hairsp; upgrade
911 of individual packages:&ndash;
912 </p><ul>
913 <li>In the <code>mingw&#8209;get</code> GUI,
914 by selecting the <span class="nowrap">
915 <code>Mark</code>&#8197;<code>for</code>&#8197;<code>Upgrade</code>
916 </span> option, in the context menu which is attached to the status icon
917 to the left of the package list entry for each package of interest;
918 (those packages, for which upgrades are available, are identified
919 by a yellow star, in the upper right corner of the status icon).
920 <p>After selecting packages to upgrade,
921 once again select the <span class="nowrap">
922 <code>Apply</code>&#8197;<code>Changes</code></span> option
923 from the <code>Installation</code> menu,
924 and proceed as in <a href="#step-2-iii">
925 section <span class="smaller">2</span>, step iii</a>.
926 </p></li>
927 <li>From the MinGW CLI, execute the command:
928 <pre class="vt box-out">
929 C:\Users\me&gt; <kbd>mingw-get upgrade</kbd> &lt;<em>package-name</em>&gt;
930 </pre>
931 for each package which you wish to upgrade,
932 (which will also, implicitly, identify each additional upgradeable package
933 upon which each specified package is dependent).
934 </li></ul>
935 </div><!-- maintenance -->
936 </div><!-- h3-numbered -->
938 <!-- $RCSfile$: end of file -->