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