Critically, if developing in C or C++, one source file must contain the Component constructor - called COMPONENT_INIT - which is the entry point to all the code in the Component. Note that unlike 'main()', COMPONENT_INIT must run to completion (and return) or the rest of your Application will not run.

It is a requirement to put all the files pertaining to a component into a separate subdirectory. Developer Studio uses the convention Component to name the Component directory to distinguish Component 'projects' from 'Application' projects - but it is not mandatory to follow this convention. In fact, having long (longer than about 20 characters) Component directory names can cause problems with the build tools and lead to some subtle and hard to track down errors. So chose a naming convention that lets you identify Components as opposed to Applications and use that.

In this article, the example application to flashes a led is called flashled, and for clarity the component source files will be in a directory called flashledComponent. The actual name is not important, but the directory name must be known as it is required by the .adef file to build the application correctly.

Component.cdef

Component.cdef (and it must be called 'Component.cdef') is the definition file that ties the Component together and describes to the build tools how to build the Component. Component.cdef is a plain text file easily editable by a normal text editor.

The Component.cdef file is built up of a number of sections that each describe various elements that make up the component. There are many other sections other than those described below that can be added to the Component.cdef file - see http://legato.io/legato-docs/latest/defFilesCdef.html for the canonical list and examples.

/*
 * sources section:
 *  list of source files required to build this component
 *  One file per line, case sensitive, including file extension 
 *  One file MUST have the COMPONENT_INIT{ } definition (the main(){} equivalent)
 */

sources:
{
    main.c
}

/*
 * requires section:
 *  specify external 'things' this component requires from the external
 *  environment
 */
requires:   
{
    apis:
    {
        GPIO1 = le_gpio.api // create an instance of the le_gpio.api
                // called GPIO1
    }
}

Source Files

As with a normal Linux application, a Component can consist of multiple source files as required by the developer. The name (including extension) of each source file must be listed in the 'sources:' section of Component.cdef or it will not be included in the build. C and C++ source files should follow the naming conventions' for GCC (.c for C source files, .cc, cxx, .cpp or .c++ for C++ files).

Header files (.h, .hxx, .hpp etc) to share constants or function declarations between source files in a Component are also allowed, but header files are not to be listed in the 'sources:' section.

There is no requirement for a particular name for the source file that contains COMPONENT_INIT, although it is a good idea to follow a common naming convention across all your Components. By default, Developer Studio names the 'main' file of a Component after the name of the Component - so for the flashled example given above, the source containing COMPONENT_INIT would be called flashled.c, in the directory flashledComponent. But if you are more comfortable naming this source file 'main.c' or 'init.c' then this will cause no problems to the build tools - as long as the correct name is in the 'sources:' section of Component.cdef.

Sample source file (main.c) for Component.cdef above

#include "legato.h"
#include "interfaces.h" /* include auto-generated api interfaces from Component.cdef */

/*
 * NOTE: GPIO1 is 'created' as an instance of le_gpio using requires: api:
 * section in Component.cdef
 */

COMPONENT_INIT
{
    le_result_t result = LE_OK;

    LE_INFO( "Component Init" );

    // configure GPIO - use WP85 pin GPIO25
    // constant renamed from LE_GPIO_ACTIVE_HIGH via binding in adef

    result = GPIO1_SetPushPullOutput( GPIO1_ACTIVE_HIGH, true ); 
    if ( result != LE_OK )
    {
        LE_INFO("SetPushPullOutput returned [%d]", result );
    }

    // turn on GPIO (set 'high')
    result = GPIO1_Activate();

    if ( result != LE_OK )
    {
        LE_INFO( "GPIO1_Activate returns [%d:%s]",
            result, LE_RESULT_TXT(result) );
    }
}

Where's my debug output?

All standard and error output from a Legato application is redirected behind the scenes to the system logger (syslogd) - so even if you have a serial connection to the 'console' port you won't see any messages. There are two ways to see the system logger output:

1. Using Developer Studio

The system log is available in Developer Studio in the 'Device Management' perspective under the 'Legato Console' tab at the bottom of the screen. The Legato Console tab also has some filtering capability to allow you to filter the output to only show log information from your application of interest.

2. Using command line

After logging into the mangOH/WP85 platform, use the command 'logread -f' to continuously scroll the system log on the console. There is no native filtering capability, but the output can be paused by pressing <CTRL>S and restarted by pressing <CTRL>Q.

Application.adef

Each application requires an adef file to describe all the resources required to build the Legato Application. Unlike the Component definition file, there is no requirement for a fixed name for the adef file - although the convention is to name the adef file after the name of the Application. As an example, the 'flashled' Application referred to above would have an adef filed named 'flashled.adef'.

executables:
{
    flashled = ( flashledComponent )
}

processes:
{
    run:
    {
        ( flashled )
    }
}

<executable>.<component>.<component_api> = service.service_api

Sample flashled.adef file

/*
 * executables section
 *  define executable processes for this application
 */
executables:
{
    flashled = ( flashledComponent )
}
/*
 * processes section:
 *  describe to Legato Supervisor what processes to run when Application
 *  is started
 */
processes:
{
    run:
    {
        ( flashled )
    }
}

/*
 * bindings section:
 *  connect internal interfaces to external services
 */
bindings:
{
    flashled.flashledComponent.GPIO1 -> gpioService.le_gpioPin25
}

Comments in definition files

It is possible to add comments to both the Component.cdef and Application.adef files. Comments take the form of 'C' comments:

/* to start a (multiline) block comment

*/ to end a (multiline) block comment

// for a single (to end of line) line comment

What's this 'sandbox' stuff all about?

Legato Applications have been designed to be as 'Secure by Default' as possible. To achieve this all Legato Applications run inside a secure 'sandbox' environment unless explicitly configured otherwise by the application developer. This means that a Legato Application cannot (by default) contact, corrupt or otherwise interfere with either other Legato Applications or the underlying Linux kernel and root file system.

This may become an issue for some applications that need direct access to particular hardware, and there is an option to 'un-sandbox' an Application by modifying the .adef file.

How do I stop my application from starting automatically?

By default, a Legato Application is configured to start automatically after being uploaded to the mangOH/WP85 platform, or when the Legato Supervisor on the mangOH/WP85 platform starts. Sometimes this autostart behaviour is not desired - especially when debugging an application that is crashing.

To stop an Application from starting automatically, add the following line to the top of the Application .adef file:

start: manual

For more information on managing the startup state of an application, please see the Tip Controlling Application Startup and the Legato documentation here: http://legato.io/legato-docs/latest/defFilesAdef.html#defFilesAdef_start