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_ARCHIVE_MFC is defined. If it is not defined, ZIP_ARCHIVE_STL will be automatically defined and the library will use STL. The Visual Studio projects provided with the ZipArchive Library already use appropriate definitions.

Windows / Linux

The ZipArchive Library by default compiles for the Windows platform. If you wish to compile the library for the Linux platform, make sure that ZIP_ARCHIVE_LNX is defined. If it is not defined, ZIP_ARCHIVE_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. In most cases the library compiles for a little-endian architecture by defining ZIP_ARCHIVE_LITTLE_ENDIAN. If it is not defined, ZIP_ARCHIVE_BIG_ENDIAN will be automatically defined and the library will compile for big-endian architecture.

Your Application Configuration

• If you are using the Windows STL version only, you don't need to worry about ZIP_ARCHIVE_MFC and ZIP_ARCHIVE_LNX definitions and you only need to care about the endianess (see above).
• In other cases than the above, 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_ARCHIVE_MFC.
  • If you are using Linux, make sure that your application defines ZIP_ARCHIVE_LNX.
• The makefile for Linux already defines ZIP_ARCHIVE_LNX and the ZipArchive Library MFC projects configurations already define ZIP_ARCHIVE_MFC. You only need to define them in your project settings.
• To define these macros in your code, you can take one of the following approaches:
  • define them in your code before including the ZipArchive.h file,
  • or define them globally in your project's settings:
    • VS 2005 and VS 2003
      • Project Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions
    • VS 6.0
      • Project Settings -> C/C++ -> Preprocessor -> Preprocessor definitions
    • Linux
      • 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_ARCHIVE_MFC or ZIP_ARCHIVE_LNX), 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++ 2005 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 this at least in two ways (in both cases you need to include ZipArchive.h header in your sources).

Integration Method 1 (Simpler)

Insert your application project and the ZipArchive Library project into the same solution/workspace and:

• VS 2005 and VS 2003
  • Set your project to reference the ZipArchive Library project (on the Solution Explorer, click References... and add the library).
• VS 6.0
  • Set project dependencies: your project dependent on ZipArchive project (click Project -> Dependencies and check the ZipArchive project).

When you use this method, the configurations in both your project and the ZipArchive Library project should match. Best, if the configurations are named the same.

Integration Method 2

• Add ZipArchive.lib to
  • VS 2005 and VS 2003
    • Project Properties -> Linker -> Input -> Additional Dependencies
  • VS 6.0
    • Project Settings -> Link -> Input -> Object/library modules
• 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 the projects):
  • To add the directories locally:
    • Add the ZipArchive.lib directory to:
      • VS 2005 and VS 2003
        • Project Properties -> Linker -> General -> Additional Library Directories
      • VS 6.0
        • Project Settings -> Link -> Input -> Additional library path
    • Add the ZipArchive Library source code directory to the preprocessor searches
      • VS 2005 and VS 2003
        • Project Properties -> C/C++ -> General -> Additional include directories
      • VS 6.0
        • Project Settings -> C++ -> Preprocessor -> Additional include directories
  • To add the directories globally into appropriate places (Include Files and Library Files)
    • VS 2005
      • Tools -> Options -> Projects and Solutions -> VC++ Directories
    • VS 2003
      • Tools -> Options -> Projects -> VC++ Directories
    • VS 6.0
      • Tools -> Options -> Directories

Choosing STL/MFC Configurations

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

• VS 2005 and VS 2003
  • 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.
• VS 6.0
  • To compile the STL version, use ZipArchive_STL.dsw or ZipArchive_STL_DLL.dsw project file.
  • To compile the MFC version, use ZipArchive.dsw or ZipArchive_DLL.dsw project file.

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 2005 and VS 2003
    • Project Properties -> General -> Use of MFC
    • Project Properties -> C/C++ -> Code Generation -> Runtime library
  • VS 6.0
    • Project -> Settings -> General -> Microsoft Foundation Classes
    • Project -> Settings -> C/C++ -> Code Generation -> Use run-time 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 2005 and VS 2003
    • Language Tools \ Visual C++ .NET \ Visual C++ Class & Template Libraries
  • VS 6.0
    • VC++ MFC and Template libraries \ MS Foundation Class Libraries
  You don't need to reinstall Visual Studio to add these libraries, just modify the installation.
• You should have defined (or undefined) Unicode in both your project and the ZipArchive Library project. Note, that Visual Studio 2005 creates Unicode projects by default, while the default ZipArchive Library configuration (Debug or Release) is not Unicode. If you start with a fresh application under Visual Studio 2005, you should choose, e.g. Debug Unicode (for MFC) or Debug STL Unicode configuration.
• 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 2005 and VS 2003
      • Project Properties -> Linker -> Input -> Ignore Specific Library
    • VS 6.0
      • Project Settings -> Link -> Input -> Ignore 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 2005 and VS 2003
      • Project Properties -> Linker -> Input -> Additional Dependencies
    • VS 6.0
      • Project Settings -> Link -> Input -> Object/library modules
  The ZipArchive Library projects already define the correct linking order, 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 it does not solve your problem with multiple symbol definitions, the reason is probably somewhere else.

Additional Considerations

• The ZipArchive Library uses a workaround to support the Zip64 format under Visual Studio 6.0 MFC, due to the fact that MFC in Visual Studio 6.0 lacks methods for >2GB files support. See Zip64 Format: Crossing the Limits of File Sizes and Number of Files and Segments for more information.
• [Visual Studio 2005 only] When you deploy your project on a computer that does not have Visual Studio 2005 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++ 2005 Redistributable Package on the client machine. A quick search in the Internet should take you in the right direction. Just make sure that you use the correct version. There are versions for different platforms (x86, x64, IA64) and they depend on the service pack you used on your Visual Studio (no SP, SP1).

CodeGear C++Builder and Borland

• To compile the library under CodeGear 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.
• To compile the library under Borland C++ 6.0 (MFC) you can use Visual C++ Project Conversion Utility (VCTOBPR.EXE) to create Borland projects. You can start this tool from the menu Tools->Visual C++ Project Conversion Utility.
  • Be sure to create Release subfolder first, otherwise you'll get a write error during compilation.
  • When you are compiling your application, add the compiled ZipArchive Library (ZipArchive.lib) to the project (Project->Add to Project) and compile.

Additional Considerations

• The ZipArchive Library does not support the Zip64 format for the Codegear C++Builder/Borland compilers, due lack of the appropriate support for files with sizes >2GB. Disable it before compiling the library. See Zip64 Format: Crossing the Limits of File Sizes and Number of Files and Segments for more information.

Linux

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

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.

Integrating with C++/CLI applications

The Library can be used in a C++/CLI application. The steps below will guide you through creating a simple CLR application (under Visual Studio 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 in the stdafx.h file.
  • You can add the ZipArchive Library directory to the Additional Include Directories in the project properties, and then you can include the header in this form: #include <ZipArchive.h>.
• Compile the Debug STL Unicode or Release STL Unicode configuration. Use /clr switch.
• If you receive link errors, make sure you have defined the ZipArchive.h header inclusion in the stdafx.h file. If it still doesn't help, you can try:
  • distinguish .NET Byte type from the Zlib library type with the same name; you can do it for example by providing the namespace name before the .NET type in your code: System::Byte (this should help if the linking error are related to ambiguous definition of the Byte type)
  • reorder headers inclusions in the stdafx.h file, if you have more headers included

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.