Installation

+ pugixml is distributed in source form. You can either download a source distribution + or checkout the Subversion repository. +

+ Source distributions +

+ You can download the latest source distribution via one of the following + links: +

http://pugixml.googlecode.com/files/pugixml-0.9.zip
+http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz
+

+ The distribution contains library source, documentation (the manual you're + reading now and the quick start guide) and some code examples. After downloading + the distribution, install pugixml by extracting all files from the compressed + archive. +

+ If you need an older version, you can download it from the version + archive. +

+ Subversion repository +

+ The Subversion repository is located at http://pugixml.googlecode.com/svn/. + There is a Subversion tag "release-{version}" for each version; + also there is the "latest" tag, which always points to the latest + stable release. +

+ For example, to checkout the current version, you can use this command: +

svn checkout http://pugixml.googlecode.com/svn/tags/release-0.9 pugixml

+ To checkout the latest version, you can use this command: +

svn checkout http://pugixml.googlecode.com/svn/tags/latest pugixml

+ The repository contains library source, documentation, code examples and + full unit test suite. +

+ Use latest version tag if you want to automatically get new versions via + svn update. Use other tags if you want to switch to + new versions only explicitly (for example, using svn switch + command). Also please note that Subversion trunk contains the work-in-progress + version of the code; while this means that you can get new features and + bug fixes from trunk without waiting for a new release, this also means + that occasionally the code can be broken in some configurations. +

+ Building pugixml +

+ pugixml is distributed in source form without any pre-built binaries; you + have to build them yourself. +

+ The complete pugixml source consists of four files - two source files, pugixml.cpp and + pugixpath.cpp, and two header files, pugixml.hpp and pugiconfig.hpp. pugixml.hpp is + the primary header which you need to include in order to use pugixml classes/functions; + pugiconfig.hpp is a supplementary configuration file (see Additional configuration + options). + The rest of this guide assumes that pugixml.hpp is either in the current directory + or in one of include directories of your projects, so that #include "pugixml.hpp" + can find the header; however you can also use relative path (i.e. #include "../libs/pugixml/src/pugixml.hpp") + or include directory-relative path (i.e. #include + <xml/thirdparty/pugixml/src/pugixml.hpp>). +

+ + + + + +

	Note
	+ You don't need to compile `pugixpath.cpp` unless you use XPath. +

+ Building pugixml as + a part of another static library/executable +

+ The easiest way to build pugixml is to compile two source files, pugixml.cpp and + pugixpath.cpp, along with the existing library/executable. This process + depends on the method of building your application; for example, if you're + using Microsoft Visual Studio^[1], Apple Xcode, Code::Blocks or any other IDE, just add pugixml.cpp and + pugixpath.cpp to one of your projects. +

+ If you're using Microsoft Visual Studio and the project has precompiled + headers turned on, you'll see the following error messages: +

pugixpath.cpp(3477) : fatal error C1010: unexpected end of file while looking for precompiled header. Did you forget to add '#include "stdafx.h"' to your source?

+ The correct way to resolve this is to disable precompiled headers for pugixml.cpp and + pugixpath.cpp; you have to set "Create/Use Precompiled Header" + option (Properties dialog -> C/C++ -> Precompiled Headers -> Create/Use + Precompiled Header) to "Not Using Precompiled Headers". You'll + have to do it for both pugixml.cpp and pugixpath.cpp, for all project configurations/platforms + (you can select Configuration "All Configurations" and Platform + "All Platforms" before editing the option): +

+ + +

+ next next next +

+ Building pugixml as + a standalone static library +

+ It's possible to compile pugixml as a standalone static library. This process + depends on the method of building your application; pugixml distribution + comes with project files for several popular IDEs/build systems. There + are project files for Apple XCode3, Code::Blocks, Codelite, Microsoft Visual + Studio 2005, 2008, 2010, and configuration scripts for CMake and premake4. + You're welcome to submit project files/build scripts for other software; + see Feedback. +

+ There are two projects for each version of Microsoft Visual Studio: one + for dynamically linked CRT, which has a name like pugixml_vs2008.vcproj, + and another one for statically linked CRT, which has a name like pugixml_vs2008_static.vcproj. + You should select the version that matches the CRT used in your application; + the default option for new projects created by Microsoft Visual Studio + is dynamically linked CRT, so unless you changed the defaults, you should + use the version with dynamic CRT (i.e. pugixml_vs2008.vcproj for Microsoft + Visual Studio 2008). +

+ In addition to adding pugixml project to your workspace, you'll have to + make sure that your application links with pugixml library. If you're using + Microsoft Visual Studio 2005/2008, you can add a dependency from your application + project to pugixml one. If you're using Microsoft Visual Studio 2010, you'll + have to add a reference to your application project instead. For other + IDEs/systems, consult the relevant documentation. +

++++ + + + + + + + + +

+ + Microsoft Visual Studio 2005/2008 + +	+ + Microsoft Visual Studio 2010 + +
+ + + +	+ + + +

+ Building pugixml as + a standalone shared library +

+ It's possible to compile pugixml as a standalone shared library. The process + is usually similar to the static library approach; however, no preconfigured + projects/scripts are included into pugixml distribution, so you'll have + to do it yourself. Generally, if you're using GCC-based toolchain, the + process does not differ from building any other library as DLL (adding + -shared to compilation flags should suffice); if you're using MSVC-based + toolchain, you'll have to explicitly mark exported symbols with a declspec + attribute. You can do it by defining PUGIXML_API + macro, i.e. via pugiconfig.hpp: +

#ifdef _DLL
+#define PUGIXML_API __declspec(dllexport)
+#else
+#define PUGIXML_API __declspec(dllimport)
+#endif
+

+ Additional configuration + options +

+ pugixml uses several defines to control the compilation process. There + are two ways to define them: either put the needed definitions to pugiconfig.hpp (it + has some examples that are commented out) or provide them via compiler + command-line. Define consistency is important, i.e. the definitions should + match in all source files that include pugixml.hpp (including pugixml sources) + throughout the application. Adding defines to pugiconfig.hpp lets you guarantee + this, unless your macro definition is wrapped in preprocessor #if/#ifdef + directive and this directive is not consistent. pugiconfig.hpp will never + contain anything but comments, which means that when upgrading to new version, + you can safely leave your modified version intact. +

+ PUGIXML_WCHAR_MODE define toggles + between UTF-8 style interface (the in-memory text encoding is assumed to + be UTF-8, most functions use char + as character type) and UTF-16/32 style interface (the in-memory text encoding + is assumed to be UTF-16/32, depending on wchar_t + size, most functions use wchar_t + as character type). See Unicode interface for more details. +

+ PUGIXML_NO_XPATH define disables XPath. + Both XPath interfaces and XPath implementation are excluded from compilation; + you can still compile the file pugixpath.cpp (it will result in an empty + translation unit). This option is provided in case you do not need XPath + functionality and need to save code space. +

+ PUGIXML_NO_STL define disables use of + STL in pugixml. The functions that operate on STL types are no longer present + (i.e. load/save via iostream) if this macro is defined. This option is + provided in case your target platform does not have a standard-compliant + STL implementation. +

+ + + + + +

	Note
	+ As of version 0.9, STL is used in XPath implementation; therefore, XPath + is also disabled if this macro is defined. This will change in version + 1.0. +

+ PUGIXML_NO_EXCEPTIONS define disables + use of exceptions in pugixml. This option is provided in case your target + platform does not have exception handling capabilities +

+ + + + + +

	Note
	+ As of version 0.9, exceptions are only + used in XPath implementation; therefore, XPath is also disabled if this + macro is defined. This will change in version 1.0. +

+ PUGIXML_API, PUGIXML_CLASS + and PUGIXML_FUNCTION defines let you + specify custom attributes (i.e. declspec or calling conventions) for pugixml + classes and non-member functions. In absence of PUGIXML_CLASS + or PUGIXML_FUNCTION definitions, + PUGIXML_API definition + is used instead. For example, to specify fixed calling convention, you + can define PUGIXML_FUNCTION + to i.e. __fastcall. Another + example is DLL import/export attributes in MSVC (see Building pugixml as + a standalone shared library). +

+ + + + + +

	Note
	+ In that example `PUGIXML_API` + is inconsistent between several source files; this is an exception to + the consistency rule. +

+ Portability +

+ pugixml is written in standard-compliant C++ with some compiler-specific + workarounds where appropriate. pugixml is compatible with the upcoming C++0x + standard (verified using GCC 4.5). Each version is tested with a unit test + suite (with code coverage about 99%) on the following platforms: +

+ Microsoft Windows: +
- + Borland C++ Compiler 5.82 +
- + Digital Mars C++ Compiler 8.51 +
- + Intel C++ Compiler 8.0, 9.0 x86/x64, 10.0 x86/x64, 11.0 x86/x64 +
- + Metrowerks CodeWarrior 8.0 +
- + Microsoft Visual C++ 6.0, 7.0 (2002), 7.1 (2003), 8.0 (2005) x86/x64, + 9.0 (2008) x86/x64, 10.0 (2010) x86/x64 +
- + MinGW (GCC) 3.4, 4.4, 4.5, 4.6 x64 +
+
+ Linux (GCC 4.4.3 x86/x64) +
+ FreeBSD (GCC 4.2.1 x86/x64) +
+ Apple MacOSX (GCC 4.0.1 x86/x64/PowerPC) +
+ Microsoft Xbox 360 +
+ Nintendo Wii (Metrowerks CodeWarrior 4.1) +
+ Sony Playstation Portable (GCC 3.4.2) +
+ Sony Playstation 3 (GCC 4.1.1, SNC 310.1) +

^[1] + All trademarks used are properties of their respective owners. +

+ Installation +

+ Getting pugixml +

+ Source distributions +

+ Subversion repository +

+ Building pugixml +

+ Building pugixml as + a part of another static library/executable +

+ Building pugixml as + a standalone static library +

+ Building pugixml as + a standalone shared library +

+ Additional configuration + options +

+ Portability +