Compilation of the ZipArchive Library and Integration with Applications
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 / Mac 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/Mac OS X, make sure that your application defines _ZIP_SYSTEM_LINUX.
- The makefile for Linux/Mac 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 2008/2005/2003
- Project Properties -> C/C++ -> Preprocessor -> Preprocessor
Definitions
- VS 6.0
- Project Settings -> C/C++ -> Preprocessor -> Preprocessor
definitions
- Linux/Mac 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++ 2008 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 2008/2005/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. Optimally, the configurations should have the same
names.
Integration Method 2
- Add ZipArchive.lib to
- VS 2008/2005/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 projects):
- To add the directories locally:
- Add the ZipArchive.lib directory to:
- VS 2008/2005/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 2008/2005/2003
- Project Properties -> C/C++ -> General -> Additional include
directories
- VS 6.0
- Project Settings -> C++ -> Preprocessor -> Additional include
directories
- To add the directories globally, add them into appropriate places (Include
Files and Library Files) in:
- VS 2008/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 2008/2005/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 2008/2005/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 2008/2005/2003
- Language Tools \ Visual C++ \ 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 use the same character set in both your project and the ZipArchive Library
project. This can be set in:
- VS 2008/2005/2003
- Project Properties -> General -> Character Set
- VS 6.0
- Project Settings -> C/C++ -> Preprocessor -> Preprocessor
definitions - define UNICODE and
_UNICODE for Unicode or define _MBCS for
multi-byte 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 2008/2005/2003
- Project Properties -> C/C++ -> Language -> Treat wchar_t
as Built-in Type
This value is set by default to:
- VS 2008 and VS 2005 - True.
- VS 2003 - False.
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 2008/2005/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 2008/2005/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 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 2008/2005 only] When you deploy your project on
a computer that does not have Visual Studio 2008/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++ 2008 Redistributable Package or Microsoft Visual C++ 2005 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.
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.
Linux/Mac 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
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.
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 CodeGear 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 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.
- To use UNC paths, replace \\ at the beginning of the UNC
path with \\?\UNC\ (
"\\\\?\\UNC\\"
when escaped).
- To use paths not limited to MAX_PATH length (260 characters
by default):
- Explicitly define
CZipFile
implementation to use Windows API (see above).
- Include \\?\ at the beginning of each path (
"\\\\?\\"
when escaped).
Paths are limited to 32,767 characters in this case.