website view en/devel/forge.php @ rev 1344
Resize balinor logo to 120px
| author | Christophe Lincoln <pankso@slitaz.org> |
|---|---|
| date | Fri Jan 22 23:02:15 2021 +0100 (2021-01-22) |
| parents | 836d86cc161c |
| children |
line source
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4 <meta charset="UTF-8">
5 <title>SliTaz - Forge (en)</title>
6 <meta name="description" content="slitaz developers forge">
7 <meta name="keywords" lang="en" content="slitaz, devel, hg, bugs">
8 <meta name="author" content="Christophe Lincoln">
9 <?php include("../../lib/html/meta-link.html"); ?>
10 </head>
11 <body>
13 <?php
14 include("../../lib/html/header.html");
15 include("../../lib/html/nav.html");
16 include("../../lib/lang.php");
17 ?>
19 <!-- Content -->
20 <section id="content">
22 <h2>Collaborative management</h2>
24 <ul>
25 <li><a href="#kiss">KISS and comply to standards.</a></li>
26 <li><a href="#tank">Build host & home.</a></li>
27 <li><a href="#repos">Mercurial repositories.</a></li>
28 <li><a href="#gui">GUI in GTK and CGI/web</a></li>
29 <li><a href="#iconv">Implementation of iconv().</a></li>
30 <li><a href="#pkgs">Building SliTaz packages.</a></li>
31 <li><a href="#website">Website Management.</a></li>
32 </ul>
34 <h2 id="kiss">KISS and comply to standards</h2>
36 <p>
37 Keep it simple: follow the best standards, carefully draft and write
38 high quality documentation, provide a stable and robust system and keep
39 the <em>rootfs</em> on the LiveCD light enough to run on machines with at
40 least 128 MB RAM. It's also possible to use GTK+2, Dialog, SHell scripts,
41 or PHP coding tools on the distribution. The idea is not to duplicate and
42 to think small...
43 </p>
45 <h2 id="tank">Tank - Build host & home</h2>
47 <p>
48 Each contributor may have an account on the project server with secure
49 access, disk space, a public directory and all development tools.
50 Developers can compile packages and maintainers of the mirror can handle
51 synchronization. Tank also hosts the Build Bot, Web boot and SliTaz Pro:
52 <a href="http://tank.slitaz.org/">tank.slitaz.org</a>
53 </p>
55 <p>
56 Instructions on using the build host are described in the Cookbook:
57 <a href="http://doc.slitaz.org/en:cookbook:buildhost">
58 SliTaz Build Host (tank)</a>.
59 </p>
61 <h2 id="repos">Mercurial repositories</h2>
63 <p>
64 SliTaz Mercurial or Hg repos can be browsed or cloned by anyone using
65 the URL: <a href="http://hg.slitaz.org/">http://hg.slitaz.org/</a>. People
66 with write access can directly use <code>repos.slitaz.org</code> which
67 requires authentication. Mercurial uses Python and is installable with:
68 <code>tazpkg get-install mercurial</code>
69 </p>
71 <h3>~/.hgrc</h3>
73 <p>
74 Before you push your first commit onto the server, be sure that you have a
75 correct Hg configuration file with your name and email address, and remember
76 to check that you are not root. Personal ~/.hgrc file example:
77 </p>
78 <pre class="script">
79 [ui]
80 username = FirstName LastName <you@example.com>
81 </pre>
83 <h4>Clone, modify, commit and push</h4>
85 <p>
86 Clone a repo, example for wok:
87 </p>
88 <pre>
89 $ hg clone http://repos.slitaz.org/wok
90 </pre>
91 <p>
92 Change directory to wok, note you must be in the repository to be able
93 to use ‘hg’ commands. To check all logs or just the last log:
94 </p>
95 <pre>
96 $ hg log
97 $ hg head
98 </pre>
99 <p>
100 Add or modify one or more files and commit:
101 </p>
102 <pre>
103 $ hg add
104 $ hg status
105 $ hg commit -m "Log message..."
106 $ hg log
107 </pre>
108 <p>
109 Note that you can use the command <code>rollback</code> to roll back to the last
110 transaction. Before pushing changes to the server, it is safe to pull once:
111 </p>
112 <pre>
113 $ hg pull
114 $ hg push
115 </pre>
116 <p>
117 Done, your changes, code or corrections are now on the server.
118 </p>
120 <h4>Updating a local wok</h4>
122 <p>
123 To update your wok with the local server (<em>pull</em> to pull the changes):
124 </p>
125 <pre>
126 $ hg pull -u
127 </pre>
129 <h4>Useful commands</h4>
131 <p>
132 Hg commands that can be used.
133 </p>
134 <ul>
135 <li><code>hg help</code> : Display the full list of commands.</li>
136 <li><code>hg rollback</code> : Undo the last action performed (commit,
137 pull, push).</li>
138 <li><code>hg log <package></code> : Display a package log.</li>
139 <li><code>hg head</code> : Display the last log.</li>
140 </ul>
142 <h2 id="gui">GUI - Pure C/GTK, Yad, Vala/Genie and CGI/web</h2>
144 <p>
145 There are many ways to create user interfaces in the open source world. From
146 the start of the project until 3.0 we mainly used a tool called Gtkdialog
147 which let us create quite nice and complex interfaces in GTK, but using a
148 scripting language that just ran without having to be compiled. But gtkdialog is
149 unmaintained and lacks many new GTK features, so we switched to Yad for simple GUI boxes.
150 For all the administration, packages and configuration tools we switched to TazPanel,
151 a CGI/web interface with a gui coded in xHTML 5 and CSS 3.
152 </p>
153 <p>
154 Yad is very simple but doesn't allow us to create complex interfaces even if we
155 only need 2 or 3 entries with labels and a few buttons, so another way
156 must be found. The advantage of a scripting language is the fact that it doesn't need
157 to be compiled and can be coded in realtime (but it produces slower applications).
158 Writing tools in C is complex and gets less contributions since SHell scripts are easier
159 to understand, so the guidelines are now to keep and continue to improve our
160 cmdline tools and provide frontends in GTK or CGI/web.
161 </p>
162 <p>
163 There are many new languages that use GTK such as Genie, Vala or GTKaml.
164 But keep in mind that they are not as popular as C and GTK and not really
165 easier to learn and use (for simple frontends you can use SHell
166 scripts to perform tasks). You can use Vala but look at a pure
167 GTK single window, it uses only 14 lines:
168 </p>
169 <pre>
170 #include <gtk/gtk.h>
172 int main(int argc, char *argv[])
173 {
174 GtkWidget *window;
176 gtk_init(&argc, &argv);
177 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
178 g_signal_connect (G_OBJECT (window), "destroy",
179 G_CALLBACK (gtk_main_quit), NULL);
181 gtk_widget_show(window);
182 gtk_main();
183 return 0;
184 }
185 </pre>
186 <p>
187 If you are not sure about which language to use, discuss it on the mailing list.
188 If you just want a small GUI function, look at tazbox in the slitaz-tools
189 repo, it has tiny desktop tools such as a logout box. The first
190 SliTaz sub-project written in pure GTK is TazWeb and you can use it to learn
191 ways to use system() to include system commands in your frontend. For
192 example TazWeb uses wget for downloads and sed to add bookmarks.
193 </p>
194 <p>
195 Yad scripts should follow TazYad guidelines:
196 <a href="http://hg.slitaz.org/slitaz-dev-tools/raw-file/tip/tazyad/README">
197 README</a> and
198 <a href="http://hg.slitaz.org/slitaz-dev-tools/raw-file/tip/tazyad/tazyad">
199 example code</a>
200 </p>
202 <h2 id="iconv">Implementation of iconv()</h2>
204 <p>
205 SliTaz uses iconv() provided by GNU glibc - any packages that offer
206 <code>libiconv</code> must use the library contained in <code>glibc-locale</code>.
207 There is therefore no longer a libiconv package (1.2 MB) in SliTaz.
208 </p>
210 <h2 id="pkgs">Building SliTaz packages</h2>
212 <p>
213 Officially building is done with the Cookutils suite. This package is installed
214 on each SliTaz system as well as documentation about using cook and
215 <a href="http://hg.slitaz.org/cookutils/raw-file/tip/doc/cookutils.en.html">creating SliTaz packages</a>
216 suitable for the TazPKG packages manager.
217 </p>
218 <p>
219 The tazpkg packages in SliTaz are automatically created via the
220 <a href="http://cook.slitaz.org/">Cooker</a> from the Cookutils package
221 and a receipt in the wok. The Cookbook describes the format of
222 <a href="http://doc.slitaz.org/en:cookbook:receipt">receipts</a>.
223 Cookutils and receipt documentation are required reading before we begin.
224 </p>
225 <p>
226 In terms of choice of package, the idea is to offer a package by task or
227 functionality, ie. the lightest application in the field and not duplicated.
228 Note that the current packages are not immutable, if you find an alternative
229 that is lighter, with more features or more <em>sexy</em> for a few extra KB,
230 you can suggest it on the Mailing List. Particular attention is given to
231 packages for the LiveCD, these should be stripped, removing unnecessary
232 dependencies and compiler options. In general candidate packages for the core
233 LiveCD are discussed on the Mailing List.
234 </p>
235 <p>
236 Before you begin to compile and create packages for SliTaz, be sure that the
237 work doesn't already exist in the
238 <a href="http://download.tuxfamily.org/slitaz/packages/undigest/">undigest</a>
239 wok provided by the primary SliTaz mirror. Don't forget that the members
240 of the list are there to help you and that the
241 <a href="http://hg.slitaz.org/cookutils/raw-file/tip/doc/cookutils.en.html">Cookutils</a>
242 documentation exists to help you get started.
243 </p>
245 <h3 id="pkgs-naming">Naming of packages</h3>
247 <p>
248 In most cases the package name is the same as the source, except for
249 Python, Perl, PHP, Ruby and Lua modules. For example, the package
250 providing a Kid template system written in Python and XML is named:
251 <code>python-kid</code>.
252 </p>
254 <h2 id="website">Website Management</h2>
256 <p>
257 The website is managed via a mercurial repository, this can be cloned by:
258 </p>
259 <pre>
260 $ hg clone http://hg.slitaz.org/website
261 Or if you have the proper permissions:
262 $ hg clone http://repos.slitaz.org/website
263 </pre>
265 <h3>xHTML coding style</h3>
267 <p>
268 The pages and different <em>books</em> are coded in xHTML 1.0
269 transitional. The title of level 1 is used only once (at the top),
270 level 2 is the title of the document and levels 3 and 4 are then used for
271 the subtitles. If a list is used instead using smart anchors;
272 then that starts at the top, just after the title of level 2.
273 Paragraphs are contained in the tags <code><p></p></code>.
274 For indentation, we use tabs - the reason being semantics and to take
275 up less space in terms of octets (bytes). To put code, like the name of
276 a command inside a paragraph: <code><code></code> is the preferred
277 method. To view commands or to utilize a terminal, the web pages use
278 <code><pre></code> to display the formatted text. Example:
279 </p>
280 <pre>
281 $ command
282 </pre>
283 <p>
284 To view text that can be copied and pasted, such as scripts,
285 bits of code, sample configuration files, etc - we also use
286 <code><pre></code>, but with a CSS class named “script”. Example:
287 </p>
288 <pre class="script">
289 <pre class="script">
291 code...
293 </pre>
294 </pre>
295 <p>
296 The <em>emphasized</em> words put themselves in the tag <code><em></code>
297 and internal links are relative. Remember to check the validity
298 of the code via the online <em>validator</em> of the W3C.
299 </p>
301 <h2 id="diff">Diff and patch</h2>
303 <p>
304 The utilities <code>diff</code> and <code>patch</code> are command-line tools
305 for creating and implementing a file containing differences between two files.
306 This technique is often used for collaboration and the changes made to the
307 original file can be clearly extracted. To create a <code>diff</code> file
308 readable by humans in a simple text editor, you must supply the <code>-u</code> option:
309 </p>
310 <pre>
311 $ diff -u file.orig file.new > file.diff
312 </pre>
313 <p>
314 To apply a patch:
315 </p>
316 <pre>
317 $ patch file.orig file.diff
318 </pre>
320 <!-- End of content -->
321 </section>
323 <?php include("../../lib/html/footer.html"); ?>
325 </body>
326 </html>