tazpkg annotate README.devel @ rev 949
modules/get, modules/install: use "release checksum" too, as defined in packages.info field #9.
Checksum from packages.md5 used in verifying downloaded package file, while checksum in packages.info[$9] used in updates checking.
Checksum from packages.md5 used in verifying downloaded package file, while checksum in packages.info[$9] used in updates checking.
author | Aleksej Bobylev <al.bobylev@gmail.com> |
---|---|
date | Thu Jul 20 22:40:46 2017 +0300 (2017-07-20) |
parents | bbc6b0a453a7 |
children |
rev | line source |
---|---|
al@822 | 1 README file for TazPkg developers |
al@822 | 2 ================================= |
al@822 | 3 |
al@822 | 4 |
al@822 | 5 Desktop integration |
al@822 | 6 ------------------- |
al@822 | 7 |
al@822 | 8 mimeapps.list: this file deprecated and not installed |
al@822 | 9 https://wiki.archlinux.org/index.php/Default_applications |
al@822 | 10 (Also, defaults.list deprecated.) |
al@822 | 11 |
al@822 | 12 MIME-type "x-scheme-handler/tazpkg" already listed in the tazpkg-url.desktop |
al@822 | 13 |
al@822 | 14 |
al@822 | 15 Categories for .desktop files are listed here: |
al@822 | 16 http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html |
al@822 | 17 |
al@822 | 18 tazpanel-pkgs.desktop: sub-category PackageManager -> category Settings |
al@822 | 19 |
al@822 | 20 |
al@822 | 21 TazPkg modules |
al@822 | 22 -------------- |
al@822 | 23 |
paul@943 | 24 About 4,000 lines of code is too big to effectively maintain in a single file. |
al@822 | 25 |
al@822 | 26 Linux way [https://en.wikibooks.org/wiki/Linux_Guide/How_Linux_Works]: |
al@822 | 27 > The Linux Way can be summarized as: |
al@822 | 28 > * Use programs that do only one task, but do it well. |
al@822 | 29 > * To accomplish complex tasks, use several programs linked together. |
al@822 | 30 > * Store information in human-readable plain text files whenever it is |
al@822 | 31 > possible. |
al@822 | 32 > * There is no "one true way" to do anything. |
al@822 | 33 > * Prefer commandline tools over graphical tools. |
al@822 | 34 |
paul@943 | 35 It is decided to split single tazpkg code into a few independent modules. |
al@822 | 36 |
paul@943 | 37 Goals: not to scroll thousands of lines to move back and forth to the internal |
al@822 | 38 tazpkg functions and to the main tazpkg code; knowledge that single code |
paul@943 | 39 changing in the one place will not have side effects in the other place; reduce |
al@822 | 40 the barrier to entry for new developers. |
al@822 | 41 |
al@822 | 42 |
paul@943 | 43 Best place to fit tazpkg modules is /usr/libexec directory. |
al@822 | 44 http://www.linuxbase.org/betaspecs/fhs/fhs/ch04s07.html |
al@822 | 45 |
al@822 | 46 > /usr/libexec includes internal binaries that are not intended to be executed |
al@822 | 47 > directly by users or shell scripts. Applications may use a single subdirectory |
al@822 | 48 > under /usr/libexec. |
al@822 | 49 |
al@822 | 50 > Applications which use /usr/libexec in this way must not also use /usr/lib to |
al@822 | 51 > store internal binaries, though they may use /usr/lib for the other purposes |
al@822 | 52 > documented here. |
al@822 | 53 |
paul@943 | 54 So, the directory for tazpkg modules is /usr/libexec/tazpkg/. |
al@822 | 55 It is out of the PATH, so modules will not interfere with original Linux |
al@822 | 56 commands and will not autocomplete in the terminal. Nothing changed with the |
al@822 | 57 user experience: it is still single tazpkg. |
al@822 | 58 |
al@822 | 59 |
al@822 | 60 To execute module we need to know full path to the module. |
al@822 | 61 We can use simple names for modules such as "help", "convert", "list", etc. |
al@822 | 62 |
al@822 | 63 |
al@822 | 64 Directory variables |
al@822 | 65 ------------------- |
al@822 | 66 |
al@822 | 67 Many programs can be configured using variables such as prefix, docdir, etc.: |
al@822 | 68 make prefix=/usr install |
al@822 | 69 |
al@822 | 70 All variables are in lower case (only DESTDIR is in upper case). See more here: |
al@822 | 71 https://www.gnu.org/prep/standards/html_node/Directory-Variables.html |
al@822 | 72 |
al@822 | 73 Makefile contains variables support with default values. |
al@822 | 74 Default prefix=/usr, all other variables are defaults to values described |
al@822 | 75 at the given link. |
al@822 | 76 |
al@822 | 77 |
al@822 | 78 Code commenting |
al@822 | 79 --------------- |
al@822 | 80 |
paul@943 | 81 Developer comments are very important to understand how the program works. |
paul@943 | 82 But these comments are useless to the end user and they just increase the size |
al@822 | 83 of the scripts without making any changes to the script business logic. It also |
paul@943 | 84 increases the size of the scripts that includes shared "libs" such as libtaz.sh. |
al@822 | 85 |
paul@943 | 86 We can strip all the comments from installed scripts, leaving those comments |
al@822 | 87 for developers in the SliTaz Hg repositories. |
al@822 | 88 |
paul@943 | 89 We need only to leave "#!/bin/sh" line and one or two lines of comments describing |
al@822 | 90 what it is and where you can find the original scripts if you want to develop |
al@822 | 91 them. |
al@822 | 92 |
al@822 | 93 |
al@822 | 94 Tests |
al@822 | 95 ----- |
al@822 | 96 |
al@822 | 97 Tests are the important part of the development process. TazPkg development is |
al@822 | 98 not easy. We have no automated tests at the moment. Only we can do manual tests, |
paul@943 | 99 but even we have no check-list. |
al@822 | 100 |
al@822 | 101 To test tazpkg effectively we need two sorts of the tests. One set of the tests |
al@822 | 102 we can reproduce in the local file system (inside special prepared chroot |
paul@943 | 103 environment). For other tests we need a special test-server that provides special |
paul@943 | 104 +test cases (emulate package database changes), this also provides both main and few |
paul@943 | 105 +undigest repositories. We can set up special scripts and test repositories on the |
al@822 | 106 existing server (cook.slitaz.org). |
al@822 | 107 |
al@894 | 108 |
al@894 | 109 HTML terminal converter |
al@894 | 110 ----------------------- |
al@894 | 111 |
al@894 | 112 In the module "help" was an attempt to write code that could easily display the |
al@894 | 113 HTML-help in a terminal. The idea is to re-use TazPkg help files, which are |
al@894 | 114 intended for display in the browser. |
al@894 | 115 |
al@894 | 116 I'll tell you about the most interesting and complex part of the script that |
al@894 | 117 starts like this: |
al@894 | 118 |
al@894 | 119 PRE=$(echo "$HLP" | sed ... |
al@894 | 120 |
al@894 | 121 Here $HLP is a part of the HTML page that we are going to show. Next the chain |
paul@943 | 122 of sed commands are transformed in this HTML source in the next way. |
al@894 | 123 |
al@894 | 124 * `/^$/d;` remove blank lines; |
al@894 | 125 * `/<pre>/,/<\/pre\>/{s|.*| &|; s| |·|g};` prepend lines within <pre>*</pre> |
al@894 | 126 tags with two unbreakable spaces, temporarily change spaces to middle dot; |
al@894 | 127 * `s|^ </*pre>$||; s|<pre>||; s|</pre>||;` remove "<pre>" tags; |
al@894 | 128 * `s| ·#| #|;` remove specified extra-space (converted to middle dot); |
al@894 | 129 * `tr '\n' ' '` convert all the newlines to spaces. Now we get one long line. |
al@894 | 130 Note that we already marked beginning of the pre-lines with two unbreakable |
al@894 | 131 spaces; |
al@894 | 132 * `s|[ ][ ]*| |g;` combine all the successive spaces and/or tabs into |
al@894 | 133 single space; |
al@894 | 134 * `s|[ ]*<dl>|O\n|g;` change opening tag "<dl>" into "O<backspace>". |
al@894 | 135 Note, here and below I use "<backspace>" character because later I'll break |
al@894 | 136 long lines using function "longline()" from libtaz.sh, which in turn uses |
al@894 | 137 Busybox function "fold". In the final step sequences like "O<backspace>" |
al@894 | 138 will be changed to "invisible" color codes, and they should have "zero |
al@894 | 139 width" when they are processed by `fold` to break long lines in the right |
al@894 | 140 places. Fortunately, Busybox `fold` knows about "<backspace>" character and |
al@894 | 141 processes it correctly, so sequence like "O<backspace>" have "zero width" |
al@894 | 142 for `fold`; |
al@894 | 143 * `s|[ ]*</dl>|L\n|g;` change closing tag "</dl>" into "L<backspace>"; |
al@894 | 144 * `s|[ ]*</*dt>||g;` remove opening and closing tags "<dt>"; |
al@894 | 145 * `s|[ ]*<dd>| |g; s|</dd>|\n|g;` now lines within tags "<dd>" are |
al@894 | 146 prepended by tabulation; |
al@894 | 147 * `s|<h4>|<b>|g; s|</h4>|</b>\n|g` change header "<h4>" into separate line |
al@894 | 148 with code `<b>...</b>\n`; |
al@894 | 149 * `s|[ ]*<p>[ ]*||g;` remove opening tag "<p>" both with extra-space; |
al@894 | 150 * `s|[ ]*</p>|\n \n|g;` remove closing tag "</p>" and append it with |
al@894 | 151 "<newline><single unbreakable space><newline>"; |
al@894 | 152 * `s| |\n |g` prepend each line of the <pre> block (marked before with the |
al@894 | 153 double unbreakable spaces) with <newline>; |
al@894 | 154 * Now we have: individual lines prepended by two unbreakable spaces for <pre> |
al@894 | 155 block, individual lines for paragraphs, as well for content of "<dt>" tag, |
al@894 | 156 individual lines prepended by tabulation for content of "<dd>" tag, |
al@894 | 157 individual lines "O<backspace>" and "L<backspace>" for begin and end of the |
al@894 | 158 "<dl>" block; |
al@894 | 159 * `s|<a [^>]*>||g; s|</a>||g;` remove links, leaving only link text; |
al@894 | 160 * `s|·| |g` change back middle dots into spaces; |
al@894 | 161 * `s|</*nobr>||g; s|­||g;` remove tags "<nobr>" and soft hyphens; |
al@894 | 162 * `s|^[ ]*||` remove space in the beginning of each line; |
al@894 | 163 * `/^$/d` remove empty lines. Note, we already have line with the single |
al@894 | 164 unbreakable space as separator between paragraphs; |
al@894 | 165 * `s|<tt>|A|g; s|<code>|A|g;` change open tags to "A<backspace>"; in the |
al@894 | 166 final step it will be changed to the color code; |
al@894 | 167 * `s|<em>|B|g; s|<strong>|B|g;` other color code; |
al@894 | 168 * `s|</tt>|D|g; s|</code>|D|g; s|</em>|D|g;` here will be code that |
al@894 | 169 cancel previous color code; |
al@894 | 170 * `s|DD|D|g;` clean doubles. |