Using libraries

Before you can compile and build an app successfully, you must link against all of the libraries that you use in your app. You can add libraries to your app manually or by using the Add Library wizard in the Momentics IDE for BlackBerry.

You can add the following types of libraries using the Add Library wizard:

Standard BlackBerry platform library
Choose this option to add libraries that are included with the BlackBerry 10 OS. These libraries are packaged as part of the BlackBerry 10 Native SDK.
Library project in the workspace
Choose this option to add a dependency to another project in your workspace. Typically, this library is code that you created and want to reuse in multiple projects.

To create your own library, see Create a library.

External library
Choose this option to add libraries that exist outside of your workspace, such as third-party libraries or custom libraries that you created or ported for use with the BlackBerry Native SDK.

By default, external libraries aren't available on the device. Therefore, you must package external libraries that are used by your app as part of the .bar file. To do so, you must change the bar-descriptor.xml file in your project. If you don't complete this step, your app can't locate the shared libraries at runtime and it won't start or will start but terminate unexpectedly. For more information, see Add shared libraries to your .bar file.

You can also link against libraries by updating the compiler and linker settings in the Momentics IDE, adding the libraries to your Makefile, or specifying the libraries to link with in your build command. If these libraries are part of the BlackBerry Native SDK, they are available on BlackBerry 10 devices. However, if you want to use third-party libraries that are not available as part of the BlackBerry Native SDK, you need to import these libraries to your project with their associated header files. For more information, see Add libraries to a C project using project properties.

For a complete list of libraries that are available in the BlackBerry 10 Native SDK, see Library support.

Add libraries using the wizard

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.

Add libraries to your Cascades app manually

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

Don't use the prefix lib when you link to built-in libraries. The name of a library you enter is the text after the prefix lib. For example, to add the libcamapi library to your app, add LIBS += -lcamapi to your .pro file.

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

LIBS += -lbbcascadesmultimedia -lbbdevice -lbbsystem

This method isn't available for C projects.

Add libraries to a C project using project properties

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.

This method applies to C projects only. It can't be used for QML or C++ projects.

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.

    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.

Add shared libraries to your .bar file

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.

Create a library

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.

Screen showing a Cascades library in the Project Explorer and the readme.txt 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

Last modified: 2015-05-07



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus