This manual is currently under construction. Pages may be missing, incomplete, or badly formatted.

Developer's Manual

Executable Archives: Automatic Execution

Automatic execution happens right after you upload an archive. If your device is in the prepared state upon upload, automatic execution is done right after your device is started.

Automatic execution is the monitored execution of a start script. It is monitored so that you can get information whether it is still running or finished, which you can use for further controlling from the outside.

The run status

The run status is a status information which is created by the nlXTP monitor, which is part of the nlXTP Guest Modules. [TODO: link to the guest modules] It contains the following values:

  • readable: bool, whether the exec_status directory exists and can be read by the host. All other values are unavailable when this is false.
  • isAlive: bool, whether the start script’s thread is still existing, and whether the nlXTP monitor is alive.
  • done: bool, set to true when the start script’s thread has exited.
  • custom_status: string, contains custom information that can be accessed from outside the device.

Especially the done value can be monitored to trigger new actions after the execution is finished.

Access to the run status

The values of the run status have to be pulled from your device. To avoid overload, the host updates these values at a certain interval. This interval increases over time, and is reset when executing any action on the respective element. [TODO: Mention at least the time frame you are talking about here. Its not clear if this is a matter of milliseconds or hours ]

Standard Output

You can access the standard and error output of your script at exec_status/out. To view this, you may need to download the archive directory.

Writing the start script

The start script can be written in any language, however, bash is preferred. It should start with a shebang (i.e., the first line defining the interpreter, like #!/bin/bash).

From the startscript, you have access to the variable $archive_dir which contains the path of the archive directory on the device. Additionally, you can use the function archive_setstatus which writes all its arguments into the custom status.

The start script is always executed in the archive directory as working directory.

Examples

This manual contains many examples for executable archives.

API References

[TODO: link] element_info rextfv_run_status