sup annotate README @ rev 36

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