rev |
line source |
pankso@22
|
1 README for SliTaz Users Packages (SUP)
|
pankso@0
|
2 ================================================================================
|
pankso@0
|
3
|
pankso@0
|
4
|
paul@9
|
5 The goal is to have a user-land packages management system using SHell scripts
|
pankso@0
|
6 to pack and install files. The sup packages can install all kind of files such
|
paul@9
|
7 as scripts, non free tools, icons, wallpapers, templates, pre-compiled binaries,
|
pankso@0
|
8 etc. Sup is designed to handle software that can/should be installed in user
|
pankso@0
|
9 space such as web frameworks.
|
pankso@0
|
10
|
pankso@44
|
11 This lets users get involved in the project without coding skills, sup provides
|
pankso@44
|
12 a cmdline tool and a GTK+ interface to install and build packages. The server
|
paul@9
|
13 provides a CGI web interface to upload packages receipts and files. The build
|
paul@9
|
14 is a simple pack without compilation since the idea is to provide custom
|
pankso@0
|
15 tools using scripting languages or precompiled packages such as Firefox.
|
pankso@0
|
16
|
paul@9
|
17 Sup will be also useful in live mode with a persistent home mounted so users
|
paul@9
|
18 will have sup packages installed without having a too big rootfs in RAM.
|
pankso@0
|
19
|
pankso@39
|
20
|
pankso@0
|
21 Quickstart
|
pankso@0
|
22 --------------------------------------------------------------------------------
|
pankso@0
|
23
|
pankso@0
|
24 1) Get source:
|
pankso@0
|
25 $ hg clone http://hg.slitaz.org/sup
|
pankso@22
|
26
|
pankso@22
|
27 2) Install SUP Tool:
|
pankso@22
|
28 $ cd sup && make
|
pankso@22
|
29 $ sudo make install
|
pankso@22
|
30
|
pankso@22
|
31 3) Play :-)
|
pankso@0
|
32 $ sup help
|
pankso@36
|
33
|
pankso@36
|
34
|
pankso@36
|
35 Cook SUP packages to be uploaded to the server
|
pankso@36
|
36 --------------------------------------------------------------------------------
|
pankso@44
|
37 Sup lets users upload packages to the server. To cook your first one you may want
|
pankso@44
|
38 to use the sup 'new' command:
|
pankso@36
|
39
|
pankso@36
|
40 $ sup -n
|
pankso@36
|
41
|
pankso@0
|
42
|
pankso@44
|
43 Packaging helpers
|
pankso@0
|
44 --------------------------------------------------------------------------------
|
pankso@44
|
45 When creating packages you want to be sure everything goes well and for that you
|
pankso@44
|
46 need testing. Sup provides some helpers to test the package. The sup_install()
|
pankso@44
|
47 function in the receip is the one who will downlaod files, extract tarballs,
|
pankso@44
|
48 move files, etc. All commands MUST be run in the current directory. To run the
|
pankso@44
|
49 sup_install function without installing anything:
|
pankso@0
|
50
|
pankso@44
|
51 $ sup run [package]
|
pankso@0
|
52
|
pankso@0
|
53
|
pankso@44
|
54 If you download big files and want to keep the in cache, you can use in your
|
pankso@44
|
55 receip the variable: ${downloads} wich is set to: ~/.cache/sup/downloads
|
pankso@0
|
56
|
pankso@0
|
57
|
pankso@0
|
58 Packages format and max size
|
pankso@0
|
59 --------------------------------------------------------------------------------
|
paul@9
|
60 Sup packages are cpio archives compressed with lzma and with a .sup extension.
|
pankso@0
|
61 The goal is to have lightweight packages with every big file downloaded from
|
pankso@0
|
62 the web.
|
pankso@0
|
63
|
pankso@22
|
64 Sup uses a minimal 'receip' with a sup_install() function to dl any wanted
|
pankso@0
|
65 files, no pkg size or file list are created when packing. A list of installed
|
pankso@0
|
66 files is generated at install.
|
pankso@0
|
67
|
pankso@22
|
68 Packages can have a single receip or a local/ folder with files to install. All
|
paul@9
|
69 downloading and extracting must be done in the cache to build up a list of files
|
paul@9
|
70 before installing. The package folder tree should look like this:
|
pankso@0
|
71
|
pankso@22
|
72 * receip SUP package receip (receip NOT receipt ;-)
|
pankso@0
|
73 * README Optional sup package desc/howto
|
pankso@0
|
74 * files For all installed files
|
pankso@0
|
75
|
pankso@0
|
76 files/
|
pankso@0
|
77 |- local/bin For executable binaries and scripts
|
pankso@0
|
78 |- local/share/XXX Where XXX is the name of the package
|
pankso@0
|
79 |- local/share/applications All .desktop files for menu entry
|
pankso@44
|
80 |- config/ For any configuration file in ~/.config
|
pankso@44
|
81 ` icons/ Applications icons folder
|
pankso@0
|
82
|
paul@9
|
83 More directories into files/ can be added according to the needs and goals
|
pankso@44
|
84 of the packages. The packages you can upload are limited to a few MB, please
|
pankso@44
|
85 download big files on installation.
|
pankso@0
|
86
|
pankso@36
|
87
|
pankso@0
|
88 Receipt variables and function
|
pankso@0
|
89 --------------------------------------------------------------------------------
|
pankso@44
|
90 Here are the variables used or usable in a sup receip as well as the uniq
|
pankso@44
|
91 function. Check out the sup-demo package for a receip example.
|
pankso@0
|
92
|
pankso@0
|
93 * $build_date Auto added by 'sup cook' to get the build date
|
pankso@0
|
94 * $sup_size Auto added by 'sup cook' to get installed size
|
pankso@0
|
95
|
pankso@0
|
96
|
pankso@0
|
97 Packages dependencies
|
pankso@0
|
98 --------------------------------------------------------------------------------
|
pankso@44
|
99 Since sup is not run as root, less deps is better - but some precompiled
|
pankso@44
|
100 packages will need some system wide tools/libraries, sup will not install any
|
pankso@44
|
101 system wide packages but warns if dependencies are not installed if DEPENDS is
|
pankso@44
|
102 set.
|
pankso@0
|
103
|
pankso@0
|
104 Sup packages can be very simple but also very complex, so feel free to use the
|
pankso@22
|
105 receip to warn or prompt users to make an action.
|
pankso@0
|
106
|
pankso@0
|
107
|
pankso@44
|
108 Development environment
|
pankso@44
|
109 --------------------------------------------------------------------------------
|
pankso@44
|
110 It's easy to work on sup code, commands will talk by themselves:
|
pankso@44
|
111
|
pankso@44
|
112 --> Cmdline client
|
pankso@44
|
113
|
pankso@44
|
114 $ hg clone http://hg.slitaz.org/sup
|
pankso@44
|
115 $ cd sup && ./sup
|
pankso@44
|
116
|
pankso@44
|
117 --> Server side needs lighttpd & TinyCM install
|
pankso@44
|
118
|
pankso@44
|
119 $ make DESTDIR=/home/tux/Public/cgi-bin/tinycm server-install
|
pankso@44
|
120 $ tazweb http://localhost/~tux/cgi-bin/tinycm/?sup
|
pankso@44
|
121
|
pankso@44
|
122
|
pankso@44
|
123 Source tree: What goes where ?
|
pankso@44
|
124 --------------------------------------------------------------------------------
|
pankso@44
|
125
|
pankso@44
|
126 * sup Client side cmdline tool to install and cook packages
|
pankso@44
|
127 --> /usr/bin/sup
|
pankso@44
|
128 * sup-box GTK+ Client side user interface to manage packages
|
pankso@44
|
129 --> /usr/bin/sup-box
|
pankso@44
|
130 * libsup.sh Shared SHell function between sup tools
|
pankso@44
|
131 --> /usr/lib/slitaz/libsup.sh
|
pankso@44
|
132 * server Server side web interface: TinyCM/SCN plugin
|
pankso@44
|
133 --> http://scn.slitaz.org/?sup
|
pankso@44
|
134
|
pankso@44
|
135
|
pankso@44
|
136 Developers coding style
|
pankso@44
|
137 --------------------------------------------------------------------------------
|
pankso@44
|
138 Keep sup simple, clean and fast. Sup tools are written in SHell script, they
|
pankso@44
|
139 use libtaz.sh and httphelper.sh functions. Sup uses XDG directories paths to
|
pankso@44
|
140 store packages' information and build process:
|
pankso@44
|
141
|
pankso@44
|
142 ~/.local User data, executables and sup database
|
pankso@44
|
143 ~/.cache Non-essential data such as tmp and build files
|
pankso@44
|
144 ~/.config Peer user configuration files
|
pankso@44
|
145 ~/.icons Applications icons used by XDG *.desktop files
|
pankso@44
|
146
|
pankso@44
|
147
|
pankso@36
|
148 Colors shems for sup tools
|
pankso@0
|
149 --------------------------------------------------------------------------------
|
pankso@36
|
150 Here are the colors guide line used in the cmdline tool:
|
pankso@36
|
151
|
pankso@36
|
152 [036/36] Cyan for installed/mirror
|
pankso@36
|
153 [035/35] Magenta for cook/wok
|
pankso@47
|
154 [033/33] Yellow for commands/functions/info()
|
pankso@36
|
155
|
pankso@36
|
156 The CGI/Web hug services match SCN/SliTaz network graphical style.
|
pankso@0
|
157
|
pankso@0
|
158
|
pankso@0
|
159 Mime type & Icon
|
pankso@0
|
160 --------------------------------------------------------------------------------
|
paul@9
|
161 The *.sup file are recognised by the system as sup packages using a mime type
|
pankso@0
|
162 XML file installed in /usr/share/mime/packages/sup.xml. When data/mime/sup.xml
|
pankso@0
|
163 is newly installed you can update the mime database:
|
pankso@0
|
164
|
pankso@0
|
165 $ update-mime-database /usr/share/mime/
|
pankso@0
|
166
|
paul@9
|
167 Sup uses a generic icon: application-x-archive
|
pankso@0
|
168
|
pankso@0
|
169
|
pankso@0
|
170 Translations
|
pankso@0
|
171 --------------------------------------------------------------------------------
|
pankso@0
|
172 To start a new translation please use msginit from the pot file directory.
|
pankso@0
|
173 Example for French/France locale (fr_FR):
|
pankso@0
|
174
|
pankso@0
|
175 $ msginit -l fr_FR -o fr.po -i tazbox.pot
|
pankso@0
|
176
|
pankso@0
|
177 To update all pot files when some new strings have been added (mainly for
|
pankso@0
|
178 developers before commit):
|
pankso@0
|
179
|
pankso@0
|
180 $ make pot
|
pankso@0
|
181
|
pankso@0
|
182 To update all translations from the pot file:
|
pankso@0
|
183
|
pankso@0
|
184 $ make msgmerge
|
pankso@0
|
185
|
pankso@0
|
186 To compile po files for testing purposes you can use 'make msgfmt' or manually
|
pankso@0
|
187 compile your translation. Example for french locale, note that the file must
|
pankso@0
|
188 be copied into /usr/share/locale/fr/LC_MESSAGES so gettext can find it:
|
pankso@0
|
189
|
pankso@0
|
190 $ msgfmt -o sup-client.mo fr.po
|
pankso@0
|
191
|
pankso@0
|
192
|
pankso@0
|
193 ================================================================================
|