5 * A guide to managed MinGW installation, for new users.
10 --><meta author="Julien Lecomte" /><!--
11 * Copyright (C) 2007, 2021, MinGW.org Project
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:
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.
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.
28 * THIS DOCUMENTATION IS PROVIDED BY THE MINGW.ORG PROJECT "AS IS" AND
29 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
30 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
31 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MINGW.ORG PROJECT, OR
32 * ITS CONTRIBUTORS, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38 * OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
42 * Note: this page assumes browser support for the following numeric
45 * ‑ non-breaking hyphen
46 * ‘ typographic left (opening) single quote
47 * ’ typographic apostrophe/right (closing) single quote
48 * “ typographic left (opening) double quote
49 * ” typographic right (closing) double quote
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: " "; 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 ); }
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.
86 set_page("title", "Getting Started with MinGW");
88 "HOWTO Set Up the MinGW Compiler Suite — a Guide for New Users"
90 </script><!-- masthead -->
92 <p>This HOWTO document provides instructions,
93 and recommendations, both for first‑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>  users,
98 regardless of experience,
99 or level of expertise.
101 <p><strong><em>Caution</em></strong> :
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>  that you
105 <strong><em>do not install MinGW in any location
106 with spaces in the absolute path name</em></strong> ;
107 you should avoid installing into any directory or subdirectory
108 having names like <code>"Program</code> <code>Files"</code>
109 or <code>"My</code> <code>Documents"</code>, etc.
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>
115 <p>The preferred installation method is using
116 the <code>mingw-get</code> “Installation Manager” 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‑Windows,
121 which is unable to run the GUI variant of <code>mingw‑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>.
127 <p>After installation,
128 you may need to perform some additional system configuration tasks yourself,
129 to ensure your MinGW applications will run.
131 you may need to set up <code>Start</code> <code>Menu</code>,
132 or <code>Desktop</code> “short‑cuts”,
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‑installation section</a>,
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‑to‑date;
147 suitable maintenance procedures are discussed in
148 <a href="#maintenance">the final section</a>
152 <div class="h3-numbered">
153 <div class="overlapped" id="start-here">
154 <h3>Setting Up the MinGW Installation Manager for First‑Time Use</h3>
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‑get‑setup.exe</code> tool</a>.
164 <p>If you have previously installed <code>mingw‑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‑get‑setup.exe</code> again;
168 you <em>should</em> simply run <code>mingw‑get.exe</code>, and
169 <a href="#install-packages">proceed directly to the next installation phase</a>.
171 <p>If do wish to run <code>mingw‑get‑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‑get‑setup.exe</code>,
180 so please download a replacement copy,
181 if yours is out of date.
183 <p>When you <em>do</em> choose to run
184 <code>mingw‑get‑setup.exe</code>,
185 you should follow this sequence of steps:–
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 — Opening Dialogue"
191 Depending on your MS‑Windows version,
192 and its system security policy configuration,
193 you may be able to invoke <code>mingw‑get‑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‑system explorer,
199 and double‑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‑get‑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 “blurb”,
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> <code>Licence</code> button.
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.
220 </div><!-- ol.setup-steps desc -->
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 — Preferences Dialogue"
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‑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:–
242 <ul><li>Your system policy forbids installation into a directory
243 at this level within the file‑system hierarchy,
244 and you are unable to obtain authorization for an exception
247 <li>You require an alternative installation root directory,
248 for the purpose of creating <em>side‑by‑side</em>
249 MinGW sandbox installations.
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‑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‑space into
257 its absolute path name.
259 <p>Other installation options, which you may select via this dialogue,
262 <ul><li>Installation of the <code>mingw‑get</code> GUI application,
263 in addition to the CLI version, (which is <em>always</em> installed).
265 <li>Installation of Windows “shortcuts”,
266 either on the desktop,
267 or in the Windows <code>Start</code> <code>Menu</code>, (or both),
268 for either the current user only (<em>strongly</em> recommended),
270 (if installed, these will launch the <code>mingw‑get</code>
271 GUI client, and thus are effective only if that is installed).
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 — the actual installation
277 of <code>mingw‑get</code>.
279 </div><!-- ol.setup-steps desc -->
281 <li><img src="https://static-cdn.osdn.net/thumb/g/5/215/800x600_0.png"
282 alt="Installer Setup — Download Dialogue"
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‑get</code>
289 are downloaded from the MinGW.org on‑line file store,
290 and installed locally, into your designated installation directory tree.
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.
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‑get‑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‑get‑setup.exe</code> again.
309 <p>When the download and installation of <code>mingw‑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:–
314 <ul><li>Click the <code>Continue</code> button,
315 to terminate <code>mingw‑get‑setup.exe</code>,
316 and <em>immediately</em> start <code>mingw‑get</code> in GUI mode;
317 (note that the <code>mingw‑get</code> GUI is available at this point,
318 at least temporarily, even if you chose not to install it permanently).
320 <li>Click the <code>Quit</code> button,
321 to terminate <code>mingw‑get‑setup.exe</code>
322 <em>without</em> starting <code>mingw‑get</code>;
323 (you may resume installation of MinGW later,
324 by running stand‑alone <code>mingw‑get</code>,
326 or — if you chose to install it as a permanent capability —
329 <p>Regardless of which of the preceding options you choose,
330 <code>mingw‑get‑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‑get</code>,
333 <em>not</em>  <code>mingw‑get‑setup.exe</code>.
335 </div><!-- ol.setup-steps desc -->
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‑get</strong></code>,
344 (which is also known,
345 particularly in its GUI guise,
346 as the “MinGW Installation Manager”),
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‑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‑standing application,
353 or by continuation from within <code>mingw‑get‑setup.exe</code>,
354 you will be presented with a three‑paned window display,
355 whence you may proceed as follows:–
357 <ol class="setup-steps">
358 <li><img src="https://static-cdn.osdn.net/thumb/g/7/709/800x600_0.png"
359 alt="Installer — Basic Package View"
361 When <code>mingw‑get</code> is invoked as a continuation
362 of <code>mingw‑get‑setup.exe</code>,
363 the initial three‑paned view will appear as on the right;
365 this view may be accessed by selecting
366 the <code>Basic</code> <code>Setup</code>
367 option in the left‑hand window pane,
369 regardless of whether <code>mingw‑get</code> is running
370 as a continuation of <code>mingw‑get‑setup.exe</code>,
371 or as a free‑standing application).
373 you will see a list (in the upper right‑hand pane) of those packages
374 which are likely to be of most interest to first‑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‑hand pane,
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‑time users,
384 we recommend that you elect to install,
386 the <code>mingw32‑base‑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‑g++‑bin</code> package.
392 </div><!-- ol.setup-steps desc -->
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 — All Package View"
399 when the GUI variant of <code>mingw‑get</code> is invoked
400 as a free‑standing application,
401 the initial three‑paned view will appear as on the right;
403 this view may be accessed by selecting the
404 <span class="nowrap"><code>All</code> <code>Packages</code></span> option,
405 in the left‑hand pane,
406 regardless of how <code>mingw‑get</code> has been started).
407 <p>You may observe that,
408 in comparison with the
409 <span class="nowrap"><code>Basic</code> <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.
421 <p>As with selection of packages from the
422 <span class="nowrap"><code>Basic</code> <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> <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,
428 and choosing the <span class="nowrap">
429 <code>Mark</code> <code>for</code> <code>Installation</code></span>
430 option from the associated context menu.
432 </div><!-- ol.setup-steps desc -->
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 — Apply Changes View"
438 Once you have made a selection of packages to be installed,
440 <span class="nowrap"><code>Basic</code> <code>Setup</code></span> view,
442 <span class="nowrap"><code>All</code> <code>Packages</code></span> view,
444 you must commit this selection,
445 to complete your installation,
446 by proceeding as follows:–
448 <li>Open the <code>Installation</code> menu,
451 <span class="nowrap"><code>Apply</code> <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>  of:–
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>  wish to commit <em>any</em> 
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>
477 </div><!-- ol.setup-steps desc -->
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‑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 “MinGW Installation Manager”</span> GUI window.
489 if you have just completed a first‑time installation,
490 you may need to perform some post‑installation system configuration,
491 as described in the following section,
492 to make your installation work.
493 <p style="display: none">
495 if you plan to use the MSYS command line interpreter system,
496 your MinGW installation should be ready to use;
498 if you choose to use MinGW from Microsoft’s
499 <span class="nowrap">“command prompt”</span>
501 then you may need to complete the
502 <a href="#post-install">MinGW post‑installation steps</a>
503 as <a href="#post-install">described below</a>.
505 </div><!-- ol.setup-steps desc -->
507 </div><!-- install-packages -->
509 <div style="clear: both"></div>
510 <div class="overlapped" id="post-install">
511 <h3>Post‑Installation Requirements for Use of the MinGW Compiler Suite</h3>
513 the process of installation alone
514 is likely to be insufficient to acquire a working MinGW system:
515 some additional one‑time system configuration is usually required.
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>  choice of infrastructure,
524 for provision of a suitable CLI,
527 which you may wish to consider,
530 <ol class="config-options">
531 <li>Run the MinGW tools <em>directly</em>, 
532 using Microsoft’s <code>cmd.exe</code> interpreter,
533 within the MS‑Windows default <span class="nowrap">
534 “<code>Command</code> <code>Prompt</code>”
535 </span> console host.
536 If you choose this option,
537 (which may <em>not</em>  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:–
545 <li>Open a <code>Command</code> <code>Prompt</code> console,
547 <pre class="vt box-out">
548 C:\Users\me> <kbd>gcc --version</kbd>
550 If this results in output similar to:
551 <pre class="vt box-out">
552 C:\Users\me> <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
556 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
558 then it appears that your process <code>PATH</code> setting
559 <em>is already</em>  suitably configured,
560 and <em>no further</em>  configuration is needed;
561 however, if the output resembles:
562 <pre class="vt box-out">
563 C:\Users\me> <kbd>gcc --version</kbd>
564 'gcc' is not recognized as an internal or external command,
565 operable program or batch file.
567 this, then the <code>PATH</code> setting in the process environment
568 <em>is not</em>  suitably configured;
569 you <em>should</em>  modify the environment configuration,
573 a number of MinGW applications — any comtemporary
574 version of the GNU Debugger being a notable example — may
575 require a definition of the <code>HOME</code> environment variable.
577 <code>Unix</code> systems define this,
578 to represent the path name of the current user’s
579 default working directory,
580 but MS‑Windows uses the <code>USERPROFILE</code> variable
582 so <code>HOME</code> is not normally defined.
584 <p>To check whether the <code>HOME</code> variable is defined,
587 <ul><li>Run the command:
588 <pre class="vt box-out">
589 C:\Users\me> <kbd>echo %HOME%</kbd>
591 in a <code>Command</code> <code>Prompt</code> console window;
592 if <code>HOME</code> has been suitably configured,
593 this should produce output similar to:
594 <pre class="vt box-out">
595 C:\Users\me> <kbd>echo %HOME%</kbd>
598 but it is more likely to produce no output at all,
599 in which case you should consider adding a <code>HOME</code> variable
600 definition to your environment variables configuration.
602 <p>If the preceding checks indicate that
603 the <code>PATH</code> configuration needs to be adjusted,
604 or that the <code>HOME</code> variable has not been defined,
605 then you should proceed as follows:–
607 <li>From the system <span class="nowrap">
608 <code>Control</code> <code>Panel</code></span>,
609 open the <code>System</code> tab,
610 access the <span class="nowrap">
611 <code>Advanced</code> <code>system</code> <code>settings</code>
613 and click the <span class="nowrap">
614 <code>Environment</code> <code>Variables</code></span> button.
617 which should now have become active,
618 observe that there are two categories of environment variables,
619 viz. a category for user‑specific variables,
620 and another for system (global) variables.
621 Please note that any environment variables,
622 which you either add, or modify, in either of these categories,
623 will be recorded in the system registry,
624 and will become visible to <em>all</em>  processes
625 which are subsequently invoked on the system,
626 (although visibility of those in the user‑specific category
627 will be restricted to processes owned by the currently‑logged‑in
628 user), and that changes to the <code>PATH</code> variable have potential
629 to introduce system security vulnerabilities;
630 thus, you should exercise caution,
631 when making such changes, and,
632 unless it is your intention that your changes should affect
633 <em>all users</em>  of the system,
634 you should prefer to make the change <em>only</em> 
635 in the user‑specific category,
636 in order to limit the potential of any vulnerability.
638 <li>Note that <code>mingw‑get</code> will have installed
639 MinGW applications into <code>C:\MinGW\bin</code>,
640 (with substitution of any alternative installation‑root path name,
641 which you may have chosen at installation time,
642 for the <code>C:\MinGW</code> prefix);
643 it is this equivalent for the <code>C:\MinGW\bin</code> path name,
644 (with prefix substitution as may be appropriate),
645 which you must now incorporate into the <code>PATH</code> variable,
646 to be passed in the environment,
647 to your <span class="nowrap">
648 <code>Command</code> <code>Prompt</code></span> process.
650 <li>Within the environment variables category
651 in which you have decided to adjust the <code>PATH</code> setting,
652 identify the entry (matching the variable name
653 <em>case‑insensitively</em> ),
654 if it exists, for the <code>PATH</code> variable definition.
656 <li>If the <code>PATH</code> variable definition <em>does</em> 
657 already exist, select it, and click the <code>Edit</code> button;
658 move the input cursor to the <em>end</em>  of the
659 <code>Value</code> field,
660 and append a semicolon (“<code>;</code>”),
661 followed by your equivalent for <code>C:\MinGW\bin</code>,
662 with prefix substitution as required.
664 <li>Conversely, if no such <code>PATH</code> variable exists,
665 click the <code>New</code> button, and create a new entry for it;
666 assign your equivalent for <code>C:\MinGW\bin</code>,
667 with prefix substitution as required,
670 <li>Similarly, to add a definition for the <code>HOME</code> variable,
671 click the <code>New</code> button, and create the requisite entry;
672 it should be given a suitable value, which typically, could be to
673 inherit the value of the <code>USERPROFILE</code> variable.
675 <li>Click the <code>OK</code> button on each nested dialogue box,
676 as you walk focus back to the top level of the <span class="nowrap">
677 <code>Control</code> <code>Panel</code></span>,
678 so saving your environment variable changes,
679 then dismiss the <span class="nowrap">
680 <code>Control</code> <code>Panel</code></span> itself.
682 <p>After you have completed the above system configuration steps,
683 you may open a standard MS‑Windows <span class="nowrap">
684 <code>Command</code> <code>Prompt</code></span> console session,
685 and you <em>should</em>  find that your MinGW tools will work,
688 <li>As a (possibly better) alternative to option
689 <span class="smaller">1</span>,
690 you may still choose to run the MinGW tools directly from
691 Microsoft’s <code>cmd.exe</code> command line interpreter,
692 but with this interpreter hosted within a console session which has
693 been started from a customized “shortcut”,
694 which itself addresses the issue of adding the equivalent of
695 <code>C:\MinGW\bin</code> to the <code>PATH</code>
696 environment variable setting;
697 this ensures that the modified <code>PATH</code> setting is visible
698 <em>only</em>  to processes which are invoked from within
699 the hosting console session itself, and thus
700 <em>significantly</em>  reduces any associated potential
701 for exposure to system security vulnerability exploits.
702 <p>To implement this <code>PATH</code> configuration technique:–
704 <li>Create a new “shortcut”,
705 ideally within the <code>MinGW</code> subdirectory
706 (folder) of your user‑specific
707 <span class="nowrap"><code>Start</code> <code>Menu</code></span>,
708 (or, if preferred, in the <code>MinGW</code> subdirectory of the
709 <span class="nowrap"><code>All</code> <code>Users</code></span>
710 <span class="nowrap"><code>Start</code> <code>Menu</code></span>,
711 noting that you may need to create the respective <span class="nowrap">
712 <code>"Start</code> <code>Menu\MinGW"</code></span> subdirectory,
713 if it does not already exist);
714 you should name this new “shortcut” as
715 <span class="nowrap"><code>"MinGW</code> <code>Prompt.lnk"</code>,</span>
716 <span class="nowrap"><code>"MinGW</code> <code>Console.lnk"</code>,</span>
717 or any similar alternative name of your own choice.
718 <li>Set the <code>Target</code> of your new “shortcut” to:
719 <pre class="vt box-out">
720 <kbd>%comspec% /c path %PATH%;C:\MinGW\bin&set HOME=%USERPROFILE%&%comspec%</kbd>
722 (with substitution for <code>C:\MinGW</code>, as appropriate,
723 if you chose an alternative prefix at installation time).
724 Alternatively, create a new MS‑Windows batch file,
725 (called <span class="nowrap"><code>C:\MinGW\mingw.bat</code>,</span>
726 for example), with content similar to:
727 <pre class="vt box-out">
728 <kbd>set HOME=%USERPROFILE%</kbd>
729 <kbd>path %PATH%;C:\MinGW\bin</kbd>
732 and set the “shortcut” <code>Target</code> to:
733 <pre class="vt box-out">
734 <kbd>%comspec% /c C:\MinGW\mingw.bat</kbd>
736 (This latter alternative offers greater flexibility than the former,
737 insofar as the batch file may be modified to accommodate configuration
738 options beyond the minimally required <code>PATH</code> augmentation,
739 and the recommended <code>HOME</code> variable assignment).
741 <li>Access the properties of the new “shortcut”,
742 and set the start‑up directory path name, within the
743 <span class="nowrap"><code>Start</code> <code>in</code></span>
744 field, to select any appropriate directory of your choice;
745 if you wish to reproduce the behaviour of the standard MS‑Windows
746 <span class="nowrap"><code>Command</code> <code>Prompt</code>,</span>
747 the appropriate assignment is:
748 <pre class="vt box-out">
749 <kbd>%HOMEDRIVE%%HOMEPATH%</kbd>
752 you may wish to take the opportunity to tweak “shortcut”
753 properties on the <code>Font</code>, <code>Layout</code>,
754 and <code>Colors</code> tabs.
756 <li>If you chose to install MSYS,
757 and you would like to use it as your working MinGW development environment,
758 in preference to the rather more limited capabilities of the MS‑Windows
759 <span class="nowrap"><code>Command</code> <code>Prompt</code>,</span>
760 then some associated configuration checks are recommended:–
763 you may need to create a “shortcut”,
764 ideally within your user‑specific
765 <span class="nowrap"><code>Start</code> <code>Menu</code>,</span>
767 <span class="nowrap"><code>All</code> <code>Users</code>,</span>
768 <span class="nowrap"><code>Start</code> <code>Menu</code>;</span>
769 the recommended name for this “shortcut” is
770 <span class="nowrap"><code>MinGW</code> <code>Shell</code>,</span>
771 and its <code>Target</code> should be set to invoke:
772 <pre class="vt box-out">
773 <kbd>C:\MinGW\MSYS\1.0\msys.bat</kbd>
775 (with the path name adjusted, as may be required,
776 to represent the actual installed location of <code>msys.bat</code>).
779 your MSYS installation <em>must</em>  be given an appropriate
780 hint to the base location of your MinGW tools.
781 This is established by means of a “mount point”
782 specification, within the <span class="nowrap">
783 <code>C:\MinGW\MSYS\1.0\etc\fstab</code></span> file,
784 (again, with the <span class="nowrap"><code>C:\MinGW\MSYS\1.0</code></span>
785 path name adjusted to match the prefix,
786 in the actual location of the <code>msys.bat</code> file);
787 if this file does not exist, you should create it,
788 but in any case, you <em>must</em>  ensure that it
789 includes (at least) a line of the form:
790 <pre class="vt box-out">
791 <kbd>C:/MinGW /mingw</kbd>
793 (again noting that the <code>C:/MinGW</code> prefix should be adjusted
794 to match any alternative, which you may have chosen at installation time,
795 and furthermore, “<code>/</code>” characters should be used
796 as directory name separators, in preference to “<code>\</code>”
797 characters, within the <code>etc/fstab</code> file).
799 <p>You may be wondering why these post‑installation instructions,
800 for MSYS, do not refer to <code>PATH</code> configuration.
801 In practice, no specific configuration is necessary, because,
802 provided the <code>/mingw</code> “mount‑point”
803 is correctly specified in the <code>fstab</code> file,
804 MSYS will correctly deduce the required <code>PATH</code> setting,
805 when any shell session is started.
806 However, it <em>is</em>  important to note that it is
807 <em>imperative</em>  that <em>no white‑space</em> 
808 is present, within the absolute path name specification for the
809 “mount‑point”;
810 thus, since this <em>must</em>  be specified as
811 an <em>absolute</em>  path name, if,
812 contrary to offered advice,
813 you have chosen an installation directory with white‑space
814 in its absolute path name,
815 you will need to determine the short (8.3) form of your
816 installation path name,
817 and use that in the “mount‑point” specification.
819 <li>Regardless of whether you choose to run the MinGW tools
820 within an MSYS session, or within a <code>cmd.exe</code> session, by default,
821 either of these will run within an MS‑Windows console host
823 If you prefer, you may choose an alternative container, such as
824 <a target="_blank" rel="noopener noreferrer" href="https://conemu.github.io">
826 <a target="_blank" rel="noopener noreferrer" href="https://github.com/bozho/console">
828 <a target="_blank" rel="noopener noreferrer" href="https://github.com/cbucher/console">
830 While it should be feasible to use any of these,
831 each will have its own configuration considerations,
832 which are beyond the scope of this HOWTO document.
835 you may decide that you would prefer to deploy MinGW within an IDE.
836 Please be aware that MinGW.OSDN offers no formal support for any such
837 deployment; however, users have reported success with
838 <a target="_blank" rel="noopener noreferrer" href="https://www.codeblocks.org">
839 Code::Blocks</a>, and with
840 <a target="_blank" rel="noopener noreferrer" href="https://www.eclipse.org">
842 (but be advised that these third‑party websites may
843 may exhibit out‑of‑date references to MinGW download sites;
844 the most up‑to‑date downloads of MinGW are <em>always</em> 
845 available from <a target="_blank" rel="noopener noreferrer"
846 href="https://osdn.net/projects/mingw/">OSDN.net</a>).
847 As with option <span class="smaller">4</span>,
848 each of these IDEs will be subject to its own configuration considerations,
849 which, once again, are beyond the scope of this HOWTO document.
851 </div><!-- post-install -->
853 <div style="clear: both"></div>
854 <div class="overlapped" id="maintenance">
855 <h3>Maintaining Currency of your MinGW Installation</h3>
856 <p>After you have installed your initial choice of MinGW,
857 and/or MSYS packages,
858 you will eventually discover that you need to perform some degree
859 of maintenance of your installation;
860 this need may be prompted by:–
862 <li>A desire to install additional packages,
863 which you had not chosen to include within your original installation.
865 <li>Availability of newer releases of those packages,
866 which you have previously installed;
867 you will wish to upgrade your existing installation,
868 to take advantage of any such newer package releases.
871 <p>Regardless of your motivation
872 for performing maintenance on your MinGW installation,
873 it is recommended that you use <code>mingw‑get</code>,
874 either in its GUI, or in its CLI mode of operation,
875 to achieve your objective.
877 <p>Whether your intention is to install a new package,
878 or simply to upgrade an installed package to a newer release,
879 you should ensure that the package information records, within
880 your locally installed copy of <code>mingw‑get</code>,
881 are kept up‑to‑date with respect to the state of
882 the online package repositories.
884 you are advised to periodically,
885 (say, if it has been more than a week since your update),
886 request an update of your local copy of the package catalogue,
887 <em>before</em>  you embark on any package installation,
888 or package upgrade activity.
889 You may accomplish this, either:–
891 <li>From the <code>mingw‑get</code> GUI,
892 by selecting the <span class="nowrap">
893 <code>Update</code> <code>Catalogue</code></span> option
894 from the <code>Installation</code> menu.
895 <li>From the MinGW CLI, simply by running the command:
896 <pre class="vt box-out">
897 C:\Users\me> <kbd>mingw-get update</kbd>
900 <p>After updating your package catalogue,
901 to synchronize with the online package repository state,
902 you may install further packages:–
904 <li>From the <code>mingw‑get</code> GUI,
905 by following the procedure described in <a href="#install-packages">
906 section <span class="smaller">2</span>, above</a>.
908 <li>From the MinGW CLI, by running the command:
909 <pre class="vt box-out">
910 C:\Users\me> <kbd>mingw-get install</kbd> <<em>package-name</em>>
913 <p>When a new version of any package,
914 which you have already installed, is released,
915 you will want to upgrade your installation,
916 to incorporate the package changes.
917 Once again, you can perform the upgrade from either
918 the <code>mingw‑get</code> GUI,
920 the simplest procedure,
921 which will upgrade <em>all</em>  installed packages,
922 for which new releases are available,
923 <em>en masse</em>,  is–
925 <li>From the <code>Installation</code> menu of
926 the <code>mingw‑get</code> GUI,
927 select the <span class="nowrap">
928 <code>Mark</code> <code>All</code> <code>Upgrades</code>
929 </span> option, followed by the <span class="nowrap">
930 <code>Apply</code> <code>Changes</code>,</span>
931 then review, and commit the changes,
932 following the procedure described in
933 <a href="#step-2-iii">section <span class="smaller">2</span>, step iii</a>,
936 <li>From the MinGW CLI, execute the command:
937 <pre class="vt box-out">
938 C:\Users\me> <kbd>mingw-get upgrade</kbd>
940 (without <em>any</em>  <span class="nowrap">
941 <code><<em>package-name</em>></code></span> argument);
942 this CLI method performs <em>identically</em>  the same
943 <em>en masse</em>‑ upgrade as the GUI method, <em>except</em> 
944 that it offers <em>no opportunity</em>  for review of the scheduled
945 changes, prior to <em>unconditionally</em>  committing them.
948 you may choose to perform a <em>selective</em>  upgrade
949 of individual packages:–
951 <li>In the <code>mingw‑get</code> GUI,
952 by selecting the <span class="nowrap">
953 <code>Mark</code> <code>for</code> <code>Upgrade</code>
954 </span> option, in the context menu which is attached to the status icon
955 to the left of the package list entry for each package of interest;
956 (those packages, for which upgrades are available, are identified
957 by a yellow star, in the upper right corner of the status icon).
958 <p>After selecting packages to upgrade,
959 once again select the <span class="nowrap">
960 <code>Apply</code> <code>Changes</code></span> option
961 from the <code>Installation</code> menu,
962 and proceed as in <a href="#step-2-iii">
963 section <span class="smaller">2</span>, step iii</a>.
965 <li>From the MinGW CLI, execute the command:
966 <pre class="vt box-out">
967 C:\Users\me> <kbd>mingw-get upgrade</kbd> <<em>package-name</em>>
969 for each package which you wish to upgrade,
970 (which will also, implicitly, identify each additional upgradeable package
971 upon which each specified package is dependent).
973 </div><!-- maintenance -->
974 </div><!-- h3-numbered -->
976 <!-- $RCSfile$: end of file -->
OSDN Git Service
