Difference between revisions of "Creating an app bin"

From WikiDLXTV
Jump to: navigation, search
(Rewritten, and updated for XML manifest)
Line 1: Line 1:
 +
== 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:
 
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
 
* 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
 
* libraries should be placed in lib/ and '''not''' in usr/lib
 
* modules should be placed in lib/modules/2.6.22.19-19-4
 
* modules should be placed in lib/modules/2.6.22.19-19-4
** lib/modules/2.6.22.19-19-4 can contain a modules.dep file which will be added to /lib/modules/2.6.22.19-19-4/modules.dep for modprobe insertion of app.bin modules
+
** 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
 
* 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 start'd when the system boots '''and''' when /sbin/resume is executed
Line 11: Line 19:
  
  
For example, I have '''test-app.app.bin''' containing the following structure:
+
Here is an example '''test-app.app.bin''' structure:
<tt><br/>README<br/>
+
version<br/>
+
bin/test-bin01<br/>
+
bin/test-bin02<br/>
+
etc/init.d/S10test-app-init<br/>
+
lib/test-lib01.so<br/>
+
lib/test-lib01.so.0.3.0<br/>
+
lib/modules/2.6.22.19-19-4/modules.dep<br/>
+
lib/modules/2.6.22.19-19-4/test-module.ko<br/>
+
lib/modules/2.6.22.19-19-4/test-dep.ko<br/>
+
sbin/test-sbin01<br/>
+
sbin/test-sbin02<br/>
+
usr/bin/ignored-bin01<br/>
+
usr/sbin/ignored-sbin01<br/></tt>
+
  
 +
<nowiki>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
 +
</nowiki>
  
'''Note:'''
+
(See [[#XML Description file]] and [[#Other important files]] for an explanation of the application.xml, README and version files).
* The '''README''' file contains ancillary information and whatever required details/etc.
+
* '''version''' contains the version of the app.bin
+
  
  
Line 38: Line 45:
 
* ldconfig is refreshed
 
* 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/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/lib/modules/2.6.22.19-19-4/modules.dep is cat'd onto the end of /lib/modules/2.6.22.19-19-4/modules.dep
 
 
* /apps/test-app/etc/init.d/S10test-app-init is symlinked into /tmp/init.d for execution by rcS/suspend/resume
 
* /apps/test-app/etc/init.d/S10test-app-init is symlinked into /tmp/init.d for execution by rcS/suspend/resume
  
Line 45: Line 51:
  
  
I included 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:
+
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:
 
<tt><br/>/lib/modules/2.6.22.19-19-4/test-module.ko: /lib/modules/2.6.22.19-19-4/test-dep.ko<br/>
 
<tt><br/>/lib/modules/2.6.22.19-19-4/test-module.ko: /lib/modules/2.6.22.19-19-4/test-dep.ko<br/>
 
/lib/modules/2.6.22.19-19-4/test-dep.ko:<br/>
 
/lib/modules/2.6.22.19-19-4/test-dep.ko:<br/>
Line 52: Line 58:
  
 
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.
 
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.
 +
 +
<nowiki>
 +
  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>
 +
</nowiki>
 +
 +
''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:
 +
 +
<nowiki>
 +
<?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&amp;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></app>
 +
    </dependencies>
 +
    <id>encFS</id>
 +
    <download>encFS.app.bin</download>
 +
</application>
 +
</nowiki>
 +
 +
 +
;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.
 +
;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;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
 +
:Required other app.bin(s)
 +
 +
;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 ==
 +
 +
While not mandatory, it is strongly recommended that you also include the following files at the root of your app.bin:
 +
 +
;README
 +
:Description, basic documentation, changelog, etc...  This can be viewed by the end user through the Addons Manager.
 +
;version
 +
:File only containing the numerical version (for example "1.0.5")

Revision as of 11:16, 9 June 2011

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>
        <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></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.
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
Required other app.bin(s)
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

While not mandatory, it is strongly recommended that you also include the following files at the root of your app.bin:

README
Description, basic documentation, changelog, etc... This can be viewed by the end user through the Addons Manager.
version
File only containing the numerical version (for example "1.0.5")