Skip to end of metadata
Go to start of metadata

Introduction

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

Pre-requisites

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.

Running fbgen.py

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:

python fbgen.py

You will be given a series of prompts:

Plugin Name []: Our Cool New Plugin

This is the human readable name of your plugin that will be used in strings. No default value

Plugin Identifier [OurCoolNewPlugin]:

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.

Plugin Prefix [OCNP]:

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.

Plugin Mime type []:

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.

Plugin Description []:

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

Plugin has no UI [false]:

Set to true if you do not plan to do any drawing with your plugin. Default is false.

Company Name []: Firebreath Dev Team

This is used for copyright notices in the resource strings. No default

CompanyIdentifier [FirebreathDevTeam]:

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.

Company Domain [firebreathdevteam.com]:

This is needed to create a unique id for the mozilla plugin, which is of the form "@[company doman]/[plugin id]". The default is generated from the company id, and we will use it.

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:

PluginConfig.cmake

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.

CMakeLists.txt

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.

Factory.cpp

This contains a subclass of FactoryBase for your plugin. The method that is called by Firebreath to create the main plugin object is in here, as are the global init and deinit functions. The default behavior is to create a [YourProjectID] object (in this case OurCoolNewPlugin object) and call OurCoolNewPlugin::StaticInitialize() and OurCoolNewPlugin::StaticDeinitialize() for the global init / deinit. You can change this here.

OurCoolNewPlugin.(cpp | h)

This is essentially the main entrypoint for your project; any time someone puts an object tag on a page with your plugin, this object gets instantiated. It has a window from which it gets events and which can draw for it, and it has an API which handles Javascript calls. The createJSAPI method creates the JSAPI (Javascript object) that will be seen by javascript when it accesses the object. This defaults in our case to OurCoolNewPluginAPI.

OurCoolNewPluginAPI.(cpp | h)

This is the default "API" class. Think of it as a Javascript object; when you access your plugin from javascript, this is the object that you'll be dealing with (unless you change that in your main plugin object. You can add methods and functions, deal with and return arrays and javascript objects, and even return other API objects with their own methods and properties.

Win/projectDef.cmake

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`.

Win/np_winmain.cpp

This provides the main entrypoints for NPAPI. Don't touch if you don't know what you're doing.

Win/dllmain.cpp

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:

So, from the root, run:

  • Windows: prep2008.cmd (or prep2005.cmd / 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.
  • Mac: ./prepmac.sh
  • Linux: ./prepmake.sh / .prepcodeblocks.sh / prepeclipse.sh

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 build/Firebreath.xxx (with .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.

License of the generated files

The project that is generated by using fbgen is not licensed by the FireBreath team and belongs in its entirety to the person who creates it.

Installing the binary

If the plugins don't work after following the installation procedures below, your browser might need to be restarted.

Windows

The binary for our new project will be built into build\bin\OurCoolNewPlugin\Debug. Change to this directory and run: regsvr32 npOurCoolNewPlugin.dll

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 $(HOME)/Library/Internet Plug-Ins.

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.

 

Linux

Copy the resulting .so into $HOME/.mozilla/plugins/.

Testing the plugin

After installing the plugin, open the file: build/projects/OurCoolNewPlugin/gen/FBControl.htm in your browser. Use your favorate javascript panel (or even javascript:... in the address bar), and try a few of these commands:

to add new features, look at the OurCoolNewPluginAPI class. Don't forget to register your new method or property in the constructor!

Class Structure

  • No labels