| 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.
|