Difference between revisions of "Create Packages"

Latest revision as of 17:19, 11 March 2020

The modified firmware includes a lightweight package management system called opkg (home page) which is similar to the Debian package management system (dpkg).

Coding your package

Most of the customised firmware is written in a language called Jim/TCL, See the Jim Manual HERE with other bits in C/C++ and the Humax runs a Linux operating system.

A number of TCL classes have been created to make it easier to work with different parts of the Humax webif environment. For example the ts class provides services for working with recordings and the epg class provides access to the programme guide.

The webif also provides a large number of .hook points where packages can integrate themselves into the existing webif infrastructure. For example the browse.hook allows new actions to be added to the browse opt+ menus.

Unfortunately documentation is sparse and there is no definitive list of all the classes and their services or of the available hook points. It is largely a case of reading existing code to find out what is available and above all asking questions on the forums, Use existing packages that have similarities as a basis for your code but don't forget to credit the original authors in your comments and forum/wiki posts.

Package Repositories

The custom firmware is configured to use the package repository at hummypkg.org.uk by default.

Package Format

A package is a UNIX Archive (ar) file which itself contains three files:

debian-binary: A file which just contains the string "2.0", a clue to the packaging system's roots.
data.tar.gz: The files which make up the package.
control.tar.gz: Package meta-information.

Creating a Package

The pkgtools package includes utilities for working with packages and can be used to create packages directly on the Humax itself. Before proceeding, install these utilities:

humax# opkg update
humax# opkg install pkgtools
humax# opkg install gzip

Next create a directory to hold your new package and create a directory within it called CONTROL, which will be used for the package meta-information:

humax# cd /mod/tmp
humax# mkdir my-first-package
humax# mkdir my-first-package/CONTROL

Note: Package names should not contain underscore (_) characters as these are used as delimiters in package file names. It is safest to stick to alpha-numeric characters and use - as a delimiter where appropriate, e.g. webif-iphone

Place the files which make up your package directly into the new package directory. Note that to save memory when running, compiled binaries should be stripped before packaging. In this example, we'll create a package which just installs a script called hello.

humax# cd /mod/tmp/my-first-package
humax# mkdir bin
humax# cat > bin/hello
#!/bin/sh

echo "Hello!"
^D
humax# chmod 755 bin/hello

Note: Files should be included relative to /mod (or /opt on the FoxSat) so in this example the bin/hello file will be installed as /mod/bin/hello

Create file package control file as CONTROL/control. Here's an example:

Package: jim-sqlite3
Priority: optional
Section: misc
Version: 0.71
Architecture: mipsel
Maintainer: af123@hummypkg.org.uk
Depends: jim(>=0.71-1),sqlite3
Description: Jim SQLite3 plugin.
 A plugin for the jim interpreter (a lightweight TCL interpreter) which
 provides access to SQLite3 databases (such as those used on the Humax).

The Debian project maintains documentation on the format of the control file which also applies to opkg packages, although some fields are not required.

Package: The package name.
Priority: Always set to optional for Humax packages.
Section: One of misc, net, devel, etc. full list
Version: The package version number of the format upstream_version[-opkg_version] more information
Architecture: Always mipsel for the HD/HDR Fox T2, and mips for the FoxSat.
Maintainer: An email address or hummy.tv/wiki username.
Depends: A list of dependencies for this package, optionally with version constraints see Debian documentation
Description: A description of the package. Continuation lines must be prefixed by white space.
Tags: An optional field that contains a URL pointing to a source of further information

The CONTROL directory can also contain other package maintenance scripts such as preinst, postinst, prerm and postrm. See the Debian documentation for more details and examples. The scripts are called with various arguments during package maintenance operations. Many simple packages do not require any maintenance scripts.

Continuing with our example package, create the bare minimum control file:

humax# cat > CONTROL/control
Package: hello
Version: 1.0
Architecture: mipsel
Maintainer: af123
Description: hello
Tags: http://wiki.hummy.tv/wiki/Custom_Firmware_Overview/

The package can now be built using the opkg-pack command:

humax# cd /mod/tmp
humax# opkg-pack my-first-package
bin/
bin/hello
Packaged contents of /mod/tmp/my-first-package/ into /mod/tmp/my-first-package//../hello_1.0_mipsel.opk 532

The package can then be installed directly from the resulting file for testing.

humax# opkg install hello_1.0_mipsel.opk
Installing hello (1.0) to root...
Configuring hello.
humax# hello
Hello!
humax# opkg remove hello
Removing package hello from root...

If you have any packages which you'd like published in the hummypkg.org.uk repository, then email them to packages@hummypkg.org.uk.

Using Git to store and maintain package

It is recommended that you use the Git library system to provide version control and to allow for collaborative development with others.

See Maintain packages with Git for a guide to using Git with Humax packages. Most of that page also applies to maintaining your own packages but there are also a few differences which are covered here.

As package owner you will be responsible for establishing the principal repository for the package and will work directly with that repository rather than a forked copy and you will also be responsible for merging the branches created by you or others into the master branch once you are satisfied they are working correctly and then removing empty branches.

Create a new repository for your package

On the Dashboard of the Hummy Git website click to create a New Repository

Provide the Package name, Visibility (Public is best) and Description but do not select the 'Initialize Repository' option then click on 'Create Repository' buttton On your local machine switch to the folder for the package and upload it the repository.

cd /mod/tmp/my-first-package
git init
git add .
git commit -a -m "first commit"
git remote add origin https://git.hpkg.tv/USERNAME/my-first-package.git
git push -u origin master

Merge changes into master branch

This can be done locally on your machine for changes you have made or on the web repository for Pull Requestsgo created by you or others

Local Merge

After completing changes switch to master branch, merge the changes, delete the branch and synchronize with the remote repository

git checkout master
git merge branch-name
git branch -d branch-name
git push

If the branch had bee pushed to the remote it can be deleted

git push origin --delete  branch-name
git remote prune origin

Remote Merge

On the Pull Request tab of the Hummy Git website Review the changes are OK and Approve the changes, or Request Changes if required

Once satisfied click on the "Merge Pull Request" button after which you can click on the "Delete Branch" button Synchronize your local repository

git checkout master
git pull

Unpacking an existing package

The pkgtools package also contains a utility which can be used to unpack an existing package into a directory structure for editing or just for investigation, NOTE :- you need to install the gzip Custom Firmware package in order to use opkg-unpack

humax# cd /mod/tmp
humax# opkg download webif
Downloading http://hummypkg.org.uk/hdrfoxt2/base/webif_0.6.4_mipsel.opk.
Downloaded webif as ./webif_0.6.4_mipsel.opk.
humax# opkg-unpack webif_0.6.4_mipsel.opk
Unpacked to webif_0.6.4_mipsel

If you have a Debian-based Linux machine, opkg packages can be examined and manipulated using the dkpg-deb command.

wget http://hummypkg.org.uk/hdrfoxt2/base/busybox_1.19.3-3_mipsel.opk
dpkg-deb -x busybox_1.19.3-3_mipsel.opk <tmpdir>

Packing and Unpacking Bundled Packages

An OPK file contains the executable program /s and all the set-up scripts required for a single Custom Firmware package, However this single package may require other packages to be present in order to work. An OPB file contains the main package and all the peripheral packages require for it to run in a single file, the OPK’s are tarred together to form this file and can be viewed as follows :-

humax# /bin/untar multimode_0.0.1_mipsel.opb
Extracting from multimode_0.0.1_mipsel.opb
 Extracting file multimode_0.0.1_mipsel.opk
 Extracting file webif_0.8.9_mipsel.opk
 Extracting file mongoose_3.0-6_mipsel.opk
 Extracting file jim_0.71-1_mipsel.opk
 Extracting file jim-sqlite3_0.71-1_mipsel.opk
 Extracting file sqlite3_3.7.6_mipsel.opk
 Extracting file jim-cgi_0.4-1_mipsel.opk
 Extracting file jim-oo_0.71_mipsel.opk
 Extracting file jim-pack_0.71_mipsel.opk
 Extracting file service-control_1.0_mipsel.opk
 Extracting file busybox_1.19.3-2_mipsel.opk
 Extracting file lsof_4.82_mipsel.opk
 Extracting file epg_1.0.8_mipsel.opk
 Extracting file hmt_1.1.3_mipsel.opk
 Extracting file ssmtp_2.64_mipsel.opk
 Extracting file anacron_2.3-1_mipsel.opk
 Extracting file cron-daemon_1.18.3-1_mipsel.opk
 Extracting file rs_0.4.0_mipsel.opk
End of multimode_0.0.1_mipsel.opb
humax#

@@ Line 1: / Line 1: @@
+__NOTOC__
 The modified firmware includes a lightweight package management system called opkg ([http://code.google.com/p/opkg/ home page]) which is similar to the Debian package management system (dpkg).
+==Coding your package==
+Most of the customised firmware is written in a language called Jim/TCL, See the Jim Manual [http://jim.tcl.tk/fossil/doc/trunk/Tcl_shipped.html '''HERE'''] with other bits in C/C++ and the Humax runs a Linux operating system.
+A number of TCL classes have been created to make it easier to work with different parts of the Humax webif environment. For example the '''ts''' class provides services for working with recordings and  the '''epg''' class provides access to the programme guide.
+The webif also provides a large number of '''.hook''' points where packages can integrate themselves into the existing webif infrastructure. For example the '''browse.hook''' allows new actions to be added to the browse opt+ menus.
+Unfortunately documentation is sparse and there is no definitive list of all the classes and their services or of the available hook points.
+It is largely a case of reading existing code to find out what is available and above all asking questions on the forums, Use  existing packages that have similarities as a basis for your code but don't forget to credit the original authors in your comments and forum/wiki posts.
 == Package Repositories ==
 The custom firmware is configured to use the package repository at [http://hummypkg.org.uk/packages.html hummypkg.org.uk] by default.
 == Package Format ==
@@ Line 19: / Line 33: @@
   humax# opkg update
   humax# opkg install pkgtools
+ humax# opkg install gzip
 Next create a directory to hold your new package and create a directory within it called CONTROL, which will be used for the package meta-information:
@@ Line 26: / Line 41: @@
   humax# mkdir my-first-package/CONTROL
-{{Note|Package names should not contain underscore (_) characters as these are used as delimiters in package file names. It is safest to stick to alpha-numeric characters and use - as a delimiter where appropriate, e.g. <tt>webif-iphone</tt>}}
+{{Note|Package names should '''not''' contain underscore (_) characters as these are used as delimiters in package file names. It is safest to stick to alpha-numeric characters and use - as a delimiter where appropriate, e.g. <tt>webif-iphone</tt>}}
-Place the files which make up your package directly into the new package directory. In this example, we'll create a package which just installs a script called <tt>hello</tt>.
+Place the files which make up your package directly into the new package directory. Note that to save memory when running, compiled binaries should be stripped before packaging. In this example, we'll create a package which just installs a script called <tt>hello</tt>.
   humax# cd /mod/tmp/my-first-package
@@ Line 39: / Line 54: @@
   humax# chmod 755 bin/hello
-{{Note|Files should be included relative to <tt>/mod</tt> so in this example the <tt>bin/hello</tt> file will be installed as <tt>/mod/bin/hello</tt>}}
+{{Note|Files should be included relative to <tt>/mod</tt> (or <tt>/opt</tt> on the FoxSat) so in this example the <tt>bin/hello</tt> file will be installed as <tt>/mod/bin/hello</tt>}}
 Create file package control file as <tt>CONTROL/control</tt>. Here's an example:
@@ Line 62: / Line 77: @@
 ; Section : One of <tt>misc</tt>, <tt>net</tt>, <tt>devel</tt>, etc. [http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections full list]
 ; Version : The package version number of the format ''upstream_version[-opkg_version]'' [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version more information]
-; Architecture : Always mipsel for the HD/HDR.
+; Architecture : Always <tt>mipsel</tt> for the HD/HDR Fox T2, and <tt>mips</tt> for the FoxSat.
 ; Maintainer : An email address or hummy.tv/wiki username.
 ; Depends : A list of dependencies for this package, optionally with version constraints [http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps see Debian documentation]
-; Description : A description of the package. Continuation lines must be prefixed by whitespace.
+; Description : A description of the package. Continuation lines must be prefixed by white space.
+; Tags : An optional field that contains a URL pointing to a source of further information
 The CONTROL directory can also contain other package maintenance scripts such as <tt>preinst</tt>, <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt>. See [http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html the Debian documentation for more details and examples]. The scripts are called with various arguments during package maintenance operations. Many simple packages do not require any maintenance scripts.
@@ Line 73: / Line 89: @@
 <pre>
 humax# cat > CONTROL/control
-Package: my-first-package
+Package: hello
 Version: 1.0
 Architecture: mipsel
 Maintainer: af123
 Description: hello
-^D
+Tags: http://wiki.hummy.tv/wiki/Custom_Firmware_Overview/
 </pre>
@@ Line 86: / Line 102: @@
 humax# cd /mod/tmp
 humax# opkg-pack my-first-package
-TODO
+bin/
+bin/hello
+Packaged contents of /mod/tmp/my-first-package/ into /mod/tmp/my-first-package//../hello_1.0_mipsel.opk 532
 </pre>
@@ Line 92: / Line 110: @@
 <pre>
-humax# opkg install my-first-package_1.0_mipsel.opk
+humax# opkg install hello_1.0_mipsel.opk
+Installing hello (1.0) to root...
+Configuring hello.
 humax# hello
 Hello!
-humax# opkg remove my-first-package
+humax# opkg remove hello
+Removing package hello from root...
+</pre>
+If you have any packages which you'd like published in the [http://hummypkg.org.uk hummypkg.org.uk] repository, then email them to [mailto:packages@hummypkg.org.uk packages@hummypkg.org.uk].
+== Using Git to store and maintain package ==
+It is recommended that you use the Git library system to provide version control and to allow for collaborative development with others.
+See [[Maintain packages with Git]] for a guide to using Git with Humax packages.
+Most of that page also applies to maintaining your own packages but there are also a few differences which are covered here.
+As package owner you will be responsible for establishing the principal repository for the package and will work directly with that repository rather than a forked copy and you will also be responsible for merging the branches created by you or others into the master branch once you are satisfied they are working correctly and then removing empty branches.
+=== Create a new repository for your package ===
+On the Dashboard of the [https://git.hpkg.tv/ Hummy Git website] click to create a New Repository
+[[File:New Repository.png|frame|centre]]
+Provide the Package name, Visibility (Public is best) and Description but ''do not'' select the 'Initialize Repository' option then click on 'Create Repository' buttton
+On your local machine switch to the folder for the package and upload it the repository.
+<pre>
+cd /mod/tmp/my-first-package
+git init
+git add .
+git commit -a -m "first commit"
+git remote add origin https://git.hpkg.tv/USERNAME/my-first-package.git
+git push -u origin master
 </pre>
-If you have any packages which you'd like published in the [http://hummypkg.org.uk hummypkg.org.uk] repository, then email them to [mailto:packages@hummypkg.org.uk].
+=== Merge changes into '''master''' branch ===
+This can be done locally on your machine for changes you have made or on the web repository for Pull Requestsgo created by you or others
+==== Local Merge ====
+After completing changes switch to master branch, merge the changes, delete the branch and synchronize with the remote repository
+<pre>
+git checkout master
+git merge branch-name
+git branch -d branch-name
+git push
+</pre>
+If the branch had bee pushed to the remote it can be deleted
+<pre>
+git push origin --delete  branch-name
+git remote prune origin
+</pre>
+==== Remote Merge ====
+On the Pull Request tab of the [https://git.hpkg.tv/ Hummy Git website] Review the changes are OK and Approve the changes, or Request Changes if required
+[[File:Review Pull request.png|frame|center]]
+Once satisfied click on the "Merge Pull Request" button after which you can click on the "Delete Branch" button
+Synchronize your local repository
+<pre>
+git checkout master
+git pull
+</pre>
 == Unpacking an existing package ==
-The <tt>pkgtools</tt> package also contains a utility which can be used to unpack an existing package into a directory structure for editing or just for investigation.
+The <tt>pkgtools</tt> package also contains a utility which can be used to unpack an existing package into a directory structure for editing or just for investigation, NOTE :- you need to install the gzip Custom Firmware package in order to use opkg-unpack
 <pre>
 humax# cd /mod/tmp
 humax# opkg download webif
-TODO
+Downloading http://hummypkg.org.uk/hdrfoxt2/base/webif_0.6.4_mipsel.opk.
+Downloaded webif as ./webif_0.6.4_mipsel.opk.
 humax# opkg-unpack webif_0.6.4_mipsel.opk
+Unpacked to webif_0.6.4_mipsel
+</pre>
+If you have a Debian-based Linux machine, opkg packages can be examined and manipulated using the dkpg-deb command.
+ wget http://hummypkg.org.uk/hdrfoxt2/base/busybox_1.19.3-3_mipsel.opk
+ dpkg-deb -x busybox_1.19.3-3_mipsel.opk <tmpdir>
+== Packing and Unpacking Bundled Packages ==
+An OPK file contains the executable program /s and all the set-up scripts required for a single Custom Firmware package, However this single package may require other packages to be present in order to work. An OPB file contains the main package and all the peripheral packages require for it to run in a single file, the OPK’s are tarred together to form this file and can be viewed as follows :-
+<pre>
+humax# /bin/untar multimode_0.0.1_mipsel.opb
+Extracting from multimode_0.0.1_mipsel.opb
+ Extracting file multimode_0.0.1_mipsel.opk
+ Extracting file webif_0.8.9_mipsel.opk
+ Extracting file mongoose_3.0-6_mipsel.opk
+ Extracting file jim_0.71-1_mipsel.opk
+ Extracting file jim-sqlite3_0.71-1_mipsel.opk
+ Extracting file sqlite3_3.7.6_mipsel.opk
+ Extracting file jim-cgi_0.4-1_mipsel.opk
+ Extracting file jim-oo_0.71_mipsel.opk
+ Extracting file jim-pack_0.71_mipsel.opk
+ Extracting file service-control_1.0_mipsel.opk
+ Extracting file busybox_1.19.3-2_mipsel.opk
+ Extracting file lsof_4.82_mipsel.opk
+ Extracting file epg_1.0.8_mipsel.opk
+ Extracting file hmt_1.1.3_mipsel.opk
+ Extracting file ssmtp_2.64_mipsel.opk
+ Extracting file anacron_2.3-1_mipsel.opk
+ Extracting file cron-daemon_1.18.3-1_mipsel.opk
+ Extracting file rs_0.4.0_mipsel.opk
+End of multimode_0.0.1_mipsel.opb
+humax#
 </pre>

Difference between revisions of "Create Packages"

Latest revision as of 17:19, 11 March 2020

Coding your package

Package Repositories

Package Format

Creating a Package

Using Git to store and maintain package

Create a new repository for your package

Merge changes into master branch

Local Merge

Remote Merge

Unpacking an existing package

Packing and Unpacking Bundled Packages

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools