Creating an app bin

From WikiDLXTV
Revision as of 13:40, 18 June 2011 by RMerlin (Talk | contribs) (Added <category> tag)

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.

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 interact with an app.bin by using the /usr/bin/app-plugman-web shell command. This command lets you load or unload an app.bin without having to reboot (NOTE: you do 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). 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.


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>
    <format>cram</format>
    <provides>
        <binary>true</binary>
        <daemon>false</daemon>
        <kernelmodule>false</kernelmodule>
        <webend>false</webend>
    </provides>
    <dependencies>
        <model>LIVE</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), 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



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")
Retrieved from "http://wiki.wdlxtv.com/index.php?title=Creating_an_app_bin&oldid=1020"