Document how to build wxWidgets with liblzma support

Explain what needs to be done under MSW in order to use LZMA compression
classes.

docs/doxygen/mainpages/const_wxusedef.h

@@ -148,6 +148,7 @@ library:
 @itemdef{wxUSE_IPV6, Use experimental wxIPV6address and related classes.}
 @itemdef{wxUSE_JOYSTICK, Use wxJoystick class.}
 @itemdef{wxUSE_LIBJPEG, Enables JPEG format support (requires libjpeg).}
+@itemdef{wxUSE_LIBLZMA, Enables LZMA compression support (see @ref page_build_liblzma).}
 @itemdef{wxUSE_LIBPNG, Enables PNG format support (requires libpng). Also requires wxUSE_ZLIB.}
 @itemdef{wxUSE_LIBTIFF, Enables TIFF format support (requires libtiff).}
 @itemdef{wxUSE_LISTBOOK, Use wxListbook class.}

docs/doxygen/mainpages/liblzma.h

@@ -0,0 +1,140 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        liblzma.h
+// Purpose:     Documentation of the use of liblzma with wxWidgets
+// Author:      Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page page_build_liblzma Using LZMA compression with liblzma
+
+To use wxLZMAInputStream and wxLZMAOutputStream classes, a public domain
+liblzma library is required when building wxWidgets. This guide explains how to
+make liblzma available and let wxWidgets build system use it. The exact steps
+depend on the operating system and compiler used, please refer to the
+section appropriate for your environment below.
+
+@section page_build_liblzma_unix Unix-like operating system (including Cygwin)
+
+Under many Unix or Unix-like (including Cygwin) systems, liblzma is available
+as a system package and the simplest thing to do is to just install it using
+the system-specific tool (apt, yum, ...). Just note that you need to install
+the liblzma-dev or liblzma-devel package in order to obtain the library headers
+and not just the library itself.
+
+If your system doesn't provide such package or you need to use a newer version
+than is available in the system repositories, it is also simple to build
+liblzma from sources: basically, just download the library sources from
+https://tukaani.org/xz/ or clone its repository and perform the usual
+
+@code
+    $ ./configure
+    $ make
+    $ make install
+@endcode
+
+commands sequence.
+
+As wxWidgets is built using either configure or CMake under Unix-like systems,
+there is nothing special to do to let wxWidgets use liblzma, as it will be
+detected automatically -- just check the end of configure or CMake output to
+confirm that it was found. If this is not the case because the library was
+installed in some non-default location, you need to provide @c CPPFLAGS and @c
+LDFLAGS on configure command line, e.g.:
+
+@code
+    $ ../configure CPPFLAGS=-I/opt/liblzma/include LDFLAGS=-L/opt/liblzma/lib
+@endcode
+
+
+@section page_build_liblzma_msw MSW not using configure
+
+When not using configure, you must edit @c wx/msw/setup.h file and change the
+value of @c wxUSE_LIBLZMA option to @c 1 manually in order to enable LZMA
+support, which is disabled by default.
+
+Next, you need to actually ensure that the library is available to be able to
+build wxWidgets:
+
+@subsection page_build_liblzma_msw_vcpkg MSW using MSVS 2015 with Vcpkg
+
+If you build wxWidgets with Microsoft Visual Studio 2015.3 or later, you can
+use Microsoft vcpkg tool (see https://github.com/Microsoft/vcpkg) to install
+liblzma as any other library and integrate it with Microsoft Visual Studio
+automatically. Please see vcpkg documentation for details, but, basically, it's
+as simple as executing the following commands:
+
+@code
+    > git clone https://github.com/Microsoft/vcpkg.git
+    > cd vcpkg
+    > .\bootstrap-vcpkg.bat
+    > .\vcpkg integrate install
+    > .\vcpkg install liblzma
+@endcode
+
+Afterwards, liblzma headers and libraries (in DLL form) will be available to
+all C++ Visual Studio projects, including wxWidgets, so you just need to build
+it as usual, i.e. by opening @c build/msw/wx_vcXX.sln file and building it.
+
+
+@section page_build_liblzma_msw_manual MSW manual setup
+
+First of all, you need to either build or download liblzma binaries. Building
+the library from source with gcc requires configure, and as you don't use an
+environment capable of running it (if you're, you're reading the wrong section
+of this guide, please go to the first one instead), it might be simpler to just
+download the binaries from https://tukaani.org/xz/
+
+However these binaries don't provide import libraries for MSVC, so you may
+prefer building from source when using this compiler, provided it is at least
+2013.2 or later (otherwise, you must use the binaries and create the import
+library from the DLL). To do it, simply open the MSVS solution provided under
+@c windows directory of the source archive corresponding to your compiler
+version and build all the relevant configurations. Notice that you may build it
+as either a static or a dynamic library, but if you choose the former, you must
+also predefine @c LZMA_API_STATIC when building wxWidgets.
+
+
+Second, you need to let wxWidgets build system know about the liblzma headers
+and libraries location. When using makefiles, with either gcc or MSVC compiler,
+this can be done simply by specifying @c CPPFLAGS and @c LDFLAGS on make
+command line, e.g.
+
+@code
+    > make -f makefile.gcc CPPFLAGS=-Ic:/dev/include LDFLAGS=-Lc:/dev/lib
+@endcode
+
+If you built liblzma as a static library, change @c CPPFLAGS to also include @c
+-DLZMA_API_STATIC.
+
+
+When building wxWidgets with MSVC project files, you must update them to use
+liblzma. For this, start by copying build\\msw\\wx_setup.props file to
+build\\msw\\wx_local.props, if you don't have the latter file yet. Then open
+this file in your favourite editor and locate the @c Link tag inside an @c
+ItemDefinitionGroup tag and add a new @c AdditionalIncludeDirectories line
+inside the @c ClCompile tag as well as add @c liblzma.lib to the @c
+AdditionalDependencies tag under @c Link itself. The result should look like
+the following, assuming liblzma sources are in c:\\src\\liblzma:
+
+@code
+  <ItemDefinitionGroup>
+    <ClCompile>
+      ... any existing lines here ...
+      <AdditionalIncludeDirectories>c:\src\liblzma\src\liblzma\api;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <!--
+        Uncomment this line if, and only if, you link with liblzma statically.
+      <PreprocessorDefinitions>LZMA_API_STATIC;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+        -->
+    </ClCompile>
+    <Link>
+      <AdditionalDependencies>... all the previously listed libraries;c:\src\liblzma\windows\vs2017\$(Configuration)\$(Platform)\liblzma_dll\liblzma.lib;%(AdditionalDependencies)</AdditionalDependencies>
+    </Link>
+  </ItemDefinitionGroup>
+@endcode
+
+Afterwards, build wxWidgets as usual and don't forget to provide @c liblzma.dll
+when distributing your application unless you have decided to link it
+statically.
+ */

interface/wx/lzmastream.h

@@ -30,6 +30,9 @@
     }
     @endcode
 
+    See @ref page_build_liblzma for information about liblzma, required in
+    order to use this class.
+
     @library{wxbase}
     @category{archive,streams}
 
@@ -69,6 +72,9 @@ public:
     is compatible with xz utilities working with .xz files and also supported
     by 7-Zip program, even though it is different from its native .7z format.
 
+    See @ref page_build_liblzma for information about liblzma, required in
+    order to use this class.
+
     @library{wxbase}
     @category{archive,streams}