• R/O
  • HTTP
  • SSH
  • HTTPS

website: 提交

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


Commit MetaInfo

修訂68897d90276709f8b6b789e23067f6c1f062f597 (tree)
時間2021-12-15 21:57:50
作者Keith Marshall <keith@user...>
CommiterKeith Marshall

Log Message

Publish MinGW installation and maintenance guidelines.

* setup.html: New file.

Change Summary

差異

--- /dev/null
+++ b/setup.html
@@ -0,0 +1,938 @@
1+<!DOCTYPE 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+ *
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
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; }
56+
57+span.smaller { font-size: 0.9em; }
58+pre.vt em::after { content: "&nbsp;"; font-size: 0.4pt; }
59+
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; }
70+
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; }
76+
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 -->
91+
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>
151+
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 -->
338+
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 -->
508+
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
556+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
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 -->
814+
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 -->
937+
938+<!-- $RCSfile$: end of file -->
Show on old repository browser