~mozillateam/mozilla-devscripts/mozilla-devscripts

mozilla-devscripts is a collection of scripts based on Makefile inheritance

usable by Mozilla packages in Ubuntu.

- mozclient is an abstract tarball creator which provides a get-new-orig

  target

- compare is an install checker looking for missing files

- minefield-packager creates debs from Firefox (official) nightly built

  tarballs

- xpi provides hooks to help package extensions in an elegant way

- lp-locale-export is an helper for translations in launchpad for mozilla

  products and extensions

============================================================================

The package contains rules for the following projects:

 - firefox-3.0

 - firefox-3.1

 - firefox-4.0

 - fennec

 - lightning-sunbird (from MOZILLA_1_8_BRANCH)

 - nspr

 - nss

 - seamonkey-2.0

 - thunderbird (2.0, from MOZILLA_1_8_BRANCH)

 - thunderbird-3.0

 - xulrunner (1.8, from MOZILLA_1_8_BRANCH)

 - xulrunner-1.9

 - xulrunner-1.9.1

 - xulrunner-2.0

 - midbrowser

 - prism

 - flock

In addition there is a xpi.mk which provides standard rules/targets to package

XPI extensions for mozilla/toolkit based applications.

=== mozclient ===

Creates a source tarball from a VCS

A clean-up script, called "remove.binonly.sh", is called to remove all

binary-only files. It is applied to all projects before packing.

Optionally, $(project)-remove.binonly.sh is also applied.

Traces of the cleaning are preserved inside that resulting tarball

in REMOVED+nobinonly.txt. If nothing has been removed, both the log and

the "+nobinonly" signature are dropped.

To use :

- in debian/control: add mozilla-devscripts to Build-Depends

- in debian/rules: add "include /usr/share/mozilla-devscripts/yourproject.mk"

Note: it is also possible to keep all project files outside of mozilla-devscripts.

To do so, mozclient needs two variables:

- MOZCLIENT_PROJECTNAME: the name of the conf file as described below, without the

  ".conf" extension

- MOZCLIENT_PROJECTDIR: a directory containing the project specific files to be used

  by mozclient. It is not a recommended to use the debian directory directly because

  there will be a confusion between debian/patches and $(MOZCLIENT_PROJECTDIR)/patches

ex:

  in debian/rules:

    MOZCLIENT_PROJECTNAME  = myproject

    MOZCLIENT_PROJECTDIR   = debian/mozclient

    include /usr/share/mozilla-devscripts/mozclient.mk

  in debian/mozclient:

    - a mandatory file called myproject.conf

    - an optional patches directory

    - an optional myproject-remove.binonly.sh file

The following targets are then available to the caller of debian/rules:

- get-orig-source

   Build a tarball according to parameters from project.mk

   and optionally using either DEBIAN_DATE or DEBIAN_TAG, and optionally

   DEBIAN_BRANCH

- list-tags

   List all the registered VCS tags from upstream server

The caller could specify the following parameters:

DEBIAN_DATE in the form YYYYMMDDtHHMM

 ex: DEBIAN_DATE=20070911t1711

or

DEBIAN_TAG in the form CVS_TAG=debian_version

 ex: DEBIAN_TAG=FIREFOX_3_0b2_RC1=3.0~b2~rc1

Optionally:

DEBIAN_KEEP_VCS to preserve the VCS files (*/CVS, .hg, ...)

 ex: DEBIAN_KEEP_VCS=1

LOCAL_BRANCH=/foo/bar/baz to point to a local branch instead of

the configured remote one. It is faster if you have to publish

tarballs quite often from this branch, such as daily snapshots.

The local branch will be updated first.

Note that the getdate are still remote so you need network connectivity.

Projects files are stored in /usr/share/mozilla-devscripts/mozclient

as .conf files. They contain the following parameters:

- MOZCLIENT_APPNAME (mandatory): package name

- MOZCLIENT_MODULES (optional): list of modules/directories for direct checkout

- MOZCLIENT_VCS (mandatory): VCS (hg, git, cvs, svn..)

- MOZCLIENT_VCS_LOC (mandatory): VCS location (cvs loc, url, ...)

- MOZCLIENT_PROJECT (optional): VCS project name. If $(NULL), then

  $(MOZCLIENT_MODULES) becomes mandatory

- MOZCLIENT_BRANCH (optional): VCS branch name

- MOZCLIENT_POSTCOCMD (optional): a shell command that is executed after checkout

- MOZCLIENT_FILE (mandatory): source file containing the version

- MOZCLIENT_GETVERSION (mandatory): how to transform the version

- MOZCLIENT_GETDATE (mandatory): get the last commit date for the project

- MOZCLIENT_SEPARATOR (optional): separator between version and date (default: ~)

- MOZCLIENT_TAREXCLUDE (optional): list of additional dirs/files to exclude

  from packaging

- MOZCLIENT_EMBEDDED (optional): create an embedded tarball (default: 0)

- MOZCLIENT_WANTMOZDIR (optional): should the root dir be 'mozilla'?

  (default: 0 unless MOZCLIENT_EMBEDDED=1)

- MOZCLIENT_WANTPATCH (optional): should we use the patch system? (default: 0)

- MOZCLIENT_DYNTAG (optional): paired with MOZCLIENT_DYNTAG_FILES, a shell

  command that is executed to get a VCS tag

- MOZCLIENT_DYNTAG_FILES (optional): list of files to get before calling

  MOZCLIENT_DYNTAG

Example with firefox-3.0:

- in debian/control, add mozilla-devscripts to Build-Depends

- in debian/rules, add:

   include /usr/share/mozilla-devscripts/firefox-3.0.mk

That's it. You've gained get-orig-source.

You can now call it:

- debian/rules get-orig-source

  => firefox-3.0_3.0~b2~cvs20071120t1456+nobinonly.orig.tar.gz

- debian/rules get-orig-source DEBIAN_DATE=20070914t1713

  => firefox-3.0_3.0~a8~cvs20070914t1713+nobinonly.orig.tar.gz

- debian/rules get-orig-source DEBIAN_TAG=FIREFOX_3_0b2_RC1=3.0~b2~rc1

  => firefox-3.0_3.0~b2~rc1+nobinonly.orig.tar.gz

=== compare ===

Compares installed files and debs content

The following target is available to the caller:

compare: check the difference between:

a/ what has been built (in dists/bin) and what has been installed (in debian/tmp)

b/ what has been installed (in debian/tmp) and what has been put in the debs

dists/bin is populated by the upstream build system

debian/tmp is populated according to upstream installer/package-static files

The following variable are available:

COMPARE_FILTER_PRE_IN and COMPARE_FILTER_PRE_OUT (for a/)

COMPARE_FILTER_IN and COMPARE_FILTER_OUT (for b/)

By default, all are 'sed' commands that could be augmented (+=) or

overwritten by the caller.

To use (if not already done for another mozilla-devscripts script)

- in debian/control: add mozilla-devscripts to Build-Depends

- in debian/rules: add "include /usr/share/mozilla-devscripts/yourproject.mk"

Example of COMPARE_FILTER_IN tweak:

COMPARE_FILTER_IN += \

  -e 's,^usr/lib/seamonkey-2.0/extensions/{f13b157f-b174-47e7-a34d-4815ddfdfeb8}.*,,' \

  $(NULL)

=== minefield-packager ===

minefield-packager creates debs from Firefox nightly built tarballs available

on mozilla web/ftp site. Those builds are often useful to check a regression

and to determine if a bug is Ubuntu specific or if it is also affecting

upstream builds. The deb produced are for testing purpose only, please don't

report bugs in Launchpad about those.

Example:

(from a writable directory)

$ make -f /usr/share/mozilla-devscripts/minefield-packager.mk

$ sudo dpkg -i firefox-minefield_3.0~b5~build2008032304-1_i386.deb

You can also ask for a particular snapshot by adding DEBIAN_DATE=id,

where id is one of the date returned by the 'list' command:

$ make -f /usr/share/mozilla-devscripts/minefield-packager.mk list

Available snapshots are:

2008-02-27-04   04-Mar-2008 19:31

2008-02-27-14   28-Feb-2008 07:30

2008-02-27-18   28-Feb-2008 04:53

2008-02-28-04   06-Mar-2008 04:56

...

2008-03-28-04   29-Mar-2008 05:03

2008-03-28-05   29-Mar-2008 06:57

2008-03-29-04   29-Mar-2008 06:50

latest  29-Mar-2008 06:50

$ make -f /usr/share/mozilla-devscripts/minefield-packager.mk DEBIAN_DATE=2008-03-28-04

$ sudo dpkg -i firefox-minefield_3.0~build2008032804-1_i386.deb

=== xpi.mk ===

targets:

---------

 install-xpi - unpack and install the contents of the .xpi file to the

               package named by the MOZ_EXTENSION_PKG parameter

 clean-xpi   - clean build cruft from install-xpi

parameters:

------------

 MOZ_EXTENSION_PKG - the binary package that will ship the extension

 MOZ_XPI_FILE      - the XPI file to unpack and install to the binary package

                     named by MOZ_EXTENSION_PKG. If not set, xpi.mk will use

                     the first |*.xpi| file found in the packages top level

                     directory

 MOZ_XPI_EMID      - use the given EMID to name the links in the applications

                     |extensions| directory. If not set, xpi.mk will try to

                     guess the right EMID by introspecting the |install.rdf|

                     shipped by the XPI

 MOZ_XPI_BUILD_COMMAND

                   - use the given command _before_ running the normal

                     |install-xpi| procedure. This parameter is useful for all

                     those extension sources that have a command/make target

                     to produce a XPI. If a developer doesn't provide the

                     command, the default one will be used.

 MOZ_XPI_MOZILLA_DIRS

                   - link the extension to the global |extensions| directory

                     of the given MOZILLAs. The default value is |firefox| and

                     |firefox-addons|, which will link the extension to the

                     /usr/lib/firefox/extensions and /usr/lib/firefox-addons/extensions

                     directories, respectively.

cdbs:

------

 If you are using cdbs (debhelper.mk) xpi.mk hooks in appropriately.

 cdbs targets to build the packages without any rule. The only thing required

 is to include the debhelper.mk from cdbs _before_ including xpi.mk.

examples:

----------

 A template is available in the branch available under the following URL:

   https://code.launchpad.net/~mozillateam/firefox-extensions/XPI.TEMPLATE

=== lp-locale-export.mk ===

Include this helper if you want to translate your mozilla application or extension

through launchpad.

XXX: document here!

=== xpi-unpack ===

This script unpacks XPI file to the provided output directory. After unpacking

the XPI file, it will look for JAR files in the output directory. All JAR files

will be unpacked to $JAR_FILE with "!" appended. For example, "test.jar" is

unpacked to "test.jar!" directory. After unpacking, the script removes all JAR

files.

To run it, pass the name of the XPI file, and the name of the output directory:

$ xpi-unpack ubufox.xpi output

In case some of the parameters are missing, input XPI file doesn't exist, or

output directory already exists, it will report an error and exit.

=== xpi-pack ===

This script prepares a XPI file from the provided input directory. First, it

will look for all unpacked JAR files in the input directory. Directories with

the unpacked JAR files have the format explained in xpi-unpack section. The

script will pack the contents of the directory to the JAR file, named like the

JAR directory, with stripped "!" sign. For example, contents of "test.jar!" are

packed to "test.jar" file. After that, it will remove all JAR directories.

Finally, it will pack the contents of the input directory to the XPI file,

which is placed inside the provided input directory. This behaviour is because

xpi.mk will look for XPI file inside top-level extension directory, which is

the input directory in that case. The script doesn't pack debian/ and temp-*/

directories to the XPI file. After XPI file is produced, it will unpack all JAR

files, in order to leave intact source.

To run it, pass the name of the input directory, and the name of the XPI file:

$ xpi-pack . ubufox.xpi

In case some of the parameters are missing, or input directory doesn't exist,

it will report an error and exit.