Application project structure

An application project contains a combination of mandatory and optional files and directories that are built into an EAP (Embedded Application Package) file with suffix .eap — the ACAP application.

The mandatory files are:

Filename	Description
[application name].(c/cpp)	Source file/files in C/C++.
LICENSE	Text file that lists all open source licensed source code distributed with the application.
Makefile	Defines how the source code is compiled, includes dependencies and sets compilation error levels.
manifest.json	Defines the application and its configuration. Used at installation of the package.

Other optional files and directories to include:

Filename	Type	Description
lib	Directory	Shared libraries custom to the application.
Postinstall Script	Shell Script	Executed at the installation of the application.
Preupgrade Script	Shell Script	Executed before upgrading the application, available from AXIS OS version 9.30.

manifest.json

The file manifest.json defines the application and its configuration.

An EAP package based on manifest.json is similar to one based on package.conf. If your ACAP application is based on package.conf, it is highly recommended to migrate to using manifest.json, see Migrating from package.conf to manifest.json.

Create a manifest.json from scratch

Create a manifest.json file based on the Manifest file schema.

To create the manifest file for a simple Hello World ACAP application:

1. Create a minimal manifest.json file with schema version:

• Schema version

Example

{
  "schemaVersion": "1.5.0"
}

2. Add basic metadata:

• Friendly name
• Identifier and binary
• Vendor name
• Version

Example

{
  "schemaVersion": "1.5.0",
  "acapPackageConf": {
    "setup": {
      "friendlyName": "Hello World",
      "appName": "hello_world",
      "vendor": "Axis Communications",
      "version": "1.0.0"
    }
  }
}

3. Add options for running mode:

• Running mode - the option never means that the application will not start or restart automatically.
• embeddedSdkVersion - the required embedded development version on the target device. Should always be set to 3.0 for new releases.

Example

{
  "schemaVersion": "1.5.0",
  "acapPackageConf": {
    "setup": {
      "friendlyName": "Hello World",
      "appName": "hello_world",
      "vendor": "Axis Communications",
      "version": "1.0.0",
      "runMode": "never",
      "embeddedSdkVersion": "3.0"
    }
  }
}

4. The resulting file.

The finished manifest.json, compare to the Hello World example manifest of the ACAP Native SDK examples.

{
  "schemaVersion": "1.5.0",
  "acapPackageConf": {
    "setup": {
      "friendlyName": "Hello World",
      "appName": "hello_world",
      "vendor": "Axis Communications",
      "version": "1.0.0",
      "runMode": "never",
      "embeddedSdkVersion": "3.0"
    }
  }
}

manifest.json content

For a list of all manifest fields and information on which are required, see Manifest schemas.

manifest.json schema

Manifest schemas have name format application-manifest-schema-v<X.Y>.json and are found in the native SDK container under /opt/axis/acapsdk/axis-acap-manifest-tools/schema/schemas.

You find descriptions of all available manifest fields for each version in Manifest schemas.

User and group

• It's recommended to use dynamic user in ACAP applications.
• Up until ACAP version 3 SDK, it was recommended to set sdk as user and group.
• At some point in the future, the sdk user will be deprecated and removed.

Dynamic user

To get a dynamic user, simply leave out acapPackageConf.user.group and acapPackageConf.user.username. The dynamic user will belong to the group addon.

An ACAP application with dynamic user will only have access to files installed under /usr/local/packages/<appName> and resources requested in the manifest.

The main advantage of using a dynamic user instead of sdk user is the higher level of security. The dynamic user does not have access to, and can not modify other ACAP applications.

Secondary groups

If the user needs additional groups, this can be specified under resources.

Example

{
  "schemaVersion": "1.5.0",
  "resources": {
    "linux": {
      "user": {
        "groups": ["storage"]
      }
    }
  },
  "acapPackageConf": {
    "setup": {
      "friendlyName": "Hello World",
      "appName": "hello_world",
      "vendor": "Axis Communications",
      "version": "1.0.0",
      "runMode": "never",
      "embeddedSdkVersion": "3.0"
    }
  }
}

License file

The LICENSE file is included in the application package. It shall contain all required open source license information for open source code distributed with the application package.

warning

If LICENSE is empty the build fails.

Local data

Application data such as configuration data and images should in runtime be saved to the localdata directory of the application project's root directory. The localdata directory is owned by APPUSR and the application has write access to it, once installed on a device. All content in the localdata directory remains after an application upgrade.

warning

Avoid continuous writes to localdata as it resides on a flash drive with limited write count per block. Internal wear leveling minimizes the risk of failure, however, it is still strongly recommended to avoid continuous writes.

info

The available free space is product dependent.