8.2. Linking with the library

Once the library is built, you can use it from your program. The general steps are:

  1. Modify your build system so that the library's header files can be included by your source code and its libraries can be linked with by your object code - specific instructions for Mac OS X, Windows, and POSIX systems are given below.

  2. Write code to save or load data to a database file.

  3. Compile the program.

  4. Link with the library.

  5. Run and debug your program.

  6. Rinse and repeat the last 4 steps until working as expected.

  7. Build your deployment package.

  8. Test your package.

  9. Repeat the above steps as necessary.

8.2.1. Linking on Mac OS X

If you use Xcode for your program:

  1. Add the serialization library's project file to your project.

  2. Add a dependency to the 'serialization_static' or 'serialization_dynamic' targets in the library's project.

  3. Add a dependency to the 'sqlite3_static' or 'sqlite3_dynamic' targets in the library's project.

  4. Select the library's project file entry in your project's main window.

  5. In the list of products displayed in the library's project, place a check in the checkbox for either the libserialization_static.a or libserialization.dylib products.

  6. In the list of products displayed in the library's project, place a check in the checkbox for either the libsqlite3_static.a or libsqlite3.dylib products.

  7. Write your code and build your program; if it fails to compile, check the header paths in your program's project; if it fails to link, check the library paths in your program's project.

  8. If you use the static library versions, go to the last step.

  9. Select your program's target in your program's project window and add a new Copy Files build phase (it should be placed after the "Link Binary With Libraries" build phase).

  10. Double click the added Copy Files phase.

  11. Change the Destination: popup menu to Executables.

  12. Clear the Path: edit field to empty.

  13. Close the Copy Files info window.

  14. Drag the libserialization.dylib and libsqlite3.dylib products into the new Copy Files build phase.

  15. Proceed as in the general instructions given above in the Linking with the library section.

If you use a Makefile, you should add CXXFLAGS and LDFLAGS so that the library's headers and library files are visible to the compiler/linker. You will also need to copy the serialization and sqlite3 libraries to the appropriate location: if you use the Xcode built libraries, then they belong with the final executable, otherwise they belong to a directory that lies on the PATH environment variable. Then proceed as in the general instructions given above in the Linking with the library section.

8.2.2. Linking on Windows

If you use Visual C++ for your program:

  1. Add the serialization library's project file to your solution: its name will be ccs_serialization.vc8.vcproj or ccs_serialization.vc9.vcproj.

  2. Add the sqlite3 library's project file to your solution: its name will be sqlite3.vc8.vcproj or sqlite3.vc9.vcproj.

  3. Select your program's project in your solution, then select Projects -> Project Dependencies... and check the checkboxes for the 'ccs_serialization' and 'sqlite3' projects. Close the dialog.

  4. Select Build -> Configuration Manager to open the Configuration Manager dialog, and for each valid configuration for your program, select the appropriate configuration for the 'sqlite3' and 'ccs_serialization' projects. For example, if you wish to use the dynamic library version of the 'sqlite3' and 'ccs_serialization' libraries, then for your program's Debug configuration, select the DebugDynamic configurations in the 'sqlite3' and 'ccs_serialization' projects, and for your program's Release configuration, select the ReleaseDynamic configurations. Be sure to close and open the Configuration Manager after setting each configuration because it sometimes gets confused and messes the settings up. Always double check the settings in the Configuration Manager otherwise you will end up building the wrong configurations.

  5. Write your code and build your program. If it fails to compile, check the include paths in your program's project by selecting your program's project in your solution, then select Project -> Properties -> Configuration Properties -> C/C++ -> General -> Additional Include Directories. If it fails to link, check the library paths in your program's project by selecting your program's project in your solution, then select Project -> Properties -> Configuration Properties -> Linker -> General -> Additional Library Directories, as well as Linker -> Input -> Additional Dependencies.

  6. If you use the static library versions, select your program's project in your solution, then go to Project -> Properties -> Configuration Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions. For each configuration that uses the serialization library, add a definition named CCS_API_STATIC to declare that you will be importing the library's interface statically. Then go to the last step.

  7. Select your program's project in your solution, then go to Project -> Properties -> Configuration Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions. For each configuration that uses the serialization library, add a definition named CCS_API_IMPORT to declare that you will be importing the library's interface dynamically (ie, using a DLL).

  8. Select your program's project in your solution, then select Projects -> Custom Build Rules..., then click Find Existing..., then navigate to the serialization library's proj_win directory, then select the CopyDLLs.rules Rule file.

  9. In the Visual C++ Custom Build Rule Files dialog, look in the Available Rule Files: list: the Copy DLLs rule that you just added should be listed. In its entry, place a check in the checkbox. Close the dialog.

  10. Select your program's project in your solution, then add the ccs_serialization.dll and sqlite3.dll libraries from <ccs_serialization_root>\build\ccs_serialization.vc8\Debug and <ccs_serialization_root>\build\sqlite3.vc8\Debug. Use the .vc8 directories if you are using Visual C++ 2005 and use the .vc9 directories if you are using Visual C++ 2008.

  11. Select the ccs_serialization.dll file that you just added to your project, then select View -> Other Windows -> Properties Window, and then change the Relative Path field to something like the following.

    • If your configurations are named DebugDynamic and ReleaseDynamic then change the Relative Path to:

      ..\path-to-serialization-library-root\build\ccs_serialization.vc8\$(ConfigurationName)\ccs_serialization.dll

    • If your configurations are named Debug and Release then change the Relative Path to:

      ..\path-to-serialization-library-root\build\ccs_serialization.vc8\$(ConfigurationName)Dynamic\ccs_serialization.dll

    Obviously, use ccs_serialization.vc9 if you are using Visual C++ 2008.

    Doing this change causes the debug version of the serialization library to be copied to your debug build directory when you build the debug version of your program, and similarly for the release version.

  12. Select the sqlite3.dll file that you just added to your project, then select View -> Other Windows -> Properties Window, and then change the Relative Path field to something like the following.

    • If your configurations are named DebugDynamic and ReleaseDynamic then change the Relative Path to:

      ..\path-to-serialization-library-root\build\sqlite3.vc8\$(ConfigurationName)\sqlite3.dll

    • If your configurations are named Debug and Release then change the Relative Path to:

      ..\path-to-serialization-library-root\build\sqlite3.vc8\$(ConfigurationName)Dynamic\sqlite3.dll

    Obviously, use sqlite3.vc9 if you are using Visual C++ 2008.

    Doing this change causes the debug version of the sqlite3 library to be copied to your debug build directory when you build the debug version of your program, and similarly for the release version.

  13. With the DLL copying set up, you should now be able to run/debug your program.

  14. Proceed as in the general instructions given above in the Linking with the library section.

8.2.3. Linking on POSIX

  1. In your Makefile, change the CXXFLAGS as necessary so that the serialization library's headers are visible to the compiler. For example, if you did not install the serialization library's headers in /usr/local/include then a -I/path/to/directory/containing/the/ccs/directory will have to be added to the CXXFLAGS. For example, the test program in the library's distribution adds this path like this:

    ccs_serialization_test_CXXFLAGS = -I$(includedir)

  2. If you use the 'GNU libtool' library builder, you can link with the library objects that the serialization library produces (because the library also uses GNU libtool to build its library files). To do so, add a dependency to the libccs_serialization.la library. For example, the test program in the library's distribution declares this dependency:

    ccs_serialization_test_LDADD = libccs_serialization.la

    After adding the dependency, go to the last step.

  3. Assuming you are not using the 'GNU libtool' library builder, then in your Makefile, change the LDFLAGS as necessary so that the serialization library's dynamic libraries are used by the linker. In other words, add these flags:

    -lsqlite3 -lccs_serialization
  4. In your Makefile, change the LDFLAGS as necessary so that the serialization library's (dynamic) libraries are visible to the linker. For example, if you did not install the serialization library's (dynamic) libraries in /usr/local/lib then a -L/path/to/directory/containing/the/built/libraries will have to be added to the LDFLAGS.

  5. You should now be able to compile/link/run your program.

  6. Proceed as in the general instructions given above in the Linking with the library section.