Component.cdef files can contain these sections:

Bundles

Lists additional files or directories to be copied from the build host into the application so they’re available to the app at runtime (e.g., audio files, web pages, executable scripts or programs built using some external build system).

This section is identical to the section with the same name in the .adef file.

C Flags

Provides a way to specify command-line arguments to pass to the compiler when compiling C source code files.

Flags are separated by whitespace.

cflags:
{
    -g -O0
    -DDEBUG=1
}

C++ Flags

Provides a way to specify command-line arguments to pass to the compiler when compiling C++ source code files.

Flags are separated by whitespace.

cxxflags:
{
    -std=c++0x
    -g -O0
}

Linker Flags

Provides a way to specify command-line arguments to pass to the compiler when linking C/C++ object (.o) files together into a component shared library (.so) file.

Flags are separated by whitespace.

ldflags:
{
    -Lfoo/bar
}

Provides

Lists things that this component provides (exports) to other software either inside or outside of the application.

The only subsection supported today is the api subsection.

API

Lists IPC services provided by this component to other components.

Contents use the same syntax as the the requires: api: section, except the options are different.

provides:
{
    api:
    {
        greet.api   // We offer the Greet API to others so they can say “hello” to the world.
        heat = digitalOutput.api
        cool = digitalOutput.api
    }
}
sources:
{
    greetServer.c
    tempControl.c
}

The component must implement the API functions being "provided".

In C, the source code must #include “interfaces.h” to get the auto-generated function prototype definitions and type definitions. The function and type names defined in the .api files will be prefixed with the interface name and an underscore (much as they are for "required" APIs).

In the above example, if greet.api defines a function called Send(), the C source code for the component (in greetServer.c) must implement a function called greet_Send().

[manual-start] Option

Normally, to reduce the amount of initialization code a component writer needs to write, the build tools will automatically try to advertise the service when the executable is run. However, sometimes this is not the preferred behaviour.

The [manual-start] option tells the build tools not to automatically advertise this API with the Service Directory when the process starts. If this option is used, the component can control exactly when it wants to start offering the service to others by calling the xxxx_AdvertiseService() function explicitly in the component source code when it is ready.

provides:
{
    api:
    {
        foo.api [manual-start]
    }
}

[async] Option

Often, the server of a service can simply implement the functions as if they were called directly by the client (even though the client may be running inside another process). So, when the client calls an API function, the server's API function gets called, and when the server returns from the function, the function returns in the client process.

However, sometimes the server needs to hold onto the client request and do other things (perhaps handing requests from other clients in the meantime) before sending a response back to the client and allowing the client to continue. This is called "asynchronous" mode, and it is enabled using the [async] keyword on the end of the api section entry.

provides:
{
    api:
    {
        bar.api [async]
    }
}

When asynchronous mode is enabled for a server-side interface, the generated code changes as follows:

A commandRef parameter is added to the beginning of all the API functions' parameter lists.
The return value is removed from every API function.
A Respond() function is generated for every API function.

In async mode, the server responds to the client's call to API function F() by calling the associated FRespond() function.

The Respond functions all take the commandRef as their first parameter. If an API function has a return value, that return value is sent to the client via the second parameter of the Respond function. Any output parameters defined in the API function are also passed as parameters to the Respond function.

See Language-Independent APIs for more information, or try it and have a look at the generated header files.

Requires

The "requires:" section is used to specify things that the component needs from its runtime environment.

It can contain various subsections:

API

Lists IPC APIs used by this component.

For example, if my component needs to use the Configuration Data API (defined in le_cfg.api) to read its configuration data:

requires:
{
    api:
    {
        le_cfg.api
    }
}

This creates a client-side IPC interface called "le_cfg" on this component, and it makes the functions and data types defined inside le_cfg.api available for use in the component's program code.

The name of the .api file (minus the ".api" extension) will be used as the name of the interface, and in C code, the names of functions and data types defined in the .api file will be prefixed with the name of the interface (plus an underscore separator).

requires:
{
    api:
    {
        print.api // WriteLine() from the API will appear in my C code as "print_WriteLine()".
    }
}

To rename the interface, an interface name followed by an equals sign ('=') can be added in front of the .api file path.

requires:
{
    api:
    {
        hello = greet.api // Send() from the API will appear as "hello_Send()" in my code.
    }
}

Multiple instances of the same API listed in the api: section must have unique instance names, and will appear as separate functions with different prefixes.

requires:
{
    api:
    {
        heat = digitalOutput.api   // Used to turn on and off the heater.
        cool = digitalOutput.api   // Used to turn on and off the cooling (A/C).
    }
}

If digitalOutput.api defines two functions On() and Off(), then the component’s source code would have four functions available to it: heat_On(), heat_Off(), cool_On(), and cool_Off().

C/C++ source code must #include “interfaces.h” to use the auto-generated function definitions. The build tools will automatically generate a version of interfaces.h customized for your component that includes all the declarations for all the interfaces that your component uses.

The build tools search for the interface definition (.api) file based on the interface search path.

Options

Normally, to reduce the amount of initialization code a component writer needs to write, the build tools will automatically generate the client-side IPC code for that API and automatically try to connect to the server when the executable is run. There are a couple of options that can be used to suppress this behaviour.

The [types-only] option tells the build tools the client only wants to use type definitions from the API. When this option is present, the client-side IPC code will not be generated for this API, but the types defined in the API will still be made available to the component (through interfaces.h in C/C++.)

The [manual-start] option tells the build tools not to automatically connect to this API's server when the process starts. If this option is used, the component can control exactly when it wants to connect to the server by calling the xxxx_ConnectService() function explicitly in the component source code.

requires:
{
    api:
    {
        foo.api [types-only]    // Only need typedefs from here.  Don't need IPC code generated.
        bar.api [manual-start]  // I'll start this when I'm ready by calling bar_ConnectService().
    }
}

File

Used to declare that certain files that reside on the target device outside of the application are to be made accessible to the application.

This section is the same as the section with the same name in the .adef file.

Dir

Used to declare that certain directories that reside on the target device outside of the application are to be made accessible to the application.

This section is the same as the section with the same name in the .adef file.

Lib

The lib: subsection of the requires: section is used to add a required library to a Component.

A required library is a library file that is expected to exist in the target file system (outside the application's sandbox) that the component needs access to at runtime.

Furthermore, this library will be linked with any executable that this component is a part of. The library name is specified without the leading "lib" or the trailing ".so".

requires:
{
    lib:
    {
        foo    // I need access to libfoo.so
    }
}

Component

Declares that this component depends on another component.

requires:
{
    component:
    {
        foo
        bar
    }
}

Any application that uses a component will also use any other components that component requires, and any components they require, etc.

Furthermore, specifying a dependency on another component ensures that calls to component initialization functions ( COMPONENT_INIT in C/C++ components ) will be sorted in the correct order. If component A depends on component B, then component B will be initialized first.

Dependency loops are not allowed. That is, a component C cannot depend on another component that (either directly or indirectly) depends on component C. The build tools will detect dependency loops and report an error.

Sources

Contains a list of source code files.

If C or C++ code, one source file must implement a COMPONENT_INIT function. The framework will automatically call that function at start-up.

sources:
{
    foo.c
    bar.c
    init.c      // This one implements the COMPONENT_INIT
}

Copyright (C) Sierra Wireless, Inc. 2014. Use of this work is subject to license.