Creating an app bin
Contents
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&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 &.
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")
