= The Fon .tgz Package Format =

== Preliminary: ==
The Fon-ng firmware comes with a set of package installation routines that can be used to '''upgrade the firmware or install extensions'''. Users can upload such packages with their browser '''on the webinterface'''.
These firmware package installation routines are part of ''fonrsa'' which is responsible for handling signed and unsinged firmware images, hotfixes and plugins.
The core functionality is implemented in the module [http://trac.fonosfera.org/fon-ng/browser/trunk/fon/fonrsa/fonrsa/fonverify.lua luci.fon.pkg.verify].

The Fon-ng Firmware also includes a lightweight plugin management system: ''fon.pkg''.
It is used to install, manage and uninstall extensions of the firmware offering new features or improving already implemented features.
It is part of the Fon-LuCI-Libraries and is registered as module [http://trac.fonosfera.org/fon-ng/browser/trunk/luci/libs/fon/luasrc/fon/pkg.lua luci.fon.pkg].

[[BR]]

== Package format ==
A Fon .tgz-package is basically a '''gzip-compressed GNU tarball''' with a set of predefined contents and the suffix ''.tgz''.
It must contain an '''executable''' ''upgrade'' - preferably a Lua script - containing the installation instructions.

A package can be digitally signed. A digital signature helps indicating that a package was assured by a certain authority (e.g. Fon).
A valid digital signature is '''required for all packages that should be installable on non-developer devices'''.

=== Plugin package format ===
Besides the mandatory ''upgrade''-entry a plugin package should contain a top-level directory ''files'' with all contents that
should be copied to the target device filesystem relative to the filesystem root.

==== Example ====
A plugin containing files that should be installed as ''/etc/config/foo'' and ''/usr/bin/bar'' should look like this:
{{{
upgrade
files/
        etc/
                config/
                        foo
        usr/
                bin/
                        bar
}}}

=== ''upgrade''-Template for plugins ===
This is an example ''upgrade'' file that can be used '''for installing plugins'''.

{{{
#!/usr/bin/lua
-- Fonspec upgrade file
-- (c) john@phrozen.org, steven@midlink.org gplv2

-- Plugin Information
local NAME    = "myplugin"      -- Root node of plugin
local HOME    = false           -- Make plugin root node the new homepage
local TITLE   = "My Plugin"     -- Plugin Title as shown on plugin page
local AUTHOR  = "Ele Font"      -- Plugin Provider as shown on plugin page
local VERSION = "0.3.1.3"       -- Plugin Version as shown on plugin page

-- Dashboard Information
local DASHBOARD = true          -- Show plugin on dashboard
local DB_ICON   = "myicon.png"  -- Plugin icon file relative to /luci-static/resources
local DB_ORDER  = 1000          -- Plugin dashboard order number


-- Logic
local os = require "os"
local fs = require "luci.fs"
local dir = require "posix".getcwd()

-- Create Plugin object
local plugin = require "luci.fon.pkg".Plugin(NAME)
if not plugin:add(TITLE, AUTHOR, VERSION) then
        print "plugin already installed!"
        os.exit(1)
end

-- Add Dashboard entry
if DASHBOARD then
        plugin:dashboard(DB_ICON, DB_ORDER, NAME)
end

-- Enable home redirect
if HOME then
        plugin:redirect()
end

-- Select files to install
plugin:addfiles(dir.."/files/")

-- Save modes
local modes = {}
for _, file in ipairs(plugin.files) do
        modes[file] = fs.stat(plugin.path .. file, "mode")
end

-- Install files
plugin:finalize()

-- Restore modes
for file, mode in pairs(modes) do
        fs.chmod(file, mode)
end
}}}