While I was the original maintainer of the MinGW FAQ, I picked up many tips and tricks for working with MinGW from the MinGW32 mailing list, its members, various MinGW related web sites and my own experience. Thanks go to the people who work on MinGW, MinGW32 mailing list members and the site developers who maintain MinGW related web sites. Special thanks go to Franco Bez for some of his source code examples on how to create a dll and other suggestions he made for the original FAQ.
I no longer have the time or the need at work to stay as involved with what's going on with the MinGW project. However, I still, quite often, find myself referring to some of the information I collected in the FAQ over the years. Since I still find it useful, I'd like to share a copy of my personal version of the FAQ as it currently stands. For ease of maintenance, I've removed many of the off-site links. I do still post links related to C/C++ and MinGW on the CppDesign mailing list where it's easier to keep up-to-date with that type of information.
If you have any further questions, please refer them to the MinGW32 mailing list. You'll find links to it and other information at the official MinGW web site. I will update this page as I run across any other interesting tips and tricks I'd like to remember.
Please note: This FAQ is copyrighted and it is in violation of copyright laws to distribute it without the permission of the author. If you're interested, feel free to read the reasoning behind this decision.
Table of Contents:
MinGW is a compiler system based on the GNU gcc/egcs projects that compiles code to be run on Win32 (Windows) systems. It provides C, C++ and Fortran compilers plus other related tools. 'MinGW' refers to the "Minimalist" Gnu-Win32 project. If you see references to MinGW32 instead of MinGW, they are referring to the same compiler system. The project's name change from MinGW32 to MinGW is to prevent the implication that MinGW will only works on 32 bit systems. As 64 and higher bit machines become more common, MinGW will evolve to work with them. The project was originally started by Colin Peters, was taken over and supervised by Mumit Khan. Earnie Boyd and other members of the MinGW mailing lists took over after Mumit. It's now kept at Sourceforge and various members of the MinGW mailing lists help to maintain it. MinGW uses the Microsoft runtime libraries, distributed with the Windows operating system. Unlike other ports of gcc to Windows, the runtime libraries are not distributed using GNU's General Public License. You, therefore, do not have to distribute your source code with your programs.
Gcc distributions such as MinGW provide a gcc executable which can be used to compile files in any language the distribution supports. They also provide other compiler drivers, which in the case of MinGW are executables such as g++, c++, g77, etc. These drivers invoke the appropriate compiler programs to compile your source code. Note that g++ and c++ are identical files except for the name difference. This is for historical purposes and allows backward compatibility with Unix compiler distributions which link c++ to g++. While you can compile and link different language files through the gcc program and the various other compiler drivers, it's recommended that you use the appropriate driver for the language you're working with. That way, determining what language specific libraries are needed and other language specific issues are all handled for you by the driver. The g++ and c++ executables are for C++, the g77 executable is for FORTRAN and the gcc executable is for C.
Along with the compiler drivers, you'll find other tools in your
bin directory. This includes cpp, a preprocessor which handles
directives such as #include and #define.
You'll also find windres, which is responsible for compiling Windows
resource files into a usable format. The executables dlltool and
dllwrap are programs used in creating and working with dlls (dynamic
link libraries). The executable ar (i.e. archiver) lets you create
and work with static libraries. The executable gdb is the GNU
debugger. Other executables are in this directory as well. For more
information on these programs, check out GNU documentation about them online or with
your distribution.
There are a variety of licenses for Open Source and freeware programs. Open Source software redistributes the source code with the project. Freeware often does not even let you see how the program you're using is created. Licenses such as the GNU general public license require you to redistribute your own source code when you add their code to your programs. The GNU library general public license isn't quite so strict, but you must make the LGPL source code available. Some source code is public domain and you can do whatever you like with it, including sell your own program which makes use of it. Licensing such as what FreeBSD uses is very lenient and lets you do practically whatever you please as well. One of the nice features of MinGW is that you can do whatever you wish with the programs you create using it and you are not required to distribute your own source code. You'll need a legal copy of crtdll.dll or msvcrt.dll on the Windows system the program will run on, but most Windows operating systems have one or both supplied with the operating system and they may be available from the Microsoft web site.
For those interested in the actual legal details and technical points regarding copyright of the MinGW compiler system, copyright information is included in the headers and the source files of the compiler distribution package. Please be sure to check the information in the version of the compiler suite you downloaded as licensing may change with new distributions. Last time I checked, the following applied:
-pg option for runtime
profiling, also falls under the GNU General Public License.
Here are some further reference sources for the various licenses that apply to pieces of the MinGW distribution:
MinGW requires the Microsoft runtime libraries. Various versions of MinGW have used either the crtdll.dll or the msvcrt.dll to provide the needed routines. Crtdll was on all Win32 systems at one time, but is no longer updated my Microsoft. It was standard on platforms such as Windows 3.11/Windows NT 3.5 and platforms that use Win32s. Msvcrt is not guaranteed to be on older Windows operating systems, but it is more up-to-date and may offer more features. It handles threading better than crtdll and supplies functions such as _i64toa and _atoi64 that crtdll doesn't. The default runtime library target for MinGW is now msvcrt.dll. You will still find remnants in the MinGW code for crtdll.dll such as ifdefs for it in include files. There used to be two versions of MinGW depending on which runtime library you wished to use with it. I don't know if there's still a way to work with crtdll.dll in preference to msvcrt.dll. Most people had switched to using the version of MinGW that used msvcrt.dll in preference to the version that worked with the older dll anyway.
It's highly recommended that you use the latest version of
MinGW. There are older versions available on the Internet or
through books and CDs. Older versions may have more bugs than the
latest version or lack support for certain C++ language features. Please
be sure that you have downloaded and are working with the
latest version, especially if you are having any difficulties with
installation or use. Support on the MinGW mailing lists or from other resources
is usually geared toward the latest release. If you are not sure of your version, you can
type gcc -dumpversion to find out what you are
using. Check the MinGW web site to find out what the latest verion
number should be.
You can download MinGW from Sourceforge. Search for the MinGW project there. Click the Download tab and you should reach the download page. Check how to install it for more details on what to download.
The main web site for MinGW is http://www.MinGW.org. You should find links to Sourceforge and other resources there.
One thing that's changed over the years that I don't think is an improvement is the installation of MinGW. When the FAQ was originally written, all you had to do was download one zip file and place the contents in the directory you wanted. That made it really convenient to install and to move the distribution between machines, hard drives or external drives. Now there are several archived and compressed files associated with MinGW and it's hard to tell which ones to use. The MinGW installation executable is out-of-date with the current release. A new installer mingw-get is in the works, so check for it, but last I checked, it wasn't ready to be used yet. I put together at the MinGW site on the How to Install page of the wiki. If you download bash (either from the MinGW downloads section or from the djgpp site) and wget (from MinGW site, gnuwin32 site at Sourceforge or elsewhere), you should be able to run the script and get down all basic files you need for compiler installation. The script is a temporary measure until the new installer is finalized. Since links are constantly changing, you should probably double check that there aren't any later versions of any of the files listed in the script in the MinGW downloads section. If there are, you'll probably want to change the version numbers in the script to match. Once you have all the files you need downloaded, you can follow the previous MinGW installation steps.
I used to install all my library files to the msys directory, so files didn't collide or co-mingle with the compiler. However, the MinGW team have redesigned things, so that the MinGW versions of most libraries and utilities (as opposed to the msys versions) need to be installed in the same directory as the compiler does. The MinGW versions are designed for general use on Windows, while the msys versions are specifically for use in the msys environment, so most developers are going to want the MinGW versions. You can download any extra libraries you want from the MinGW downloads section. I've added a section at the MinGW wiki to cover some of the libraries one typically may want to add. If you want to use xz for compression and decompression, you'll also need to install the MinGW libiconv binary files first so you have the needed dll for it.
You may also want to use a program like spkg, so you can easily uninstall these files again. However, if you use spkg, you'll probably need to change the names of the tarballs to match Slackware naming conventions and possibly may need to change their decompression format so that spkg knows how to work with them.
Previous mingw installation steps:
Download the MinGW distribution. If files are in zip format, unzip them. (Zip/unzip utilities are available from http://www.info-zip.org/pub/infozip/Info-ZIP.html.) If files are in another format, such as tar.gz or tar.lzma, you can use 7za to decompress them. (7zip and command line tool 7za are available from http://www.7-zip.org/.) You can also use a version of tar that can handle xz and lzma format. A standalone basic tar is available from the MinGW downloads page. If the bin directory that holds MinGW executables isn't already in your path, add it. That's it.
If you need help setting your path, try the following.
On Windows NT, select Start/Settings/Control Panel/System/Environment
and edit your path. For Windows XP, Start/Settings/Control Panel/System/Advanced/Environment Variables
and edit your path.
For Windows 95/98, edit your autoexec.bat file.
If you already have a line that starts with PATH or SET PATH, add the
MinGW bin directory to your list or you can add the
following after the line that sets your path in autoexec.bat:
SET PATH=C:\MinGW\bin;%PATH%
Substitute the directory your MinGW binaries (such as gcc.exe)
are located in for C:\MinGW\bin. If your autoexec.bat file runs any
other batch files at the end of it, be sure to place the lines to
change your path before calling another batch file. For example,
my autoexec.bat file used to have a line that runs a batch file to change the
screen color when it's done setting everything else. When I placed path
changes after the batch file call, the path never gets updated. This
is only a problem with calling other batch files (files with .bat extension).
You can run programs like doskey from your autoexec.bat with no problem.
MinGW can be installed and run when other compilers are on your machine. I have djggp, OpenWatcom and the Borland command line compiler all coexisting happily on the same computer and can compile the same source code with any of these.
The important thing is that MinGW needs to be able to find its executables in the file path. If you mix djgpp file paths with MinGW file paths, you can have problems when your system tries to find the appropriate executables. If you must have both compilers' locations in your path, make sure the proper one comes first in the list. The safest situation is to only have the compiler you're working with listed in your current path.
set path=%~dp0\mingw\bin;%path% to a batch file adds the mingw\bin subdirectory underneath the directory where you ran that batch file to your path.
C:\mingw\msys\bin\sh.exe --login -i. (Update the directory location to point to your msys\bin directory.) You can specify other directories in your .profile in your msys user directory.
There are now several mailing lists for MinGW. Check the MinGW web site for more information and locations or search on Sourceforge for the MinGW project. If you have any further questions or would like to get involved in MinGW, the MinGW web site is the place to go to get started.
I do maintain a C/C++ related mailing list called CppDesign. It's purpose is to share information on C/C++ that may be of interest to experienced programmers and to discuss various design related issues and trade-offs. Links and/or update information on any of the C/C++ compilers or other C/C++ development tools are welcome as is information on Open Source and free C/C++ libraries and source code. If you're looking for some of the interesting links to libraries and programs that used to be in this FAQ, CppDesign is the place to go.
A portable app is a program that can be moved and run easily from a removable drive like a USB flash drive. MinGW really isn't set up to run as a portable app. On the plus side, MinGW doesn't need to make any changes to your registry in order to run successfully. However, it does need to know where to look for the programs in the compiler suite that it needs to run. You can:
The drive letters may need to be edited to point to your removable drive every time you run. You can use the path trick in the batch file technique to deal with changing drive letters.
The MinGW installation executable is not set up as a portable app. You can run it once to get all the compressed and archived files you need to run MinGW or try to figure out what files you need on your own and download them from Sourceforge yourself.
Msys is often used along with MinGW. Like the MinGW installation executable, the Msys installation executable is also not set up to run as a portable app. I have been able to get msys to run on a Windows system where I didn't have administration rights. I copied all the files from an installed version on my own machine to a location on the target machine. I ran the msys executable and let it fail when it didn't have certain rights on the machine. I did note that activating msys was much slower on the machine than it would be normally.
Bloodshed Software has a package called Dev C++ that includes the MinGW compiler suite and other tools such as an IDE. I have heard that there are ways to make this distribution run more like a standard portable app.
Other compiler packages are available for Win32 systems. These include:
For locations of help and tutorial files or sites, check on the CppDesign mailing list. These change frequently, so I'll no longer be trying to keep up with them in the FAQ.
Luckily, some documentation does now come with MinGW itself. I do recommend the C and C++ library documentation that comes freely with OpenWatcom. It's very helpful. lcc-win also provides some good documentation. You can download a c.api file for SciTE users if you check the SciTE web site for details.
If you need some good, simple examples of how to do common or useful things in C (and sometimes C++) check for the Snippets collection. It's now archived at various web sites.
The gcc compiler series has been built successfully with many different runtime libraries. MinGW provided two different runtime library options, crtdll.dll and msvcrt.dll at one time. See the msvcrt vs crtdll section for more information. Both crtdll.dll and msvcrt.dll are available on most, if not all, Windows operating systems. The Cygnus gcc distribution uses the Cygnus runtime library which is available under the GNU General Public License. Similarly, the U/Win gcc distribution uses its own runtime library which is also available under the GNU General Public License. The main problem with using GPL'd runtime libraries is that all source (including your own) must be distributed with the executables created by the compiler. When crtdll.dll or msvcrt.dll are used as runtime libraries this is not an issue.
Other runtime libraries are usable with MinGW/gcc. One such library in the works is PW32, the Posix-over-Win32 layer, at Sourceforge. It provides a subset of POSIX and UNIX functions. Other alternatives are available at Sourceforge as well. Just run a search on MinGW and runtime. The OpenWatcom runtime library source is now available for download. Another option, if anyone's inclined to take on the project, might be to combine MinGW with the Watcom runtime library.
The simplest method of debugging is to add write statements to
the code in order to tell what's going on. In C, puts and printf
are useful. In C++, cout is helpful. In Windows, the MessageBox
is helpful as long as you don't call it during a paint routine. If
you do anything in a Windows application that tries to repaint the screen during a paint
call, you can get stuck in an infinite loop. Some programmers find using assert
statements a good method to help debug.
If you can get the address of a program crash and you have a map file for your program, you can locate the line or routine where the program crashed.
Certain systems, such as Windows NT and some Windows 98 machines, have a program named Dr. Watson available which will supply information about a program when it crashes. Some commercial compilers also supply a program with this functionality. If you have one of these programs available on your system, you can use the address of the crash supplied by it to help locate the problem. If anyone knows of any freeware programs that duplicate this functionality or has source code to find the address during a crash, please let me know.
Here are three ways to create a map file. Choose the method you like best. In these examples, I've used sample names such as file.map and file.exe. Change the map, executable and object files to ones more relevant to your particular project.
ld file.exe -Map file.map nm --extern-only --defined-only -v --print-file-name file.exe > file.map g++ -Wl,-Map,file.map -o file file.o otherfile.o
On systems such as Windows NT, you can specify what application is run when a program crashes. To do so, edit the Debugger value for the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug registry key and change it to the program you want run after a crash. Windows makes available the ID of the process to debug and an event ID to signal when the debugger finishes calling DebugActiveProcess. These can be passed via command line to the program listed as Debugger. Setting the auto value for this registry key to 1 causes the program listed as Debugger to automatically run. Setting it to 0 brings up a crash dialog instead.
Dr. MinGW is a just-in-time exception handler for MinGW. It will automatically install itself as the default debugger in the registry if run with the proper options. If you do not already have some debugger installed on your system, you may have to add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug to your registry by hand before successfully running the install option.
For more in depth debugging, you will most likely need the help of a debugger program. MinGW includes gdb (GNU debugger) in its distribution. I have not kept up with current development on gdb, but this was basically a command line debugger.
Many people prefer a GUI front end to their debugger. I'm not aware if this has changed, but MinGW used to supply only a command line debugger in its distribution. This leaves two options for GUI debuggers.
There are several IDEs (Integrated Development Environments) for Win32 platforms. Some are freeware and some are not. Some are specifically tailored to MinGW and others are for more general use. Please see the CppDesign mailing list and search the archive or ask the members there if you need recommendations. I do remember trying RSXIDE and finding it worked well with djgpp and MinGW and a DDE capable editor like PFE. I've also used Quincy with the Borland command line compiler, but it too works with MinGW.
The various Emacs and Vi programs and their offshots such as Vim (Vi Improved) and Cream are always popular. My current favorite Open Source programming editor is SciTE. It works beautifully with MinGW, other C/C++ compilers and other languages. It lets you intergrate compiling, building and running programs through the editor as well as giving the ability to click on compiler errors within the editor and jump to the appropriate files. It is now very flexible, but can be hard to figure out how to customize. See my article on SciTE customization tips for some help.
As I mentioned, I used to maintain a list of links to IDEs and editors, but other sites have taken over the job and added many more options. A good search engine should be able to locate some of these sites.
MinGW can be used as a cross-compiler, operating on Linux and producing programs that work on Windows target machines. See the MinGW web site or the MinGW mailing list for more details. There may be a cross-compiled distribution available at the MinGW project on Sourceforge on the download page.
The information on msys has been moved to its own page. Please update any links accordingly.
The information on msys has been moved to its own page. Please update any links accordingly.
Here's an example. The following is a code sample for a simple C program. Cut and paste it into a file named hello.c to try it out.
#include <stdio.h>
int main(int argc, char **argv)
{
printf ("Hello\n");
return (0);
}
If you want to create a console mode executable hello.exe from a c file called hello.c, try the following:
gcc -c hello.c
gcc -o hello hello.o
Alternatively, you can compile and link in one step using:
gcc -o hello hello.c
The following is a code sample for a simple C++ program. Cut and paste it into a file named hello.cpp to try it out.
#include <iostream>
int main(int argc, char **argv)
{
cout << "Hello" << endl;
return (0);
}
For the C++ program, use the following to compile and link:
g++ -c hello.cpp g++ -o hello hello.o
Here's an example. The following is a code sample for a simple Windows program. Cut and paste it into a file named hello.c to try it out.
#include <windows.h>
int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance, PSTR szCmdLine, int iCmdShow)
{
MessageBox (NULL, "Hello", "Hello Demo", MB_OK);
return (0);
}
If you want to create a Windows executable hello.exe, from a c file called hello.c, try the following:
gcc -c hello.c
gcc -o hello hello.o -mwindows
-mwindows switch is needed to create Windows executables
instead of console applications. It assures the appropriate Windows libraries
are linked in for you.
To get a console screen along with a standard windows application, add
the -mconsole flag as well as -mwindows.
If you have resources from a resource file (.rc) that also need to be added to your executable, you'll need to compile the resource file as well as your other source files and include the compiled resources when linking to create the executable. Here's an example that shows how to compile and link in a resource file named resfile.rc.
windres -o resfile.o resfile.rc gcc -o hello hello.o resfile.o -mwindows
Here's an example. Cut and paste the following into a file named dllfct.h:
#ifdef BUILD_DLL // the dll exports #define EXPORT __declspec(dllexport) #else // the exe imports #define EXPORT __declspec(dllimport) #endif // function to be imported/exported EXPORT void tstfunc (void);
Cut and paste the following into a file named dllfct.c:
#include <stdio.h>
#include "dllfct.h"
EXPORT void tstfunc (void)
{
printf ("Hello\n");
}
Cut and paste the following into a file named hello.c:
#include "dllfct.h"
int main ()
{
tstfunc ();
return (0);
}
To create the dll and an executable that uses it, try the following:
gcc -c hello.c gcc -c -DBUILD_DLL dllfct.c dllwrap --output-lib=libtstdll.a --dllname=tst.dll --driver-name=gcc dllfct.o gcc -o hello.exe hello.o -L./ -ltstdll
Note: While C functions in dlls are generally portable across compilers, I'm told that this isn't necessarily true for C++. When writing your own dlls, you can mark C++ functions and data in dlls as extern "C" to help bridge some of the C++ portability issues between compilers. See the MinGW32 mailing list archives for more portability concerns regarding dlls.
A library file (.lib or .a) is used in conjunction with a dll to let the compiler know what routines are available in the dll and how to connect to them. While dlls are supposed to be portable across compilers, the library file may not be. You can use the methods in the linking to dlls section to link to one. However, if you do not have the source files and do not want to use commands in your source code such as LoadLibrary, FreeLibrary and GetProcAddress, you can attempt to create a library file from the available dll. In order to create the library file, you will first need to create a definition file (.def).
There are several methods that can be tried in order to create a definition file (.def) when one is not supplied.
-o option.
This example uses grep and sed. If you have a dll named file.dll that you wish to create a def file for named file.def, try the following:
echo EXPORTS > file.def nm file.dll | grep ' T _' | sed 's/.* T _//' >> file.def
To create a library file named file.a from the dll and def file, type:
dlltool --def file.def --dllname file.dll --output-lib file.a
This example uses Perl. Copy the following Perl script to a file called dll.pl and use it:
open (OUTFILE,">dll.def");
print OUTFILE "EXPORTS\n";
open (INFILE,"dll.fil");
while(<INFILE>)
{
if ($_ =~ /T _/)
{
$line = $_;
$line =~ s/.* T _//;
print OUTFILE $line;
}
}
close (INFILE);
close (OUTFILE);
If you have a dll file named file.dll. At the command line, type:
nm file.dll > dll.fil perl dll.pl
A def file named dll.def will be created. You can rename this as needed. You'll also probably want to delete dll.fil when you're finished with this process.
If you don't have any of these tools on your system, you can still use nm to create a def file and edit it by hand through an editor. For example:
nm file.dll > dll.fil find " T _" dll.fil > dll.def
Replace the line at the top of dll.def that was created by the find program
and shows a file name with a line that says EXPORTS. Set your editor to search for
T _ and erase it and anything on the line before it, leaving
only the routine names in the file.
objdump -p file.dll > dll.fil
[Ordinal/Name Pointer] Table in dll.fil and use the list of functions
following it to create your def file.
I was surprised to find a copy of one of my articles related to this topic currently available on the web. It was on how to access Oracle in C/C++ programs using MinGW and Oracle dlls. In the past, I was successful at creating C/C++ programs that were run standalone or as CGI programs and that connected to the Oracle database with dlls provided by an Oracle installation.
Windows programs use WinMain instead of main. However, MinGW is set up so that you can use either.
Some users on the MinGW32 mailing list have noticed ending up with unusually large executable sizes. This can happen if you leave in debugging information. To make your executables smaller, try linking with the -s switch or use the strip program on the final executable (not the object or library files). Compiling without the -g option is another alternative.
Due to binary compatibility issues between different compilers, you cannot directly link in libraries or object code from one compiler to another compiler such as MinGW and expect it to work. The reverse is true as well. Even dlls are not completely portable across compilers. To deal with this issue, various standards such as COM and CORBA were created.
If you want to use a library or objects from one compiler with another, the easiest way to do it is to have the source (.c, .cpp, .rc, .def, etc.) and to compile and build that code with the desired compiler and its tools. You can use the same dll with different compilers with varying degrees of success. You'll need either a .def file or to use calls such as LoadLibrary/GetProcAddress to do so. The self-hosting version of MinGW32 provides better support of Visual C++ binary compatibility. You can use certain libraries built with Visual C++ with this version of MinGW32 without having to rebuild them using MinGW and vice versa.
If you place libraries before the object files that reference them, the linker will be unable to find them. The linker works left-to-right, single pass. The easiest way to avoid the problem is to place all libraries after the object files. It is also recommended that libraries to be linked with should not be repeated on the command line. While listing the same library more than once works with several linkers, the MinGW linker currently has problems with this situation and may leave needed routines out of the link when this is done.
Here's an example of a line that links in multiple objects and libraries:
gcc -o hello hello.o util.o pdcurses.a -ltstdll
The command links in the libraries pdcurses.a and libtstdll.a to create an executable hello.exe.
Although dlls are supposed to be fairly portable across different Windows compilers, accessing dlls through a library file (.lib or .a) is not. The library file formats are specific to particular compilers and cannot be used portably with different compilers unless the compiler provides support for it.
There are two ways to link to a dll.
If you have object files for the dll created by MinGW, you can create def and library files. Here's one method to do so.
dlltool --output-def file.def --output-lib libfile.a [list of objects]Substitute your object file names for
[list of objects].
If you only have the dll file, see the section on
how to create a def file
for alternative techniques.
Once you have a def file, you can create a library file (.a)
in the proper format for MinGW using dlltool. For example:
dlltool --def file.def --dllname file.dll --output-lib file.a
With this method, no library file (.lib or .a) is required. You can connect directly to the dll. LoadLibrary must be called before the dll can be accessed. FreeLibrary should be called before exiting the program. GetProcAddress is used to access specific functions in the dll by retrieving their addresses. You'll need to call GetProcAddress for each function from the dll you want to work with. Check a Win32 reference for more information on the use of these functions.
You can get help by using the --help option.
For example:
gcc --help
You can display the compiler version using the -dumpversion option.
You can display the platform using the -dumpmachine option.
You can specify include files not in your path by using -I.
For example:
gcc -c hello.c -I../pdcurses
You can specify a directory for library files indicated by the -l
option by using -L.
You can use -g to add debug information for the debugger to work
properly.
You can use -D to specify a define.
For example:
gcc -c hello.c -D__WINDOWS__
You can use -v to find out more about the executables being
invoked.
For example:
gcc -v
MinGW displays compilation and linking errors to stderr instead of stdout. To easily view these errors, you may need to redirect the output to stdout or a file. Some methods to do so include using one of the following programs:
Some users have had trouble with the DOS box (aka Windows Command Prompt) closing after building a program and haven't been able to see their errors. The MinGW32 mailing list came up with several suggestions on how to deal with this. One suggestion from Franco Bez is as follows:
By modifying a few Registry Keys - you can add a context menu item
Run - stay open, so you simply right click on
the Batch file and choose Run - stay open and your batch
runs and stays open.
The following Registry files do this and a little more:
DOS Box for Folders and files - opens a dos box in the folderNotepad for all files, even those with missing/unknown
extension - opens the file in Notepad for editingRun - stay open for bat, com and exe filesPlace the following lines in a file (such as Win95_98.reg or WinNT.reg) and
simply merge the file for your system to your registry by doubleclicking it.
The example below is for Windows NT. If you are using a Windows 95 or 98
system, change all the occurrences of cmd to command.com.
REGEDIT4 [HKEY_CLASSES_ROOT\*] [HKEY_CLASSES_ROOT\*\shell] [HKEY_CLASSES_ROOT\*\shell\dos_box] @="DOS Box" [HKEY_CLASSES_ROOT\*\shell\dos_box\command] @="cmd" [HKEY_CLASSES_ROOT\*\shell\open] @="Notepad" [HKEY_CLASSES_ROOT\*\shell\open\command] @="Notepad.exe %1" [HKEY_CLASSES_ROOT\Folder\shell] [HKEY_CLASSES_ROOT\Folder\shell\dos_box] @="DOS Box" [HKEY_CLASSES_ROOT\Folder\shell\dos_box\command] @="cmd /k cd %1" [HKEY_CLASSES_ROOT\batfile\shell] [HKEY_CLASSES_ROOT\batfile\shell\runstayopen] @="R&un - Stay open" [HKEY_CLASSES_ROOT\batfile\shell\runstayopen\command] @="cmd /k %1" [HKEY_CLASSES_ROOT\comfile\shell] [HKEY_CLASSES_ROOT\comfile\shell\runstayopen] @="R&un - Stay open" [HKEY_CLASSES_ROOT\comfile\shell\runstayopen\command] @="cmd /k %1" [HKEY_CLASSES_ROOT\exefile\shell] [HKEY_CLASSES_ROOT\exefile\shell\runstayopen] @="R&un - Stay open" [HKEY_CLASSES_ROOT\exefile\shell\runstayopen\command] @="cmd /k %1"
MinGW has some support for COM programs. Programmers have had much better luck writing COM applications in C than C++. Work is in progress to improve support. Check the MinGW32 mailing list archives for more details on COM and links to example files.
A preprocessor allows you to programatically include a file in several other files without having to repeat the code in each files. It also lets you conditionally include certain parts of a file based on defined settings.
Most C/C++ programs make use of the preprocessor. Even other languages like Fortran may make use of one to help with program maintenance issues. You can use the preprocessor on other file types as well such as HTML files to take advantage of its benefits for web development and help file creation. With web design, this technique can replace server side includes (SSI) or asp include files.
Try this command to preprocess html files and be able to #include pieces of HTML code in them:
g++ -C -E -P -x c sourcefilename.htm -o finaloutputfilename.html
The -C option keeps the preprocessor from discarding C/C++ comments (lines starting with // or delimited with /* */). The -E option is needed with the -C option and causes the results of the preprocessor to show either to standard output or to an output file if one is given. The -P option keeps linemarkers generated for the included files from appearing in the output. The -x C option specifies the source language (in this case C). Since the file has an extension of .htm or .html instead of .c or .cpp, the precompiler does not know how to deal with the file. This tells it to deal with the file as if it was a C file. The -o option indicates the name of the output file, in this case finaloutputfilename.html
In this example, I've given my source file the extension of .htm to keep from confusing it with the final result files with extensions of .html. You can also keep your source files in one directory and the output files in another. When you run the preprocessor from a command line be sure to substitute the names of the files you are working with for sourcefilename.htm and finaloutputfilename.html.
To simplify the process even further, use a makefile to preprocess all the files for an entire web site with one command.
Working with a make program is one very good solution to keep from having to continually type all your compiler commands on the command line. There are several versions of make available both as freeware and commercially. A port of GNU make is available at the MinGW site and other Windows ports are available. A version of make that handles long command lines in a DOS environment or when working with DOS programs is available especially for djgpp with the djgpp distribution. Watcom includes wmake. Microsoft has a free version of their nmake program hiding somewhere at their web site. (Run a search at their site to find it.) Msys supplies a copy of make and actually prefers you use it and keep other versions you have out of the MinGW bin directory.
To run make, type make at the command line in the directory where a makefile resides. If the
file is not specifically named makefile, you'll need to specify the file name. For instance,
to run a file named makeprog.mak, use the command:
makefile -f makeprog.mak
I have a Windows port of the GNU make program that I use for all my compilers. That gives me one common syntax to use for my makefiles since different companies' versions of make have their own way of doing things. I keep make in a general purpose utility directory that is part of my environment path, so it's usually the first version that's run whenever I need it. When I run msys, it doesn't look in that directory since it's not part of the enivornment path for msys. That way, msys uses its own version of make.
When using make, be careful of tabs when editing your makefile. My editors are set to turn tabs to spaces and if you do that with your makefile, make won't work properly. The program requires tabs in certain locations of your makefile as part of the command syntax. There's an example of how to change tab settings when editing makefiles with the Scite editor in my SciTE Tips.
Make can be used with a variety of languages and programs. You don't have to use it only with MinGW or only for C/C++. If you're into web development or creating help files, you can use make and the MinGW preprocessor in place of techniques such as SSI or templates as a method of adding repeated html code to several files.
Here's a sample makefile for working with web pages. It runs any files with the .htm extension
through the MinGW preprocessor and creates output files with the .html extension. It also cleans (deletes) any files
with the *.html extension if you run make clean. Using this as a template,
you can substitute .c or .cpp files for .htm files, .o files for .html and change the compiler directive to
gcc -c or g++ -c to see this work for C/C++ files. You can also substitute file extensions and commands for
other file types and languages that you work with.
src=$(wildcard *.htm) objects = $(src:%.htm=%.html) all: $(objects) $(objects) : $(src); g++ -C -E -P -x c $< -o $@ #Use del or rm or deltree or whatever the name is of your machine's command to delete files. #Might need to include path to the command in some instances. #clean: ; /mingw/msys/bin/rm *.html clean: ; del *.html
If you have changes to source code, it may be easier to distribute them as patches than to send the entire code to someone or list the changes by hand. Patching is an automated process of updating files using tools such as patch and diff.
Patches can be created by comparing two files with the diff program or from various version control systems such as RCS. Several versions of diff have been ported to Windows and DOS. Check sites that have Win32 ports of Unix style tools or use the version supplied with msys. There are also several versions of the patch program available for use in applying patches to source code. Detailed help information on using diff and patch and the various options available for working with them was also available in WinHelp format from the Virtually Un*x site.
To create a patch, compare the two versions of the file with diff. Here's an example:
diff --ignore-all-space old\file.cpp current\file.cpp > patch.fil
The example ignores whitespace and compares the old version of file.cpp
in directory old with the latest version in directory current. The
output is redirected to a file. Most patches these days also include
the -c or -u option which allows programmers
to figure out what has changed in a file by viewing the context of the
lines around it. Another common option is -r for working
with entire directories instead of single files. The option -p
may also be useful. It adds information on what C functions a change
appears in.
To patch a file, you'll need the original source file (old version) and the file with the patches created by diff. Here's an example of how to call patch:
patch -o file.cpp ..\old\file.cpp patch.fil
The command patches file.cpp in the old directory and outputs the updated
file to file.cpp (specified by the -o option). Another useful
switch for use with patch is -p which can affect the naming/location
of files and can be used when working with compared directories.
Spkg is a package manager based on the Linux Slackware package management system. It has been ported to Windows. You'll find a copy at http://spkg.megous.com/.
After recently working with some Linux Slackware variants, I found myself wondering what Windows had to offer as far as package management and packaging tools. Without a package manager, it can be very hard to keep track of all the various Open Source libraries that may get installed on your system while trying to build Open Source programs. I'm currently working on another web page discussing makefiles, build scripts and package management tools. I've had some success in porting a portion of the Tukaani Slackware pkgtool scripts and was able to port the program spkg to Windows. The spkg modifications for Windows have been integrated with the original source code to create the latest version of spkg. Source and Windows executable are available from the site mentioned above.
MinGW does provide a system called mingwports. A mingwport is a group of files that create a template for porting libraries or programs. The files basically execute a series of commands to build a library or program from scratch. They automate all the steps a user would generally take to create that library or executable. It appears to work very similar to the SlackBuild script concept, but requires a lot more files. I've updated the offical MinGW wiki with a page containing what I've learned so far in my experimentation with mingwport scripts. I'm also working on an idea to create build scripts in a cross-platform manner, so you can generate and regenerate a SlackBuild script, a script in a custom format or a mingwport script in a more automated fashion from input and templates. If anyone's interested in more information on my script generation project or working with a package management tool, feel free to join my CppDesign mailing list to discuss these topics further.
As far as package management tools and build scripts, Windows seems behind Linux in this area. This is probably because most average Windows users don't build all their programs from source. Linux users or the people in charge of their distribution's repository have to do this each and every time key libraries such as glibc change. Luckily, Windows usually has excellent backward compatibility and does not require this kind of major library change very often. There's a package management tool for SFU/SUA. Cygwin uses their installation program for package management. They may possibly have other package manager programs ported from POSIX systems. There is code for package management systems for Windows at Sourceforge. I really haven't seen a lot of support and documentation in this area for Windows machines. As a matter-of-fact, I found very little documentation on how to create and submit mingwports (and thus decided to try my best to document what I could figure out at the official MinGW wiki). As mentioned, I hope to add a page to my web site covering build scripts, package managers and related topics when I have time to complete it. I'm also in the process of reworking my patches page to include build scripts as time allows.
MinGW provides access to the Win32 API. Theoretically, if you own the MFC source code you could build MFC libraries for MinGW. No one's tried this so far. If anyone does successfully accomplish it, please say so and it will be added to this document.
For OWL owners, there is a port with additional features which supports various compilers including the gcc compiler line. Thanks to Greg Chicares on the MinGW32 mailing list for supplying this information.
There are a number of these available. The following are known to have worked with MinGW. There are several other libraries out there.
--enable-static and --disable-share
When I started this FAQ, I had to write some of the makefiles to get popular libraries to work with MinGW. Many didn't work. Today, along with several programs written specifically for MinGW or Windows programs ported from Visual C++ or other compilers to MinGW, quite a few popular Linux programs will compile with MinGW and even more will do so if you use msys. I'm leaving some of my previous library recommendations in the FAQ, but if you're looking for something specific, run a search on the Internet or ask on the MinGW or CppDesign mailing lists. I am very happy to report there are far too many libraries that work with MinGW for one person to list them all.
You can check projects such as Gnuwin32 on Sourceforge or DevPaks created by the Dev C++ developers for pre-compiled standard libraries that you can easily add to MinGW and Msys.
const char *const lib_pkgconfig = "\\lib\\pkgconfig";to:
const char *const lib_pkgconfig = "/lib/pkgconfig";
Here is a list of some of the libraries and programs from the original FAQ that could be built with MinGW.
My GL related header files (gl*.h) are in:
/MinGW/include/GL
If you do not have the appropriate glut dll(s) installed on your system, move dll(s) to your Windows system32 directory.
To link with the GL libraries, don't forget the flags:
-mwindows -lglut -lglu32 -lopengl32
or in some cases:
-mwindows -lglut32 -lglu32 -lopengl32
Check Sourceforge for packaged versions of these already built and ready to be used in a Win32 environment. The patent on the GIF compression algorithm is now out of date, so the GIF format is a viable option for Open Source developers.
http://linux.techass.com/projects/xdb/
Dbase/Clipper compatible, cross-platform database library.
Successfully compiled with file locking off under MinGW.
http://libodbcxx.sourceforge.net/
C++ class library, similar to JDBC, for ODBC access.
Compiled and built successfully with MinGW. For now, see the
MinGW32 mailing list for some of the changes that were needed.
See also, ODBC access below since ODBC is required to use this library.
Oracle can be accessed using Oracle's pro*c and sqllib80.dll (or sqllib18.dll for those with older versions of pro*c). There was an example article on how to access Oracle from unsupported compilers at Oracle's web site. Oracle's OCI interface also works in some cases using oci.dll or ociw32.dll. Here's a link to an old article I wrote about how to access Oracle in C/C++ programs using MinGW and Oracle dlls.
An ODBC manager (such as ODBC Data Sources program accessible via the Control Panel) is necessary to run ODBC programs. ODBC is available from Microsoft and other sources. Use your favorite search engine to see if you can find a version to download.
Cross platform, C++ database library.
http://www.hypertable.org/index.html
Non-SQL databases for large scale web applications are now the rage. I've seen some mention of getting Hypertable to compile with MinGW.
Check the Available C++ Libraries FAQ at http://www.trumphurst.com/cpplibs/ for more options.
Library/Tool used to help write internationalized and localized programs.
GNU library for command line editing.
Compression library. Includes makefile for MinGW32.
Posix threads. A version of this library has been ported to Win32 to make up for missing Posix threading functionality on Windows. Check for RedHat's port or another Win32 version.
http://josefsson.org/gnutls4win
Library used by some communications programs.
General purpose library providing network, parsing, threading, security, database and other functionality.
Cross platform, general purpose C++ libraries. Not the easiest library in the world to build and there's a lot to it, but some Open Source projects find these routines useful and portable.
Cross platform, C/C++ internationalization library. Based on the work of IBM and others in internationalization. This library is used by Boost.
Besides make, IDEs and editors and Debuggers, there are several basic utilities and tools that have become standards over the years.
Many users have found Win32 or DOS versions of Unix programming tools very helpful. Search for the Gnuwin32 project at Sourceforge or UnxUtils at Sourceforge or archives of the Virtually UN*X tools. Gnuish MS-DOS collections found at many ftp archives have older versions of the standard GNU utilities ported to 16 bit DOS. Less, http://www.greenwoodsoftware.com/less/ is a very nice file filter for viewing files quickly. It's similar to the DOS more program, but less does more. Microsoft is now offering a shell called Powershell at their web site. It works on later versions of Windows and among other things, emulates popular Unix/Linux shell commands. I also want to mention msys at the MinGW site. It gives a Linux like shell environment and standard linux tools. It's great for compiling programs that need to go through the ./configure protocol.
For those who prefer working with tools other than those found in Unix environments, be sure to check out the DOS utilites at FreeDOS, http://www.freedos.org/ If you want utilities similar to standard MS DOS ones, this is a great place to look. FreeDOS utilities even includes a deltree version that works on Windows NT and other versions of Windows that no longer supply it. All tools at FreeDOS are compiled for DOS 16 bit systems. Source is included with most.
My favorite Open Source tools (and some freeware ones too) are mentioned on my Switching to Open Source page.
Some of the Open Source tools I like to use required patches to get them to work. I've started a patches page to keep track of fixes I've had to do for code on various operating systems and compilers. The page includes some patches for Open Source programs that build using MinGW.
I am a proponent of Open Source and Creative Commons style projects, so you may be wondering why I copyrighted this FAQ rather than using a GNU or Creative Commons licensing scheme. At the time I originally wrote the FAQ, I was monitoring the mingw32 mailing list daily and updating it as new and frequent questions appeared. I did not want versions of it proliferating all over the web, especially as it was a work in progress. I was hoping to keep the FAQ up-to-date and accurate. There's no way I could ensure the information I was disseminating was accurate and up-to-date if there were old copies being distributed elsewhere. My original intention was to have one copy only and other sites were welcome to link to it if they needed to refer to information. Please note that anyone distributing versions of this FAQ or the original versions is in violation of copyright laws. If you see old versions of the FAQ, please let the distributors know. If you have an old copy of the FAQ at your web site, please remove it. Please link to the current official MinGW FAQ at the MinGW web site or if you want, you can link to the unofficial alternative version you are currently reading at my web site. I also believe strongly in fair use. You have the right to keep a copy of this document or various incarnations for personal use (not for distribution purposes).
Since I'm no longer maintaining the official FAQ, I will not be updating this document nearly as often as I used to update the original. I have, however, decided to keep the copyright license intact, since I still intend to be updating the document and still do not want a proliferation of out-of-date MinGW documents widely distributed. I feel it's more beneficial to the community to have a place to go for reliable information on the project, rather than having several old, outdated copies on as many web sites as possible. Several web sites might reach more people, but if developers are unhappy with the product because the documentation is wrong or not user friendly, it's a disservice to that Open Source project. If you're as excited about the prospects of MinGW and what it can do as I am, then please link or refer people to the official MinGW web site instead of copying dated documentation. Also, please participate and help them keep the new MinGW wiki up-to-date and accurate. Thank you.