So, I've gotten some requests on explaining how to actually package stuff into dbp-files. I've hold off from this since all the relevant features aren't implemented or decided yet. However, see this as a preliminary guide that will change in the future.
If you read this post after the Pyra has been released, or after a package manager/repo has been released, it is most likely outdated. There will probably be better ways to create packages, eg. something like makepnd.
First off: All packages need a package ID, this is something unique like "someprogram-maintainer" that is unlikely to ever conflict with other packages. Packages of different versions should have the same ID if they are compatible (ie. upgrading from version x to version y won't break program z.) See below about default.desktop for details about the package id.
The first step is to gather all the files that your program will need inside a folder. If you need to compile the program with a installation prefix, use
/mnt/dbp/images/package-id
This directory is not writable. However, in the event that multi-user support is implemented, the writable directory will not be predictable, it'll be known at run-time as cwd
unless the running executable is exported without environment override, see below.
This directory should contain all read-only data needed by the program in the structure it expects.
Generate a squashfs image from this directory. using:
mksquashfs directory_with_files image.sqfs
The next step is assembling the meta-data. This is where things will change over time. Since to repo (or package manager exists, and no real discussion has been held about it, this is very much in draft state.
Create another directory. In this directory, you'll need at least two more directories, meta and icons.
Inside the meta/ directory, you should put all the .desktop files for your application. One file per program launcher. For .desktop files in general, see the example below.
[Desktop Entry]
Version=1.0
Type=Application
Categories=Game;ArcadeGame
Name=OpenTyrian
Comment=OpenTyrian
Exec=opentyrian
Icon=tyrian-128.png
Path=
Terminal=false
StartupNotify=false
Exec name is the file name of the executable to launch without any leading directories. Icon name is a .png file inside the icons/ directory. All icons inside icons/ are exported, so only put the ones used there, and keep their file sizes reasonable. Icon names will automatically be mangled at run time to avoid collisions. The rest of the file is a pretty
standard FreeDesktop file.
Additionally,
all valid .dbp files have a meta/default.desktop. This contains package meta data under a special section, "[Package Entry]". Note that this file can also be a file launcher, and a "[Desktop Entry]" will describe its default action when the package file is executed directly. An example "[Package Entry]" is shown below.
[Package Entry]
Id=SomeProgram_slaeshjag
Name=Some Package!
Name[sv_SE]=Ett paket!
Arch=armhf
Exec=bin/someprogram;someotherprogram
NoEnvExec=some-term-program
SysDependency=vim>=7.4
PkgDependency=some-dbp;other-dbp
Version=1.3.2
Appdata=notthepkgid
Icon=package_icon.png
Id may only contain the characters A-Z a-z 0-9 -_. (regex: /[-_\.a-zA-Z0-9]+/ ) No spaces!
Name is a human readable string with the name of the package. Ignored by the dbp-system, but will probably be used by a future package manager and/repo.
Arch is currently not used, but should be armhf for anything compiled for the Pyra. If the package only contains platform independent scripts, you may instead use:
Arch=any
Exec is a ;-separated list of executables inside the squashfs to export into path. So if I export bin/some_exec, some_exec will be in path.
The Exec= key is used to export executables to run in an environment simlar to PNDs. CWD changes, environment variables are overridden to direct writes to appdata etc. For games, this is how you want to export your executable. Since the exported executables end up in path, they should have reasonable names, like "someprogram", not "run.sh".
Binaries exported with NoEnvExec= will not have its environment altered. This is preferred for any command line tools.
SysDependiencies is a ;-separated list of dpkg packages that must be installed. Currently only one version requirement is allowed (>= or == or <=,) however this will change in the future.
PkgDependency is a ;-separated list of dbp's that needs to be installed (listed by package id.) Currently, no version numbers are supported, but these will be handled in the same way as with dpkg packages.
Version number is currently ignored, however this will be used in the future for PkgDependency checking. Version numbers must adhere to
SemVer.
Appdata= specified a different name for the appdata directory. It follows the same naming rules as the package ID.
Icon works the same way as for the .desktop launchers, however inside the [Package Entry] section, it defines the icon for the package file itself.
Inside [Package Entry], only the entries "Id" and "Version" are mandatory. If Arch= is omitted, Arch=any is assumed.
Finally, zip these up. The resulting zip file should have "meta/" and "icons/" directly in the root. Append the zip file to the squashfs file and rename the resulting file
<package name>.dbp
This file should be recognized by the dbp system. In the future, a utility will be provided that validates a dbp file and lists information about it.
File suffix is preliminary and may change after a couple dozen forum polls.
This probably ended up slightly messy, someone with better writing skills than me will have to re-write it at some point.