Compilation Preprocessor Directives

The file _platform.h contains preprocessor directives that control the compilation process under various platforms. You can alter the definition of these directives to produce the desired version of the ZipArchive Library.

STL / MFC

The ZipArchive Library by default compiles using STL. If you wish to compile the library using MFC, make sure that _ZIP_IMPL_MFC is defined. If it is not defined, _ZIP_IMPL_STL will be automatically defined and the library will use STL.

Windows / Linux / OS X

The ZipArchive Library by default compiles for the Windows platform. If you wish to compile the library for the Linux/Mac OS X platform, make sure that _ZIP_SYSTEM_LINUX is defined. If it is not defined, _ZIP_SYSTEM_WIN will be automatically defined and the library will compile for the Windows platform.

Endianess Detection

The ZipArchive Library can work on little-endian and big-endian architectures. It tries a simple detection of the current architecture, but you may need to adjust it. By default, the library compiles for a little-endian architecture. Define _ZIP_BIG_ENDIAN to compile the library for a big-endian architecture.

Your Application Configuration

• Make sure that your application compiles with the same macro definitions as the ZipArchive Library.
  • If you are using Windows MFC, make sure that your application defines _ZIP_IMPL_MFC.
  • If you are using Linux/OS X, make sure that your application defines _ZIP_SYSTEM_LINUX.
• The makefile for Linux/OS X already defines _ZIP_SYSTEM_LINUX and the ZipArchive Library MFC projects configurations already define _ZIP_IMPL_MFC. You only need to define them in your project settings.
• To define these macros in your code, you can use one of the following methods:
  • define them in your code before including the ZipArchive.h file,
  • or define them globally in your project's settings:
    • VS 2022/2019/2017
      • Project Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions
    • Linux/OS X
      • define them e.g. in your makefile
  • or adjust the _platform.h file directly. The defined directives in this file will be visible to both the ZipArchive Library and your application. This solution however has some disadvantages:
    • If you are using original ZipArchive projects (they already define _ZIP_IMPL_MFC or _ZIP_SYSTEM_LINUX), you may receive macro redefinition warning.
    • If you are compiling applications for different platforms from the same ZipArchive Library sources, you may experience recompilation of the ZipArchive Library that follows every _platform.h file modification.

Compilation and Integration

The ZipArchive Library uses Microsoft Visual Studio C++ 2010 project files by default. To compile under a different environment, copy the appropriate project files to the ZipArchive Library sources folder. The project files can be found in the _projects folder in the library distribution sources package.

Microsoft Visual Studio

To add the ZipArchive Library functionality to your application you need to link the library with it. You can do it e.g. with one of the following methods. In both cases you need to include ZipArchive.h header in your sources.

Integration Method 1 (Simpler)

Add your application project and the ZipArchive Library project to the same solution/workspace and:

• VS 2022/2019/2017
  • Set your project to reference the ZipArchive Library project (on the Solution Explorer, either: right click your project, select References... from the menu and add the library or - depending on the version - click Add Reference...) on the References node.

When you use this method, the configurations in both your project and the ZipArchive Library project should match. Optimally, the configurations should have the same names.

Integration Method 2

• Add ZipArchive.lib to
  • VS 2022/2019/2017
    • Project Properties -> Linker -> Input -> Additional Dependencies
• Set the proper directories, so that Visual Studio can find the library and its headers. You can do this locally (for the current project only), or globally (for all projects):
  • To add the directories locally:
    • Add the ZipArchive.lib directory to:
      • VS 2022/2019/2017
        • Project Properties -> Linker -> General -> Additional Library Directories
    • Add the ZipArchive Library source code directory to the preprocessor searches
      • VS 2022/2019/2017
        • Project Properties -> C/C++ -> General -> Additional include directories
  • To add the directories globally, add them into appropriate places (Include Files and Library Files) in:
    • VS 2022/2019/2017
      • Project Properties -> VC++ Directories

Choosing STL/MFC Configurations

The Visual Studio projects provided with the ZipArchive Library already include appropriate preprocessor definitions for STL/MFC compilations.

• VS 2022/2019/2017>
  • To compile the STL version, use configurations that include STL in its names.
  • To compile the MFC version, use configurations that do not include STL in its names.

64-bit Compilation

• VS 2022/2019/2017
  • As from 4.6.4 version, x64 configurations are provided in the library projects.
  • Open Configuration Manager (Build -> Configuration Manager...).
  • In the Active solution platform select <New...>.
  • Select x64 platfrom in the Type or select the new platform field.
  • Keep Copy settings from set to Win32 and Create new project platforms checked.
  • Click OK.
  • Ensure x64 is selected in the Active solution platform drop down and you can now compile for x64.

How to Avoid Linking Problems

• Your project should use the MFC library and the Runtime Library in same way as the ZipArchive Library project. This can be set in:
  • VS 2022/2019/2017
    • Project Properties -> General -> Use of MFC
    • Project Properties -> C/C++ -> Code Generation -> Runtime library
• If you are compiling for Unicode, make sure that you have installed the necessary libraries. During installation you need to select Static Libraries for Unicode and Shared Libraries for Unicode. They are located in:
  • VS 2022/2019/2017
    • Not needed.
  You don't need to reinstall Visual Studio to add these libraries, just modify the installation.
• You should use the same character set in both your project and the ZipArchive Library project. This can be set in:
  • VS 2022/2019/2017
    • Project Properties -> General -> Character Set
• Treat wchar_t as Built-in Type option should be set to the same value in your application project and in the ZipArchive Project. This option can be found in:
  • VS 2022/2019/2017
    • Project Properties -> C/C++ -> Language -> Treat WChar_t as Built-in Type
  This value is set by default to:
  • VS 2022/2019/2017 - Yes or True.
  When compiling a project that uses the ZipArchive Library and Qt it may be required to set this value to False.
• When you create a new project configuration or modify an existing one that uses (or was using before your modification) MFC, you may experience some problems coming from the order that Visual Studio links libraries. This results in link errors saying that some symbols are already defined in a different library. In link errors you will probably see two libraries mentioned, such as mfcs80.lib and MSVCRT.lib. The libraries will differ depending on other settings. You may correct the order of linking in the following way:
  • Ignore both libraries in project's settings:
    • VS 2022/2019/2017
      • Project Properties -> Linker -> Input -> Ignore Specific Default Libraries
  • Add both libraries in the correct order in project's settings. The CRT library should go first (in the example above, this would be the MSVCRT.lib file.
    • VS 2022/2019/2017
      • Project Properties -> Linker -> Input -> Additional Dependencies
  The ZipArchive Library projects already define the correct linking order in some places, but if you change some settings (such as use of MFC, Runtime Library or Unicode), you will need to adjust the above settings. Also, if you will change the project settings to not use MFC, you will probably want to clear those settings.
• If you experience linking problems with projects that use ATL, you can try the following:
  • Try using MD configurations when dynamically linking to ATL and MT configurations when statically linking to ATL.
  • You may need to adjust the order of linking libraries as described above.
  • If you are using MFC, you may need to remove any using namespace declarations for ATL namespaces.
  • Try including ZipArchive.h file in a top level header, e.g. in stdafx.h.

Additional Considerations

• [Visual Studio 2022/2019/2017/2015/2013/2012/2010/2008/2005 only] When you deploy your project on a computer that does not have the related Visual Studio version installed, you may experience exceptions being thrown by your application that come from the fact that it cannot find correct libraries. In this case, you will probably need to install Microsoft Visual C++ Redistributable Package on the client machine depending with which version of Visual Studio the project was compiled. Make sure that you use the correct version of the package. There are versions for different platforms (x86, x64, IA64) and they depend on the service pack you have installed on your Visual Studio.

C++Builder and Borland

To compile the library under C++Builder, create e.g. a Static Library project, add source files to it and compile. If you receive an error during linking saying that [TLib Error] library too large, please restart with library page size 32. , increase the Page Size value in the Project Options on the "TLib" page. A value of 128 should be sufficient.

Linux/OS X

The ZipArchive Library does not use the Zlib library that is installed in the system. The Zlib library included in the ZipArchive Library is slightly modified for its needs.

• Compile the ZipArchive Library by typing: make The resulting file is a static library libziparch.a
• You can copy the library and the headers (if you have an appropriate rights) to /usr/lib and /usr/include/ziparchive (you can change them in Makefile) with the command: make install
• Now you can link the library to your application. If the library is in the same directory, as your application, you can for example, use the command:g++ $I. -o app app.cpp -lstdc++ -lziparch
• If you wish to uninstall the library type:make uninstall

iOS

The ZipArchive Library can be compiled for iOS using e.g. the following steps (appropriate for XCode 4):

• Create a new C/C++ Library project for OS X (available under File -> New -> Project -> OS X -> Framework & Library -> C/C++ Library).
• Click Next.
• Ensure the Type is set to Static, update other data as needed and finish creation of the project.
• In the project's build settings, set Base SDK to Latest iOS.
• Set Architectures to Standard.
• Verify that Build Active Architecture Only and Valid Architectures suit your needs (sometimes, you may want to add e.g. i386 architecture).
• Verify that the active scheme is set correctly (to iOS Device or a simulator).
• In the Preprocessor Macros section define macros to appropriate for your compilation. Unless you already defined them in the source code, normally, you will need to include there:
  • _ZIP_SYSTEM_LINUX=1
  • _ZIP_BZIP2_INTERNAL=1
• Build the project.

MinGW

You can compile the ZipArchive Library using the provided Makefile.mingw file under both the MSYS shell and the Windows Command Line.

• Under the MSYS shell type: make -f Makefile.mingw
• Under the Windows Command Line make sure that the path to the mingw32-make.exe file is known and then type: mingw32-make.exe -f Makefile.mingw

Additional Considerations

• MinGW should be compiled as a Windows STL version.
• Make sure that you have Windows API files installed in MinGW. These files are available at the MinGW web site.

CMake

It's possible to compile the ZipArchive Library using CMake, but the necessary macro definitions need to be included in the config file, e.g.:

IF((MSVC))
set_property(
TARGET ZipArchive
PROPERTY COMPILE_DEFINITIONS _USRDLL ZIP_BUILD_DLL ZIP_HAS_DLL
NO_DUMMY_DECL _CRT_RAND_S
)
ENDIF((MSVC))

CZipFile Implementations

The functionality described in this paragraph is usually handled automatically by the ZipArchive Library.
There are three implementations of the CZipFile class (responsible for file operations in the library):

• STL - uses STL libraries for file operation. Used for the STL version of the library.
• MFC - uses MFC libraries for file operation. Used for the MFC version of the library.
• Windows API - uses Windows API directly for file operations. Used under Microsoft Visual Studio 6.0 (MFC) and C++Builder, because the libraries under these compilers do not support large files.

If you need, you can adjust this behavior by setting the _ZIP_FILE_IMPLEMENTATION definition in the _features.h file to the following values:

• ZIP_ZFI_DEFAULT - to use default implementation.
• ZIP_ZFI_STL - to use STL implementation (possible with all versions of the library).
• ZIP_ZFI_WIN - to use Windows API implementation (possible with all versions of the library, but only under Windows).

The reason MFC implementation cannot be defined explicitly is that it can be used only with the MFC version of the library.

Integrating with C++/CLI applications

The Library can be used in a C++/CLI application. You can follow the steps below to create a simple CLR application (under Visual Studio 2022/2019/2017/2015/2013/2012/2010/2008/2005):

• Create a new C++ CLR Console Application
• Add the ZipArchive Library project to the solution
• Add a reference to the ZipArchive Library project in the sample application project (on the Solution Explorer, click References... and add the ZipArchive Library project)
• Include the ZipArchive.h header file. To avoid linking errors, you should place the include in the stdafx.h file.
• Compile the Debug Unicode STL MD or Release Unicode STL MD configuration. Use /clr switch.
• If you receive link errors, you can try reordering of headers inclusions in the stdafx.h file.

Compiling as DLL

Windows

• Your application that uses the ZipArchive Library as the DLL version needs to have ZIP_HAS_DLL defined. The ZipArchive.dll must be accessible for your application at the runtime. You can put it in your application's executable directory.
• The ZipArchive Library project configuration that compiles the DLL version needs to have ZIP_HAS_DLL and ZIP_BUILD_DLL defined.

Linux

On some systems (m68k and the SPARC), when you want to compile the ZipArchive Library for the dynamic linking, you need to modify makefile files (for the Zlib and ZipArchive) so that CFLAGS definition includes -fPIC.

UNC Paths and Very Long Paths (Windows Only)

To use the functionality described in this section, it is required to compile the ZipArchive Library in Unicode mode and use CZipFile implementation to use Windows API (see above).

• ZipArchive Library automatically includes the neccessary long path prefix when needed.
• To manually prefix the paths:
  • To use long UNC paths, replace \\ at the beginning of the UNC path with \\?\UNC\ ("\\\\?\\UNC\\" when escaped).
  • To use long file paths (not limited to 260 characters for file paths and 248 characters for folder paths) include \\?\ at the beginning of each path ("\\\\?\\" when escaped). Paths are limited to 32,767 characters in this case.