From: Michael Prokop Date: Wed, 1 Sep 2010 16:38:10 +0000 (+0200) Subject: Update documentation according to recent squashfs-lzma-tools4 integration. Provide... X-Git-Tag: v0.11.0~15 X-Git-Url: https://git.grml.org/?p=grml-live.git;a=commitdiff_plain;h=8cf1f25a072cb80a9d4fa821db2ff7ffab179677 Update documentation according to recent squashfs-lzma-tools4 integration. Provide PDF and EPUB documentation. --- diff --git a/debian/grml-live.docs b/debian/grml-live.docs index 66f2ad4..d3c20f0 100644 --- a/debian/grml-live.docs +++ b/debian/grml-live.docs @@ -1,2 +1,4 @@ docs/grml-live.html +docs/grml-live.epub +docs/grml-live.pdf docs/grml-live-remaster.html diff --git a/docs/Makefile b/docs/Makefile index a64b80b..ba8aa4e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,6 +1,6 @@ all: doc -doc: doc_man doc_html +doc: doc_man doc_html doc_epub doc_pdf doc_html: html-stamp @@ -21,10 +21,25 @@ man-stamp: grml-live.txt grml-live-remaster.txt xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl grml-live-db.xml touch man-stamp -online: doc_html +doc_epub: epub-stamp + +epub-stamp: + a2x --icons -a toc -a toclevels=3 -a docinfo -f epub grml-live.txt + touch epub-stamp + +doc_pdf: pdf-stamp + +pdf-stamp: + a2x --icons -a toc -a toclevels=3 -a docinfo -f pdf grml-live.txt + touch pdf-stamp + +online: doc_html doc_epub doc_pdf scp grml-live.html grml:/var/www/grml/grml-live/index.html + scp grml-live.pdf grml:/var/www/grml/grml-live/ + scp grml-live.epub grml:/var/www/grml/grml-live/ clean: - rm -rf grml-live-remaster.html grml-live-remaster.xml grml-live-remaster.8 - rm -rf grml-live.html grml-live.xml grml-live.8 html-stamp man-stamp - rm -rf grml-live-db.html grml-live-db.xml grml-live-db.8 html-stamp man-stamp + rm -f grml-live-remaster.html grml-live-remaster.xml grml-live-remaster.8 + rm -f grml-live.html grml-live.xml grml-live.8 grml-live.epub grml-live.pdf + rm -f grml-live-db.html grml-live-db.xml grml-live-db.8 + rm -f html-stamp man-stamp epub-stamp pdf-stamp diff --git a/docs/grml-live-docinfo.xml b/docs/grml-live-docinfo.xml new file mode 100644 index 0000000..aaee686 --- /dev/null +++ b/docs/grml-live-docinfo.xml @@ -0,0 +1,24 @@ + + + + + Michael + Prokop + + Grml Solutions + + + + + + + + 0.1 + 2010-09-01 + MP + Initial document version with included revision information. + + + diff --git a/docs/grml-live.txt b/docs/grml-live.txt index 51a1554..dc2ca8e 100644 --- a/docs/grml-live.txt +++ b/docs/grml-live.txt @@ -476,13 +476,13 @@ Current state of grml-live with squashfs-tools and kernel --------------------------------------------------------- To make it easier to track problems this section documents current state of -grml-live playing together with squashfs-tools / squashfs-lzma-tools (for -building the compressed file) and the kernel version. Documentation of this -section is up2date by 7rd of september 2009, please report any bugs you -encounter. +grml-live playing together with squashfs-tools / squashfs-lzma-tools / +squashfs-lzma-tools4 (for building the compressed file) and the kernel version. +Documentation of this section is up2date by 1st of september 2010, please report +any bugs you encounter. -Difference between squashfs-lzma-tools and squashfs-tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Difference between squashfs-lzma-tools, squashfs-lzma-tools4 and squashfs-tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Whereas the ZLIB compression is much faster in the build process, the LZMA compression provides a smaller resulting ISO. If you're wondering: the official @@ -490,39 +490,94 @@ Grml builds use the LZMA compression. Squashfs-tools was introduced in Debian and once provided support for LZMA compression. Sadly LZMA compression within squashfs-tools became unsupported and -therefore squashfs-lzma-tools had to be introduced by the Grml team. Different -kernel versions provide different squashfs file formats (version 3.x for kernel -versions until 2.6.28-grml[64], since kernel 2.6.31-grml[64] it's the 4.x -format). +therefore squashfs-lzma-tools[4] had to be introduced and maintained by the Grml +team. Different kernel versions provide different squashfs file formats. Kernel +versions until 2.6.28-grml[64] used the 3.x file format but those outdated +kernels aren't supported by grml-live automatically anymore nowdays (manual +handling through SQUASHFS_BINARY possible though). Kernel versions +2.6.31-grml[64] and 2.6.33-grml[64] use openwrt's squashfs lzma file format +version 4. Kernel versions starting with 2.6.35-grml[64] use the mainline ondisk +file format version 4. If you're wondering which package supports what, here's a short overview: -* squashfs-tools 1:4.0-1: ZLIB as default, no LZMA support/options, file format -version 4 +* squashfs-lzma-tools4 4.0-x: ZLIB as default, LZMA support via '-comp lzma' +option (enabled by grml-live by default), file format version 4 (mainline +version), package maintained and available from Grml, recommended for current +grml-live builds featuring kernels >=2.6.35-grml[64] + +* squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via '-lzma' option +(enabled by grml-live by default), file format version 4 (openwrt style), +package maintained and available from Grml, recommended for any grml-live builds +with kernel versions 2.6.31-grml[64] and 2.6.33-grml[64] + +* squashfs-tools 1:4.0-x: ZLIB as default, no LZMA support/options, file format +version 4, package maintained and available from Debian, recommended only for +ZLIB-only builds of any grml-live builds with kernel versions >=2.6.31-grml[64] + +//////////////////////////////////////////////////////////////////////////////// +Outdated, JFTR: * squashfs-tools 1:3.3-7: ZLIB as default, no LZMA support/options, file format version 3 -* squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via -nolzma +* squashfs-tools 1:3.2r2-9exp1: LZMA as default, ZLIB support via '-nolzma' option, file format version 3 -* squashfs-lzma-tools 4.0-2: ZLIB as default, LZMA support via -lzma option, -file format version 4 - -* squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via -nolzma option, +* squashfs-lzma-tools 3.3-1: LZMA as default, ZLIB support via '-nolzma' option, file format version 3 +//////////////////////////////////////////////////////////////////////////////// + +Now, depending on the kernel version you want to use you need different versions +of squashfs-tools/squashfs-lzma-tools[4]. Yes, that's a mess (don't ask how much +this sucks for us developers) - though we're putting lots of effort into our +toolchain to automatically handle this for you through the grml-live build +system and provide proper documentation. The situation is supposed to calm down +with the recent integration of the squashfs file format 4 in the mainline +kernel. Support for LZMA is pending and as soon as it's available mainline this +should dramatically simplify the situation for developers as well as users. + +[TIP] +If you want to force usage of a specific mksquashfs binary just set the +SQUASHFS_BINARY configuration/environment variable. Set SQUASHFS_OPTIONS for +customizing the options that should be used by the mksquashfs binary during +build process. + +Using squashfs-lzma-tools4 4.0-1 on the build system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +squashfs-lzma-tools4 4.0-1 is available via the Grml repositories. It provides +the mksquashfs-lzma4 and unsquashfs-lzma4 binaries. The package does NOT +conflict with neither Debian's squashfs-tools package nor Grml's +squashfs-lzma-tools package, so you can install all of them at the same time and +the build system will try to figure out the best matching binary automatically +for you. + +The packages can be downloaded from +link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools4/] + +It provides support for the new squashfs file format version 4 (as available in +mainline, so *not* the one being used by squashfs-lzma-tools and kernel +2.6.33-grml) and therefore requires kernel versions starting with +2.6.35-grml[64]. It supports LZMA as well as ZLIB compression. Just use the +defaults for enabling LZMA or use grml-live's '-z' option if you want to use +ZLIB compression instead. -Depending on the kernel version you want to use you need different versions -squashfs-tools/squashfs-lzma-tools. Yes, that's pretty a mess (don't ask how -much this sucks for us developers) - though this is supposed to calm down with -the recent integration of squashfs file format 4 in the mainline kernel. Support -for LZMA is pending and should dramatically simplify the situation for -developers as well as users as soon as it's available mainline. +* Kernel 2.6.31-grml[64]: works with ZLIB compression, fails with LZMA +* Kernel 2.6.33-grml[64]: works with ZLIB compression, fails with LZMA +* Kernel 2.6.35-grml[64]: works with ZLIB *and* LZMA compression + +[NOTE] +squashfs-lzma-tools4 is the recommended package for building up2date ISOs with +grml-live! Please use other squashfs-* packages only if you want to build live +systems providing kernel versions older than 2.6.35-grml*. Use +squashfs-lzma-tools4 from Grml if you want to remaster any Grml releases MORE +RECENT than 2010.04. Using squashfs-lzma-tools 4.0-2 on the build system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -squashfs-lzma-tools 4.0-2 is available via the grml repositories. It provides +squashfs-lzma-tools 4.0-2 is available via the Grml repositories. It provides the mksquashfs-lzma and unsquashfs-lzma binaries. The package does NOT conflict with Debian's squashfs-tools package (you can install both of them at the same time). @@ -530,29 +585,30 @@ time). The packages can be downloaded from link:http://deb.grml.org/pool/main/s/squashfs-lzma-tools/[http://deb.grml.org/pool/main/s/squashfs-lzma-tools/] -It provides support for the new squashfs file format version 4 and therefore -requires kernel versions newer than 2.6.28-grml[64]. It supports LZMA as well as -ZLIB compression. Just use the defaults for enabling LZMA or use grml-live's -'-z' option if you want to use ZLIB instead. +It provides support for the new squashfs file format version 4 (based on openwrt +patches, this is *not* the mainline file format that's being used by kernel +2.6.35-grml and squashfs-lzma-tools4!) and therefore requires kernel versions +newer than 2.6.28-grml[64]. It supports LZMA as well as ZLIB compression. Just +use the defaults for enabling LZMA or use grml-live's '-z' option if you want to +use ZLIB instead. -* Kernel 2.6.23-grml[64]: does not work -* Kernel 2.6.26-grml[64]: does not work -* Kernel 2.6.28-grml[64]: does not work +* Kernel \<=2.6.28-grml[64]: does not work * Kernel 2.6.31-grml[64]: works * Kernel 2.6.33-grml[64]: works +* Kernel 2.6.35-grml[64]: works for ZLIB compression, fails for LZMA [NOTE] - -Please use squashfs-lzma-tools >=4.0-2 from Grml if you want to remaster any -grml release being MORE RECENT than 2009.05. +Please use squashfs-lzma-tools >=4.0-2 from Grml only if you want to remaster +Grml releases 2009.10 and 2010.04 or live systems with their according kernel +versions. Using squashfs-tools 1:4.0-X on the build system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ squashfs-tools >=1:4.0-1 is available in Debian/unstable and Debian/testing. It -provides the mksquashfs and unsquashfs binaries. The package does NOT -conflict with the squashfs-lzma-tools 4.0-2 package (you can install both of -them at the same time). +provides the mksquashfs and unsquashfs binaries. The package does NOT conflict +neither with the squashfs-lzma-tools 4.0-2 package nor with the +squashfs-lzma-tools4 package (so you can install all of them at the same time). The packages can be downloaded from link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/] @@ -560,32 +616,37 @@ link:ftp://ftp.de.debian.org/debian/pool/main/s/squashfs-tools/[ftp://ftp.de.deb It provides support for the new squashfs file format version 4 and therefore requires kernel versions newer than 2.6.28-grml[64]. -It does NOT support LZMA compression. If you need LZMA support please use -Grml's squashfs-lzma-tools (see section above) instead. +It does NOT support LZMA compression (dropped with +link:http://packages.debian.org/changelogs/pool/main/s/squashfs-tools/current/changelog[version +1:3.3-4] and not yet re-integrated yet, see +link:http://bugs.debian.org/594595[#594595]). If you need LZMA support please +use Grml's squashfs-lzma-tools[4] (see sections above) instead. -* Kernel 2.6.23-grml[64]: does not work -* Kernel 2.6.26-grml[64]: does not work -* Kernel 2.6.28-grml[64]: does not work -* Kernel 2.6.31-grml[64]: works -* Kernel 2.6.33-grml[64]: works +* Kernels \<=2.6.28-grml[64]: does not work +* Kernel 2.6.31-grml[64]: works (ZLIB only) +* Kernel 2.6.33-grml[64]: works (ZLIB only) +* Kernel 2.6.35-grml[64]: works (ZLIB only) [NOTE] -Please use squashfs-tools >=1:4.0-1 only if you want to remaster grml releases -MORE RECENT than 2009.05 using the ZLIB compression. +Please use squashfs-tools >=1:4.0-1 only if you want to remaster Grml releases +starting with 2009.10 using the ZLIB compression, please use squashfs-lzma-tools +/ squashfs-lzma-tools4 otherwise instead. + +////////////////////////////////////////////////////////////////////////////////// +Outdated, JFTR: Using squashfs-lzma-tools 3.3-1 on the build system ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -squashfs-lzma-tools 3.3-1 from the grml repository supports kernel +squashfs-lzma-tools 3.3-1 from the Grml repository supports kernel 2.6.26-grml[64] and 2.6.28-grml[64] using both LZMA and ZLIB (-nolzma) -compression. It's the recommended package for building ISOs with grml-live -currently! +compression. The packages can be downloaded from link:http://deb.grml.org/pool/main/s/squashfs-lzma/[http://deb.grml.org/pool/main/s/squashfs-lzma/]. [NOTE] -Please use squashfs-lzma-tools 3.3-1 if you want to remaster grml release +Please use squashfs-lzma-tools 3.3-1 only if you want to remaster Grml releases 2008.11 or 2009.05. Using squashfs-tools 1:3.3-7 on the build system @@ -634,6 +695,7 @@ Using with LZMA compression: to Debian package squashfs-lzma-tools 3.3-1 (see section above). * Kernel 2.6.28-grml: does NOT work, please use ZLIB mode instead or switch to Debian package squashfs-lzma-tools 3.3-1 (see section above). +////////////////////////////////////////////////////////////////////////////////// [[faq]] FAQ @@ -643,7 +705,7 @@ FAQ How do I deploy grml-live on a plain Debian installation? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The easiest way to get a running grml-live setup is to install grml or +The easiest way to get a running grml-live setup is to install Grml or grml-medium using grml2hd (for example inside KVM, Virtualbox, VMware,... if you don't want to run it on a physical system). Of course using grml-live on a plain, original Debian installation is supported as well. So there we go. @@ -680,11 +742,11 @@ Instructions Pin: origin deb.grml.org Pin-Priority: 1 - Package: squashfs-tools + Package: squashfs-lzma-tools Pin: origin deb.grml.org Pin-Priority: 996 - Package: squashfs-lzma-tools + Package: squashfs-lzma-tools4 Pin: origin deb.grml.org Pin-Priority: 996 EOF @@ -701,13 +763,17 @@ Instructions # install relevant tools # please check out http://grml.org/grml-live/#current_state when encountering problems! - apt-get -o APT::Install-Recommends=false install grml-live squashfs-tools squashfs-lzma-tools + apt-get -o APT::Install-Recommends=false install grml-live squashfs-lzma-tools squashfs-lzma-tools4 # adjust grml-live configuration for our needs: cat > /etc/grml/grml-live.local << EOF - # consider using LZMA only for space reasons (resulting in longer - # build time but smaller ISO): - SQUASHFS_OPTIONS="-nolzma" + ## want a faster build process and don't need smaller ISOs? + ## if so use zlib compression, for kernels >=2.6.35-grml* and squashfs-lzma-tools4: + # SQUASHFS_OPTIONS="-comp gzip -b 256k" + ## ... or for kernels <=2.6.33-grml* and squashfs-lzma-tools: + # SQUASHFS_OPTIONS="-nolzma -b 256k" + ## want to use a specific squashfs binary? + # SQUASHFS_BINARY='/usr/bin/mksquashfs' # install local files into the chroot CHROOT_INSTALL="/etc/grml/fai/chroot_install" ## adjust if necessary (defaults to /grml/grml-live): @@ -1012,6 +1078,17 @@ Bugs Please report feedback, link:http://grml.org/bugs/[bugreports] and wishes link:http://grml.org/contact/[to the grml-team]! +[[documentation]] +Documentation +------------- + +The most recent grml-live documentation is available online at +http://grml.org/grml-live/ and for offline reading also available +in different formats: + +* http://grml.org/grml-live/grml-live.epub +* http://grml.org/grml-live/grml-live.pdf + [[authors]] Authors -------