User Guide
This user guide is a work in progress.
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.
- 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”
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.)
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
.)
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)