Release files - Squashfs 1.2

1.2	13 MAR 2003	Append feature and new mksquashfs options added

and the date typos in the CHANGES file have been fixed :)

Signed-off-by: Phillip Lougher <phillip@squashfs.org.uk>

4 files changed, 203 insertions, 36 deletions

diff --git a/ACKNOWLEDGEMENTS b/ACKNOWLEDGEMENTS
index dc2eb1d..a50ce92 100644
--- a/ACKNOWLEDGEMENTS
+++ b/ACKNOWLEDGEMENTS
@@ -22,4 +22,6 @@ He also reported a problem where 32K block filesystems hung when used as initrds
 Arkadiusz Patyk reported a problem where 32K block filesystems hung when used
 as a root filesystem mounted as a loopback device.
 
+Joe Blow emailed me that I'd forgotten to put anything in the README about
+mounting the squashfs filesystem.
 
diff --git a/CHANGES b/CHANGES
index ae29d8e..06e40fe 100644
--- a/CHANGES
+++ b/CHANGES
@@ -6,7 +6,7 @@
 
 	Fixed bugs with initrds and device nodes
 
-1.1	8 JAN 2002	Added features
+1.1	8 JAN 2003	Added features
 
 	1. Kernel squashfs can now mount different byte order filesystems.
 	2. Additional features added to mksquashfs.  Mksquashfs now supports
@@ -18,10 +18,26 @@
 	   can now be created.
 	4. Patch for 2.4.20 kernels.
 
-1.1b	16 JAN 2002	Bug fix release
+1.1b	16 JAN 2003	Bug fix release
 
-	Fixed readpage deadlock bug.  This was a rare deadlock bug that happened when
-	pushing pages into the page cache when using greater than 4K blocks.  I never
-	got this bug when I tested the filesystem, but two people emailed me on the same
-	day about the problem!  I fixed it by using a page cache function that wasn't
-	there when I originally did the work, which was nice :-)
+	Fixed readpage deadlock bug.  This was a rare deadlock bug that
+	happened when pushing pages into the page cache when using greater
+	than 4K blocks.  I never got this bug when I tested the filesystem,
+	but two people emailed me on the same day about the problem!
+	I fixed it by using a page cache function that wasn't there when
+	I originally did the work, which was nice :-)
+
+1.2	13 MAR 2003	Append feature and new mksquashfs options added
+
+	Mksquashfs can now add to existing squashfs filesystems.  Three extra
+	options "-noappend", "-keep-as-directory", and "root-becomes"
+	have been added.
+
+	The append option with file duplicate detection, means squashfs can be
+	used as a simple versioning archiving filesystem. A squashfs
+	filesystem can be created with for example the linux-2.4.19 source.
+	Appending the linux-2.4.20 source will create a filesystem with the
+	two source trees, but only the changed files will take extra room,
+	the unchanged files will be detected as duplicates.
+
+	See the README file for usage changes.
diff --git a/INSTALL b/INSTALL
index 9030136..50287a0 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,17 +1,38 @@
 			INSTALLING SQUASHFS
 
-The squashfs1.1b.tar.gz file contains this file, a readme file, a changes file,
-the squashfs patch files, and the squashfs-tools directory (mksquashfs).
+The squashfs1.2.tar.gz file contains this file, a readme file,
+an acknowledgements file, a changes file, the squashfs patch files, and
+the squashfs-tools directory (mksquashfs).
+
+1. Patching the kernel
+----------------------
 
 There are three kernel patch files depending on your 2.4.x kernel version.
-squashfs1.1b-2.4.19-patch will patch 2.4.19 kernels.  squashfs1.1b-2.4.20-patch
-will patch 2.4.20 kernels, and squashfs1.0c-1.1b-patch will upgrade a
-squashfs1.0c patched 2.4.19 kernel to a new squashfs1.1b patched 2.4.19 kernel.
+squashfs1.2-2.4.19-patch will patch 2.4.19 kernels.  squashfs1.2-2.4.20-patch
+will patch 2.4.20 kernels, and squashfs1.0c-1.2-patch will upgrade a
+squashfs1.0c patched 2.4.19 kernel to a new squashfs1.2 patched 2.4.19 kernel.
+
+IMPORTANT: if you are upgrading from 1.1b, you do not need to repatch
+your kernel, the kernel patch files are unchanged from 1.1b, only
+the squashfs-tools directory and mksquashfs need to be updated.
+
+To patch your kernel, cd into the top level directory, and run the "patch"
+comand, e.g. assuming linux-2.4.20
+
+%cd /usr/src/linux-2.4.20
+%patch -p1 < location-of-squashfs/squashfs1.2-2.4.20-patch
+
+Where "location-of-squashfs" is the path to the squashfs1.2 source directory.
 
 The squashfs patches patch the relevant kernel files to add configure support,
 initrd support, include files, and the squashfs directory under linux/fs/.
 Once patched, the kernel must be reconfigured, with squashfs support turned on
-(either Y/M) to ensure that inflatefs is built into the kernel.
+(either Y/M) to ensure that inflatefs is built into the kernel.  The
+squashfs kernel option can be found in the filesystems subsection of the
+configure menus.
+
+2. Building squashfs tools
+--------------------------
 
 The squashfs-tools directory contains the mksquashfs program.  This can be
 made by typing make.  The Makefile assumes that the squashfs patched
diff --git a/RELEASE-README b/RELEASE-README
index bd6d738..4a7c971 100644
--- a/RELEASE-README
+++ b/RELEASE-README
@@ -1,9 +1,12 @@
-	SQUASHFS 1.1 - A squashed read-only filesystem for Linux
+	SQUASHFS 1.2 - A squashed read-only filesystem for Linux
 
 	Copyright 2003 Phillip Lougher (phillip@lougher.demon.co.uk)
 
 	Released under the GPL licence (version 2 or later).
 
+Squashfs is currently at release 1.2.  Please see the CHANGES file, and
+read the following mksquashfs section for recent changes to squashfs.
+
 Squashfs is a highly compressed read-only filesystem for Linux (kernel 2.4.x).
 It uses zlib compression to compress both files, inodes and directories.
 Inodes in the system are very small and all blocks are packed to minimise
@@ -15,11 +18,14 @@ use (i.e. in cases where a .tar.gz file may be used), and in constrained
 block device/memory systems (e.g. embedded systems) where low overhead is
 needed.
 
-The filesystem is currently stable, and has been tested on PowerPC, i586
-and Sparc architectures.
+The section 'mksquashfs' gives information on using the mksquashfs tool to
+create and append to squashfs filesystems.  The 'using squashfs' section
+gives information on mounting and using squashfs filesystems stored on block
+devices and as normal files using the loopback device.
 
-Squashfs overview
------------------
+
+1. Squashfs overview
+--------------------
 
 1. Data, inodes and directories are compressed.
 
@@ -43,23 +49,33 @@ Squashfs overview
    mount filesystems created on different byte order machines.
 
 
-mksquashfs
-----------
+2. mksquashfs
+-------------
 
 As squashfs is a read-only filesystem, the mksquashfs program must be used to
-create populated squashfs filesystems.
+create populated squashfs filesystems.  Beginning with Squashfs 1.2, mksquashfs
+will also append directories and files to pre-existing squashfs filesystems, see
+the following 'appending to squashfs filesystems' subsection.
 
 SYNTAX:./mksquashfs source1 source2 ...  dest [options] [-e list of exclude dirs/files]
 
 Options are
 	-info				print files written to filesystem
 	-b block size			size of blocks in filesystem, default 32768
+	-noappend			Do not append to existing filesystem on dest, write a new filesystem
+					This is the default action if dest does not exist, or if no filesystem is on it
+	-keep-as-directory		If one source directory is specified, create a root directory
+					containing that directory, rather than the contents of the directory
+	-root-becomes name		When appending source files/directories, make the original
+					root become a subdirectory in the new root called name, rather
+					than adding the new source items to the original root
 	-noI -noInodeCompression	do not compress inode table
 	-noD -noDataCompression		do not compress data blocks
 	-nopad				do not pad filesystem to a multiple of 4K
-	-check_data			add checkdata for greater filesystem integrity checks
+	-check_data			add checkdata for greater filesystem checks
 	-le				create a little endian filesystem
 	-be				create a big endian filesystem
+	-version			print version, licence and copyright message
 
 Source1 source2 ... are the source directories/files containing the
 files/directories that will form the squashfs filesystem.  If a single
@@ -72,20 +88,56 @@ the specified sources into a single filesystem, with the root directory
 containing each of the source files/directories.  The name of each directory
 entry will be the basename of the source path.   If more than one source
 entry maps to the same name, the conflicts are named xxx_1, xxx_2, etc. where
-xxx is the original name, i.e.
+xxx is the original name.
+
+To make this clear, take two example directories.  Source directory
+"/home/phillip/test" contains  "file1", "file2" and "dir1".
+Source directory "goodies" contains "goodies1", "goodies2" and "goodies3".
+
+usage example 1:
+
+%mksquashfs /home/phillip/test output_fs
+
+This will generate a squashfs filesystem with root entries
+"file1", "file2" and "dir1".
+
+example 2:
+
+%mksquashfs /home/phillip/test goodies output_fs
+
+This will create a squashfs filesystem with the root containing
+entries "test" and "goodies" corresponding to the source
+directories "/home/phillip/test" and "goodies".
+
+example 3:
 
-%mksquashfs /home/phillip/test /tmp/source2 source3 /tmp/test output_fs
+%mksquashfs /home/phillip/test goodies test output_fs
 
-Will create a filesystem with the root directory containing directory
-entries test source2 source3 test_1
+This is the same as the previous example, except a third
+source directory "test" has been specified.  This conflicts
+with the first directory named "test" and will be renamed "test_1".
 
 Multiple sources allow filesystems to be generated without needing to
 copy all source files into a common directory.  This simplifies creating
 filesystems.
 
-Dest is the destination where the squashfs filesystem will be written.  This
-can either be a conventional file or a block device.  If the file doesn't exist
-it will be created, if it does exist it will be truncated.
+The -keep-as-directory option can be used when only one source directory
+is specified, and you wish the root to contain that directory, rather than
+the contents of the directory.  For example:
+
+example 4:
+
+%mksquashfs /home/phillip/test output_fs -keep-as-directory
+
+This is the same as example 1, except for -keep-as-directory.
+This will generate a root directory containing directory "test",
+rather than the "test" directory contents "file1", "file2" and "dir1".
+
+The Dest argument is the destination where the squashfs filesystem will be
+written.  This can either be a conventional file or a block device.  If the file
+doesn't exist it will be created, if it does exist and a squashfs
+filesystem exists on it, mksquashfs will append.  The -noappend option will
+write a new filesystem irrespective of whether an existing filesystem is present.
 
 The -e option allows files/directories to be specified which are
 excluded from the output filesystem.  If an exclude file/directory is
@@ -129,9 +181,76 @@ by loopback, which requires files to be a 4K multiple.  If the filesystem is
 being written to a block device, or is to be stored in a bootimage, the extra
 pad bytes are not needed.
 
-Filesystem layout
+2.1 appending to squashfs filesystems
+-------------------------------------
+
+Beginning with squashfs1.2, mksquashfs can append to existing squashfs
+filesystems.  Three extra options "-noappend", "-keep-as-directory",
+and "root-becomes" have been added.
+
+Running squashfs with the destination directory containing an existing
+filesystem, will add the source items to the existing filesystem.  By default,
+the source items are added to the existing root directory.
+
+To make this clear... An existing filesystem "image" contains root entries
+"old1", and "old2".  Source directory "/home/phillip/test" contains  "file1",
+"file2" and "dir1".
+
+example 1:
+
+%mksquashfs /home/phillip/test image
+
+Will create a new "image" with root entries "old1", "old2", "file1", "file2" and
+"dir1"
+
+example 2:
+
+%mksquashfs /home/phillip/test image -keep-as-directory
+
+Will create a new "image" with root entries "old1", "old2", and "test".
+As shown in the previous section, for single source directories
+'-keep-as-directory' adds the source directory rather than the
+contents of the directory.
+
+example 3:
+
+%mksquashfs /home/phillip/test image -keep-as-directory -root-becomes original-root
+
+Will create a new "image" with root entries "original-root", and "test".  The
+'-root-becomes' option specifies that the original root becomes a subdirectory
+in the new root, with the specified name.
+
+The append option with file duplicate detection, means squashfs can be
+used as a simple versioning archiving filesystem. A squashfs filesystem can
+be created with for example the linux-2.4.19 source.  Appending the linux-2.4.20
+source will create a filesystem with the two source trees, but only the
+changed files will take extra room, the unchanged files will be detected as
+duplicates.
+
+
+3. Using squashfs
 -----------------
 
+Squashfs filesystems should be mounted with 'mount' with the filesystem type
+'squashfs'.  If the filesystem is on a block device, the filesystem can be
+mounted directly, e.g.
+
+%mount -t squashfs /dev/sda1 /mnt
+
+Will mount the squashfs filesystem on "/dev/sda1" under the directory "/mnt".
+
+If the squashfs filesystem has been written to a file, the loopback device
+can be used to mount it (loopback support must be in the kernel), e.g.
+
+%mount -t squashfs image /mnt -o loop
+
+Will mount the squashfs filesystem in the file "image" under
+the directory "/mnt".
+
+
+4. Filesystem layout
+--------------------
+
 Brief filesystem design notes follow.
 
 A squashfs filesystem consists of five parts, packed together on a byte alignment:
@@ -154,8 +273,8 @@ Compressed data blocks are written to the filesystem as files are read from
 the source directory, and checked for duplicates.  Once all file data has been
 written the completed inode, directory and uid/gid lookup tables are written.
 
-Metadata
---------
+4.1 Metadata
+------------
 
 Metadata (inodes and directories) are compressed in 8Kbyte blocks.  Each
 compressed block is prefixed by a two byte length, the top bit is set if the
@@ -206,8 +325,8 @@ file are stored contiguously in the filesystem.  The top bit of each block
 length is set if the block is uncompressed, either because the -noD option is
 set, or if the compressed block was larger than the uncompressed block.
 
-Directories
------------
+4.2 Directories
+---------------
 
 Like inodes, directories are packed into the metadata blocks, and are not
 aligned on block boundaries, therefore directories can overlap compressed
@@ -240,8 +359,8 @@ as necessary.  The organisation is as follows:
 			
 This organisation saves on average 3 bytes per filename.
 
-File data
----------
+4.3 File data
+-------------
 
 File data is compressed on a block by block basis and written to the
 filesystem.  The filesystem supports up to 32K blocks, which achieves
@@ -254,3 +373,12 @@ The filesystem reads and decompresses a larger block containing that page
 very inefficient filesystem, as 28K must be thrown away.   Squashfs,
 solves this problem by explicitly pushing the extra pages into the page
 cache.
+
+
+5. Author info
+--------------
+
+Squashfs was written by Phillip Lougher, email phillip@lougher.demon.co.uk,
+in Chepstow, Wales, UK.   If you like the program, or have any problems,
+then please email me, as it's nice to get feedback!
+