sup annotate README @ rev 1

Improve README
author Christophe Lincoln <pankso@slitaz.org>
date Fri Feb 24 06:24:54 2017 +0100 (2017-02-24)
parents 798dc81db13b
children ea32afc2e4da
rev   line source
pankso@0 1 SliTaz Users Packages
pankso@0 2 ================================================================================
pankso@0 3
pankso@1 4 CURRENT : cook extract and install work nicely.
pankso@0 5
pankso@0 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
pankso@0 8 as scripts, non free tools, icons, wallpapers, templates, pre-compiled binary,
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
pankso@0 12 This let user get involve in the project without coding skills, sup provide a
pankso@0 13 cmdline tool and a GTK+ interface to install and build packages. The server
pankso@0 14 provide a CGI web interface to upload packages receipt and files. The build
pankso@0 15 is a simple pack without compilations since the idea is to provide custom
pankso@0 16 tools using scripting languages or precompiled packages such as Firefox.
pankso@0 17
pankso@0 18 Sup will be also usefull in live mode with a persistent home mounted so users
pankso@0 19 will have installed sup packages 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@0 26 2) Change dir and become root:
pankso@0 27 $ cd sup && su
pankso@0 28 3) Install clients as root:
pankso@0 29 $ make && make install-clients
pankso@0 30 4) Play :-)
pankso@0 31 $ sup help
pankso@0 32
pankso@0 33
pankso@0 34 Where goes what ?
pankso@0 35 --------------------------------------------------------------------------------
pankso@0 36
pankso@0 37 * sup Client side cmdline tool to install and cook packages
pankso@0 38 --> /usr/bin/sup
pankso@0 39 * sup-box GTK+ Client side user iinterface to manage packages
pankso@0 40 --> /usr/bin/sup-box
pankso@0 41 * libsup.sh Shared SHell function between sup tools
pankso@0 42 --> /usr/lib/slitaz/libsup.sh
pankso@0 43 * server Server side web interface: TinyCM/SCN plugin
pankso@0 44 --> http://scn.slitaz.org/?sup
pankso@0 45
pankso@0 46
pankso@0 47 Development environment
pankso@0 48 --------------------------------------------------------------------------------
pankso@0 49 It's easy to work on sup code, commands will talk by them self:
pankso@0 50
pankso@0 51 --> Cmdline client
pankso@0 52 $ hg clone http://hg.slitaz.org/sup
pankso@0 53 $ cd sup && ./sup
pankso@0 54
pankso@0 55 --> Server side needs lighttpd & TinyCM install
pankso@0 56 $ make DESTDIR=/home/tux/Public/cgi-bin/tinycm server-install
pankso@0 57 $ tazweb http://localhost/~tux/cgi-bin/tinycm/?sup
pankso@0 58
pankso@0 59
pankso@0 60 Developers coding style
pankso@0 61 --------------------------------------------------------------------------------
pankso@0 62 Keep sup simple, clean and fast. Sup tools are written in SHell script, ther
pankso@0 63 use libtaz.sh and httphelper.sh functions. Sup use XDG directories paths to
pankso@0 64 store packages information and build process:
pankso@0 65
pankso@0 66 ~/.local User data, executables and sup database
pankso@0 67 ~/.cache Non-essiential data such as tmp and build files
pankso@0 68 ~/.config Peer user configuration files
pankso@0 69
pankso@0 70
pankso@0 71 Packages format and max size
pankso@0 72 --------------------------------------------------------------------------------
pankso@0 73 Sup packages are cpio archive compressed with lzma and with a .sup extension.
pankso@0 74 The goal is to have lightweight packages with every big file downloaded from
pankso@0 75 the web.
pankso@0 76
pankso@0 77 Sup use a minimal 'receipt' with an sup_install() function to dl any wanted
pankso@0 78 files, no pkg size or file list are created when packing. A list of installed
pankso@0 79 files is generated at install.
pankso@0 80
pankso@0 81 Package can have a single receipt or a local/ folder with files to install. All
pankso@0 82 download and extracting must be done in the cache to build-up a list of files
pankso@0 83 before installing. The package folder tree should look like that:
pankso@0 84
pankso@0 85 * receipt Sup package receipt
pankso@0 86 * README Optional sup package desc/howto
pankso@0 87 * files For all installed files
pankso@0 88
pankso@0 89 files/
pankso@0 90 |- local/bin For executable binaries and scripts
pankso@0 91 |- local/share/XXX Where XXX is the name of the package
pankso@0 92 |- local/share/applications All .desktop files for menu entry
pankso@0 93 ` config/ For any configuration file in ~/.config
pankso@0 94
pankso@0 95 More directories into files/ can be added accourding to the needs and goal
pankso@0 96 of the packages
pankso@0 97
pankso@0 98 Receipt variables and function
pankso@0 99 --------------------------------------------------------------------------------
pankso@0 100 Her is the variables used or usable in sup receipt as well as the uniq function.
pankso@0 101 Checkout the sup-demo package for a receipt example.
pankso@0 102
pankso@0 103 * $build_date Auto added by 'sup cook' to get the build date
pankso@0 104 * $sup_size Auto added by 'sup cook' to get installed size
pankso@0 105
pankso@0 106
pankso@0 107 Packages dependencies
pankso@0 108 --------------------------------------------------------------------------------
pankso@0 109 Since sup is not run as root, less deps is better but some precompiled packages
pankso@0 110 will need some system wide tools/libraries, sup will not install any system wide
pankso@0 111 package but warn is dependencies are not installed if DEPENDS is set.
pankso@0 112
pankso@0 113 Sup packages can be very simple but also very complex, so feel free to use the
pankso@0 114 receipt to warn or promt users to make an action.
pankso@0 115
pankso@0 116
pankso@0 117 Cook sup packages to be uploaded to server
pankso@0 118 --------------------------------------------------------------------------------
pankso@0 119 Sup let users upload package to server. To cook your first one you may want to
pankso@0 120 the sup-demo package:
pankso@0 121
pankso@0 122 $ sup cook --init
pankso@0 123 $ cp -rf /usr/share/sup/wok/sup-demo ~/.local/share/sup/wok
pankso@0 124 $ sup cook sup-demo
pankso@0 125
pankso@0 126
pankso@0 127 Mime type & Icon
pankso@0 128 --------------------------------------------------------------------------------
pankso@0 129 The *.sup file are reconised by the system as sup packages using an mime type
pankso@0 130 XML file installed in /usr/share/mime/packages/sup.xml. When data/mime/sup.xml
pankso@0 131 is newly installed you can update the mime database:
pankso@0 132
pankso@0 133 $ update-mime-database /usr/share/mime/
pankso@0 134
pankso@1 135 Sup use a generic icon: application-x-archive
pankso@0 136
pankso@0 137
pankso@0 138 Translations
pankso@0 139 --------------------------------------------------------------------------------
pankso@0 140 To start a new translation please use msginit from the pot file directory.
pankso@0 141 Example for French/France locale (fr_FR):
pankso@0 142
pankso@0 143 $ msginit -l fr_FR -o fr.po -i tazbox.pot
pankso@0 144
pankso@0 145 To update all pot files when some new strings have been added (mainly for
pankso@0 146 developers before commit):
pankso@0 147
pankso@0 148 $ make pot
pankso@0 149
pankso@0 150 To update all translations from the pot file:
pankso@0 151
pankso@0 152 $ make msgmerge
pankso@0 153
pankso@0 154 To compile po files for testing purposes you can use 'make msgfmt' or manually
pankso@0 155 compile your translation. Example for french locale, note that the file must
pankso@0 156 be copied into /usr/share/locale/fr/LC_MESSAGES so gettext can find it:
pankso@0 157
pankso@0 158 $ msgfmt -o sup-client.mo fr.po
pankso@0 159
pankso@0 160
pankso@0 161 ================================================================================