///////////////////////////////////////////////////////////////////////////// // Name: liblzma.h // Purpose: Documentation of the use of liblzma with wxWidgets // Author: Vadim Zeitlin // 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 ... any existing lines here ... c:\src\liblzma\src\liblzma\api;%(AdditionalIncludeDirectories) ... all the previously listed libraries;c:\src\liblzma\windows\vs2017\$(Configuration)\$(Platform)\liblzma_dll\liblzma.lib;%(AdditionalDependencies) @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. */