1\chapter{Getting Started} 2 3% ============================================================================ 4\section{Using VMime in your programs} 5 6First, make sure you have successfully compiled and installed VMime using the 7instructions described in Chapter \ref{chapter_building}. To use VMime in your 8program, you simply have to include VMime headers: 9 10\begin{lstlisting} 11#include <vmime/vmime.hpp> 12\end{lstlisting} 13 14\vnote{for versions older than 0.6.1, include $<$vmime/vmime$>$.} 15 16As of version 0.6.1, VMime uses {\vcode pkg-config} to simplify compiling and 17linking with VMime. The {\vcode pkg-config} utility is used to detect the 18appropriate compiler and linker flags needed for a library. 19 20You can simply build your program with: 21 22\begin{verbatim} 23 $ g++ `pkg-config --cflags --libs vmime` -static -o myprog myprog.cpp 24\end{verbatim} 25 26to use the static version, or with: 27 28\begin{verbatim} 29 $ g++ `pkg-config --cflags --libs vmime` -o myprog myprog.cpp 30\end{verbatim} 31 32to use the shared version. 33 34\vnote{it is highly recommended that you link your program against the shared 35version of the library.} 36 37All VMime classes and global functions are defined in the namespace 38{\vcode vmime}, so prefix explicitely all your declarations which use VMime 39with {\vcode vmime::}, or import the {\vcode vmime} namespace into the global 40namespace with the C++ keywork {\vcode using} (not recommended, though). 41 42 43% ============================================================================ 44\section{If you can not (or do not want to) use {\vcode pkg-config}} 45 46{\bf Linking with the shared library (.so):} compile your program with the 47{\vcode -lvmime} flag. You can use the -L path flag if the library file is 48not in a standard path (ie. not in /usr/lib or /usr/local/lib). 49 50\vnote{if you want to link your program with the shared version of VMime 51library, make sure the library has been compiled using CMake build system 52({\vcode make}, then {\vcode make install}). When you compile with SCons, 53only the static library is built and installed.} 54 55{\bf Linking with the static library (.a):} follow the same procedure as for 56shared linking and append the flag -static to force static linking. Although 57static linking is possible, you are encouraged to use the shared (dynamic) 58version of the library. 59 60 61% ============================================================================ 62\section{Platform-dependent code} 63 64While the most part of VMime code is pure ANSI C++, there are some features 65that are platform-specific: file management (opening/reading/writing files), 66network code (socket, DNS resolution) and time management. All the 67non-portable stuff is done by a bridge object called a platform handler (see 68{\vcode vmime::platform}). 69 70If your platform is POSIX-compatible (eg. GNU/Linux, *BSD) or is Windows, 71then you are lucky: VMime has built-in support for these platforms. If not, 72don't worry, the sources of the built-in platform handlers are very well 73documented, so writing you own should not be very difficult. 74 75If your VMime version is $<=$ 0.9.1, you should tell VMime which platform 76handler you want to use at the beginning of your program (before using 77\emph{any} VMime object, or calling \emph{any} VMime global function). 78 79So, if your platform is POSIX, your program should look like this: 80 81\begin{lstlisting}[caption={Initializing VMime and the platform handler}] 82#include <vmime/vmime.hpp> 83#include <vmime/platforms/posix/posixHandler.hpp> 84 85int main() 86{ 87 vmime::platform:: 88 setHandler <vmime::platforms::posix::posixHandler>(); 89 90 // Now, you can use VMime 91 // ...do what you want, it's your program... 92} 93\end{lstlisting} 94 95For using VMime on Windows, include 96{\vcode vmime/platforms/windows/windowsHandler.hpp} and use the following line 97to initialize the platform handler: 98 99\begin{lstlisting} 100vmime::platform:: 101 setHandler <vmime::platforms::windows::windowsHandler>(); 102\end{lstlisting} 103 104\vnote{since version 0.9.2, this is not needed any more: the platform 105handler is installed automatically using the platform detected during the 106build configuration.} 107 108\vnote{since version 0.8.1, {\vcode vmime::platformDependant} was renamed 109to {\vcode vmime::platform}. The old name has been kept for compatibility 110but it is recommended that you update your code, if needed.} 111 112