Port Self-contained Apps
Porting Apps with Root Access
Use Legato APIs and Build System
Use Your Own main() with Legato APIs

Port Self-contained Apps

Use this method to port your legacy apps if:

the apps don't require root privileges.
you can't (or don't want to) make changes to source code.

Here's the high-level steps port your app to Legato:

Build the app’s executables and libraries using the legacy program’s build system.

Create an .adef file for your app.

Leave the executables: section in .adef empty.

Include files to be installed as part of the app (executables, libraries, configuration files, devices, etc.) in the files: section of .adef.

Include files that need to be imported into the sandbox from the target’s file system (e.g., /dev/zero, /dev/null) in the import: section of .adef.

Add run: lines in the processes: section in the .adef to define processes that should run in the app.

Run mkapp on the .adef file to build the app.

Run instapp on the built app file to install the app on target.

Run app start appName on target to start the app.

Here's the foo.adef file (for application foo) that has executables bar1 and bar2 and needs library lib1. The application name should be the same as the .adef file name.

files:
    [rx] bar1   /bin/ 
    [rx] bar2   /bin/ 
    [r] lib1    /lib/
processes:
    run: (bar1) 
    run: (bar2)

To build the app, run:

 mkapp foo.adef

Other app settings (e.g., faultAction) can also be set in the .adef files. See adef processes.

Porting Apps with Root Access

Use this method if you're going to change your source code. It's necessary if your legacy apps require root privileges or access to system resources like /proc. This means your app will be ported as a non-sandboxed Legato app.

In the .adef file, you'll have to turn-off sandboxing:

sandboxed: false

Use Legato APIs and Build System

The preferred method to port a legacy app to Legato is to use the Legato build system, because it does framework initialization automatically.

To use Legato's build system:

Add this to all source files that will call Legato APIs:

 #include "legato.h"

Remove the legacy program's main() function. Complete any app-specific initializations and processing in the COMPONENT_INIT function. The Legato build system generates a main() function to initialize the Legato framework and call COMPONENT_INIT. This must be done for each executable in the app.

Optionally, modify the source to use the Legato event loop.

Optionally, modify the source to use Legato signal handlers, memory pools, IPC, etc.

Write the adef file for the app. The foo.adef file would be something like:

executables: 
    bar1 ( bar1.c ) 
    bar2 ( bar2.c )
processes: 
    run: (bar1) 
    run: (bar2)

Build the app using mkapp foo.adef -t target where [target] is something like wp7 or ar7.

Install the app on target using instapp.

The event loop is an essential part of Legato's event-driven apps where programs act only when events are triggered; otherwise, these event-driven apps are idle and don't consume the CPU. Using the event loop, each thread in the program has its own event queue.

Legacy apps may choose not to use the Legato event loop and can instead run their programs using legacy event processing.

Note:: If legacy event handling is used in conjunction with the Legato event loop, extreme care must be taken so the two systems don't interfere with each other.

Legato memory pools can also be used to allow programs to control memory use in a deterministic way; this avoids memory fragmentation, gives memory corruption protection, and allows Legato diagnostic tools to examine memory usage.

Legato apps don't use malloc() and free() directly. If legacy apps use malloc() and free(), they won't have the benefits of Legato memory pools.

Warning:: If memory pools are used in conjunction with malloc() and free(), memory fragmentation could occur.

Use Your Own main() with Legato APIs

Another option when porting legacy apps is to continue to use your own main() function and build system, and still take advantage of the Legato APIs.

To use the Legato APIs, you'll need to link the liblegato.so library and include legato.h in any source files that call Legato APIs. The _legato_InitFramework() function should be called before any Legato API functions are called.