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