Table of Contents
In order to build a program with GNU tools, you need a build system. A build system is a mechanism which will build your sources according to project description in some format. There are many such build systems available. Currently WinGDB supports one which is the most popular and the most mature -- GNU make.
GNU make stores information about projects in files called "makefiles". They have simple text format, specifying build goals, rules how to achieve them, and dependencies between these goals. Usually you have to write such file by hand. It is likely that your project already has one, authored by you or someone else. But if it's not the case, WinGDB offers you a convenient feature to generate such file directly from Visual Studio project. The generator works for three kinds of projects: executables, shared libraries and static libraries. This mode of the generator is called the Generate mode. It overwrites the whole makefile.
Another option is to patch existing makefile to reflect latest changes in source files set (e.g. when you add, remove or rename files). WinGDB offers a special mode, called Update mode. This mode does not generate the makefile from scratch. Instead, it modifies existing makefile, replacing only relevant sections and leaving the rest intact. It allows you to use your own makefiles, and at the same time be relieved from tedious task of updating the sources list manually.
To generate a makefile, you need to set some additional options first. It is recommended to configure your project using Project configuration wizard which has makefile generation options and asks minimal number of questions. On the other hand, if you want to have more control over the process, use Properties. There is Makefile section in the dialog, giving access to the following options:
If you don't know which switches are needed, it's recommended you start with Project configuration wizard, since it will supply some required switches automatically for some platforms. Still you're enouraged to read a development guide for your platform, which should explain all specific options.
Currently you have also to provide include directories (as "-I<directory>" switches). WinGDB does not read these from Visual Studio project yet. This will be implemented in the future.
Similarly to include directories, WinGDB does not read corresponding settings from Visual Studio project yet. This will be implemented in some future release.
In order to configure the compiler and linker flags more easily, you can use the switch editor feature. Click on the button next to corresponding field and choose Edit [tool] options... from the menu. For example:
The switch editor dialog will appear. Its design is similar to Visual Studio compiler/linker option editor. The editor contains commonly used options, mostly having their counterparts in Visual Studio. Two separate editors exist: for compilers (C and C++) and the linker. The linker option editor assumes the LD linker is called through the GCC driver and supplies -Wl and -Xlinker wrapper switches automatically where appropriate.
Certain settings can be imported from underlying Visual Studio project. In order to open import window, click the Import button. Now you can select which properties shall be imported.
Not every option can be imported, as only a subset of them have reasonable equivalent in the Visual C++ configuration. Also note that for path properties (like Additional include directiories), it makes sense only to import values defined by relative paths or variables. Absolute paths may be not meaningful on other platform.
Makefile generator uses also several settings from other tabs. These settings are:
When the generator is configured, you can perform actual makefile generation. Right click on a project in Solution Explorer and select the Generate makefile option.
The makefile will be created in the same directory as your project file. If some makefile already exists in that location, WinGDB will ask if you want to overwrite it.
Makefiles generated by WinGDB support multiple configurations defined in the source project. To select particular configuration, set BUILD_CONFIGURATION environment variable to the name of the configuration.
Project configuration wizard will set this option for you.
To update a makefile, you need to set the Generator mode option to Update:
Next, a small modification to your makefile must be done. Open the makefile in a text editor and add a comment line anywhere, according to the following general format:
# WinGDB SourceNames:<name>, SourcePaths:<name>, HeaderNames:<name>
This line tells WinGDB that you want the makefile to be updated, and what are the names of make variables to be modified. WinGDB will find assignments to these variables and modify assigned lists. In case of multiple assignments to particular variable, only the first one will be modified (allowing you e.g. to add more sources later).
You do not need to specify all variable names. Each of the is optional. For example, you can update only the list of source names:
# WinGDB SourceNames:SOURCES # ... some rules ... SOURCES= \ source1.cpp \ source2.cpp \ source3.cpp # ... some rules ...
In such case, WinGDB will change the whole assignment to SOURCES, according to currently present source files in the project. The asssignment can span over multiple lines. WinGDB will correctly escape the line endings in case of multiline assignments. You can specify arbitrary variable name instead of SOURCES. Names shall contain only letters, digits and underscores to avoid makefile errors.
Other currently supported lists are SourcePaths and HeaderNames. The SourcePaths list contains relative paths to source files, as opposed to SourceNames which contains plain names. HeaderNames contains names of header files, which can be useful in dependencies. More types of lists may be supported by subsequent versions of WinGDB.
You can trigger the update of makefile in exactly same way as above, using the Generate makefile option from WinGDB menu.
The most complex and powerful option is to use custom scripts to generate build files. You can generate files for any build system this way -- not necessarily a makefile. WinGDB provides fully-featured script interpreter for that purpose, based on the Lua scripting language. The scripting language is augmented with large number of functions allowing to access Visual Studio project data and path manipulation. The syntax of Lua language makes it very easy to create files out of templates.
To generate a build file with a script, you need to set Generator mode option to Run script.
In the Generator script name field, specify the script name (.lua extension will be added automatically). The script is supposed to be located in WinGDB data directory, for example:
You can open scripts from that directory by using Edit generator script... option from main WinGDB menu. Select a script to edit, or type in new script name. The script should have .lua extension.
There is also an example of generator script, named example.lua. This is a very simple makefile generator (simplified version of standard WinGDB makefile generator). It shows basic techniques and functions. You can use it as a base for your own generators. Warning: the 'example.lua' file might get overwritten when installing new version of WinGDB, therefore make a copy for editing.
For Lua syntax introduction, consult the Lua primer section of the manual. You can also browse the full Lua syntax reference. For a description of WinGDB extensions and actual functions used in generators, please look into this section of the manual.
The generator script need not be in the data directory. You can also specify alternative location in the Generator script name field as one of the following:
In second case, specify a path like the one below. Note that $(ProjectDir) value already contains a backslash at the end, so there isn't one before 'scripts'.
Table of Contents