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