These sections are available in the .adef files:

sandboxed

Specifies if the app will be launched inside a sandbox.

Permitted content in this section is:

true - app will be run inside of a sandbox.
false - app won't be run in a sandbox.

The default is true.

If an app is not inside of a sandbox (unsandboxed), it can see the target device's real root file system. A sandboxed app can't see the target's real root file system; instead, a sandboxed app has its own, separate root file system (which it can't leave).

Each app has its own user ID and primary group ID. User name and primary group name is "appxxxx", where the "xxxx" is replaced with the name of the app.

Sandboxed apps aren't allowed to be members of other groups and are not allowed to have any capabilities (see "man 7 capabilities") set on their executables.

Unsandboxed apps are allowed to have executables with capabilities and be members of other groups (see the "groups:" section).

While a user and/or group will be automatically created if missing for the specified app, only users and groups of sandboxed apps will be automatically deleted when those apps are uninstalled.

sandboxed: false

start

Specifies if the app should start automatically at start-up: "auto" sets the app to start automatically by the Supervisor. "manual" sets the app to start through a manual prompt to the Supervisor. Default is auto.

start: auto

numProcs

Specifies the maximum number of processes allowed to run at one time: an integer number of processes. Default is 10.

numProcs: 4

mqueueSize

Specifies the maximum number of bytes that can be allocated for POSIX MQueues. Default is 512.

mqueueSize: 22

rtSignalQueueSize

Specifies the maximum number of real-time signals that can be queued (waiting for delivery) to processes. This can be per thread in the app.

Default is 100.

rtSignalQueueSize: 10

memLimit

Specifies the maximum amount of memory (in kilobytes) that all processes in an app can share. Default is 40960.

memLimit: 4000

cpuShare

Specifies the relative cpu share for an application.

Cpu share is used to calculate the cpu percentage for a process relative to all other processes in the system. New cgroups and processes default value of 1024 if not otherwise configured. The actual percentage of the cpu allocated to a process is calculated like this:

(share value of process) / (sum of shares from all processes contending for the cpu)

All processes within a cgroup share the available cpu percentage share for that cgroup like this:

cgroupA is configured with the default share value, 1024. cgroupB is configured with 512 as its share value. cgroupC is configured with 2048 as its share value.

cgroupA has one process running. cgroupB has two processes running. cgroupC has one process running.

This assumes all processes in cgroupA, cgroupB and cgroupC are running and not blocked waiting for an I/O or timer event, and another system process is also running.

Sum of all shares (including the one system process) is 1024 + 512 + 2048 + 1024 = 4608

The process in cgroupA will get 1024/4608 = 22% of the cpu. The two processes in cgroupB will share 512/4608 = 11% of the cpu, each process getting 5.5%. The process in cgroupC will get 2048/4608 = 44% of the cpu. The system process will get 1024/4608 = 22% of the cpu.

cpuShare: 512

fileSystemSize

Specifies the maximum amount of RAM that can be consumed by an app's temporary (volatile) file system at runtime. Default is 128K

fileSystemSize: 120K

files

Lists additional files to be included in an app so they’re available at runtime (e.g., audio files, web pages, executable scripts or programs from external build system).

Three things need to be specified for each file:

Access permissions - any combination of one or more of the following letters, enclosed in square brackets:

r = readable
w = writeable but changes will be discarded on reset
p = writeable and changes to it will be persistent (i.e., survive power failure or reset)
x = executable

If permissions values are not specified, then read-only ([r]) is the default.

Note: Access permissions aren't implemented yet.

Build system path - file system path on the build PC where the file is located at build time.

Target path - file system path inside the app sandbox on the target where the file will appear at runtime. The path can be relative to the directory where the .adef file is located. Paths of files included in the apps will be automatically prefixed during builds with "/opt/legato/apps/xxxx", where "xxxx" is replaced by the app name.

File paths can be enclosed in quotation marks (either single ' or double "). This is required when the file path contains spaces.

files:

    [r]     audio/alert.wav     /usr/share/sounds/
    [rx]  third-party/foobar/bin/foobar   /bin/
    htdocs/index.html   /var/www/
    "stuff/file name with spaces"  /usr/share/stuff/
    'stuff/another file'   /usr/share/stuff/

File Permissions

File permissions and ownership in the original file on the dev host file system are copied into the application for both users and groups.

When the application is installed on a target:

the owner and group are set to root on all files in the app.
the executable permission is removed from all files outside of the application's bin directory.
executable permission is granted to all directories.
executable permission is granted to all files inside the application's bin directory.
write permission is removed from everything in the application.
the setuid bit is cleared on everything in the application.

executables

Lists executables to be constructed and moved to the “bin” directory inside the app.

An executable’s content is specified inside parentheses after the name, and can be one of these:

relative file system path to source code file (e.g., a .c, .java, or .lua file)
component
relative file system path to library file (e.g., .a or .so file).

Only .c files, components, and libraries are currently supported.

executables:
    myexe1 ( file1.c libgoodstuff.so )
    myexe2 ( foobar toto )

If a component from the “components:” section is included in an executable, then that component will be built and linked into the executable, and its COMPONENT_INIT function will be run at process start-up. Furthermore, that component’s runtime files (shared libraries, Lua source code, etc.) will be packaged inside the application for installation on the target.

If a source file is included in an executable, the build tools will search for it in the file system according to the source search path. When found, it will be compiled (if written in a compiled language) and linked into the executable. Note that all the source files specified for an executable will together be considered a component (called "default"), and one of those source files will be expected to implement a COMPONENT_INIT function, which will get called at start-up.

If a library is “included in” an executable in this way, that library is expected to be found in the “import” or “files” section of the application’s .adef file or in the “files” section of the Component.cdef file of a component that appears in the “components:” section of the .adef file. When the executable is linked, it will be linked with these “included” libraries in the order in which they are listed. Note that it's permitted to list the same library more than once, as is sometimes necessary in order to satisfy all unresolved symbols, due to the single-pass nature of the linker.)

The mechanism by which the executable is constructed will depend on the type of content and the target device. For example, C files will be compiled and linked using the appropriate compiler tool chain, depending on what target device the application is being built for. The same goes for components written in C. Java code will be compiled to Java bytecode. Lua code will be simply copied into the application.

Note: In some cases, there may be incompatibilities between components or source code files that prevent them from being included in the same executable. For example, you may not be able to put Java sources and C sources into the same executable together. If you do violate one of these restrictions, the build tools will tell you about it.

import

The import section lists things imported to the app’s sandbox at runtime from outside of the sandbox. The contents appear similar to the files: section’s content, but meanings are different: Things listed in the “import” section are expected to be found on the target at runtime. They are not copied into the app at build time; they're made accessible to the app inside of its sandbox at runtime.

Currently, only virtual file system objects (files, directories, named sockets and pipes, device files, etc.) are explicitly imported. (Note: IPC interfaces are imported by components using the Component.cdef file’s “import” section.)

This section is ignored if the app is not sandboxed (if sandboxed set to false).

Items in the import section have essentially the same format as items in the files section, except the first path must be an absolute path (beginning with ‘/’).

The first path is the object to be imported. This is an absolute path in the target’s file system, outside of the sandbox (beginning with ‘/’).

The second path is the absolute file system path inside the app’s sandbox where the object will appear at runtime.

File paths can be enclosed in quotation marks (either single ' or double "). This is required when the file path contains spaces.

import:
    // I get character stream input from outside via a named pipe (read-only)
    /var/run/someNamedPipe  /var/run/

    // I need read and write access to UART2.
    [rw] /dev/ttyS1  /dev/

    // I need to be able to play back audio files installed in /usr/local/share/audio.
    "/usr/local/share/audio/error message.wav" /usr/share/audio/
    '/usr/local/share/audio/success message.wav' /usr/share/audio/

Permissions settings in import can't override permissions on the object in the target’s file system. If an object is read-only for the app’s user account in the root file system, it'll still be read-only accessible inside the app’s sandbox (even if imported “[rw]” in the app’s .adef file).

File permissions and ownership (group and user) on the original file in the target system remain in effect inside the sandbox.

groups

Add an unsandboxed app's user to groups on the target system. Not permitted for sandboxed apps.

groups:
    www-data
    modem

processes

The processes section of the .adef also has sub-sections, see adef processes.