Skip to content
zloether edited this page Sep 13, 2010 · 9 revisions

This user guide is a work in progress.

Warning

GMSC is currently alpha code. It’s a delicate flower that hasn’t been tested nearly as thoroughly as it needs to be. Use at your own risk.

System Requirements

  • Bash
  • PHP
  • Smarty (Note: Smarty’s libraries must be in PHP’s path)


    On Debian/Ubuntu/Xandros you can install these via:

    $ sudo aptitude install php5-cli bash smarty

    To add the Smarty libraries to PHP’s path you have to edit /etc/php5/cli/php.ini
    Backup the original php.ini:

    $ sudo cp /etc/php5/cli/php.ini /etc/php5/cli/php.ini.orig

    Now open /etc/php5/cli/php.ini and locate the line that looks like this:
    ; include_path = “.:/usr/share/php”

    Change it to:
    include_path = “.:/usr/share/php:/usr/share/php/smarty”

Quick Start User Guide

Things have to be set up exactly right for the compiler to succeed. Error messages are not as descriptive as they should be. Back up your work before you run the compiler. Good luck. (More detailed documentation is on its way.)

Configure Your User Scripts

Good things come to those who follow the directions.

Step 1. In the project’s _input directory, create a folder named after your extension without spaces, all lowercase, i.e.:

$ mkdir mygreatextension

Step 2. Copy the config.inc.php file into your new directory. (Copy a sample from any of the _input subdirectories into your new directory.) In it, fill in your extension’s name, description, GUID, homepage, Firefox’s min and max version compatibility, update URL, and help message. For example:

'name'=>"Better Gmail 2",

'description'=>"Enhances Gmail with a compilation of useful features written by Greasemonkey user script developers. All scripts copyright their original authors. Click on the script homepage in the Help tab for more information.",

'creator'=>"Gina Trapani  (All user scripts copyright their original authors)",

'guid'=>'123456789',

'homepage'=>"http://ginatrapani.org/workshop/firefox/bettergmail2/",

'minVersion'=>'1.5',

'maxVersion'=>'3.1b3',

'updateURL'=>'https://secure.ginatrapani.org/workshop/firefox/update.rdf',

'helpMsg'=>'Refresh Gmail to apply your changes.',

Step 3. (Optional) Save a 32×32 pixel icon.png file in your new directory, which will appear as your extension’s icon.

Step 4. Make a user_scripts subdirectory, and copy all the user scripts you want to include in your extension into it.

Step 5. For each user script, add @author, @homepage, @enabledbydefault, @tab parameters, all of which will show up in your extension’s options dialog. For example, each user script should have a header that looks like this:

	// ==UserScript==
	// @name           An Awesome User Script
	// @description	   This script injects awesomeness into web pages.
	// @include        http://example.com/awesome/*
	
	// @homepage          http://example.com/awesome-user-script-homepage
	// @author            Jill Smith, Jack Jones
	// @tab               General
	// @enabledbydefault  true
	// ==/UserScript==

If the script conflicts with another script, add an @conflict parameter and set it to the other script’s short name. (If the other script is called conflictinducer.user.js, then the line should be @conflict conflictinducer.)

Run the Compiler

To run the compiler, make compile.sh executable, and run it, i.e.:

$ chmod +x compile.sh
$ ./compile.sh bettergmail2 1.8

Here’s more on the command usage:

Usage: compile.sh extension_short_name version_number [package_mode]
Short name:
  Extension "short name" is also the name of the folder where its files live, 
  all lower case, without spaces (i.e., bettergmail2)
Version number:
  Version number (i.e., 1.0 or 2.3)
Package mode: dist | test | amo
  dist for installable xpi (most common, default if not specified)
  test for deflated version for testing
  amo for installable xpi without an updateURL (for uploading to Mozilla Add-ons)