summaryrefslogtreecommitdiff
path: root/README
blob: 96be739efc9357ae467e79f55150e9d64057941e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
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
 - 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

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!


=== med-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:

$ med-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.


=== med-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 med-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:

$ med-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.