The hardest part of learning any new system is getting started; knowing that, the FireBreath dev team is pleased to introduce the fbgen.py tool
What it does
fbgen.py will create a blank project for you based on parameters that you give it. You can still change all of those things, of course, but it gets you started a lot faster; in fact, it's so easy that even we use it, and we wrote the system =]
How to use it
All you need to run fbgen.py is python 2.5, 2.6, or 2.7. Version 3.2.3 (the current latest) does NOT work, but other versions have not been tested and may work.
- If you don't have python installed, one way to get the latest version from the 2.x tree is downloading it from here: http://python.org/download/
Once you have Python installed, you should be good to go. If you really really don't want to install Python, you can specialize the fbgen template by hand.
Note: if you are trying to use an old version, you may need Cheetah as well. This is easily solved – don't use an old version.
You should now have python set up. I'm going to also make the assumption that you have already either checked Firebreath out of source control or otherwise obtained a copy and that you have CMake 2.8 or greater installed on your machine with python in the path.
The instructions here assume that you are on windows, but mac and linux should be similar.
In the root of the firebreath project, run:
You will be given a series of prompts:
This is the human readable name of your plugin that will be used in strings. No default value
This is the code-friendly identifier that will be used to name classes, the project directory, etc. The default is the plugin name with invalid characters stripped out. We will use this default.
The plugin prefix is used to generate project names in visual studio; it is usually easiest to keep short, but should be recognizable. The default is the first letter of each word in your plugin name, forced to at least 3 characters and no more than 5. We will use this default.
The MIME type that you will use with the object tag to embed your plugin into the page. We will use the default, which is generated from the plugin identifier.
A human readable description of the plugin that will go in the strings resource that is compiled into the plugin; it will be visible in navigator.plugins on NPAPI-based browsers. No default
Set to true if you do not plan to do any drawing with your plugin. Default is false.
This is used for copyright notices in the resource strings. No default
This is used to generate the ActiveX PROGID ([CompanyID].[PluginID]) and a few other things in the plugin config. We'll use the default, which is the company name stripped of characters that are invalid for a code-friendly ID.
This is needed to create a unique id for the mozilla plugin, which is of the form
That's it! Now you will see "Processing templates" and a lot of files (see below) get generated, and at the end it will say "Files placed in ....\projects\OurCoolNewPlugin"
What just happened
fbgen.py just took the information you gave it and created you a plugin project directory under projects. In our example, the files went to projects/OurCoolNewPlugin. Any project directories found in the projects/ subfolder of the firebreath project will be included when you generate the project files (more on this later)
These are the files that were created:
Arguably the most important file in the project to get right, this is where 90% of the configuration happens. Nearly all of the things you were prompted for by fbgen.py go directly into this file. Don't worry – you can change it if you want to. Configuration options from this file are used to generate other files that are critical to your plugin configuration.
If you're familiar with CMake, you probably recognize this file. It's the main config file for generating your project; there are some behind the scenes things that will include PluginConfig.cmake and the project itself will be added by Win/projectDef.cmake, but any files that will be cross platform and should be included in your project get added here. You probably won't have to touch this for a simple plugin.
This contains a subclass of
This is the other half of the project definition started in `CMakeLists.txt` – the half that deals specifically with Windows. In the future there will be a `Linux/projectDef.cmake` and a `Mac/projectDef.cmake`.
This provides the main entrypoints for NPAPI. Don't touch if you don't know what you're doing.
This provides the dllmain entrypoint to your DLL. Don't touch if you don't know what you're doing.
Generating and opening the project
The project files aren't yet usable – we need to generate them first. You have to run the `prep` script for your platform, which will result in CMake generating project files for all of your projects.
Note that you must download and install CMake before this step! Note that the cygwin version of cmake has been reported to not work, so get the native platform version from the CMake website! See also:
- Full build instructions for Windows
- Full build instructions for Mac
- Full build instructions for Linux (may also work on other *nix)
So, from the root, run:
prep2010.cmdif you have VS2005/2010)
- There is also a prep2010x64.cmd, but that is only for building a 64 bit version of the plugin; very few people use 64 bit browsers on windows, so you probably don't want to use the x64 prep script; it is there because there are a few rare exceptions to this rule. If you aren't sure, you aren't one of them.
CMake will generate project files for all of your projects.
On Windows 7, make sure you're running the cmd shell with Administrator privileges.
In our case, we can then either open
.xxx being e.g.
.sln for Visual Studio) to get a project file with all of the plugin projects in the
projects/ subfolder, or
build/projects/OurCoolNewPlugin/OurCoolNewPlugin.xxx to get just the plugin we created. Build it and you should be good to go!
With the make-based solution on Linux, a simple
make in the above mentioned directories should suffice.
Installing the binary
If the plugins don't work after following the installation procedures below, your browser might need to be restarted.
The binary for our new project will be built into
build\bin\OurCoolNewPlugin\Debug. Change to this directory and run:
It should display a message to the effect that the control was registered successfully.
Mac OS X
Create a symbolic link to the resulting
OurCoolNewPlugin.plugin bundle and move the symbolic link into either one of:
~/Library/Internet Plugins- per-user installation
/Library/Internet Plugins- global installation
If the browser does not seem to recognize the symbolic link, you could configure your Xcode project to install the binary automatically after each build. However, like other Build Settings, the following four will be erased whenever you re-make your project by running prepmac.sh. In Groups & Files, expand Targets, doubleclick
OurCoolNewPlugIn (with the "Lego" block icon). In the Target Settings window which appears, click the 'Build' tab, scroll down to the 'Deployment' section. Then,
• Check ON 'Deployment Location'.
• Change 'Installation Build Products Location to
• Change 'Installation Directory' to either
/Library/Internet Plug-Ins or
Xcode can also be configured to install the binary automatically after each build via the following CMake code, which should be added to the end of your <Project>/Mac/projectDef.cmake file. Select the appropriate "releasePlugin" call to install either per-user or globally.
Copy the resulting
Testing the plugin
After installing the plugin, open the file:
to add new features, look at the
OurCoolNewPluginAPI class. Don't forget to register your new method or property in the constructor!