ActDK Project Structure

This document describes directories generated by actdk init.

• app
• model
• include
• manifesto
• .actdk
• .actdk/cache
• .actdk/long_descriptions

app

app is a directory for all scripts and executables running in the Actcast application. ActDK transfers all the directories and files in app into the Actcast application image.

model

model is a directory for nnoir files, which are sources of conversion (from deep-learning models to stub codes) by actdk compile.

include

The include directory contains c-header files generated by actdk compile to run the stub codes.

manifesto

The manifesto directory contains manifesto files used to describe the resources needed at runtime. The initialization process generates the files below.

• default.json
• pi4_or_later.json

The file names are arbitrary. You must specify what boards are supported and what devices are needed to run on the board.

.actdk

This directory contains configuration files about the project. The following files are stored:

• dependencies.json
• files.json
• setting.json

dependencies.json

dependencies.json specifies packages used in Actcast applications.

• "apt"
  • "apt" is for packages provided by Raspbian.
• "pip"
  • "pip" is for packages provided by pip3.

{
  "apt": ["libraspberrypi0", "libraspberrypi-bin", "python3", "python3-pil"],
  "pip": ["actfw-raspberrypi"]
}

You can specify dependencies for each target types for future extension. In target type wise dependencies, base_image can be set.

{
  "apt": ["python3", "python3-pil"],
  "pip": [],
  "raspberrypi-buster": {
    "apt": ["libraspberrypi0", "libraspberrypi-bin", "python3-pil"],
    "pip": ["actfw-raspberrypi"],
    "base_image": "idein/actcast-rpi-app-base:buster-1"
  }
}

• "base_image" (optional)
  • "base_image" is for Docker image that is used as the base of app.

files.json

files.json configures the project structure. It includes information about the Actcast application’s entry-point and the live monitoring script, but you don’t need to change this file for general usage.

{
  "main": "main",
  "healthchecker": "healthchecker",
  "act_setting": "act_settings.json"
}

setting.json

setting.json contains basic settings of the project. This file is generated by actdk init command automatically, but users can freely edit it by hand. However, please notice that re-running actdk init overwrites this file.

{
  "app_id": "example",
  "app_server_id": 48,
  "short_description": "A test application",
  "short_descriptions": {
    "ja": "テストアプリケーション",
    "eo": "Una testa aplikaĵo"
  },
  "target_types": [
    "raspberrypi-buster"
  ],
  "apt_repository": "http://one.of/raspbian/mirror"
}

• "app_id"
  • the application name
• "app_server_id"
  • the application ID
• "short_description"
  • the one-line description
• "short_descriptions"
  • One-line descriptions in languages other than English. Use language codes described in ISO 639-1 as property names and put the description in that language to values.
• "target_types"
  • Exists for future extension
• "apt_repository"
  • Used when you want to set up an apt mirror. mirror redirection system is used by default.

.actdk/cache

This directory is used by actdk to store project-local cache data. Users must not edit this directory directly. We recommend to add this path to .gitignore if you use git to manage the project.

Before version 1.7.0 of actdk, actdk used .actdklastremote and actdkbuildid for this purpse. Since version 1.7.0, these files are deprecated. Some commands of actdk automatically migrate these files to a new format if .actdk/cache/project_state.json does not exist, and these files exist.

.actdk/long_descriptions

When you write descriptions in languages other than English, put the description files under this directory. Use language codes described in ISO 639-1 as file name.

root.tar (optional)

Overview

root.tar is a tar archive that contains a directory tree to add directly to the app. By placing root.tar at the root of the project, you can include its contents in the application image.

When to use

In general, use .actdk/dependencies.json for packages that can be installed with apt or pip. Use a custom base_image when you need to add packages or files in a reusable Docker image. For details on base_image, see dependencies.json. Use root.tar when you want to bundle files directly in the project, instead of using apt, pip, or a custom base_image, and include them in the application image. Possible use cases include:

• the application needs a distribution that is not provided as an apt or pip package, such as a runtime distributed as a zip or tar.gz archive;
• vendor-provided files must be placed as-is, such as headers, shared libraries, or executables for a specific device;
• artifacts are hard to generate during actdk build, such as a native binary built in another environment;
• files must be placed outside the app directory at fixed paths, such as an executable under /usr/local/bin, runtime files under /opt/<name>, or shared libraries under /usr/lib.

How to create

Place the files to add under a directory, then archive that directory as root.tar.

For example, to place files under /opt/example and /usr/local/bin/example-command in the application image:

mkdir -p rootfs/opt/example rootfs/usr/local/bin
cp -R example-files/. rootfs/opt/example/
cp example-command rootfs/usr/local/bin/example-command
chmod 755 rootfs/usr/local/bin/example-command
tar --owner=0 --group=0 -C rootfs -cf root.tar opt usr

The paths in the archive are interpreted relative to the extraction destination directory. For example, when extracted to the root of the application image, an archive entry usr/local/bin/example-command will be placed at /usr/local/bin/example-command. You can check the archive contents with tar -tf root.tar.

Place the created root.tar at the root of the ActDK project before running actdk build or actdk upload.

To Application Development top