From b324eaf164f9fa79e1ebbb7261e650fbde312374 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 7 Mar 2011 16:24:48 +0200 Subject: Start Part III, Profiles --- doc/manual.xhtml | 131 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 111 insertions(+), 20 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 41af7f8..85f03df 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -473,6 +473,24 @@ for consistency. + + PART III PROFILES + + + + 11Profiles Introduction + + + + 12Boost Profile + + + + +
12.1
12.2
12.3
+ + + @@ -1904,9 +1922,9 @@ class person object pointers. Plus, ODB profile libraries, that are available for commonly used frameworks and libraries (such as Boost and Qt), provide support for smart pointers found in these frameworks and - libraries. It is also easy to add support for our own smart pointers, - as described in Section 6.4, "Using Custom Smart - Pointers".

+ libraries (Part III, "Profiles"). It is also + easy to add support for our own smart pointers, as described in + Section 6.4, "Using Custom Smart Pointers".

3.3 Database

@@ -3350,16 +3368,16 @@ namespace odb

5 Containers

-

The ODB runtime library provides built-in persistence support for - all the commonly used standard C++ containers, namely, +

The ODB runtime library provides built-in persistence support for all the + commonly used standard C++ containers, namely, std::vector, std::list, std::set, std::multiset, std::map, and std::multimap. Plus, ODB profile libraries, that are - available for commonly used frameworks and libraries (such as Boost - and Qt), provide persistence support for containers found in these - frameworks and libraries. It is also easy to persist custom - container types as discussed later in Section 5.4, - "Using Custom Containers".

+ available for commonly used frameworks and libraries (such as Boost and + Qt), provide persistence support for containers found in these frameworks + and libraries (Part III, "Profiles"). It is also easy + to persist custom container types as discussed later + in Section 5.4, "Using Custom Containers".

We don't need to do anything special to declare a member of a container type in a persistent class. For example:

@@ -3694,18 +3712,18 @@ private:

6 Relationships

Relationships between persistent objects are expressed with pointers or - containers of pointers. The ODB runtime library provides built-in - support for the TR1 shared_ptr/weak_ptr, + containers of pointers. The ODB runtime library provides built-in support + for the TR1 shared_ptr/weak_ptr, std::auto_ptr, and raw pointers. Plus, ODB profile libraries, that available for commonly used frameworks and libraries - (such as Boost and Qt), provide support for smart pointers found - in these frameworks and libraries. It is also easy to add support - for a custom smart pointer as discussed later in - Section 6.4, "Using Custom Smart Pointers". Any supported - smart pointer can be used in a data member as long as it can be + (such as Boost and Qt), provide support for smart pointers found in these + frameworks and libraries (Part III, "Profiles"). It is + also easy to add support for a custom smart pointer as discussed later + in Section 6.4, "Using Custom Smart Pointers". Any + supported smart pointer can be used in a data member as long as it can be explicitly constructed from the canonical object pointer - (Section 3.2, "Object Pointers"). - For example, we can use weak_ptr if the object pointer + (Section 3.2, "Object Pointers"). For example, we can + use weak_ptr if the object pointer is shared_ptr.

When an object containing a pointer to another object is loaded, @@ -4422,7 +4440,7 @@ t.commit (); std::auto_ptr, and odb::lazy_ptr for raw pointers. The ODB profile libraries provide lazy pointer implementations for smart pointers from popular frameworks and - libraries.

+ libraries (Part III, "Profiles").

While we will discuss the interface of lazy pointers in more detail shortly, the most commonly used extra function provided by these @@ -6878,6 +6896,79 @@ namespace odb what() function returns a human-readable description of an error.

+ + + + +
+

PART III   + PROFILES

+ +

Part III covers the integration of ODB with popular C++ frameworks + and libraries.

+ + + + +
+

11 Profiles Introduction

+ +

ODB profiles are a generic mechanism for integrating ODB with other + C++ frameworks and libraries. A profile provides glue code, packaged + into a profile library, which allows you to seamlesly persist various + components, such as smart pointers, containers, and value types from + your favorite C++ framework or library. For example, the Boost profile + implementation is provided by the libodb-boost profile + library.

+ +

While we will need to link the profile library to our application, + it is also necessary to let the ODB compiler know which profiles we + are using. This is acomplished with the --profile + (or -p alias) option. For example:

+ + 
+odb --profile boost ...
+
+ +

Some profiles, especially those covering frameworks or libraries that + consist of multiple sub-libraries, provide sub-profiles which allow you + to pick and chooses which components you would like to use in your + application. For example, the boost profile contains + the boost/data-time sub-profile. If we are only + interested in the date_time types, then we can + pass boost/data-time instead of boost + to the --profile option, for example:

+ + 
+odb --profile boost/date-time ...
+
+ +

To summarize, you will need to perform the following steps in order + to make use of a profile in your application:

+ +
    +
  1. ODB compiler: if necessary, specify the path to the profile library + headers (-I option).
    2. +
  2. ODB compiler: specify the profile you would like to use with + the --profile option.
    3. +
  3. C++ compiler: if necessary, specify the path to the profile library + headers (normally -I option).
    4. +
  4. Linker: link the application with the profile library.
    5. +
+ +

The remaining chapters in this part of the manual describe the + individual profiles supported by ODB.

+ +
+

12 Boost Profile

+ +

The ODB profile implementation for Boost is provided by the + libodb-boost profile library. To enable all supported Boost + sub-libraries, specify boost as the profile name in + the --profile ODB compiler option. Alternatively you can + enable only specific sub-profiles. The available sub-profiles are + discussed in the following sections.

+ -- cgit v1.1