tazlito annotate doc/tazlito.en.html @ rev 473

typo in build loram
author Pascal Bellard <pascal.bellard@slitaz.org>
date Mon Dec 25 13:03:49 2017 +0100 (2017-12-25)
parents d7d87b67adeb
children
rev   line source
pankso@280 1 <!DOCTYPE html>
al@442 2 <html lang="en">
pankso@117 3 <head>
pankso@280 4 <meta charset="utf-8" />
al@314 5 <title>TazLito Manual—SliTaz Live Tool</title>
pankso@280 6 <link rel="shortcut icon" href="favicon.ico" />
al@314 7 <link rel="stylesheet" type="text/css" href="../slitaz-doc.css" />
al@314 8 <script type="text/javascript" src="../slitaz-doc.js"></script>
pankso@117 9 </head>
pankso@280 10 <body>
pankso@280 11
al@314 12 <header>
pankso@211 13 <h1>Tazlito Manual</h1>
al@314 14 </header>
pankso@280 15
pankso@117 16 <!-- Start content -->
pankso@117 17 <div id="content">
pankso@117 18
pankso@117 19 <h2>NAME</h2>
al@314 20
al@314 21 <p>Tazlito—SliTaz Live Tool.</p>
al@314 22
pankso@117 23
pankso@117 24 <h2>SYNTAX</h2>
al@314 25
pankso@117 26 <pre>
pankso@117 27 tazlito [command] [list|iso|flavor] [dir]
pankso@117 28 </pre>
pankso@117 29
al@314 30
pankso@117 31 <h2>DESCRIPTION</h2>
al@314 32
al@314 33 <p>Tazlito is a small utility to extract a LiveCD, rebuild the ISO image and
al@314 34 regenerate the root filesystem of the LiveCD. Tazlito can also generate
al@314 35 a distribution from a list of packages previously downloaded. To run, Tazlito
al@314 36 uses the configuration file <tt>/etc/tazlito/tazlito.conf</tt> or an easily
al@314 37 generated <tt>tazlito.conf</tt> found in the current directory. It specifies
al@314 38 the name of the ISO, volume, maintainer and the paths of the packages
al@314 39 to distribute and the generated ISO. Tazlito can also set up a directory
al@314 40 containing additional files which will be copied to the LiveCD when generating
al@314 41 the distribution.</p>
al@314 42 <p>Tazlito is distributed under the free GNU licence GPL v.3, installed
paul@339 43 by default on SliTaz and installed/successfully tested on Debian GNU/Linux. You
al@314 44 will find additional information about creating a LiveCD in the Handbook.</p>
al@314 45
pankso@117 46
pankso@117 47 <h2>COMMANDS</h2>
pankso@128 48
al@314 49
al@314 50 <h3 id="usage">usage</h3>
al@314 51
al@314 52 <p>The <code>usage</code> command displays a summary of available commands with
al@314 53 a short description:</p>
al@314 54
pankso@117 55 <pre>
al@314 56 # tazlito usage
pankso@117 57 </pre>
pankso@128 58
al@314 59
al@314 60 <h3 id="stats">stats</h3>
al@314 61
al@314 62 <p><code>stats</code> displays the configuration variables, the paths to the
al@314 63 various files and directories, and information on the ISO image:</p>
al@314 64
pankso@117 65 <pre>
al@314 66 # tazlito stats
pankso@117 67 </pre>
pankso@128 68
al@314 69
al@314 70 <h3 id="gen-config">gen-config</h3>
al@314 71
al@314 72 <p>The <code>gen-config</code> command allows you to generate a configuration
al@314 73 file ready to be edited. By default the file is created in the current
al@314 74 directory, but can be in another directory if specified via the command line:</p>
al@314 75
pankso@117 76 <pre>
al@314 77 # tazlito gen-config
al@314 78 # tazlito gen-config <em>/path/to/distro</em>
pankso@117 79 </pre>
pankso@128 80
al@314 81
al@314 82 <h3 id="configure">configure</h3>
al@314 83
al@314 84 <p>This command configures the system configuration file or one found in the
al@314 85 current directory:</p>
al@314 86
pankso@117 87 <pre>
al@314 88 # tazlito configure
pankso@117 89 </pre>
pankso@128 90
al@314 91
al@314 92 <h3 id="gen-iso">gen-iso</h3>
al@314 93
al@314 94 <p>The <code>gen-iso</code> command can generate a new LiveCD image following
al@314 95 modifications and additions to the root filesystem of the CD-ROM. To function,
al@314 96 this command needs a directory containing the distro-tree of the Live system.
al@314 97 This tree can easily be built with the
al@314 98 <a href="#extract-distro"><code>extract-distro</code></a> command, modified and
al@314 99 rebuilt via:</p>
al@314 100
pankso@117 101 <pre>
al@314 102 # tazlito gen-iso
pankso@117 103 </pre>
pankso@128 104
al@314 105
al@314 106 <h3 id="gen-initiso">gen-initiso</h3>
al@314 107
al@314 108 <p>The <code>gen-initiso</code> command will do the same work as
al@314 109 <code>gen-iso</code>, but it rebuilds the initramfs compressed system prior.
al@314 110 The initramfs contains the root filesystem and must be rebuilt if modified:</p>
al@314 111
pankso@117 112 <pre>
al@314 113 # tazlito gen-initiso
pankso@117 114 </pre>
pankso@128 115
al@314 116
al@314 117 <h3 id="list-flavors">list-flavors</h3>
al@314 118
al@314 119 <p>The <code>list-flavors</code> command downloads (if necessary) and displays
al@314 120 a list of the different flavors available. You can force the download with the
al@314 121 <code>--recharge</code> option:</p>
al@314 122
pankso@117 123 <pre>
al@314 124 # tazlito list-flavors
al@314 125 # tazlito list-flavors --recharge
pankso@117 126 </pre>
pankso@128 127
al@314 128
al@314 129 <h3 id="get-flavor">get-flavor</h3>
al@314 130
al@314 131 <p>The <code>get-flavor</code> command downloads (if necessary) and prepares the
al@314 132 files for <a href="#gen-distro"><code>gen-distro</code></a> to generate
al@314 133 a flavor:</p>
al@314 134
pankso@117 135 <pre>
al@314 136 # tazlito get-flavor <em>particular-flavor</em>
pankso@117 137 </pre>
pankso@128 138
al@314 139
al@314 140 <h3 id="show-flavors">show-flavor</h3>
al@314 141
al@314 142 <p>The <code>show-flavor</code> command displays the description of the flavor
al@314 143 and its size after regeneration. The options <code>--brief</code> and
al@314 144 <code>--noheader</code> reduce the output displayed:</p>
al@314 145
pankso@117 146 <pre>
al@314 147 # tazlito show-flavor <em>particular-flavor</em>
al@314 148 # tazlito show-flavor <em>particular-flavor</em> --brief
al@314 149 # tazlito show-flavor <em>particular-flavor</em> --brief --noheader
pankso@117 150 </pre>
pankso@128 151
al@314 152
al@314 153 <h3 id="gen-flavor">gen-flavor</h3>
al@314 154
al@314 155 <p>The <code>gen-flavor</code> command creates a description file of a new
al@314 156 flavor from the results of generating a distro
al@314 157 (<a href="#gen-distro"><code>gen-distro</code></a>). The <tt>.flavor</tt> file
al@314 158 can then be sent to slitaz.org:</p>
al@314 159
pankso@117 160 <pre>
al@314 161 # tazlito gen-flavor <em>new-flavor</em>
pankso@117 162 </pre>
pankso@128 163
al@314 164
al@314 165 <h3 id="gen-liveflavor">gen-liveflavor</h3>
al@314 166
al@314 167 <p>The <code>gen-liveflavor</code> command creates a description file of a new
al@314 168 flavor from the results of generating a distro based on the current system. The
al@314 169 <code>--help</code> option provides more information:</p>
al@314 170
al@314 171 <pre>
al@314 172 # tazlito gen-liveflavor
al@314 173 # tazlito gen-liveflavor --help
pankso@117 174 </pre>
pankso@128 175
al@314 176
al@314 177 <h3 id="upgrade-flavor">upgrade-flavor</h3>
al@314 178
al@314 179 <p>The <code>upgrade-flavor</code> command refreshes a flavor file by updating
al@314 180 the list of packages with the latest versions available:</p>
al@314 181
pascal@158 182 <pre>
al@314 183 # tazlito upgrade-flavor <em>this-flavor</em>
pascal@158 184 </pre>
pascal@158 185
al@314 186
al@314 187 <h3 id="extract-flavor">extract-flavor</h3>
al@314 188
al@314 189 <p>The <code>extract-flavor</code> command converts a flavor into an easily
al@314 190 modifiable tree structure in <tt>/home/slitaz/VERSION/flavors</tt> which can be
al@314 191 managed with mercurial:
al@314 192 <a href="http://hg.slitaz.org/flavors">http://hg.slitaz.org/flavors</a>. For
al@314 193 example on cooking you will have the work directory in
al@314 194 <tt>/home/slitaz/cooking</tt>.</p>
al@314 195
pascal@158 196 <pre>
al@314 197 # tazlito extract-flavor <em>this-flavor</em>
pascal@158 198 </pre>
pascal@158 199
al@314 200
al@314 201 <h3 id="pack-flavor">pack-flavor</h3>
al@314 202
al@314 203 <p>The <code>pack-flavor</code> command converts a tree structure in
al@314 204 <tt>/home/slitaz/VERSION/flavors</tt> into a flavor file (<tt>.flavor</tt>).
al@314 205 It is inverse of
al@314 206 <a href="#extract-flavor"><code>tazlito extract-flavor</code></a>:</p>
al@314 207
pascal@158 208 <pre>
al@314 209 # tazlito pack-flavor <em>this-flavor</em>
pascal@158 210 </pre>
pascal@158 211
al@314 212
al@314 213 <h3 id="extract-distro">extract-distro</h3>
al@314 214
al@314 215 <p>The <code>extract-distro</code> command is used to extract an ISO image from
al@314 216 the LiveCD to rebuild the structure of the root CD-ROM and system. It is then
al@314 217 possible to make the desired changes or additions and rebuild the ISO image via
al@314 218 <a href="#gen-iso"><code>gen-iso</code></a> or
al@314 219 <a href="#gen-initiso"><code>gen-initiso</code></a>. Example of use:</p>
al@314 220
pankso@117 221 <pre>
al@314 222 # tazlito extract-distro <em>slitaz-cooking.iso</em>
pankso@117 223 </pre>
pankso@128 224
al@314 225
al@314 226 <h3 id="gen-distro">gen-distro</h3>
al@314 227
al@314 228 <p>The <em>Generate Distribution</em> command can generate the distro-tree and
al@314 229 an ISO image via a list of packages. To function, this command needs a list of
al@314 230 packages, a directory containing all the (<tt>.tazpkg</tt>) packages on the
al@314 231 list, and a directory to generate the distribution. The list of packages can be
al@314 232 extracted from a flavor with the
al@314 233 <a href="#get-flavor"><code>get-flavor</code></a> command. If one uses the
al@314 234 LiveCD, the options <code>--cdrom</code> and <code>--iso=</code> permit the
al@314 235 regeneration of packages that place files in <tt>/boot</tt> without being
al@314 236 obliged to download them and recovers the additional files of the LiveCD. The
al@314 237 path to the various directories are configured in the configuration file and
al@314 238 packages can be downloaded from the SliTaz mirrors or generated by Cookutils.
al@314 239 To generate a distribution:</p>
al@314 240
pankso@117 241 <pre>
al@314 242 # tazlito gen-distro
al@314 243 # tazlito gen-distro --cdrom
al@314 244 # tazlito gen-distro --iso=<em>slitaz.iso</em>
al@314 245 # tazlito gen-distro <em>package-list</em>
pankso@117 246 </pre>
pankso@128 247
al@314 248
al@314 249 <h3 id="clean-distro">clean-distro</h3>
al@314 250
al@314 251 <p>Removes all files generated or extracts of the structure of the LiveCD:</p>
al@314 252
pankso@117 253 <pre>
al@314 254 # tazlito clean-distro
pankso@117 255 </pre>
pankso@128 256
al@314 257
al@314 258 <h3 id="check-distro">check-distro</h3>
al@314 259
al@314 260 <p>This command simply verifies if files installed by the packages are present
al@314 261 on the system:</p>
al@314 262
pankso@117 263 <pre>
al@314 264 # tazlito check-distro
pankso@117 265 </pre>
pankso@128 266
paul@153 267
al@314 268 <h3 id="writeiso">writeiso</h3>
al@314 269
al@314 270 <p>This command will write the current filesystem to a cpio archive
al@314 271 (<tt>rootfs.gz</tt>) and then generate a bootable ISO image. Writeiso can be
al@314 272 used in a HD install or in live mode and will also archive your current
al@314 273 <tt>/home</tt> directory. This command lets you easily remaster and build your
al@314 274 own LiveCD image, just boot, modify any files, and then:</p>
al@314 275
pankso@128 276 <pre>
al@314 277 # tazlito writeiso [gzip|lzma|none]
al@314 278 # tazlito writeiso gzip
al@314 279 # tazlito writeiso gzip <em>image-name</em>
pankso@128 280 </pre>
pankso@128 281
al@314 282 <h3 id="check-list">check-list</h3>
al@314 283
al@314 284 <p>Checks if the <tt>distro-packages.list</tt> is updated with the latest
al@314 285 package versions:</p>
al@314 286
pascal@158 287 <pre>
al@314 288 # tazlito check-list
pascal@158 289 </pre>
pascal@158 290
al@314 291
al@314 292 <h3 id="repack">repack</h3>
al@314 293
al@314 294 <p>Recompresses the rootfs with the best possible compression:</p>
al@314 295
pascal@158 296 <pre>
al@314 297 # tazlito repack <em>slitaz.iso</em>
pascal@158 298 </pre>
pascal@158 299
al@314 300
al@314 301 <h3 id="merge">merge</h3>
al@314 302
al@314 303 <p>Combines several flavors like nested Russian dolls. Each rootfs is a subset
al@314 304 of the previous. The first rootfs is extracted from the ISO image used in the
al@314 305 third argument. The flavor will then be chosen to launch at startup according
al@314 306 to the amount of RAM available:</p>
al@314 307
pascal@158 308 <pre>
al@314 309 # tazlito merge <em>160M slitaz-core.iso 96M rootfs-justx.gz 32M rootfs-base.gz</em>
pascal@158 310 </pre>
pascal@158 311
al@314 312
al@314 313 <h3 id="build-loram">build-loram</h3>
al@314 314
al@314 315 <p>Creates an ISO image flavor for low RAM systems from a SliTaz ISO image. You
al@314 316 can build a flavor with <tt>/</tt> always in RAM or where <tt>/</tt> resides on
al@314 317 the CD-ROM:</p>
al@314 318
pascal@171 319 <pre>
al@314 320 # tazlito build-loram <em>slitaz.iso loram.iso</em>
al@314 321 # tazlito build-loram <em>slitaz.iso loram-cdrom.iso</em> cdrom
pascal@171 322 </pre>
pascal@171 323
al@314 324
al@314 325 <h3 id="emu-iso">emu-iso</h3>
al@314 326
al@314 327 <p>The <code>emu-iso</code> command uses the Qemu emulator to start and run
al@314 328 SliTaz. Qemu is used to test the newly built ISO image without burning to a
al@314 329 CD-ROM or booting into frugal mode:</p>
al@314 330
paul@121 331 <pre>
al@314 332 # tazlito emu-iso
al@314 333 # tazlito emu-iso path/to/image.iso
paul@121 334 </pre>
pankso@128 335
al@314 336
al@314 337 <h3 id="burn-iso">burn-iso</h3>
al@314 338
al@314 339 <p><code>burn-iso</code> will guess the CD-ROM device and its speed, and wodim
al@314 340 (part of cdrkit) will begin to burn an ISO image. The default ISO image is the
al@314 341 one located in the current configuration file, but it's possible to specify
al@314 342 a different image via the command line:</p>
al@314 343
pankso@117 344 <pre>
al@314 345 # tazlito burn-iso
al@314 346 # tazlito burn-iso <em>slitaz-hacked.iso</em>
pankso@117 347 </pre>
pankso@117 348
al@314 349
pascal@158 350 <h2>FLAVORS</h2>
pascal@158 351
al@314 352 <p>A <tt>.flavor</tt> file contains just a few KB of information needed to
al@314 353 (re)manufacture a custom LiveCD of SliTaz.</p>
al@314 354
al@314 355
al@314 356 <h3 id="rebuild-flavor">Manufacture a flavor</h3>
al@314 357
al@314 358 <p>You can choose the flavor to (re)manufacture from among those available:</p>
al@314 359
pascal@158 360 <pre>
pascal@158 361 # tazlito list-flavors
pascal@158 362
pascal@158 363 List of flavors
pascal@158 364 ================================================================================
pascal@158 365 Name ISO Rootfs Description
pascal@158 366 ================================================================================
pascal@158 367 base 6.9M 13.1M Minimal set of packages to boot
pascal@158 368 core-3in1 31.5M 105.6M SliTaz core system with justX and base alternatives
pascal@158 369 core 31.5M 104.6M SliTaz core system
pascal@158 370 eeepc 31.2M 105.4M SliTaz eeepc system
paul@159 371 justX 16.1M 51.2M SliTaz with a minimal X environment
pascal@158 372 </pre>
al@314 373
al@314 374 <p>We will start by remanufacturing the <em>eeepc</em> flavor which uses 105.4M
al@314 375 of RAM and has a CD-ROM size of 31.2M:</p>
al@314 376
pascal@158 377 <pre>
pascal@158 378 # tazlito clean-distro
al@314 379 # tazlito get-flavor <em>eeepc</em>
pascal@158 380 # tazlito gen-distro
pascal@158 381 </pre>
pascal@158 382
al@314 383
al@314 384 <h3 id="create-flavor">Create a flavor</h3>
al@314 385
al@314 386 <p>To create a flavor, you must:</p>
al@314 387
pascal@158 388 <ul>
al@314 389 <li>Either create an ISO image with <a href="#gen-distro"><code>tazlito
al@314 390 gen-distro</code></a> and then create a flavor file with
al@314 391 <a href="#gen-flavor"><code>tazlito gen-flavor</code></a></li>
pascal@158 392 <li>Either directly create the tree structure that defines the flavor
al@314 393 (see <a href="#extract-flavor"><code>tazlito extract-flavor</code></a>)
al@314 394 and then create the flavor with <a href="#pack-flavor"><code>tazlito
al@314 395 pack-flavor</code></a></li>
al@314 396 <li>Either use the <a href="http://pizza.slitaz.org/">online builder</a></li>
pascal@158 397 </ul>
pascal@158 398
al@314 399
al@314 400 <h3 id="publish-flavor">Post a flavor</h3>
al@314 401
al@314 402 <p>Because a <tt>.flavor</tt> file contains just a few KB, it can be easily sent
al@314 403 via the <a href="http://www.slitaz.org/en/mailing-list.php">mailing list</a>.</p>
al@314 404
al@314 405 <p>The results of <a href="#extract-flavor"><code>tazlito
al@314 406 extract-flavor</code></a> can also be put in
al@314 407 <a href="http://hg.slitaz.org/flavors">mercurial</a>. This method is
al@314 408 preferred because the tree will be directly visible with the
al@314 409 <a href="http://hg.slitaz.org/flavors/file/tip">mercurial web interface</a>.</p>
al@314 410 <p>This tree includes:</p>
al@314 411
pascal@158 412 <ul>
al@314 413 <li>A <b>receipt</b> file describing the flavor thanks to the variables:
al@314 414 <ul>
al@314 415 <li>FLAVOR: The flavor name.</li>
al@314 416 <li>SHORT_DESC: Short description.</li>
al@314 417 <li>VERSION: Free format.</li>
al@314 418 <li>MAINTAINER: Email address of maintainer.</li>
al@314 419 <li>FRUGAL_RAM: Minimum RAM required (optional).</li>
al@314 420 <li>ROOTFS_SIZE: Size of rootfs.gz decompressed into RAM
al@314 421 (optional).</li>
al@314 422 <li>INITRAMFS_SIZE: Size of rootfs.gz on the CD-ROM (optional).</li>
al@314 423 <li>ISO_SIZE: Size of CD-ROM (optional).</li>
al@314 424 <li>ROOTFS_SELECTION: Optional, see <a href="#meta-flavor">Meta
al@314 425 flavor</a> below.</li>
al@314 426 </ul>
al@314 427 </li>
al@314 428 <li>The file <b>packages.list</b> containing the list of packages without
al@314 429 specifying the version (tazlito uses the latest available). This file
al@314 430 is missing if ROOTFS_SELECTION exists in the receipt.</li>
al@314 431 <li>The optional <b>mirrors</b> file containing the list of unofficial
al@314 432 mirrors (undigest) to be added to include personal packages.</li>
al@314 433 <li>The optional directory <b>rootfs</b> containing the tree to add to the
al@314 434 root filesystem rootfs.gz (configuration files usually).</li>
al@314 435 <li>The optional directory <b>rootcd</b> containing the tree to add to the
al@314 436 root of the CD-ROM.</li>
pascal@158 437 </ul>
pascal@158 438
al@314 439
al@314 440 <h3 id="tune-flavor">Adapt a flavor</h3>
al@314 441
al@314 442 <p>It is often easier to modify an existing flavor than to create one from
al@314 443 scratch. To adapt the eeepc flavor for example:</p>
al@314 444
pascal@158 445 <pre>
pascal@158 446 # tazpkg get-install mercurial
pascal@158 447 # cd /home/slitaz
pascal@158 448 # hg clone http://hg.slitaz.org/flavors
pascal@158 449 # cd flavors
al@314 450 # cp -a <em>eeepc myslitaz</em>
pascal@165 451 </pre>
pascal@158 452
al@314 453 <p>Files in <tt>myslitaz</tt> can then be changed, and:</p>
al@314 454
al@314 455 <pre>
al@314 456 # tazlito pack-flavor <em>myslitaz</em>
al@314 457 </pre>
al@314 458
al@314 459 <p>Will simply create the new flavor.</p>
al@314 460
al@314 461 <p>Tip: you can skip mercurial installation by extracting a flavor. Using the
al@314 462 previous example:</p>
al@314 463
al@314 464 <pre>
al@314 465 # tazlito get-flavor <em>eeepc</em>
al@314 466 # tazlito extract-flavor <em>eeepc.flavor</em>
al@314 467 # cd /home/slitaz/flavors
al@314 468 # cp -a <em>eeepc myslitaz</em>
al@314 469 </pre>
al@314 470
al@314 471
al@314 472 <h3 id="meta-flavor">Meta flavor</h3>
al@314 473
al@314 474 <p>A meta flavor contains several flavors like nested Russian dolls. The flavor
al@314 475 will be launched at startup according to the amount of RAM available. The
paul@339 476 ROOTFS_SELECTION variable defines the minimum RAM and corresponding flavor
al@314 477 parameters, <a
al@314 478 href="http://hg.slitaz.org/flavors/file/tip/core-4in1/receipt">example</a>:</p>
al@314 479
pascal@158 480 <pre>
pascal@158 481 ROOTFS_SELECTION="160M core 96M justX 32M base"
pascal@158 482 </pre>
al@314 483
al@314 484 <p>A meta flavor doesn't contain a list of packages (<tt>packages.list</tt>).
al@314 485 SliTaz kernels prior to 2.6.30 do not support meta flavors.</p>
al@314 486
pascal@158 487
pankso@117 488 <h2>MAINTAINER</h2>
al@314 489
al@314 490 <p>Christophe Lincoln &lt;pankso at slitaz.org&gt;<br />
al@314 491 Pascal Bellard &lt;pascal.bellard at slitaz.org&gt;</p>
pankso@117 492
pankso@117 493 <!-- End content -->
pankso@117 494 </div>
al@314 495
al@314 496 <footer>
pascal@466 497 Copyright &copy; <span class="year"></span> <a href="http://www.slitaz.org/">SliTaz GNU/Linux</a>
al@314 498 </footer>
al@314 499
pankso@117 500 </body>
pankso@117 501 </html>