[BOOTDATA]: Diverse improvements for mkisofs support and ISO image configuration:

- Make our build system create the required empty directory for mkisofs, instead. (It's not the purpose of the SVN to hold special files/directories just to make host tools happy; instead it's the job of the buld system to create them.)
- Place the boot files (catalog & co.) preferably at the beginning of the ISO image (it makes ISO image analysis easier, and is back-compatible with cdmake & oscdimg & windows ISOs): use the build system to generate the mkisofs sorting file. See the CMakeLists.txt for more details.
- Set in one place the ISO manufacturer & volume name strings so that it makes easier to bulk-change them (and makes features like CORE-12233 a bit easier to maintain).
- The EFI image must be set up with no emulation mode! (See section "12.3.2.1 ISO-9660 and El Torito" of the UEFI spec v2.4 errata B, for example).

[MKISOFS]: Add some useful offline documentation.

CORE-11988

svn path=/trunk/; revision=73104

reactos/boot/CMakeLists.txt

@@ -12,7 +12,7 @@ elseif(ARCH STREQUAL "arm")
 elseif(ARCH STREQUAL "aarch64")
     set(EFI_PLATFORM_ID "aa64")
 else()
-    message(FATAL_ERROR "Unknown ARCH, can't generate a valid UEFI boot filename.")
+    message(FATAL_ERROR "Unknown ARCH '" ${ARCH} "', cannot generate a valid UEFI boot filename.")
 endif()
 
 add_custom_target(efisys
@@ -20,92 +20,157 @@ add_custom_target(efisys
     DEPENDS native-fatten fat bootmgfw bcd_hive
     VERBATIM)
 
-##bootcd
+if(USE_MKISOFS)
-#clear it out
+# Create an 'empty' directory (guaranteed to be empty) to be able to add
+# arbitrary empty directories to the ISO image using mkisofs.
+file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/empty)
+endif()
+
+# Retrieve the full paths to the generated files of the 'isoboot', 'isobtrt' and 'efisys' targets
+set(_isoboot_file ${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isoboot.bin) # get_target_property(_isoboot_file isoboot LOCATION)
+set(_isobtrt_file ${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isobtrt.bin) # get_target_property(_isobtrt_file isobtrt LOCATION)
+set(_efisys_file  ${CMAKE_CURRENT_BINARY_DIR}/efisys.bin) # get_target_property(_efisys_file  efisys  LOCATION)
+
+if(USE_MKISOFS)
+# Create a mkisofs sort file to specify an explicit ordering for the boot files
+# to place them at the beginning of the image (makes ISO image analysis easier).
+# See mkisofs/schilytools/mkisofs/README.sort for more details.
+# As the default file sort weight is '0', give the boot files sort weights >= 1.
+# Note that it is sad that '-sort' does not work using grafted points, and as a
+# result we need in particular to use the boot catalog file "path" mkisofs that
+# mkisofs expects, that is, the boot catalog file name is appended to the first
+# host-system path listed in the file list, whatever it is, and that does not
+# work well if the first item is a graft point (and especially if it's a file
+# and not a directory). To fix that, the trick is to use as the first file item
+# the empty directory created earlier. This ensures that:
+# - the boot catalog file path is meaningful;
+# - since its contents are included by mkisofs in the root of the ISO image,
+#   using the empty directory ensures that no extra unwanted files are added.
+# 
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bootfiles.sort "\
+${CMAKE_CURRENT_BINARY_DIR}/empty/boot.catalog 4
+${_isoboot_file} 3
+${_isobtrt_file} 2
+${_efisys_file} 1
+")
+endif()
+
+# ISO image identificator names
+set(ISO_MANUFACTURER "ReactOS Foundation")  # For both the publisher and the preparer
+set(ISO_VOLNAME      "ReactOS")             # For both the Volume ID and the Volume set ID
+
+## BootCD
+# Create the file list
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst "")
 
 if(USE_MKISOFS)
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst "${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+
     add_custom_target(bootcd
-        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/bootcd.iso -iso-level 4 -volid "ReactOS" -path-list ${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst -graft-points -no-cache-inodes -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -hide boot.catalog -publisher "ReactOS Foundation" -preparer "ReactOS Foundation"
+        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/bootcd.iso -iso-level 4
+            -publisher ${ISO_MANUFACTURER} -preparer ${ISO_MANUFACTURER} -volid ${ISO_VOLNAME} -volset ${ISO_VOLNAME}
+            -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -no-emul-boot -hide boot.catalog
+            -sort ${CMAKE_CURRENT_BINARY_DIR}/bootfiles.sort
+            -no-cache-inodes -graft-points -path-list ${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst
         DEPENDS native-mkisofs
         VERBATIM)
 else()
     add_custom_target(bootcd
-        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isoboot.bin\#pEF,e,b${CMAKE_CURRENT_BINARY_DIR}/efisys.bin @${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst REACTOS ${REACTOS_BINARY_DIR}/bootcd.iso
+        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${_isoboot_file}\#pEF,e,b${_efisys_file} @${CMAKE_CURRENT_BINARY_DIR}/bootcd.lst REACTOS ${REACTOS_BINARY_DIR}/bootcd.iso
         DEPENDS native-cdmake efisys
         VERBATIM)
 endif()
 
-##bootcdregtest
+## BootCDRegTest
-#clear it out
+# Create the file list
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst "")
 
 if(USE_MKISOFS)
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst "${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+
     add_custom_target(bootcdregtest
-        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/bootcdregtest.iso -iso-level 4 -volid "ReactOS" -path-list ${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst -graft-points -no-cache-inodes -eltorito-boot loader/isobtrt.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -hide boot.catalog -publisher "ReactOS Foundation" -preparer "ReactOS Foundation"
+        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/bootcdregtest.iso -iso-level 4
+            -publisher ${ISO_MANUFACTURER} -preparer ${ISO_MANUFACTURER} -volid ${ISO_VOLNAME} -volset ${ISO_VOLNAME}
+            -eltorito-boot loader/isobtrt.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -no-emul-boot -hide boot.catalog
+            -sort ${CMAKE_CURRENT_BINARY_DIR}/bootfiles.sort
+            -no-cache-inodes -graft-points -path-list ${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst
         DEPENDS native-mkisofs
         VERBATIM)
 else()
     add_custom_target(bootcdregtest
-        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isobtrt.bin\#pEF,e,b${CMAKE_CURRENT_BINARY_DIR}/efisys.bin @${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst REACTOS ${REACTOS_BINARY_DIR}/bootcdregtest.iso
+        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${_isobtrt_file}\#pEF,e,b${_efisys_file} @${CMAKE_CURRENT_BINARY_DIR}/bootcdregtest.lst REACTOS ${REACTOS_BINARY_DIR}/bootcdregtest.iso
         DEPENDS native-cdmake efisys
         VERBATIM)
 endif()
 
-##livecd
+## LiveCD
-#clear it out
+# Create the file list
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "")
 
 if(USE_MKISOFS)
-    #create the empty Desktop, Favorites, and Start Menu folders
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "${CMAKE_CURRENT_BINARY_DIR}/empty\n")
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Desktop=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Favorites=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+    # Create the empty Desktop, Favorites, and Start Menu folders
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Start Menu/Programs=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Desktop=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Favorites=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Start Menu/Programs=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
 
     add_custom_target(livecd
-        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/livecd.iso -iso-level 4 -volid "ReactOS" -path-list ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst -graft-points -no-cache-inodes -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -hide boot.catalog -publisher "ReactOS Foundation" -preparer "ReactOS Foundation"
+        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/livecd.iso -iso-level 4
+            -publisher ${ISO_MANUFACTURER} -preparer ${ISO_MANUFACTURER} -volid ${ISO_VOLNAME} -volset ${ISO_VOLNAME}
+            -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -no-emul-boot -hide boot.catalog
+            -sort ${CMAKE_CURRENT_BINARY_DIR}/bootfiles.sort
+            -no-cache-inodes -graft-points -path-list ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst
         DEPENDS native-mkisofs
         VERBATIM)
 else()
-    #create the empty Desktop, Favorites, and Start Menu folders
+    # Create the empty Desktop, Favorites, and Start Menu folders
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Desktop\n")
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Favorites\n")
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/livecd.lst "Profiles/Default User/Start Menu/Programs\n")
 
     add_custom_target(livecd
-        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isoboot.bin\#pEF,e,b${CMAKE_CURRENT_BINARY_DIR}/efisys.bin @${CMAKE_CURRENT_BINARY_DIR}/livecd.lst REACTOS ${REACTOS_BINARY_DIR}/livecd.iso
+        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${_isoboot_file}\#pEF,e,b${_efisys_file} @${CMAKE_CURRENT_BINARY_DIR}/livecd.lst REACTOS ${REACTOS_BINARY_DIR}/livecd.iso
         DEPENDS native-cdmake efisys
         VERBATIM)
 endif()
 
-##hybridcd
+## HybridCD
-#clear it out
+# Create the file list
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "")
 
 if(USE_MKISOFS)
-    #create the empty Desktop, Favorites, and Start Menu folders
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "${CMAKE_CURRENT_BINARY_DIR}/empty\n")
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Desktop=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Favorites=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+    # Create the empty Desktop, Favorites, and Start Menu folders
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Start Menu/Programs=${REACTOS_SOURCE_DIR}/boot/bootdata/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Desktop=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Favorites=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Start Menu/Programs=${CMAKE_CURRENT_BINARY_DIR}/empty\n")
 
     add_custom_target(hybridcd
-        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/hybridcd.iso -iso-level 4 -volid "ReactOS" -path-list ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst -graft-points -no-cache-inodes -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -hide boot.catalog -publisher "ReactOS Foundation" -preparer "ReactOS Foundation"
+        COMMAND native-mkisofs -o ${REACTOS_BINARY_DIR}/hybridcd.iso -iso-level 4
+            -publisher ${ISO_MANUFACTURER} -preparer ${ISO_MANUFACTURER} -volid ${ISO_VOLNAME} -volset ${ISO_VOLNAME}
+            -eltorito-boot loader/isoboot.bin -no-emul-boot -boot-load-size 4 -eltorito-alt-boot -eltorito-platform efi -eltorito-boot loader/efisys.bin -no-emul-boot -hide boot.catalog
+            -sort ${CMAKE_CURRENT_BINARY_DIR}/bootfiles.sort
+            -no-cache-inodes -graft-points -path-list ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst
         DEPENDS native-mkisofs bootcd livecd
         VERBATIM)
-
-    add_cd_file(TARGET efisys FILE ${CMAKE_CURRENT_BINARY_DIR}/efisys.bin DESTINATION loader NO_CAB FOR bootcd regtest livecd hybridcd)
 else()
-    #create the empty Desktop, Favorites, and Start Menu folders
+    # Create the empty Desktop, Favorites, and Start Menu folders
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Desktop\n")
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Favorites\n")
     file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst "livecd/Profiles/Default User/Start Menu/Programs\n")
 
     add_custom_target(hybridcd
-        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${CMAKE_CURRENT_BINARY_DIR}/freeldr/bootsect/isoboot.bin\#pEF,e,b${CMAKE_CURRENT_BINARY_DIR}/efisys.bin @${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst REACTOS ${REACTOS_BINARY_DIR}/hybridcd.iso
+        COMMAND native-cdmake -j -m -bootdata:2\#p0,e,b${_isoboot_file}\#pEF,e,b${_efisys_file} @${CMAKE_CURRENT_BINARY_DIR}/hybridcd.lst REACTOS ${REACTOS_BINARY_DIR}/hybridcd.iso
         DEPENDS native-cdmake efisys bootcd livecd
         VERBATIM)
 endif()
 
+if(USE_MKISOFS)
+    add_cd_file(TARGET efisys FILE ${CMAKE_CURRENT_BINARY_DIR}/efisys.bin DESTINATION loader NO_CAB NOT_IN_HYBRIDCD FOR bootcd regtest livecd hybridcd)
+endif()
+
 add_subdirectory(freeldr)
 add_subdirectory(bootdata)
 add_subdirectory(environ)

reactos/sdk/tools/mkisofs/schilytools/mkisofs/README.compression

@@ -0,0 +1,17 @@
+Transparent decompression (-z option) is available on Linux kernels
+using kernel version 2.4.14 or 2.4.9-ac14 or later.
+
+You also need the zisofs-tools package, containing the mkzftree
+utility, to create the compressed files; this package is available at:
+
+ftp://ftp.kernel.org/pub/linux/utils/fs/zisofs/
+
+The mkzftree utility can also be used to read compressed CD-ROMs on
+systems which do not support transparent decompression.
+
+The use of a separate utility allows compression to be controlled on a
+per-file basis.  A file which is not compressed can be read on any
+system.
+
+Transparent decompression is implemented as an extension to Rock
+Ridge, so Rock Ridge needs to be enabled (-R or -r options.)

reactos/sdk/tools/mkisofs/schilytools/mkisofs/README.eltorito

@@ -0,0 +1,98 @@
+/* @(#)README.eltorito	1.2 00/03/18 eric */
+
+What is El Torito?
+------------------
+Simply put, El Torito is a specification that says how a cdrom should
+be formatted such that you can directly boot from it.
+
+The "El Torito" spec says that ANY cdrom drive should work (scsi/eide)
+as long as the BIOS supports El Torito. So far this has only been
+tested with EIDE drives because none of the scsi controllers that has
+been tested so far appears to support El Torito. The motherboard
+definately has to support El Torito. The ones that do let you choose
+booting from HD, Floppy, Network or CDROM.
+
+How To Make Bootable CDs
+------------------------
+
+For the x86 platform, many BIOS's have begun to support bootable CDs.
+The standard my patches for mkisofs is based on is called "El Torito".
+
+The "El Torito" standard works by making the CD drive appear, through BIOS
+calls, to be a normal floppy drive. This way you simply put an floppy
+size image (exactly 1440k for a 1.44 meg floppy) somewhere in the
+iso fs. In the headers of the iso fs you place a pointer to this image.
+The BIOS will then grab this image from the CD and for all purposes it
+acts as if it were booting from the floppy drive. This allows a working
+LILO boot disk, for example, to simply be used as is.
+
+It is simple then to make a bootable CD. First create a file, say "boot.img"
+which is an exact image of the boot floppu currently in use. There is
+at least one HOWTO on making bootable floppies. If you have a bootable
+floppy handy, you can make a boot image with the command
+
+dd if=/dev/fd0 of=boot.img bs=10k count=144
+
+assuming the floppy is in the A: drive.
+
+Place this image somewhere in the hierarchy which will be the source
+for the iso9660 filesystem. It is a good idea to put all boot related
+files in their own directory ("boot/" under the root of the iso9660 fs,
+for example), but this is not necessary.
+
+One caveat - Your boot floppy MUST load any initial ramdisk via LILO,
+not the kernel ramdisk driver! This is because once the linux kernel
+starts up, the BIOS emulation of the CD as a floppy disk is circumvented
+and will fail miserably. LILO will load the initial ramdisk using BIOS
+disk calls, so the emulation works as designed.
+
+The "El Torito" specification requires a "boot catalog" to be created as 
+ll.
+This is a 2048 byte file which is of no interest except it is required.
+My patches to mkisofs will cause it to automatically create the
+boot catalog. You must specify where the boot catalog will go in the
+iso9660 filesystem. Usually it is a good idea to put it the same place
+as the boot image, and a name like "boot.catalog" seems appropriate.
+
+
+So we have our boot image in the file "boot.image", and we are going to
+put it in the directory "boot/" under the root of the iso9660 filesystem.
+We will have the boot catalog go in the same directory with the name
+"boot.catalog". The command to create the iso9660 fs in the file
+bootcd.iso is then
+
+mkisofs -b boot/boot.img -c boot/boot.catalog -o bootcd.iso .
+
+The -b option specifies the boot image to be used (note the path is
+relative to the root of the iso9660 disc), and the -c option is
+for the boot catalog file.
+
+Now burn the CD and its ready to boot!
+
+CAVEATS
+-------
+
+I don't think this will work with multisession CDs.
+
+If your bootable floppy image needs to access the boot floppy, it has
+to do so through BIOS calls. This is because if your O/S tries to talk to
+the floppy directly it will bypass the "floppy emulation" the El Torito spec
+creates through BIOS. For example, under Linux it is possible to
+have an initial RAM disk loaded when the kernel starts up. If you let the
+kernel try to read in the initial RAM disk from floppy, it will fail
+miserably because Linux is not using BIOS calls to access the floppy drive.
+Instead of seeing the floppy image on the CD, Linux will be looking at
+the actually floppy drive.
+
+The solution is to have the initial boot loader, called LILO, load your
+initial RAM disk for you.  LILO uses BIOS calls entirely for these
+operations, so it can grab it from the emulated floppy image.
+
+I don't think making a CD bootable renders it unreadable by non-El Torito
+machines. The El Torito spec uses parts of the iso9660 filesystem which
+were reserved for future use, so no existing code should care what it does.
+
+Mkisofs currently stores identification records in the iso9660 filesystem
+saying that the system is a x86 system. The El Torito spec also allows
+one to write PowerPC or Mac id's instead. If you look at the code in write.c
+you could figure out how to change what is written.

reactos/sdk/tools/mkisofs/schilytools/mkisofs/README.hide

@@ -0,0 +1,206 @@
+Hiding files on a CD
+=====================
+
+This document attempts to show how to hide files from being seen by an
+operating system accessing a CD as an ISO9660/Rock Ridge, Joliet or HFS
+CD. It also highlights some of the limitations ...
+
+Note: this document is about the various -hide options - not be confused with
+the -hidden options.
+
+The -hidden options set the 'EXISTENCE' bit in the directory entry which
+means the file or directory will be invisible - unless some special option
+is used to mount or view the CD - Linux has the 'unhide' mount option to
+make these files visible. i.e. the directory entry exists on the CD.
+
+With hindsight, to avoid confusion with the -hidden option, it would have
+been better to chose an option name like '-omit' instead of '-hide'...
+
+The various -hide options actually exclude the relevant directory entry
+from the directory tree. Therefore, it is not possible to access a file
+or directory that has be hidden with the -hide option when the ISO9600/Rock
+Ridge directory is mounted - because the directory entry does not exist on the
+CD (but the file data does). You would probably be able to access this file
+or directory when mounted as a Joliet or HFS CD (depending on other options
+used). Similarly, a directory entry hidden with the -hide-joliet option
+will not be accessible when mounted as an Joliet CD. Similarly for -hide-hfs
+etc.
+
+If you don't want a file or directory to appear on the CD at all, then use the
+-exclude options, not the -hide options (mkisofs completely ignores any
+file/directory excluded with the -exclude options).
+
+
+Using the hide options
+======================
+
+There are 6 hide options:
+
+-hide		   Hide a file/directory from the ISO9660/Rock Ridge directory
+-hide-list	   As above, but read file names from a file
+-hide-joliet	   Hide a file/directory from the Joliet directory
+-hide-joliet-list  As above, but read file names from a file
+-hide-hfs	   Hide a file/directory from the HFS directory
+-hide-hfs-list	   As above, but read file names from a file
+
+You can use the -hide, -hide-joliet and/or -hide-hfs options as many times
+as you like on the command line, but if you have many files to hide, then
+it may be better to put your file names in a file (one per line) and use
+the corresponding 'list' option. You can also use the three -hide-list options
+as many times as you want.
+
+The arguments to the -hide options are either the 'basename' or the 'whole
+path name' of a file. That is, if you use the option:
+
+% mkisofs -hide ABC [-other-options] CD_directory
+
+then any file with the name ABC will be hidden. If you want to be more
+specific, then use the whole name - as seen by mkisofs e.g.:
+
+% mkisofs -hide CD_directory/XYZ/ABC [-other-options] CD_directory
+
+will hide just the file 'CD_directory/XYZ/ABC' - not any other file called
+'ABC' that might exist under 'CD_directory'. However, if your command line
+is like:
+
+% mkisofs -hide CD_directory/XYZ/ABC [-other-options] ./CD_directory
+
+Then the file 'CD_directory/XYZ/ABC' will not be hidden because as far as
+mkisofs is concerned. Its whole path is actually './CD_directory/XYZ/ABC'.
+
+You can use wild cards in the -hide arguments.
+
+If the file name to be hidden is a directory, then the directory and all
+its contents are hidden.
+
+The main use of the hide options is on a multi platform (hybrid CD) to hide
+various files/directories that are operating system specific from been seen
+on the CD when mounted on another OS. i.e. You may want to hide Macintosh
+executables from being seen when the CD is mounted as a Joliet CD on a PC etc.
+
+For example, say we want to create a ISO9660/Rock Ridge, Joliet, HFS hybrid
+CD from files/directories in the directory called 'cd_dir' - which are:
+
+MAC/
+MAC/app
+MAC/data/
+MAC/data/file1
+PC/
+PC/app
+PC/data/
+PC/data/file1
+UNIX/
+UNIX/app
+UNIX/data
+UNIX/data/file1
+COMMON/
+COMMON/some_files
+
+We could use the command line:
+
+% mkisofs -r -J -hfs -hide MAC -hide PC -hide-joliet MAC \
+	-hide-joliet UNIX -hide-hfs PC -hide-hfs UNIX -o cd.iso cd_dir
+
+This will give a CD that when mounted as a Rock Ridge CD, you will only 
+see the directories UNIX and COMMON, as a Joliet CD the directories
+PC and COMMON, and as an HFS CD the directories MAC and COMMON.
+
+If you also had the three files in the current directory called README.hfs,
+README.joliet and README.unix - but you wanted to have each of these
+files appear as just 'README' when mounted, then you could use the above
+command line with the following:
+
+% mkisofs -r -J -hfs -graft-points -hide MAC -hide PC -hide-joliet MAC \
+	-hide-joliet UNIX -hide-hfs PC -hide-hfs UNIX \
+	-hide README.hfs -hide README.joliet -hide-joliet README.hfs \
+	-hide-joliet README.uni -hide-hfs README.joliet -hide-hfs README.unix \
+	README=README.hfs README=README.joliet README=README.unix \
+	-o cd.iso cd_dir
+
+Note: we've used the -graft-points option as we're using the '=' syntax
+to insert the files called README.hfs, README.joliet and README.unix as
+'README'
+
+The resulting CD when mounted as a Rock Ridge CD, will have the directories
+UNIX and COMMON - with the file called README - which was originally 
+called README.unix.
+
+However, in most circumstances, it would be better to have the contents
+of each of the OS specific directories (plus the contents of the COMMON
+directory) to appear at the top level of the CD. i.e. when the CD is mounted
+(as ISO9660/Rock Ridge, Joliet or HFS) it has the contents:
+
+README
+app
+data/file1
+some_files
+
+Unfortunately, this is not as straight forward as it may seem - i.e. doing
+the following may seem OK, but it won't work - for reasons I'll explain 
+later:
+
+It gets a bit messy using the -graft-points syntax above, so we'll assume
+each of the MAC, UNIX and PC directories contain the correct README, We'll
+also change to the 'cd_dir' directory and use the command:
+
+mkisofs -r -J -hfs -hide MAC -hide PC -hide-joliet MAC \
+	-hide-joliet UNIX -hide-hfs PC -hide-hfs UNIX \
+	-o cd.iso MAC PC UNIX COMMON
+
+You will get errors like:
+
+mkisofs: Error: UNIX/README and MAC/README have the same Rock Ridge name
+...
+mkisofs: Unable to sort directory 
+
+This is because you can not hide "pathspecs" that are directories ("pathspecs"
+are file names given on the command line, or in a path-list file). This a 
+"feature" of mkisofs. In this case nothing is actually hidden at all.
+
+So you might think that the following may work:
+
+mkisofs -r -J -hfs -hide "MAC/*" -hide "PC/*" -hide-joliet "MAC/*" \
+	-hide-joliet "UNIX/*" -hide-hfs "PC/*" -hide-hfs "UNIX/*" \
+	-o cd.iso MAC PC UNIX COMMON
+
+which may appear to work - but when the CD is mounted as an ISO9660/Rock Ridge
+or Joliet CD, then the directory "data" is missing.
+
+Again this is a feature of mkisofs - the directories PC/data and UNIX/data
+are mapped by mkisofs to the same output directory called "/data" - the
+various "hide" flags are stored with this directory info - in this case as 
+the output directory "/data" is first hidden from the ISO9660/Rock Ridge and
+then the Joliet directory, the net result is that "/data" gets hidden from
+both directories ... the way mkisofs hides HFS directories is slightly
+different, so in this case the directory "data" exists on the HFS volume
+and contains the correct contents.
+
+However, it is possible to obtain the required result, but we have to be
+careful about hiding multiple input directories that map to a single output
+directory.
+
+To do this we have to hide just the files in these directories (or more
+accurately, all the non-directories). This is best done by using lists of
+files to hide for example: 
+
+find PC -type f -print > pc.list
+find UNIX -type f -print > unix.list
+find MAC -type f -print > mac.list
+
+mkisofs -r -J -hfs -hide-list pc.list -hide-list mac.list \
+	-hide-joliet-list unix.list -hide-joliet-list mac.list \
+	-hide-hfs-list pc.list -hide-hfs-list unix.list \
+	-o cd.iso MAC PC UNIX COMMON
+
+i.e. instead of trying to hide a directory and letting mkisofs hide its
+contents, we explicitly hide all the files in the directory, but not the
+directory and any of its sub-directories.
+
+This will work for the above input files, but if your directory trees contain
+symbolic links and/or directories that will not get merged, then the hide lists
+will have to be tailored to get the required result.
+
+
+James Pearson 22-Nov-2001
+
+Any comments/problems to j.pearson@ge.ucl.ac.uk

reactos/sdk/tools/mkisofs/schilytools/mkisofs/README.joliet

@@ -0,0 +1,53 @@
+Some thoughts on Joliet - why it is a dumb idea to have a CD
+with Joliet enhancements but without Rock Ridge.
+It also helps you to understand why it it not possible to append
+a new session to a multi-session Joliet CD when Rock Ridge is
+missing.
+
+-	Joliet is not an accepted independant international standard
+	like ISO-9660 or Rock Ridge (IEEE-P1282).
+	Joliet has been created in 1995 - Rock Ridge in 1990.
+	Rock Ridge became a IEEE standard around 1992.
+
+Joliet is an unjustified addition to ISO-9660.
+
+-	The Joliet tree has no relation to the
+	ISO-9660 tree. Files from the ISO-9660 tree and from the
+	Joliet tree only share content. In general, it is not
+	possible to find the ISO-9660 name from a Joliet name
+	and vice versa if you check both trees on a CD.
+
+	Rock Ridge extensions are located at the end of each
+	ISO-9660 directory record. This makes the Rock Ridge
+	tree closely coupled to the ISO-9660 tree.
+
+-	Joliet does not allow all characters too, so the
+	Joliet filenames are not identical to the filenames
+	on disk.
+
+	As the ISO-9660 tree is the standard reference tree
+	on a CD and the ISO-9660 filenames don't allow all
+	characters and there is a length limitation, the
+	ISO-9660 names cannot be mapped to the filenames on the
+	OS reference tree on disk for doing multi-session.
+
+	Due to different limitations, the short ISO-9660 name 
+	is in most cases not equal to the Joliet name or the
+	Rock Ridge name.
+
+-	Joliet has a filename length limitation of 64 chars (independent
+	from the character coding and type e.g. European vs. Japanese)
+	This is annoying as modern filesystems all allow 255 chars
+	per path name component.
+
+	Joliet uses UTF-16 coding while Rock Ridge uses ISO-8859 or
+	UTF-16 based chars and allows 255 octets. Using UTF-8,
+	Rock Ridge allows 85 Japanese characers or 255 US-ASCII chars.
+
+Other than slightly longer filenames, Joliet offers no new properties
+over plain ISO 9660. Rock Ridge is an open extendable standard and
+there is no filesystem property on Win32 that could not be implemented 
+using Rock Ridge.
+
+Except Linux and FreeBSD, there is no POSIX-like like OS that supports
+Joliet. Never create Joliet only CD's for that reason.

reactos/sdk/tools/mkisofs/schilytools/mkisofs/README.sort

@@ -0,0 +1,102 @@
+Sort the order of file data on the CD
+=====================================
+
+Note: this option does not sort the order of the file names that appear
+in the ISO9660 directory. It sorts the order in which the file data is
+written to the CD image.
+
+This option is useful in order to optimize the data layout on a CD.
+
+To use, type something like:
+
+mkisofs -o cdimage.iso -sort sort_file [other_options] cd_dir
+
+The file 'sort_file' contains two columns of:
+
+filename	weight
+
+where filename is the whole name of a file/directory as mkisofs will see it
+and weight is a whole number between +/- 2147483647
+
+The files will be sorted with the highest weights first and lowest last.
+The default weight is zero.
+
+If the filename is a directory name, then all the files in that directory (and
+sub-directories) will use its weight as their default weight.
+
+e.g.
+
+If the directory 'cd_dir' contains two directories called 'dir1' and 'dir2'
+with files 'A', 'B' and 'C' in dir1 and 'X', 'Y' and 'Z', the the file
+'sort_file' could look something like:
+
+cd_dir/dir2	1000
+cd_dir/dir2/Y	2000
+cd_dir/dir1/B	-2000
+cd_dir/dir1/A	-8000
+
+Note: There must be only one space or tab character between the filename and
+the weight and the weight must be the last characters on a line. The filename
+is taken to include all the characters from the first in a line, up to, but
+not including the last space or tab character on a line. This is to allow
+for space characters to be in, or at the end of a filename.
+
+
+The command:
+
+mkisofs -o cdimage.iso -sort sort_file cd_dir
+
+will sort the above file data as:
+
+cd_dir/dir2/Y
+cd_dir/dir2/X
+cd_dir/dir2/Z
+cd_dir/dir1/C
+cd_dir/dir1/B
+cd_dir/dir1/A
+
+Note: files 'X' and 'Z' both have the weight 1000 - their sort order will then
+be the normal ISO9660 sort order (i.e. alphabetical in this case).
+
+File C will have the default weight of 0
+
+Warning: the filenames in the sort list MUST match the whole path as seen by
+mkisofs. i.e. in the above case, if the command line was:
+
+mkisofs -o cdimage.iso -sort sort_file ./cd_dir
+
+then the sort_file filename will have to changed as accordingly.
+
+Notes
+=====
+
+CDs are written from the middle outwards. High weighted files will be nearer
+the inside of the CD.
+
+Wildcards in the filename list should work.
+
+If a file appears more than once in the source directory tree, then the file
+is only added once to the CD image - i.e. a hard linked file, or symbolic
+link if using the -f option. The file will be sorted according to the
+highest weighting given to any of the linked files.
+
+Zero length files are not sorted - the 'start extent' *may* appear to be in
+the middle of another file after sorting. This is because zero length files
+are given the start extent after the last file added to the CD at that time.
+This address is not changed by the sorting, so it may appear that the file
+address is in another file - however as they are zero length, this will
+not matter!
+
+Directories are not sorted by this flag - directories HAVE to be in the
+ISO9660 sort order - however, the files the directory entry points to, can be
+anywhere on the CD.
+
+Existing files from any previous sessions will not be sorted - they already
+exist on the CD and can not be moved!
+
+I have no idea if this is really useful ...
+
+
+James Pearson 22-Nov-2001
+
+Any comments/problems to j.pearson@ge.ucl.ac.uk