From: Keith Marshall Date: Wed, 15 Dec 2021 12:57:50 +0000 (+0000) Subject: Publish MinGW installation and maintenance guidelines. X-Git-Url: http://git.osdn.net/view?p=mingw%2Fwebsite.git;a=commitdiff_plain;h=68897d90276709f8b6b789e23067f6c1f062f597;ds=sidebyside Publish MinGW installation and maintenance guidelines. * setup.html: New file. --- diff --git a/setup.html b/setup.html new file mode 100644 index 0000000..9b7fb8f --- /dev/null +++ b/setup.html @@ -0,0 +1,938 @@ + + + + +

This HOWTO document provides instructions, +and recommendations, both for first‑time installation, +and subsequent maintenance of the MinGW (GCC) compiler suite, +and ancillary MinGW applications and/or tools; +the recommended method of installation is suitable +for all  users, +regardless of experience, +or level of expertise. +

+

Caution : +MinGW may have problems with paths containing spaces, and if not, +other programs used with MinGW may often experience problems with such paths. +Thus, we strongly recommend  that you +do not install MinGW in any location +with spaces in the absolute path name ; +you should avoid installing into any directory or subdirectory +having names like "Program Files" +or "My Documents", etc. +

+

The preferred installation target directory, +its path name having been chosen to comply with the preceding recommendation, +is C:\MinGW +

+

The preferred installation method is using +the mingw-get “Installation Manager” tool, +as described below. +While a manual installation is possible, +we recommend it only for expert users, +unless you have a very old version of MS‑Windows, +which is unable to run the GUI variant of mingw‑get. +If you really want (or need) to resort to it, +instructions for manual installation are provided in +this alternative HOWTO document. +

+

After installation, +you may need to perform some additional system configuration tasks yourself, +to ensure your MinGW applications will run. +Most importantly, +you may need to set up Start Menu, +or Desktop “short‑cuts”, +to launch a suitable command line interpreter session, +with appropriate environment variable settings, +(notably, the PATH setting), +for running MinGW applications; +further details may be found in the +post‑installation section, +below. +

+

Ultimately, +having completed installation and configuration, +you will wish to perform occasional maintenance tasks, +perhaps to install additional packages, +and certainly to install software updates, +and so keep your installation up‑to‑date; +suitable maintenance procedures are discussed in +the final section +of this document. +

+ +
+
+

Setting Up the MinGW Installation Manager for First‑Time Use

+

The first step, +in the recommended procedure for creating a new MinGW installation, +is to install the mingw-get installer itself; +this can be most readily accomplished by downloading, +and subsequently running, +the GUI mingw‑get‑setup.exe tool. +

+

If you have previously installed mingw‑get, +and your objective is to upgrade, or to extend, +its associated (existing) MinGW installation, +then you should not run mingw‑get‑setup.exe again; +you should simply run mingw‑get.exe, and +proceed directly to the next installation phase. +

+

If do wish to run mingw‑get‑setup.exe, +and you already have a local copy, +we strongly recommend that you check its publication date, +to ensure that it is no older than the current release, +as identified at https://osdn.net/projects/mingw; +you should always run the most recent release of +mingw‑get‑setup.exe, +so please download a replacement copy, +if yours is out of date. +

+

When you do choose to run +mingw‑get‑setup.exe, +you should follow this sequence of steps:– +

+
    +
  1. Installer Setup — Opening Dialogue
    +Depending on your MS‑Windows version, +and its system security policy configuration, +you may be able to invoke mingw‑get‑setup.exe +directly from the download link specified above; +alternatively, you may need to save a local copy, +locate it in the file‑system explorer, +and double‑click to invoke it. +In either case, and again depending on Windows version, +and security policy configuration, +you may need to authorize execution of +mingw‑get‑setup.exe, +and the changes it will make to your system, +after which you should see a dialogue similar +to that depicted to the right. +

    When you see this dialogue, +we advise you to acquaint yourself with the content +of the warranty disclaimer, and additional “blurb”, +which appears below the copyright notice; +you may also wish to review the licensing terms, +which will be displayed in a web browser window, +if you click the View Licence button. +

    +

    When you are ready to proceed, +click the Install button to move on to the next step; +alternatively, you may click the Cancel button +to abandon the installation process. +

    +
    +
    2. +
    +
  2. Installer Setup — Preferences Dialogue
    +On progressing from the opening dialogue, +by clicking on the Install button +as stipulated in the preceding step, +you will be presented with a new dialogue, +as depicted to the right. +Here, you have the opportunity to select from +a set of optional configuration attributes for +your mingw‑get installation, +and for the associated MinGW installation, +which you will use it to manage. +

    You may observe, when this dialogue is opened, +that the installation directory is specified, by default, +to be C:\MinGW. +We strongly recommend that you leave this +at its default setting, +except in the particular cases where:– +

    • Your system policy forbids installation into a directory +at this level within the file‑system hierarchy, +and you are unable to obtain authorization for an exception +to such a policy. +
      • +
    • You require an alternative installation root directory, +for the purpose of creating side‑by‑side +MinGW sandbox installations. +
    +

    If you do choose to change the installation directory, +you may click the Change button to open +a standard file‑system navigation dialogue, +whence you may select, or create, an alternative directory; +do please heed the warning about avoiding any +directory name, which introduces white‑space into +its absolute path name. +

    +

    Other installation options, which you may select via this dialogue, +include:– +

    +
    • Installation of the mingw‑get GUI application, +in addition to the CLI version, (which is always installed). +
      • +
    • Installation of Windows “shortcuts”, +either on the desktop, +or in the Windows Start Menu, (or both), +for either the current user only (strongly recommended), +or for all users; +(if installed, these will launch the mingw‑get +GUI client, and thus are effective only if that is installed). +
    +

    Once you have specified your choice of installation root directory, +and completed your selection of installation options, +you may click the Continue button, +to proceed to the next step — the actual installation +of mingw‑get. +

    +
    +
    3. +
  3. Installer Setup — Download Dialogue
    +Your computer must remain actively connected to the internet, +throughout this step, which should proceed without user intervention. +

    While the process proceeds, you should observe a dialogue similar to +that depicted to the right; the data displayed will be dynamically +updated, as the constituent packages of mingw‑get +are downloaded from the MinGW.org on‑line file store, +and installed locally, into your designated installation directory tree. +

    +

    You may observe that, +while download and installation are in progress, +the Continue and Quit +buttons are disabled; +they will be enabled, only when the process completes. +

    +

    If errors occur, during the download and installation process, +only the Quit button will be enabled, +allowing you to terminate mingw‑get‑setup.exe; +please consult the FAQ, or seek advice via the mailing list, +for assistance to troubleshoot, and resolve the errors, +before running mingw‑get‑setup.exe again. +

    +

    When the download and installation of mingw‑get +completes successfully, both the Continue, +and the Quit buttons will be enabled. +At this point, you may choose to:– +

    +
    • Click the Continue button, +to terminate mingw‑get‑setup.exe, +and immediately start mingw‑get in GUI mode; +(note that the mingw‑get GUI is available at this point, +at least temporarily, even if you chose not to install it permanently). +
      • +
    • Click the Quit button, +to terminate mingw‑get‑setup.exe +without starting mingw‑get; +(you may resume installation of MinGW later, +by running stand‑alone mingw‑get, +either in CLI mode, +or — if you chose to install it as a permanent capability — +in GUI mode). +
    +

    Regardless of which of the preceding options you choose, +mingw‑get‑setup.exe has completed its task; +when you proceed to the next stage of the installation process, +you will be running mingw‑get, +not  mingw‑get‑setup.exe. +

    +
    +
+
+ +
+
+

Using the MinGW Installation Manager to Install Packages

+

Once you have completed the installation of +mingw‑get, +(which is also known, +particularly in its GUI guise, +as the “MinGW Installation Manager”), +you may use it to proceed with the installation of your choice of packages, +to complete (or subsequently extend) your MinGW installation. +Assuming that you have started the GUI variant of mingw‑get, +either (having chosen to install it +at step ii of the set up procedure) +as a free‑standing application, +or by continuation from within mingw‑get‑setup.exe, +you will be presented with a three‑paned window display, +whence you may proceed as follows:– +

+
    +
  1. Installer — Basic Package View
    +When mingw‑get is invoked as a continuation +of mingw‑get‑setup.exe, +the initial three‑paned view will appear as on the right; +(alternatively, +this view may be accessed by selecting +the Basic Setup +option in the left‑hand window pane, +at any time, +regardless of whether mingw‑get is running +as a continuation of mingw‑get‑setup.exe, +or as a free‑standing application). +

    Within this view, +you will see a list (in the upper right‑hand pane) of those packages +which are likely to be of most interest to first‑time MinGW users; +you may select any one of these packages, +to see related package information on the tabs of +the lower right‑hand pane, +and, +by clicking on the small square button, +to the left of any selected package entry, +you may choose (from its context menu) to mark one (or more) packages, +which you would like to install ... +for first‑time users, +we recommend that you elect to install, +at least, +the mingw32‑base‑bin package, +(which comprises the C compiler and essential ancillary tools); +if you require a C++ compiler, +in addition to the C compiler, +you should also elect to install +the mingw32‑g++‑bin package. +

    +
    2. +
    +
  2. Installer — All Package View
    +Conversely, +when the GUI variant of mingw‑get is invoked +as a free‑standing application, +the initial three‑paned view will appear as on the right; +(alternatively, +this view may be accessed by selecting the +All Packages option, +in the left‑hand pane, +regardless of how mingw‑get has been started). +

    You may observe that, +in comparison with the +Basic Setup view, +this view offers a selection of many more packages, +from which you may choose those which you would like to install +... so many more that, +to see the entire selection, +you will need to scroll the list in the upper right window pane; +if you find this extensive package list to be too confusing, +you may refine the visible selection by clicking on +any of the subsidiary package categories, +as shown in the package category tree view, +in the left hand pane. +

    +

    As with selection of packages from the +Basic Setup view, +you may elect to install any packages which are visible in the +All Packages view, +making your selection by clicking on the small square button, +to the left of the name of each chosen package, +in turn, +and choosing the +Mark for Installation +option from the associated context menu. +

    +
    +
    3. +
    +
  3. Installer — Apply Changes View
    +Once you have made a selection of packages to be installed, +from either the +Basic Setup view, +or the +All Packages view, +as described above, +you must commit this selection, +to complete your installation, +by proceeding as follows:– +
      +
    1. Open the Installation menu, +(on the menu bar), +and select the +Apply Changes option; +(this will open a dialogue, +similar to that shown to the right).
      2. +
    2. Review the schedule of pending installation actions, +(noting that you may need to scroll the lists of packages for which deletion, +upgrade, or installation actions have been scheduled, +for any of these lists which includes more than six package entries), +then choose one  of:– +
        +
      • Click the Apply button, +to complete all scheduled actions, +update indicated installation status, +clear the schedule of pending actions, +and return to the selection phase of installation, +to allow initiation of a further package selection.
        • +
      • Click the Defer button, +if you would like to modify your package selection; +this will take you back to the package selection phase of installation, +to allow you to make your desired changes.
        • +
      • Click the Discard button, +if you do not  wish to commit any  +of the scheduled changes; +this will clear your active package selection, +then return you to the package selection phase of installation, +whence you may start the installation process again.
        • +
    +
    +
    4. +
  4. +After you have completed your selection of packages, +and you have committed all of the changes which are needed to install them, +you may quit from mingw‑get, +either by selecting the Quit option +from the Installation menu, +or by simply closing the +“MinGW Installation Manager” GUI window. +Having done so, +and in particular, +if you have just completed a first‑time installation, +you may need to perform some post‑installation system configuration, +as described in the following section, +to make your installation work. +

    +At this point, +if you plan to use the MSYS command line interpreter system, +your MinGW installation should be ready to use; +however, +if you choose to use MinGW from Microsoft’s +“command prompt” +console subsystem, +then you may need to complete the +MinGW post‑installation steps +as described below. +

    +
    +
+
+ +
+
+

Post‑Installation Requirements for Use of the MinGW Compiler Suite

+

As noted above, +the process of installation alone +is likely to be insufficient to acquire a working MinGW system: +some additional one‑time system configuration is usually required. +

+

Although some users may choose +to use an integrated development environment (IDE), +it is important to understand that, fundamentally, +MinGW applications are intended for deployment +using a command line interface (CLI); +the scope of the necessary system configuration +is dependent on your  choice of infrastructure, +for provision of a suitable CLI, +or IDE. +Some choices, +which you may wish to consider, +include:– +

+
    +
  1. Run the MinGW tools directly,  +using Microsoft’s cmd.exe interpreter, +within the MS‑Windows default +“Command Prompt” + console host. +If you choose this option, +(which may not  be the most appropriate choice), +you will, at least, need to ensure that the MinGW tools can be found +in the cmd.exe executable search PATH, +as configured in the process environment. +The default system configuration will not normally support +this capability, without making an appropriate PATH adjustment; +to check if any such adjustment is necessary:– +
      +
    • Open a Command Prompt console, +and run the command: +
      +C:\Users\me> gcc --version
+
      +If this results in output similar to: +
      +C:\Users\me> gcc --version
+gcc (MinGW GCC Build-2) 9.2.0
+Copyright (C) 2019 Free Software Foundation, Inc.
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
      +then it appears that your process PATH setting +is already  suitably configured, +and no further  configuration is needed; +however, if the output resembles: +
      +C:\Users\me> gcc --version
+'gcc' is not recognized as an internal or external command,
+operable program or batch file.
+
      +this, then the PATH setting in the process environment +is not  suitably configured; +you should  modify the environment configuration, +as advised below. +
    +

    If the preceding check indicates that +the PATH configuration needs to be adjusted, +then you should proceed as follows:– +

      +
    • From the system +Control Panel, +open the System tab, +access the +Advanced system settings + dialogue, +and click the +Environment Variables button. +
      • +
    • In the dialogue, +which should now have become active, +observe that there are two categories of environment variables, +viz. a category for user‑specific variables, +and another for system (global) variables. +Please note that any environment variables, +which you either add, or modify, in either of these categories, +will be recorded in the system registry, +and will become visible to all  processes +which are subsequently invoked on the system, +(although visibility of those in the user‑specific category +will be restricted to processes owned by the currently‑logged‑in +user), and that changes to the PATH variable have potential +to introduce system security vulnerabilities; +thus, you should exercise caution, +when making such changes, and, +unless it is your intention that your changes should affect +all users  of the system, +you should prefer to make the change only  +in the user‑specific category, +in order to limit the potential of any vulnerability. +
      • +
    • Note that mingw‑get will have installed +MinGW applications into C:\MinGW\bin, +(with substitution of any alternative installation‑root path name, +which you may have chosen at installation time, +for the C:\MinGW prefix); +it is this equivalent for the C:\MinGW\bin path name, +(with prefix substitution as may be appropriate), +which you must now incorporate into the PATH variable, +to be passed in the environment, +to your +Command Prompt process. +
      • +
    • Within the environment variables category +in which you have decided to adjust the PATH setting, +identify the entry (matching the variable name +case‑insensitively ), +if it exists, for the PATH variable definition. +
      • +
    • If the PATH variable definition does  +already exist, select it, and click the Edit button; +move the input cursor to the end  of the +Value field, +and append a semicolon (“;”), +followed by your equivalent for C:\MinGW\bin, +with prefix substitution as required. +
      • +
    • Conversely, if no such PATH variable exists, +click the New button, and create a new entry for it; +assign your equivalent for C:\MinGW\bin, +with prefix substitution as required, +as its value. +
      • +
    • Click the OK button on each nested dialogue box, +as you walk focus back to the top level of the +Control Panel, +so saving your environment variable changes, +then dismiss the +Control Panel itself. +
    +

    After you have completed the above system configuration steps, +you may open a standard MS‑Windows +Command Prompt console session, +and you should  find that your MinGW tools will work, +without further ado. +

    2. +
  2. As a (possibly better) alternative to option +1, +you may still choose to run the MinGW tools directly from +Microsoft’s cmd.exe command line interpreter, +but with this interpreter hosted within a console session which has +been started from a customized “shortcut”, +which itself addresses the issue of adding the equivalent of +C:\MinGW\bin to the PATH +environment variable setting; +this ensures that the modified PATH setting is visible +only  to processes which are invoked from within +the hosting console session itself, and thus +significantly  reduces any associated potential +for exposure to system security vulnerability exploits. +

    To implement this PATH configuration technique:– +

      +
    • Create a new “shortcut”, +ideally within the MinGW subdirectory +(folder) of your user‑specific +Start Menu, +(or, if preferred, in the MinGW subdirectory of the +All Users +Start Menu, +noting that you may need to create the respective +"Start Menu\MinGW" subdirectory, +if it does not already exist); +you should name this new “shortcut” as +"MinGW Prompt.lnk", +"MinGW Console.lnk", +or any similar alternative name of your own choice. +
    • Set the Target of your new “shortcut” to: +
      +%comspec% /k path %PATH%;C:\MinGW\bin
+
      +(with substitution for C:\MinGW, as appropriate, +if you chose an alternative prefix at installation time). +Alternatively, create a new MS‑Windows batch file, +(called C:\MinGW\mingw.bat, +for example), within which the: +
      +path %PATH%;C:\MinGW\bin
+
      +PATH augmentation command is executed, +and set the “shortcut” Target to: +
      +%comspec% /k C:\MinGW\mingw.bat
+
      +(This latter alternative offers greater flexibility than the former, +insofar as the batch file may be modified to accommodate configuration +options beyond the minimally required PATH augmentation). +
      • +
    • Access the properties of the new “shortcut”, +and set the start‑up directory path name, within the +Start in +field, to select any appropriate directory of your choice; +if you wish to reproduce the behaviour of the standard MS‑Windows +Command Prompt, +the appropriate assignment is: +
      +%HOMEDRIVE%%HOMEPATH%
+
      +At the same time, +you may wish to take the opportunity to tweak “shortcut” +properties on the Font, Layout, +and Colors tabs. +
    3. +
  3. If you chose to install MSYS, +and you would like to use it as your working MinGW development environment, +in preference to the rather more limited capabilities of the MS‑Windows +Command Prompt, +then some associated configuration checks are recommended:– +
      +
    • Firstly, +you may need to create a “shortcut”, +ideally within your user‑specific +Start Menu, +or within the +All Users, +Start Menu; +the recommended name for this “shortcut” is +MinGW Shell, +and its Target should be set to invoke: +
      +C:\MinGW\MSYS\1.0\msys.bat
+
      +(with the path name adjusted, as may be required, +to represent the actual installed location of msys.bat). +
      • +
    • Secondly, +your MSYS installation must  be given an appropriate +hint to the base location of your MinGW tools. +This is established by means of a “mount point” +specification, within the +C:\MinGW\MSYS\1.0\etc\fstab file, +(again, with the C:\MinGW\MSYS\1.0 +path name adjusted to match the prefix, +in the actual location of the msys.bat file); +if this file does not exist, you should create it, +but in any case, you must  ensure that it +includes (at least) a line of the form: +
      +C:/MinGW	/mingw
+
      +(again noting that the C:/MinGW prefix should be adjusted +to match any alternative, which you may have chosen at installation time, +and furthermore, “/” characters should be used +as directory name separators, in preference to “\” +characters, within the etc/fstab file). +
    +

    You may be wondering why these post‑installation instructions, +for MSYS, do not refer to PATH configuration. +In practice, no specific configuration is necessary, because, +provided the /mingw “mount‑point” +is correctly specified in the fstab file, +MSYS will correctly deduce the required PATH setting, +when any shell session is started. +However, it is  important to note that it is +imperative  that no white‑space  +is present, within the absolute path name specification for the +“mount‑point”; +thus, since this must  be specified as +an absolute  path name, if, +contrary to offered advice, +you have chosen an installation directory with white‑space +in its absolute path name, +you will need to determine the short (8.3) form of your +installation path name, +and use that in the “mount‑point” specification. +

    4. +
  4. Regardless of whether you choose to run the MinGW tools +within an MSYS session, or within a cmd.exe session, by default, +either of these will run within an MS‑Windows console host +container. +If you prefer, you may choose an alternative container, such as + +ConEmu, + +Console2, or + +ConsoleZ. +While it should be feasible to use any of these, +each will have its own configuration considerations, +which are beyond the scope of this HOWTO document. +
    5. +
  5. Alternatively, +you may decide that you would prefer to deploy MinGW within an IDE. +Please be aware that MinGW.OSDN offers no formal support for any such +deployment; however, users have reported success with + +Code::Blocks, and with + +Eclipse, +(but be advised that these third‑party websites may +may exhibit out‑of‑date references to MinGW download sites; +the most up‑to‑date downloads of MinGW are always  +available from OSDN.net). +As with option 4, +each of these IDEs will be subject to its own configuration considerations, +which, once again, are beyond the scope of this HOWTO document. +
+
+ +
+
+

Maintaining Currency of your MinGW Installation

+

After you have installed your initial choice of MinGW, +and/or MSYS packages, +you will eventually discover that you need to perform some degree +of maintenance of your installation; +this need may be prompted by:– +

    +
  • A desire to install additional packages, +which you had not chosen to include within your original installation. +
    • +
  • Availability of newer releases of those packages, +which you have previously installed; +you will wish to upgrade your existing installation, +to take advantage of any such newer package releases. +
    • +
+

Regardless of your motivation +for performing maintenance on your MinGW installation, +it is recommended that you use mingw‑get, +either in its GUI, or in its CLI mode of operation, +to achieve your objective. +

+

Whether your intention is to install a new package, +or simply to upgrade an installed package to a newer release, +you should ensure that the package information records, within +your locally installed copy of mingw‑get, +are kept up‑to‑date with respect to the state of +the online package repositories. +To achieve this, +you are advised to periodically, +(say, if it has been more than a week since your update), +request an update of your local copy of the package catalogue, +before  you embark on any package installation, +or package upgrade activity. +You may accomplish this, either:– +

    +
  • From the mingw‑get GUI, +by selecting the +Update Catalogue option +from the Installation menu. +
  • From the MinGW CLI, simply by running the command: +
    +C:\Users\me> mingw-get update
+
    +
+

After updating your package catalogue, +to synchronize with the online package repository state, +you may install further packages:– +

    +
  • From the mingw‑get GUI, +by following the procedure described in +section 2, above. +
    • +
  • From the MinGW CLI, by running the command: +
    +C:\Users\me> mingw-get install <package-name>
+
    +
+

When a new version of any package, +which you have already installed, is released, +you will want to upgrade your installation, +to incorporate the package changes. +Once again, you can perform the upgrade from either +the mingw‑get GUI, +or the MinGW CLI; +the simplest procedure, +which will upgrade all  installed packages, +for which new releases are available, +en masse,  is– +

    +
  • From the Installation menu of +the mingw‑get GUI, +select the +Mark All Upgrades + option, followed by the +Apply Changes, +then review, and commit the changes, +following the procedure described in +section 2, step iii, +above. +
    • +
  • From the MinGW CLI, execute the command: +
    +C:\Users\me> mingw-get upgrade
+
    +(without any  +<package-name> argument); +this CLI method performs identically  the same +en masse‑ upgrade as the GUI method, except  +that it offers no opportunity  for review of the scheduled +changes, prior to unconditionally  committing them. +
+

Alternatively, +you may choose to perform a selective  upgrade +of individual packages:– +

    +
  • In the mingw‑get GUI, +by selecting the +Mark for Upgrade + option, in the context menu which is attached to the status icon +to the left of the package list entry for each package of interest; +(those packages, for which upgrades are available, are identified +by a yellow star, in the upper right corner of the status icon). +

    After selecting packages to upgrade, +once again select the +Apply Changes option +from the Installation menu, +and proceed as in +section 2, step iii. +

    • +
  • From the MinGW CLI, execute the command: +
    +C:\Users\me> mingw-get upgrade <package-name>
+
    +for each package which you wish to upgrade, +(which will also, implicitly, identify each additional upgradeable package +upon which each specified package is dependent). +
+
+
+ +