Tell people to run maemo-optify-deb with fakeroot.
[maemo-af:maemo-optify.git] / README
1 These are some tools to make moving file into /opt convenient for
2 Debian packages.  This is useful on Maemo 5 since /opt is on a
3 different partition than / and has much more space.
4
5 * Overview
6
7 ** maemo-optify
8
9 The maemo-optify tool works on a Debian package in unpacked form.
10 This is a directory as it is created by debian/rules just before
11 calling dpkg-deb.  It will move selected files to /opt/maemo/ and
12 replace the originals with symbol links to the new location.  You can
13 call it from debian/rules right before dh_builddep, for example.
14
15 ** maemo-optify-deb
16
17 The maemo-optify-deb tool works on a Debian package itself.  It will
18 unpack it, maybe run maemo-optify, and pack it up again.
19
20 When passing the --auto option, maemo-optify-deb will read some
21 configuration information from a freshly built source package in front
22 of it and will perform the requested optifications.  See below for how
23 to control this.
24
25 * Optification from debian/rules
26
27 You can put a call to "maemo-optify" into debian/rules, immediately
28 after dh_gencontrol or equivalent, like this:
29
30     maemo-optify PACKAGE DIR
31
32 where PACKAGE is the name of the binary package that you want to
33 optify, and DIR is the directory with the files of the package.  If
34 you omit DIR, it defaults to "debian/PACKAGE".  (The name of the
35 package is needed for the heuristics that maemo-optify performs.)
36
37 If you omit PACKAGE as well, maemo-optify will work on all packages
38 that are listed in debian/control.
39
40 * Optification of .deb files
41
42 Optification of an existing .deb archive file is as simple as
43
44     $ fakeroot maemo-optify-deb package.deb
45
46 This will modify package.deb in place.  (The fakeroot is there to make
47 sure that the files keep their original permissions and ownership
48 information.)
49
50 * Control
51
52 You can control the tools with the "debian/optify" file in your source
53 package.  Right now, it can only contain a single word that determines
54 the "mode" for 'maemo-optify-deb --auto'.  The mode can be one of the
55 following:
56
57  - none
58  
59  No optification is done.
60  
61  - all
62
63  All packages listed in debian/files are optified.
64
65  - auto
66
67  Some of the packages listed in debian/files are optified, based on
68  some heuristic.  The heuristic is designed to make "auto" a useful
69  default mode that works with almost all packages.
70
71 When in "auto" mode, maemo-optify-deb will investigate each package to
72 decide whether to optify it or not.  Right now, a package is not
73 optified in this case when it already contains the "/opt" directory,
74 or when it looks like it might be a Python package.
75
76 When debian/optify does not exist, the default mode is taken from the
77 MAEMO_OPTIFY_DEFAULT_MODE environment variable.  When that variable is
78 not set either, the mode is "none".
79
80 Maemo-optify has a heuristic for selecting which files to move.  By
81 default, it will never move files that are less than 2kb and it will
82 only move directories that have the same name as the package.  In the
83 future, this might be controllable from debian/<package>.optify files.
84
85
86 TODO
87
88 - Read debian/<package>.optify in maemo-optify and get things like
89   threshold and whitelists / blacklists from it.
90
91 - Add option to maemo-optify for the package name so that it doesn't
92   need to be guessed from the directory.
93
94 - Make maemo-optify-deb robust and give it an option to not overwrite
95   the package in place.