Creating an app bin
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/184.108.40.206-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/220.127.116.11-19-4/test-module.ko lib/modules/18.104.22.168-19-4/test-dep.ko sbin/test-sbin01 sbin/test-sbin02 usr/bin/ignored-bin01 usr/sbin/ignored-sbin01
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/22.214.171.124-19-4 is scanned for modules and any found are symlinked into /lib/modules/126.96.36.199-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/188.8.131.52-19-4/modules.dep:
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/184.108.40.206-19-4 and not /apps/test-app/lib/modules/220.127.116.11-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> <url>http://forum.wdlxtv.com/viewtopic.php?f=40&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></app> </dependencies> <id>encFS</id> <download>encFS.app.bin</download> </application>
- The name of your application.
- A description of what your application does, no more than a few sentences.
- The app.bin's author name(s)
- Release date, using the YYYY-MM-DD format.
- App.bin version. This will be used when determining if an update is available.
- The size of your app.bin (in bytes), if you need to enforce a minimum app.bin size - only needed for the ext3 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.
- 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".
- Whether your app.bin provides any binary file
- Does it provide a daemon that runs in background
- Does it provide any new kernel module
- Does it provide a new icon on the webend or similar web interface
The dependencies block lists various requirements for your app.bin.
- Which WDTV devices are supported. Add one new <model></model> block per device. Valid values are: LIVE, PLUS, G2.
- 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.
- Set min to lowest supported WDLXTV version. max can be left blank if there is no known max supported version.
- Is WDTVExt required?
- Is network access required?
- Required config setting(s) (eg. APACHE=ON)
- Required other app.bin(s)
- The ID by which your application will be identified, with no spaces. Usually use the app's name.
- The filename of your app.bin
Other important files
While not mandatory, it is strongly recommended that you also include the following files at the root of your app.bin:
- Description, basic documentation, changelog, etc... This can be viewed by the end user through the Addons Manager.
- File only containing the numerical version (for example "1.0.5")