sup annotate README @ rev 47

Improve package info
author Christophe Lincoln <pankso@slitaz.org>
date Fri Mar 10 10:11:59 2017 +0100 (2017-03-10)
parents d86e4e894a97
children 8b0596f22f98
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 ================================================================================