Using libraries

You can add libraries to your project, whether they are standard BlackBerry platform libraries, library projects in your workspace, or libraries on your computer. To add libraries to your project:

1. In the Project Explorer view, right-click a project and select Configure > Add Library. Or select a project and, on the toolbar, click Project > Add Library.

2. In the Add Library Dependency dialog box, choose one of the following options:

   • Standard BlackBerry platform library - Choose this option to add libraries that are installed on the device or that the SDK provides. Click Next and select one or more libraries to add to your project.

   • Library project in the workspace - Choose this option to add a dependency to another project that exists in your IDE workspace. Click Next and select the workspace project and folders to add. You can view the source folders in a tree view, or as a flat list by selecting the Show include folders as a flat list option.

   • External library - Choose this option to add libraries that exist outside your workspace, such as third-party libraries. Click Next and provide the location of the library file and the directories to add to the include path. Location options are included for both device and simulator. If you aren't building and packaging your app for both, you can omit one.

3. Click Next to view the Summary page. Review the Summary page carefully to ensure that the build and packaging changes are as expected. To change your choices, click Back.

4. Click Finish.

To link against a library manually, add a LIBS variable to the .pro file for your app and specify the library name prefixed with -l. For example, if you want to link against the bb/cascades/multimedia library, you must include the following line:

LIBS += -lbbcascadesmultimedia

If you need to link against more than one library, you can list them all on the same line.

LIBS += -lbbcascadesmultimedia -lbbdevice -lbbsystem

If you know the name of the library you want to add to your project, you may find it faster to add it directly to a C project using the Properties dialog box. This technique is useful when the wizard doesn't list the name of the library you are adding.

To add a library to your app by using the Properties dialog box:

1. In the Momentics IDE, in the Project Explorer view, right-click a project and select Properties.
2. In the Properties dialog box, select C/C++ Build > Settings.
3. On the Tool Settings tab, select QCC Linker > Libraries.
4. In the Libraries section, click the Add button.
5. In the Enter Value dialog box, type the name of library and click OK.
   Tip: Don't type the prefix lib when you type the name of the library. The name of a library you enter is the text after the prefix of "lib". For example, if the function you want has a library name of libcamapi.so, type camapi to add the library.

If you use a shared library that's not part of the BlackBerry 10 Native SDK, the shared library isn't available on your device and must be packaged as part of your app.

You can add external shared libraries or libraries that you create. The BlackBerry 10 OS uses a runtime linker to find shared libraries for your app. The BlackBerry 10 OS loads a shared library only when it's not already loaded in memory. Shared libraries are identified by a fully qualified path in the LD_LIBRARY_PATH in the bar-descriptor.xml file of your app.

To identify the path to a shared library in your app:

1. In the Momentics IDE, open the bar-descriptor.xml file in your project. Click the Source tab.
2. Locate the LD_LIBRARY_PATH entry and specify the folder that your shared library is located in when it's deployed on a device or simulator.
3. Save the file.

You can create three types of libraries: Cascades, Static, and Shared. You can create a Cascades library to reuse Qt app logic or custom QML components. You can create a static or shared library to reuse C or C++ code. A static library is included in your .pro file and linked when you build a release version of your app. A shared library is bundled with your app and linked dynamically by your app when it starts.

To create a static or shared library, see Managing projects.

To create a Cascades library, use the New BlackBerry Project wizard in the Momentics IDE:

1. On the File menu, click New > BlackBerry Project.
2. In the left pane, select Library as your project type.
3. In the right pane, select Cascades as your library type and click Next.
4. In the Project name field, type a name for your project and click Next.
5. Select the API level that you want your library to compile against and click Finish.

Your Cascades library project opens in the Project Explorer view and the readme.txt file opens in the editor.

The readme.txt file describes how to do the following:

• Link the library to your app
• Build your app to link your library
• Use your Cascades library as a shared or static library
• Convert your Cascades library into a generic Qt library
• Debug your shared library
• Add translations for additional languages to your library