DBP file format: Difference between revisions - Pyra Wiki

 
(25 intermediate revisions by 2 users not shown)
Line 9: Line 9:


The zip part contain the meta-data related to the DBP.
The zip part contain the meta-data related to the DBP.
=== meta-data structure ===
In the metadata zip file, you can have up to 3 directories :
# <b>meta</b>: (<i>mandatory</i>) contain the "default.desktop" (<i>mandatory</i>) and all other .desktop files
# <b>icons</b>: the directory where the icons will be looked after
# <b>teasers</b>: the directory where the screenshots will be looked after
Beside, it is recommended to zip this without compression (using the "-Z store" flag).
The reason for this is simple : the deflate algorythm wont gain much on png compressed files, and the gain on desktop files is a question of bytes. While the performance gain while reading the files is substantial for dbpd.


=== Sample session to build a dbp ===
=== Sample session to build a dbp ===


Say you have a your application in a "rootfs" directory and a meta" directory containing the metadata.
Say you have a your application in a "rootfs" directory and a meta" directory containing the metadata.
<pre>
$ ls
icons  meta  rootfs
$ mksquashfs rootfs target.squash -all-root -force-gid 0
Creating 4.0 filesystem on target.squash, block size 131072.
....
$ zip -r target.zip meta icons
  adding: meta/ (stored 0%)
...
$ cat target.squash target.zip > target.dbp
</pre>


== meta-data structure ==
  $ <b>ls</b>
  icons  meta rootfs  teasers
  $ <b>mksquashfs rootfs target.squash -all-root -force-gid 0</b>
  Creating 4.0 filesystem on target.squash, block size 131072.
  ....
  $ <b>zip -Z store -r target.zip meta icons teasers</b>
    adding: meta/ (stored 0%)
  ...
  $ <b>cat target.squash target.zip > target.dbp</b>
  $ <b>zip -A target.dbp</b>


== the desktop file(s) ==
== the desktop file(s) ==
This file format is normed by the free-desktop community. The specs can be found [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.1.html here].
This file format is normed by the free-desktop community. The complete specs can be found [https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.1.html here], but this guide duplicates all of the bits you're likely to use.
 
Remember, the default.desktop file should have the Package Entry **after** the Desktop Entry


=== Desktop Entry ===
=== Desktop Entry ===
In a dbp file, only a handful of [Desktop Entry] sections should be written. It corresponds to a system menu entry targetting an application from within the dbp package. Each [Desktop Entry] section need to be a dedicated file.
Here is the standard fields the dbp system reuse.
{| class="wikitable" style="text-align: left;"
{| class="wikitable" style="text-align: left;"
|-
|-
Line 38: Line 49:
! style="width:40%;" |Description
! style="width:40%;" |Description
! style="width:30%;" |Example
! style="width:30%;" |Example
|-
|Type
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L203 R]
|N
|Type of desktop file (Possible values: Application, Link, Directory)
|Type=Application
|-
|-
|Name
|Name
|R
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L219 R]
|R
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L163 R]
|Name of the app
|Name of the app
|Name=dosbox
|Name=dosbox
|-
|-
|Comment
|Comment
|N
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L221 O]
|O
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L159 O]
|Description of the app
|Description of the app
|Comment=A DOS emulator
|Comment=A DOS emulator
|-
|Version
|N
|O
|Version of the app
|Version=0.74+svn20200103
|-
|Type
|N
|O
|Type of app
|Type=Application
|-
|-
|Categories
|Categories
|N
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L234 R]
|O
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L172 O]
|Categories
|Categories, see the [https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry main] ones, and the [https://specifications.freedesktop.org/menu-spec/latest/apas02.html additional] ones.
|Categories=Game;Emulator
|Categories=Game;Emulator
|-
|-
|Exec
|Exec
|R
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L207 R]
|N
|N
|The binary in the squashfs part to start
|The binary in the squashfs part to start
Line 76: Line 81:
|-
|-
|Icon
|Icon
|O
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L223 O]
|O
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L160 O]
|The icon in the "icons" directory (expect .png)
|The icon in the "icons" directory (expect .png)
|Icon=dosbox.png
|Icon=dosbox.png
|-
|X-DBP-Screenshot
|N
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/f32b535b8db31f932fbcb09c6d3c2136a932b845/classes/UploadPage.php#L205 O]
|A single screenshot for this app (as found in the "teasers" directory)
|X-DBP-Screenshot=app1.png
|-
|X-DBP-Screenshots
|N
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/f32b535b8db31f932fbcb09c6d3c2136a932b845/classes/UploadPage.php#L208 O]
|A set of screenshots for this app (as found in the "teasers" directory)
|X-DBP-Screenshots[0]=appx_0.png
X-DBP-Screenshots[1]=appx_1.png
|-
|Version
|N
|N
|Version of the app
|Version=0.74+svn20200103
|-
|-
|Terminal
|Terminal
|N
|N
|N
|N
|Is this a terminal apps ?
|Spawn a terminal for this app to run in, if set.
|Terminal=false
|Terminal=false
|-
|-
Line 90: Line 114:


=== Package Entry ===
=== Package Entry ===
This section doesnt exist in the free-desktop specification. One and only one of this section should be found per dbp package. Here are the fields standardized with our extention :
This section doesnt exist in the free-desktop specification (So this is dbp exclusive stuff here). One and only one of this section should be found per dbp package. Here are the fields :
{| class="wikitable" style="text-align: left;"
{| class="wikitable" style="text-align: left;"
|-
|-
Line 97: Line 121:
! style="width:5%;" |Repo
! style="width:5%;" |Repo
! style="width:40%;" |Description
! style="width:40%;" |Description
! style="width:30%;" |Example
! style="width:40%;" |Example
|-
|-
|Id
|Id
|R
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L277 R]
|R
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L97 R]
|Uniq identifier for the dbp file.
|Unique identifier for the dbp file.
|Id=dosbox
|Id=dosbox
|-
|-
|Name
|Name
|R
|N
|R
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L102 R]
|Name of the package
|Name of the package
|Name=DOSbox
|Name=DOSbox
|-
|Arch
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-run/common/run.vala#L43 O]
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L105 R]
|Binary architecture of that package
|Arch=armhf
|-
|Appdata
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L292 O]
|N
|Name of the appdata to use (default: name of the package)
|Appdata=dosbox
|-
|-
|Icon
|Icon
|N
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbp-validate-extracted/validate.c#L283 O]
|O
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L119 O]
|Icon of the package (found in the "icons" directory)
|Icon of the package (found in the "icons" directory)
|Icon=dosbox.png
|Icon=dosbox.png
Line 119: Line 155:
|Version
|Version
|N
|N
|O
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L352 R]
|Version of the package
|Version of the package
|Version=0.74+svn20200103
|Version=0.74+svn20200103
|-
|Arch
|O
|O
|Binary architecture of that package
|Arch=armhf
|-
|-
|Exec
|Exec
|R
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbpd/package.c#L169 O]
|N
|N
|TODO
|List of executables to export With environment override
|Exec=bin/dosbox;dosbox.launch
|Exec=bin/dosbox;dosbox.launch
|-
|NoEnvExec
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/dbpd/package.c#L170 O]
|N
|List of executables to export Without environment override
|
|-
|Dependency[deb]
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/libdbpmgr/dependencies.c#L555 O]
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L115 O]
|Debian packages requiered.
|Dependency[deb]=libsdl2-image-2
|-
|Dependency[dbp]
|[https://dev.pyra-handheld.com/packages/dbp/-/blob/e0e58fe10a07ce1deb598dc5a6f794aaad9f10f1/libdbpmgr/dependencies.c#L556 O]
|[https://dev.pyra-handheld.com/sebt3/pyraRepo/-/blob/566a9ffbbf914247654c63b7dc688018d96a2fcb/classes/UploadPage.php#L113 O]
|dbp package requiered to run this one.
|Dependency[dbp]=dosbox
|-
|-
|}
|}

Latest revision as of 13:07, 4 July 2021

Please note: we're not going to describe something as painful as the pxml file here :P

file structure

a .dbp files is composed of 2 concatenated files :

  1. a squashfs file
  2. an *uncompressed* zip

The squashfs part contain your application(s) and everything it might need to run.

The zip part contain the meta-data related to the DBP.

meta-data structure

In the metadata zip file, you can have up to 3 directories :

  1. meta: (mandatory) contain the "default.desktop" (mandatory) and all other .desktop files
  2. icons: the directory where the icons will be looked after
  3. teasers: the directory where the screenshots will be looked after

Beside, it is recommended to zip this without compression (using the "-Z store" flag). The reason for this is simple : the deflate algorythm wont gain much on png compressed files, and the gain on desktop files is a question of bytes. While the performance gain while reading the files is substantial for dbpd.

Sample session to build a dbp

Say you have a your application in a "rootfs" directory and a meta" directory containing the metadata.

 $ ls
 icons  meta  rootfs   teasers
 $ mksquashfs rootfs target.squash -all-root -force-gid 0
 Creating 4.0 filesystem on target.squash, block size 131072.
 ....
 $ zip -Z store -r target.zip meta icons teasers
   adding: meta/ (stored 0%)
 ...
 $ cat target.squash target.zip > target.dbp
 $ zip -A target.dbp

the desktop file(s)

This file format is normed by the free-desktop community. The complete specs can be found here, but this guide duplicates all of the bits you're likely to use.

Remember, the default.desktop file should have the Package Entry **after** the Desktop Entry

Desktop Entry

In a dbp file, only a handful of [Desktop Entry] sections should be written. It corresponds to a system menu entry targetting an application from within the dbp package. Each [Desktop Entry] section need to be a dedicated file. Here is the standard fields the dbp system reuse.

LABEL dbpd Repo Description Example
Type R N Type of desktop file (Possible values: Application, Link, Directory) Type=Application
Name R R Name of the app Name=dosbox
Comment O O Description of the app Comment=A DOS emulator
Categories R O Categories, see the main ones, and the additional ones. Categories=Game;Emulator
Exec R N The binary in the squashfs part to start Exec=dosbox
Icon O O The icon in the "icons" directory (expect .png) Icon=dosbox.png
X-DBP-Screenshot N O A single screenshot for this app (as found in the "teasers" directory) X-DBP-Screenshot=app1.png
X-DBP-Screenshots N O A set of screenshots for this app (as found in the "teasers" directory) X-DBP-Screenshots[0]=appx_0.png

X-DBP-Screenshots[1]=appx_1.png

Version N N Version of the app Version=0.74+svn20200103
Terminal N N Spawn a terminal for this app to run in, if set. Terminal=false

Package Entry

This section doesnt exist in the free-desktop specification (So this is dbp exclusive stuff here). One and only one of this section should be found per dbp package. Here are the fields :

LABEL dbpd Repo Description Example
Id R R Unique identifier for the dbp file. Id=dosbox
Name N R Name of the package Name=DOSbox
Arch O R Binary architecture of that package Arch=armhf
Appdata O N Name of the appdata to use (default: name of the package) Appdata=dosbox
Icon O O Icon of the package (found in the "icons" directory) Icon=dosbox.png
Version N R Version of the package Version=0.74+svn20200103
Exec O N List of executables to export With environment override Exec=bin/dosbox;dosbox.launch
NoEnvExec O N List of executables to export Without environment override
Dependency[deb] O O Debian packages requiered. Dependency[deb]=libsdl2-image-2
Dependency[dbp] O O dbp package requiered to run this one. Dependency[dbp]=dosbox

legend

letter meaning
R Required
O Optionnal
N Not used
Back
Top