Overview

The system definition (.sdef) files, application definition (.adef) files, and component definition (Component.cdef) files are used as input to the Build Tools mksys, mkapp, mkexe, and mkcomp (known collectively as the "mk tools").

These definition files, together with Language-Independent APIs, make it easier to develop reusable, component-based software within the Legato framework, and allows a great deal of boiler-plate code to be automatically generated.

Interfaces are defined using .api files. Implementations of those interfaces are constructed as reusable components. Components can be combined into applications. Applications can be installed and run on target devices. Furthermore, applications can be integrated into systems of communicating applications that can be deployed together to target devices.

.cdef Files

Component definition .cdef files are used to define the external interfaces and internal content of reusable software components.

Each component has a single Component.cdef file, which defines

what source code files are used to build the component
what files from the build system are to be included in any app that includes the component
what IPC interfaces the component exports or imports
memory pool sizes (future)
configuration settings for the component (future)

.adef Files

Application definition .adef files are used to define the external interfaces and internal content of applications that can be built, installed, and run on target devices.

.adef files can also be used to override some settings of components without having to change those components themselves, thereby making the components more reusable.

Each application has a .adef file, which defines

what executables should be built from what components
what additional files from the build system are to be included in the app
what processes should be started (by running what executables with what command-line arguments and environment variables) when the app starts
whether the app should automatically start when the target device boots
whether the app should be run in a sandbox
what files (or other file system objects) from the target root file system are to be made available to the app at runtime
what limits should be placed on the app at runtime (such as cpu limits, memory limits, etc.)
overrides for memory pool sizes and configuration settings for components in the app (future)
IPC bindings between components within the app

.sdef Files

System definition .sdef files are used to interconnect applications with each other and the targets runtime environment (e.g., hardware devices).

These files can also be used to override some settings of applications without having to change those applications themselves, thereby making the applications more reusable.

A .sdef file defines a system of one or more applications that can be deployed to target devices in the field. Each .sdef file lists

what apps are to be installed on the device
what IPC connections are permitted between apps
overrides for limits, configuration settings, and IPC bindings within apps

Note: Support for .sdef files is incomplete.

Common File Format

All of the definition files have the same basic format.

They're divided into sections with content specific to each section.

A section always starts with a section name followed by a colon (':').

sources:
    helloWorld.c

All sections are optional (they can be empty or omitted).

Sections can be in any order, multiple occurrences are permitted, and some sections have sub-sections.

Tabs, spaces, new-lines, and carriage-returns are all ignored (except that a newline terminates a C++ style comment), so the author's choice of indentation and spacing style is relatively unrestricted.

Comments

Comments can be included using

 // C++-style one-line comments.

 /* or
    C-style multi-line comments. */

Sample

/* Component.cdef file for a hypothetical web server component that provides a control API
 * (defined in httpdCtrl.api) that allows other apps to start and stop the web server via IPC.
 */

files:
    // Include all the web pages from the build host in the application, and have them appear
    // to the application under /var/www.

    htdocs   /var/www/

export :     // Note that space is allowed between the section name and the colon.

    httpdCtrl.api

sources:

    httpd.c

Build Tool Search Paths

Two are used:

source search path - lists file system directories where the build tools look for source code files and components.
interface search path - lists file system directories where the build tools look for interface definition files (.h files and .api files).

The default search path “.” is the current working directory where the build tool ran.

Search paths can be changed through mk tools command-line options:

'-s' (or ‘-c’) sets the source search path
‘-i’ sets the interface search path

$ mksys packageTracker.sdef -i ~/work/interfaces -s ~/work/components

Precedence and Overriding

Settings in a .sdef file override settings from both the .adef and Component.cdef, while the .adef overrides settings in the Component.cdef. This increases reusability by allowing an integrator to override a component's or app's settings without having to change that component or app.

Also, all configuration settings can be overridden on the target device at runtime (although, many will not take effect until the application is restarted).

Customizing Builds Using Environment Variables

It is possible to use environment variables inside of .sdef, .adef, and Component.cdef files.

This is done in the same way as in shell scripts, by prefixing the environment variable name with a dollar sign ($).

import:
    $BUILD_ROOT/interfaces/httpdCtrl.api

Some useful environment variables:

LEGATO_ROOT = path to where the Legato framework sources are located
TARGET = build target (e.g., ar7, wp7, localhost)
LEGATO_BUILD = shorthand for $LEGATO_ROOT/build/$TARGET

What's Next?

Application Definition (.adef) Files
Component Definition (.cdef) Files
System Definition (.sdef) Files

Or move to the next level:

Build Tools
Demo Applications