From 811f0b5538c0e7ea50e4b62b61194c783c0f209e Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Wed, 14 Aug 2013 01:51:50 -0500 Subject: [PATCH] wimlib-imagex: More documentation updates --- NEWS | 13 +++ doc/imagex-apply.1.in | 3 +- doc/imagex-extract.1.in | 6 +- doc/imagex-update.1.in | 5 +- doc/imagex.1.in | 176 ++++++++++++++++++++-------------------- make-windoze-release | 15 +++- 6 files changed, 121 insertions(+), 97 deletions(-) diff --git a/NEWS b/NEWS index e499cf00..a0d271b6 100644 --- a/NEWS +++ b/NEWS @@ -18,6 +18,16 @@ Version 1.5.0: ratio by default, which is usually what is desired, at a cost of some speed. + For convenience, `wimlib-imagex' now supports being invoked as + wimCOMMAND, where COMMAND is the command as in `wimlib-imagex COMMAND'; + for example, it can be invoked as `wimapply' as an alternative to + `wimlib-imagex apply'. The appropriate hard links are created in UNIX + installations of `wimlib-imagex', while for the Windows distribution of + `wimlib-imagex', batch files that emulate this behavior are generated. + + `wimlib-imagex' no longer recognizes the 'mount', 'mountrw', and + 'unmount' commands on Windows, since they didn't work on Windows anyway. + Security descriptors are now extracted correctly on Windows. `mkwinpeimg' now supports grabbing files from the WAIK supplement rather @@ -36,6 +46,9 @@ Version 1.5.0: A few changes were made to the error codes returned by library routines. + This update bumps the shared library version number up to 9, since it + doesn't quite not maintain binary compatibility with previous releases. + Version 1.4.2: Fixed bug in `wimlib-imagex export' that made it impossible to export an image from a WIM that is readonly at the filesystem level. diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 18012969..66697f73 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -11,7 +11,8 @@ Imaging (WIM) file \fIWIMFILE\fR. This command is also available as simply This command is designed to extract, or "apply", one or more full WIM images. If you instead want to extract only certain files or directories contained in a WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or -\fB@IMAGEX_PROGNAME@ mount\fR instead. +\fB@IMAGEX_PROGNAME@ mount\fR instead. (\fB@IMAGEX_PROGNAME@ mount\fR is not +supported on Windows.) .PP \fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract. It may be a 1-based index of an image in \fIWIMFILE\fR, the name of an image in diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in index ff9eaa01..40e29763 100644 --- a/doc/imagex-extract.1.in +++ b/doc/imagex-extract.1.in @@ -83,9 +83,9 @@ See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about what data and metadata are extracted on UNIX-like systems versus on Windows. .PP On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux), -one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR and -then extract the desired files or directories using any standard command-line or -graphical program. +one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1) +and then extract the desired files or directories using any standard +command-line or graphical program. .PP Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@ diff --git a/doc/imagex-update.1.in b/doc/imagex-update.1.in index f262e5e3..4cc99608 100644 --- a/doc/imagex-update.1.in +++ b/doc/imagex-update.1.in @@ -129,8 +129,9 @@ quotes and single quotes for the inner quotes. Example: mountrw\fR, since if a WIM image can be mounted read-write, then there theoretically is no need for \fB@IMAGEX_PROGNAME@ update\fR. The main advantage of \fB@IMAGEX_PROGNAME@ update\fR is that it works on both UNIX-like systems and -Windows, whereas \fB@IMAGEX_PROGNAME@ mountrw\fR only works on UNIX-like -systems, and even then just those with a compatible FUSE implementation. +Windows, whereas \fB@IMAGEX_PROGNAME@ mountrw\fR is only available on UNIX-like +systems, and even then it only works on those with a compatible FUSE +implementation. .PP Symbolic links inside a WIM image are not dereferenced when being interpreted. So, for example, if you have a WIM image that contains a symbolic link diff --git a/doc/imagex.1.in b/doc/imagex.1.in index 6a952ac2..fc0edd28 100644 --- a/doc/imagex.1.in +++ b/doc/imagex.1.in @@ -32,23 +32,31 @@ .br \fB@IMAGEX_PROGNAME@ update\fR \fIarguments...\fR .SH DESCRIPTION -\fB@IMAGEX_PROGNAME@\fR is able to deal with archives in the Windows Imaging -Format (.wim files). Its interface is meant to be similar to Microsoft's -imagex.exe program. +\fB@IMAGEX_PROGNAME@\fR deals with archives in the Windows Imaging Format (.wim +files). Its interface is meant to be similar to Microsoft's "imagex.exe" +program, but it also provide many useful extensions. .PP -To do its work, \fB@IMAGEX_PROGNAME@\fR uses \fBwimlib\fR, a library which -provides interfaces for manipulating WIM archives. You could wimlib in your own -programs if you wanted to. wimlib's public interface is documented. +To do its work, \fB@IMAGEX_PROGNAME@\fR uses \fBwimlib\fR, a C library which +provides interfaces for manipulating WIM archives. You can wimlib in your own +programs if desired, although \fB@IMAGEX_PROGNAME@\fR already provides access to +most of wimlib's functionality. In some cases, however, there are general +interfaces which are only used by \fB@IMAGEX_PROGNAME@\fR in a specific way, so +it may be worth taking a look if you're looking to do something beyond what +\fB@IMAGEX_PROGNAME@\fR directly supports. .SH COMMANDS -The available commands were listed above, and there is a separate manual page -for each. Note: to save typing, if the appropriate hard links are installed, a -command \fB@IMAGEX_PROGNAME@ \fICOMMAND\fR can be accessed as simply -\fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for -\fB@IMAGEX_PROGNAME@ apply\fR. +\fB@IMAGEX_PROGNAME@\fR accepts one of a number of commands (listed above in +\fBSYNOPSYS\fR), and additional arguments depending on the specific command. +Although \fB@IMAGEX_PROGNAME@\fR will print usage information with \fB--help\fR +or if you invoke it incorrectly, the full documentation for each +\fB@IMAGEX_PROGNAME@\fR command can be found in the appropriate manual page. +.PP +Note: to save typing, if appropriate hard links or batch files have been +installed, a command \fB@IMAGEX_PROGNAME@ \fICOMMAND\fR can be accessed as +simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fB@IMAGEX_PROGNAME@ +apply\fR. .SH SUPPORTED FEATURES -The following general features are currently supported (note: this is not a -complete list; also, certain features, such as mounting, are supported on UNIX -but not Windows): +The following are some of the main features currently supported by +\fB@IMAGEX_PROGNAME@\fR, and pointers to the relevant commands: .IP \[bu] 4 Create a stand-alone WIM from a directory or NTFS volume (\fB@IMAGEX_PROGNAME@ capture\fR) .IP \[bu] @@ -64,9 +72,11 @@ Apply an image from a stand-alone or split WIM to a directory or NTFS volume Apply an image from a special pipable WIM format sent over standard input (\fB@IMAGEX_PROGNAME@ apply\fR) .IP \[bu] -Mount an image from a stand-alone or split WIM read-only (\fB@IMAGEX_PROGNAME@ mount\fR) +Mount an image from a stand-alone or split WIM read-only (\fB@IMAGEX_PROGNAME@ +mount\fR) (not available on Windows) .IP \[bu] -Mount an image from a stand-alone WIM read-write (\fB@IMAGEX_PROGNAME@ mountrw\fR) +Mount an image from a stand-alone WIM read-write (\fB@IMAGEX_PROGNAME@ +mountrw\fR) (not available on Windows) .IP \[bu] Extract individual files or directories from a WIM without mounting it (\fB@IMAGEX_PROGNAME@ extract\fR) @@ -91,85 +101,81 @@ Support for all WIM compression types, both compression and decompression (LZX, XPRESS, and none) .IP \[bu] WIM integrity table is supported (\fB--check\fR option to many commands) -.IP \[bu] -WIM XML data (parsed and written using \fBlibxml\fR(3)) .SH DIFFERENCES FROM MICROSOFT IMAGEX -Although \fB@IMAGEX_PROGNAME@\fR is similar to Microsoft's implementation of -ImageX, there are a number of key differences between the two programs: -.IP \[bu] 6 -\fB@IMAGEX_PROGNAME@\fR is supported on both UNIX-based systems and Windows; -thus, much functionality was designed around this. +Although \fB@IMAGEX_PROGNAME@\fR shares some similarities with Microsoft's +implementation of ImageX, this section lists some noteworthy differences between +the two programs: +.IP \[bu] 4 +\fB@IMAGEX_PROGNAME@\fR is supported on both UNIX-like systems and Windows; +thus, some functionality was designed around this. .IP \[bu] The command-line syntax of the two programs is similar but not exactly the same. .IP \[bu] -As of wimlib v1.5.0, for convenience \fB@IMAGEX_PROGNAME@\fR automatically -preserves the integrity table in WIMs that have one, even when \fB--check\fR is -not specified. -.IP \[bu] -As of wimlib v1.5.0, a special "pipable" WIM format that is not compatible with -Microsoft's software is supported. This allows capturing and applying images -directly to standard output or from standard input, respectively; this can be -used to pipe images to or from a server over the network to implement fast -filesystem imaging and restore. -.IP \[bu] -On UNIX, because Microsoft designed the WIM file format to accomodate -Windows-specific and NTFS-specific features, wimlib must have two separate image -capture and application modes (although the \fB@IMAGEX_PROGNAME@\fR subcommands -for the modes are the same): one for general image capture and application, and -one for the capture or application of an image specifically from/to an NTFS -volume. +Because Microsoft designed the WIM file format to accomodate Windows-specific +and NTFS-specific features, on UNIX-like systems wimlib must have two separate +image capture and application modes (although the \fB@IMAGEX_PROGNAME@\fR +commands for the modes are the same): one for image capture and application +from/to a directory, and one for the capture or application of an image +specifically from/to an NTFS volume. .IP "" -Note: the above applies to UNIX builds of \fB@IMAGEX_PROGNAME@\fR. On the -Windows build, there is only one image capture and application mode, similar to -Microsoft's ImageX. +Note: the above applies to builds of \fB@IMAGEX_PROGNAME@\fR for UNIX-like +systems. On the Windows build, there is only one image capture and application +mode, similar to Microsoft's ImageX. .IP \[bu] -Microsoft's version has some weird limitations, like it won't let you extract a -WIM on a shared folder, and it requires some commands to be run only from -Windows PE and not from regular Windows. \fB@IMAGEX_PROGNAME@\fR does not have -these unusual limitations. +wimlib supports multithreaded compression, which can make it much faster to +create compressed WIM files. .IP \[bu] -There are bugs in Microsoft's WIM library and I obviously have not included the -same bugs in wimlib, although in some cases I have had to work around bugs for -compatibility purposes. +wimlib's XPRESS compressor is slightly better than Microsoft's (in terms of +compression ratio). .IP \[bu] -\fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@ optimize\fR, -which lets you easily remove wasted space in a WIM (which can arise after -a WIM image is appended or mounted read-write). +wimlib's LZX compressor is slightly worse than Microsoft's (in terms of +compression ratio), but it's still better than XPRESS compression. .IP \[bu] -\fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR, which lets you -easily join the parts of a split WIM. +\fB@IMAGEX_PROGNAME@ capture\fR defaults to LZX ("maximum") compression for new +WIMs, as opposed to Microsoft's software which defaults to XPRESS ("fast") +compression. .IP \[bu] \fB@IMAGEX_PROGNAME@\fR offers the extra commands \fB@IMAGEX_PROGNAME@ extract\fR and \fB@IMAGEX_PROGNAME@ update\fR, which let you quickly extract files from or make changes to a WIM image without mounting it. .IP \[bu] -\fB@IMAGEX_PROGNAME@ apply\fR supports keeping files hard-linked or symlinked -across WIM images when extracted from a WIM. So you can, for example, extract -different versions of Windows from an install.wim without using much extra -space. (Note: this functionality is only available in UNIX builds of wimlib.) +\fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@ +optimize\fR, which lets you easily remove wasted space in a WIM (which can arise +after a WIM image is appended or mounted read-write). .IP \[bu] -\fB@IMAGEX_PROGNAME@ capture\fR supports combining multiple separate directories -and files together in a configurable way to create a WIM image. +\fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR, +which lets you easily join the parts of a split WIM. .IP \[bu] -wimlib's XPRESS compressor is better than Microsoft's. +For convenience, \fB@IMAGEX_PROGNAME@\fR automatically preserves the integrity +table in WIMs that have one, even when \fB--check\fR is not specified. .IP \[bu] -wimlib's LZX compressor is worse than Microsoft's. +wimlib supports a special "pipable" WIM format (not compatible with Microsoft's +software). This allows capturing and applying images directly to standard +output or from standard input, respectively; this can be used to pipe images to +or from a server over the network to implement fast filesystem imaging and +restore. .IP \[bu] -wimlib supports multithreaded compression, which can make it much faster to -create compressed WIM files. +wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ capture\fR) +supports combining multiple separate directories and files together in a +configurable way to create a WIM image. .IP \[bu] -\fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes, -owners, and groups are stored. (Note: this functionality is only available in -UNIX builds.) +Microsoft's ImageX has some weird limitations, like it won't let you extract a +WIM on a shared folder, and it requires some commands to be run only from +Windows PE and not from regular Windows. \fB@IMAGEX_PROGNAME@\fR does not have +these unusual limitations. +.IP \[bu] +There are bugs in Microsoft's WIM library and I obviously have not included the +same bugs in wimlib, although in some cases I have had to work around bugs for +compatibility purposes. .IP \[bu] -\fB@IMAGEX_PROGNAME@ mount\fR and \fB@IMAGEX_PROGNAME@ mountrw\fR are much faster than -Microsoft's versions for some reason. I don't know what they have their program -do that takes so long to simply set up a mountpoint. (Note: this functionality -is only available in UNIX builds.) +wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ mount\fR) support +mounting an image from a split WIM, but Microsoft's software does not. (Note: +this functionality is not available in Windows builds of wimlib and +\fB@IMAGEX_PROGNAME@\fR.) .IP \[bu] -\fB@IMAGEX_PROGNAME@ mount\fR supports mounting an image from a split WIM, but -Microsoft's software does not. (Note: this functionality is only available in -UNIX builds.) +\fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes, +owners, and groups are stored. (Note: this functionality is only available in +builds of wimlib for UNIX-like systems.) .SH LOCALES AND CHARACTER ENCODINGS On Windows, wimlib works in UTF-16LE, and there should be no problems with character encodings. @@ -177,19 +183,15 @@ character encodings. On UNIX, wimlib works primarily in the locale-dependent multibyte encoding, which you are strongly recommended to set to UTF-8 to avoid any problems. .SH CASE SENSITIVITY -The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between UNIX -and Windows. \fB@IMAGEX_PROGNAME@\fR internally treats filenames as -case-sensitive, but on Windows it will treat paths actually provided by the user -as case-insensitive in order to get the "expected" behavior. Otherwise, options -and non-path arguments should be specified in lower case. -.SH WARNING -Note: \fBwimlib\fR and \fB@IMAGEX_PROGNAME@\fR are experimental. Use Microsoft's -imagex.exe if you have to make sure your WIM files are made "correctly". Feel -free to submit a bug report if you find a bug. -.PP -Some parts of the WIM file format are poorly documented or even completely -undocumented, so I've just had to do the best I can to read and write WIMs in a -way that appears to be compatible with Microsoft's software. +The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between +UNIX-like systems and Windows. Filenames are internally treated as +case-sensitive, but on Windows paths actually provided by the user will be +treated as case-insensitive in order to get the "expected" behavior. Otherwise, +options and non-path arguments should be specified in lower case. +.SH LICENSE +wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public +License version 3 or later. Be aware this means this software is provided as-is +and has no warranty; see COPYING for details. .SH REPORTING BUGS Report bugs to ebiggers3@gmail.com. .SH SEE ALSO diff --git a/make-windoze-release b/make-windoze-release index c185ee5a..c11138ef 100755 --- a/make-windoze-release +++ b/make-windoze-release @@ -25,20 +25,27 @@ fi make -j2 -rm -f $DESTDIR/{libwim-*.dll,doc/*,README*,NEWS*} +rm -f $DESTDIR/{libwim-*.dll,doc/*,README*,NEWS*,wim*.bat} cp .libs/imagex.exe $DESTDIR/wimlib-imagex.exe cp .libs/libwim-*.dll $DESTDIR cp README* NEWS $DESTDIR - - for fil in ./doc/wimlib-imagex-*.1; do - echo $fil base=`basename $fil` base=${base%%.1} + cmd=$(echo $base | sed s/wimlib-imagex-//) + if [ $cmd == mount -o $cmd == mountrw -o $cmd == unmount ]; then + continue + fi + + echo $fil #MANWIDTH=80 man $fil | col -b > $DESTDIR/doc/$base man -t $fil | ps2pdf - $DESTDIR/doc/${base}.pdf + sed 's/$/\r/g' > $DESTDIR/wim${cmd}.bat <<- EOF + @echo off + %~dp0\\wimlib-imagex $cmd %* + EOF done #for fil in $DESTDIR/{README*,NEWS} $DESTDIR/doc/*; do -- 2.43.0