Creating an app bin

From WikiDLXTV
Jump to: navigation, search

Introduction

App.bin files are a way to install new applications under WDLXTV. They can be installed on any plugged USB drive, or on a remote network share through NETMOUNT (for advanced users only!). The easiest method to install them under WDLXTV 0.5.0 is to access the Addons Manager through the WDTV webend. Users of older WDLXTV versions have to manually download the app.bin file, copy it to their plugged USB disk, then reboot to enable it.


Structure of an app.bin

app.bin consists of a filesystem (either cramfs or ext3) located inside a file.

When creating a custom app.bin you should follow these guidelines:

  • binaries should be placed in bin/ or sbin/ and not in usr/bin and usr/sbin
  • libraries should be placed in lib/ and not in usr/lib
  • modules should be placed in lib/modules/2.6.22.19-19-4
    • Since WDLXTV 0.4.7.3 it is no longer required to supply a modules.dep file - WDLXTV will take care of calling depmod for you when the app.bin is loaded.
  • etc/init.d/ contains the init scripts that will be called when the system boots & reboots
    • init.d scripts are start'd when the system boots and when /sbin/resume is executed
    • init.d scripts are stop'd when /sbin/suspend is executed (/sbin/reboot executes /sbin/suspend)
    • init.d scripts should contain at the minimum start and stop cases
    • only SXX scripts are executed during rcS


Here is an example test-app.app.bin structure:

README
version
application.xml
bin/test-bin01
bin/test-bin02
etc/init.d/S10test-app-init
lib/test-lib01.so
lib/test-lib01.so.0.3.0
lib/modules/2.6.22.19-19-4/test-module.ko
lib/modules/2.6.22.19-19-4/test-dep.ko
sbin/test-sbin01
sbin/test-sbin02
usr/bin/ignored-bin01
usr/sbin/ignored-sbin01

(See #XML Description file and #Other important files for an explanation of the application.xml, README and version files).


After test-app.app.bin is mounted by /bin/crazymount at /apps/test-app/ the following things happen:

  • /apps/test-app/bin and /apps/test-app/sbin are added to PATH
  • /apps/test-app/lib is added to ld.so.conf
  • ldconfig is refreshed
  • /apps/test-app/lib/modules/2.6.22.19-19-4 is scanned for modules and any found are symlinked into /lib/modules/2.6.22.19-19-4
  • /apps/test-app/etc/init.d/S10test-app-init is symlinked into /tmp/init.d for execution by rcS/suspend/resume


Now /apps/test-app/usr/bin and /apps/test-app/usr/sbin both contain binaries...but those two locations are not scanned, therefore binaries in both locations will not be available without full path.


There are two kernel modules inside of test-app.app.bin, here is the contents of /apps/test-app/lib/modules/2.6.22.19-19-4/modules.dep:
/lib/modules/2.6.22.19-19-4/test-module.ko: /lib/modules/2.6.22.19-19-4/test-dep.ko
/lib/modules/2.6.22.19-19-4/test-dep.ko:


This means that test-module.ko depends on test-dep.ko and therefore when test-module.ko is modprobe'd test-dep.ko will be inserted first by the system. Take note that the modules.dep file contains locations that are inside of /lib/modules/2.6.22.19-19-4 and not /apps/test-app/lib/modules/2.6.22.19-19.


Creating an app.bin

Once you have your files organized and ready for bundling into an app.bin, you must decide whether your app.bin will require write access to it or not. Writable app.bin must be built using ext3, while read-only app.bins will use cramfs.

appmake

devtools.app.bin includes the script appmake which will create app.bin images for you from a source directory. You need to supply a valid application.xml manifest in the root of your application dir for appmake to work (see below). Here are two examples

# ls -al src/encFS/
drwxr-xr-x    3 root     root          4096 Jun 26  2011 .
drwxr-xr-x   34 root     root          4096 Apr  5 19:30 ..
-rwxr-xr-x    1 root     root          1068 Jun 26  2011 application.xml
drwxr-xr-x    2 root     root          4096 Jun 15  2011 bin

# appmake src/encFS app/encFS

  File: encFS.app.bin
   Dir: app/encFS/
Format: cram
  Size: 167936 Bytes (164 KB)

created app/encFS/
generating CRAMFS encFS.app.bin... [ OK ]
checking CRAM filesystem...     [ OK ]
copying application.xml...      [ OK ]

# ls -al app/encFS/
drwxr-xr-x    2 root     root          4096 May 18 19:34 .
drwxr-xr-x   25 root     root          4096 May 18 19:34 ..
-rwxr-xr-x    1 root     root          1067 May 18 19:34 application.xml
-rw-r--r--    1 root     root         65536 May 18 19:34 encFS.app.bin
# ls -al src/eggdrop/
drwxr-xr-x   10 www-data www-data      4096 Jun 26  2011 .
drwxr-xr-x   34 root     root          4096 Apr  5 19:30 ..
-rw-r--r--    1 www-data www-data     25060 Jun  8  2011 README
-rw-r--r--    1 root     root          1081 Oct 27  2011 application.xml
drwxr-xr-x    5 www-data www-data      4096 Jun 15  2011 doc
lrwxrwxrwx    1 www-data www-data        14 Feb 19 11:31 eggdrop -> eggdrop-1.6.20
-rwxr-xr-x    1 www-data www-data    484636 Jun  8  2011 eggdrop-1.6.20
-rw-------    1 www-data www-data        91 Jun  9  2011 eggdrop.chan
-rwxr-xr-x    1 root     root         53217 Jun 26  2011 eggdrop.conf
-rw-------    1 www-data www-data       205 Jun 15  2011 eggdrop.user
-rwxr-xr-x    1 www-data www-data      1776 Jun 15  2011 eggdrop_wec.php
drwxr-xr-x    3 www-data www-data      4096 Jun 15  2011 etc
drwxr-xr-x    4 www-data www-data      4096 Jun 15  2011 help
drwxr-xr-x    2 www-data www-data      4096 Jun 15  2011 language
drwxr-xr-x    2 www-data www-data      4096 Jun 15  2011 lib
lrwxrwxrwx    1 www-data www-data        14 Feb 19 11:31 modules -> modules-1.6.20
drwxr-xr-x    2 www-data www-data      4096 Jun 15  2011 modules-1.6.20
drwxr-xr-x    2 www-data www-data      4096 Jun 15  2011 scripts
drwxr-xr-x    2 www-data www-data      4096 Jun 15  2011 text

# appmake src/eggdrop app/eggdrop

  File: eggdrop.app.bin
   Dir: app/eggdrop/
Format: ext3
  Size: 8388608 Bytes (8192 KB)

generating EXT3FS eggdrop.app.bin...    [ OK ]
creating EXT3 filesystem...     [ OK ]
setting EXT3 properties...      [ OK ]
checking EXT3 filesystem...     [ OK ]
mounting EXT3 filesystem...     [ OK ]
copying files...                [ OK ]
unmounting EXT3 filesystem...   [ OK ]
checking EXT3 filesystem...     [ OK ]
copying application.xml...      [ OK ]

# ls -al app/eggdrop/
drwxr-xr-x    2 root     root          4096 May 18 19:37 .
drwxr-xr-x   25 root     root          4096 May 18 19:34 ..
-rw-r--r--    1 root     root          1081 May 18 19:37 application.xml
-rw-r--r--    1 root     root       1347439 Oct 27  2011 eggdrop-1.6.20-4.app.tgz
-rw-r--r--    1 root     root       8294400 May 18 19:37 eggdrop.app.bin

Old School

The following page has detailed information on how to build your app.bin files - http://sourceforge.net/apps/trac/wdtvtools/wiki/Tutorials/CreateApplicationImage.

IMPORTANT: when using cramfs, you must use a 16K block size. Make sure your version of mkcramfs lets you specify a custom block size (some newer versions of it do), or that you are using a patched version of mkcramfs such as the one included in the WDLXTV's devtools.app.bin.


Loading and unloading app.bin

Starting with WDLXTV 0.5.0, you can use /usr/bin/app-plugman-web shell command to handle apps. This command lets you load or unload an app.bin without having to reboot.
You can also access the app repository with this tool and download new apps.
This is handy for developers to try out a new build without having to reboot the WDTV.

  usage: app-plugman-web list|listenabled|listdisabled
         app-plugman-web repolist [<repo>]
         app-plugman-web repoinfo <app.bin> [<repo>]
         app-plugman-web download <app.bin> <path> [<repo>]
         app-plugman-web enable|disable </full/path/to.app.bin>
         app-plugman-web load|unload </full/path/to.app.bin>

load and unload will allow you to dynamically load or unload your app.bin while testing it.


NOTE: You either have to source the file /tmp/sys.path or have to start a new shell session if your app.bin is modifying the system PATH, or else your existing session won't use any PATH changes done by the app.bin.

app-plugman-web load /path/to/your/nice.app.bin
. /tmp/sys.path


XML Description file

To describe your app.bin, you must include an XML description file, named application.xml. This file must be located at the root of your app.bin, and will be used by the Addons Manager and the online web repositories. Here is an example, as well as an explanation of the various entries:

<?xml version="1.0"?>
<application>
    <name>EncFS</name>
    <desc>EncFS is a Free (GPL) FUSE-based cryptographic filesystem that transparently 
          encrypts files, using an arbitrary directory as storage for the encrypted files.</desc>
    <author>recliq</author>
    <date>2011-03-26</date>
    <version>1.7.2-2</version>
    <category>System</category>
    <url>http://forum.wdlxtv.com/viewtopic.php?f=40&amp;t=2229</url>
    <size>458752</size>
    <force_size>458752</force_size>
    <format>cram</format>
    <provides>
        <binary>true</binary>
        <daemon>false</daemon>
        <kernelmodule>false</kernelmodule>
        <webend>false</webend>
    </provides>
    <dependencies>
        <model>LIVE</model>
        <model>PLUS</model>
        <basefirmware>
            <min>1.02.21</min>
            <max>1.02.21</max>
        </basefirmware>
        <firmware>
            <min>0.4.3.1</min>
            <max></max>
        </firmware>
        <wdtvext>false</wdtvext>
        <network>false</network>
        <config></config>
        <app>Main|someapp</app>
    </dependencies>
    <id>encFS</id>
    <download>encFS.app.bin</download>
</application>
 


name
The name of your application.
desc
A description of what your application does, no more than a few sentences.
author
The app.bin's author name(s)
date
Release date, using the YYYY-MM-DD format.
version
App.bin version. This will be used when determining if an update is available.
category
Category under which your app will appear on the Addons Manager.
size
The size of your app.bin (in bytes), this is set automatic by appmake in most cases.
force_size
The size of your app.bin (in bytes), if you need to enforce a minimum app.bin size - only needed for the ext3 format.
format
Which filesystem is used inside your app.bin file. Valid values are: cram (which will be read-only) and ext3 (which will be writable). This is used on the wdlxtv.com web repository to automatically generate an app.bin file out of SVN. cramfs is the default.
url
An URL pointing to a support website or forum post. Special chars must be replaced with HTML entities, i.e. & becomes &amp;.


The provides block contains a few entries pertaining to what your app.bin provides. These values must be set as "true" or "false".

binary
Whether your app.bin provides any binary file
daemon
Does it provide a daemon that runs in background
kernelmodule
Does it provide any new kernel module
webend
Does it provide a new icon on the webend or similar web interface


The dependencies block lists various requirements for your app.bin.

model
Which WDTV devices are supported. Add one new <model></model> block per device. Valid values are: LIVE, PLUS, G2.
basefirmware
Set min to the lowest supported BaseFW (if in doubt, use 1.01.00). max can be left blank if there is no known max supported version.
firmware
Set min to lowest supported WDLXTV version. max can be left blank if there is no known max supported version.
wdtvext
Is WDTVExt required?
network
Is network access required?
config
Required config setting(s) (eg. APACHE=ON)
app
Any other required app.bin, using the following syntax: reponame|appname. One block per required app.bin.
id
The ID by which your application will be identified, with no spaces. Usually use the app's name.
download
The filename of your app.bin. Usually it's something like <id>.app.bin.



Other important files

Two other files are required in your app.bin, especially if you want to have them submitted for hosting on the main repository

README
This should include a description of your application, some basic documentation (such as any custom configuration required by the user), and also include a basic changelog explaining the changes between various releases. This file will be viewable through the Addons Manager.
version
File only containing the numerical version (for example "1.0.5")


Adding webinterface controls