One of the more common complaints that we receive about the FireBreath project relates to our use of cmake to generate the project. This page is intended to help explain the reasons for using cmake, why we chose it, and how much worse this would actually be if we didn't use it.
FireBreath has a primary design goal to wrap as much of the browser-specific logic of plugin development as possible, while not impeding the ability of the plugin developer (that's you) to create whatever they want. In order to do this, it is important that the plugin developer should never have to modify any project but their own.
When creating a plugin, you never run cmake directly. Instead, there are a set of "prep" commands in the root of FireBreath that allow you to generate the project files. As of the time of this writing the prep commands (and the tool they generate projects for) are as follows:
prep2005.cmd- Visual Studio 2005 (windows only)
prep2008.cmd- Visual Studio 2008 (windows only)
*prep2008x64.cmd- Visual Studio 2008 (windows 64-bit only, 64-bit plugin build)
prep2010.cmd- Visual Studio 2010 (windows only)
*prep2010x64.cmd- Visual Studio 2010 (windows 64bit only, 64-bit plguin build)
prepcodeblocks.sh- Unix derivative (linux, bsd, etc); Generates project files for Code::Blocks and makefiles.
prepeclipse.sh- Unix derivatives (linux, bsd, etc); Generates project files for Eclipse and makefiles. will not work correctly on Mac.
prepmake.sh- Unix derivatives (linux, bsd, etc); Generates makefiles.
prepmac.sh- XCode project files, needed to build a plugin on Mac OS X.
* Note that the x64 windows build commands should generally not be used unless you know that you need them. Most windows browsers run in 32 bit mode, not 64 bit mode, so a 64 bit build is most likely not what you want. Also note that if you create a 64 bit windows plugin it will only work on 64 bit versions of the browser; firefox is currently 32 bit on windows and the default Internet Explorer choice is also 32 bit, and the 64 bit plugin will not work on these browsers.
After you have used a prep script to generate project files of one type, you cannot generate project files for another type without deleting the
After running a prep command, the project files will be in the
build/FireBreath.slnas your main project
build/directory with the name of your project (e.g.
When you run a prep command, it scans the
projects/ subdirectory of the FireBreath tree. This directory is not in source control – you have to create it, or
fbgen will create it for you (see CreatingANewPluginProject). Any directories in there that contain a CMake (plugin) project will be added.
If you call any of the above prep commands with "examples" as an argument (e.g.
prep2008.cmd examples), project files will be generated in buildex/ and it will use plugins found in the "examples/" subdirectory.
When using cmake, you should never make changes directly to the project files (i.e.
Makefile, etc). Instead, modify one of the following files in your plugin directory. The relevant files in the FBTestPlugin directory are:
Once changes are made, the "prep" command should be run again so that cmake can generate the updated project files.
If you ever screw up your project file (it happens) and possibly get very weird build errors you cannot explain, simply delete your build directory and regenerate it with the prep script.
CMake uses absolute paths to generate the project files, so if you move the FireBreath tree you will need to re-run your "prep" command.
With all of that said, many of you may be wondering "Why go through all of this hassle?". Here are a few of the things that CMake makes possible for us:
projects/subdirectory can be automatically detected
NpapiPluginprojects depend on plugin-specific constants and so need to be built for each plugin; with cmake, you never have to modify these files
PluginConfig.cmakecan be used to generate resource files, registry files, and header files for common plugin configuration items, such as:
These are just a few of the reasons; if anyone can find a way that works as well or better than cmake at solving all of these problems, we would be happy to consider other options.