Mercurial > thymian

comparison 3rdparty/vmime/doc/book/start.tex @ 0:a4671277546c tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
created the repository for the thymian project
author ferencd
date Tue, 17 Aug 2021 11:19:54 +0200
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:a4671277546c
1 \chapter{Getting Started}
2
3 % ============================================================================
4 \section{Using VMime in your programs}
5
6 First, make sure you have successfully compiled and installed VMime using the
7 instructions described in Chapter \ref{chapter_building}. To use VMime in your
8 program, 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
16 As of version 0.6.1, VMime uses {\vcode pkg-config} to simplify compiling and
17 linking with VMime. The {\vcode pkg-config} utility is used to detect the
18 appropriate compiler and linker flags needed for a library.
19
20 You 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
26 to 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
32 to use the shared version.
33
34 \vnote{it is highly recommended that you link your program against the shared
35 version of the library.}
36
37 All VMime classes and global functions are defined in the namespace
38 {\vcode vmime}, so prefix explicitely all your declarations which use VMime
39 with {\vcode vmime::}, or import the {\vcode vmime} namespace into the global
40 namespace 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
48 not 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
51 library, make sure the library has been compiled using CMake build system
52 ({\vcode make}, then {\vcode make install}). When you compile with SCons,
53 only the static library is built and installed.}
54
55 {\bf Linking with the static library (.a):} follow the same procedure as for
56 shared linking and append the flag -static to force static linking. Although
57 static linking is possible, you are encouraged to use the shared (dynamic)
58 version of the library.
59
60
61 % ============================================================================
62 \section{Platform-dependent code}
63
64 While the most part of VMime code is pure ANSI C++, there are some features
65 that are platform-specific: file management (opening/reading/writing files),
66 network code (socket, DNS resolution) and time management. All the
67 non-portable stuff is done by a bridge object called a platform handler (see
68 {\vcode vmime::platform}).
69
70 If your platform is POSIX-compatible (eg. GNU/Linux, *BSD) or is Windows,
71 then you are lucky: VMime has built-in support for these platforms. If not,
72 don't worry, the sources of the built-in platform handlers are very well
73 documented, so writing you own should not be very difficult.
74
75 If your VMime version is $<=$ 0.9.1, you should tell VMime which platform
76 handler 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
79 So, 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
85 int 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
95 For using VMime on Windows, include
96 {\vcode vmime/platforms/windows/windowsHandler.hpp} and use the following line
97 to initialize the platform handler:
98
99 \begin{lstlisting}
100 vmime::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
105 handler is installed automatically using the platform detected during the
106 build configuration.}
107
108 \vnote{since version 0.8.1, {\vcode vmime::platformDependant} was renamed
109 to {\vcode vmime::platform}. The old name has been kept for compatibility
110 but it is recommended that you update your code, if needed.}
111