Differences

This shows you the differences between two versions of the page.

--- create_pacman_package [2021/12/29 23:43] – renamed package-info.txt to .PKGINFO to simplify instructions across versions atari
+++ create_pacman_package [2023/02/24 16:34] (current) – [What is pacman?] nit: Spelling maximumentropy
@@ Line 5: / Line 5: @@
 In Batocera **v27** and higher, you can utilize [[https://www.archlinux.org/pacman/|pacman]] to install and manage packages. It is the underlying tool behind the [[updates_and_downloads|content downloader]]. It is a straightforward package manager that's easy to work with.
-You don't need development skills to create a package, just a bit of patience. If you've copied files too and from directories before, you already have the skill-set required for this.
+You don't need development skills to create a package, just a bit of patience. If you've copied files to and from directories before, you already have the skill-set required for this.
 ===== Create your own package =====
@@ Line 31: / Line 31: @@
 <code>
-/userdata/system/package/nes-alterego/
+/userdata/system/package/nes-alter-ego/
                          └─ userdata/
                             └─ roms/
@@ Line 45: / Line 45: @@
 <code>
-/userdata/system/package/nes-alterego/
+/userdata/system/package/nes-alter-ego/
                          └─ userdata/
                             └─ roms/
@@ Line 58: / Line 58: @@
 ==== Package info file ====
-Next we need to create the file that contains meta-information about the package itself. Create a new text file in the package's folder. For our example, this would be ''/userdata/system/packaging/nes-alterego/''.
+<WRAP center round tip>
+In order to see hidden files in Batocera, ensure that "Show Hidden" is checked in the **View** menu at the top left.
-{{:screenshot-2021.12.13-11h07.53.png|}}
+{{:screenshot-2021.12.30-10h48.52.png|}}
+</WRAP>
-This file must be named ''.PKGINFO''. If unable to create a file with that name for whatever reason, you can download the script below and place it in the appropriate place (you may need to turn on "Show hidden files/folders" in your file manager).
+Next we need to create a hidden file that contains the meta-information about the package itself. Create a new text file named ''.PKGINFO'' in the package's folder. For our example, this would be ''/userdata/system/packaging/nes-alter-ego/.PKGINFO''.
+{{:screenshot-2021.12.13-11h07.53.png|}}
 {{:screenshot-2021.12.13-11h10.12.png|}}
-Open the file for editing and paste the following in (or just download the file and place it there):
+This file must be named ''.PKGINFO''. If unable to create a file with that name for whatever reason, you can download the script below and place it in ''system/packaging/nes-alter-ego/'' on the network share (you may need to turn on "Show hidden files/folders" in your file manager).
-<file - package-info.txt>
+<file - .PKGINFO>
 pkgname = nes-alter-ego
 pkgver = 1.0.0-1
-pkgdesc = NES freeware puzzle game by Shiru, Kulor, Denis Grachev
+pkgdesc = Alter Ego - A freeware puzzle game by Shiru, Kulor, Denis Grachev.
 arch = any
 group = sys-nes
 packager = your_name
 url = https://wiki.batocera.org/start
 </file>
-Replace the lines as appropriate! Here are the **required** lines:
+Insert the lines above into the ''.PKGINFO'' text file (you can open it by just double-clicking). Replace the lines as appropriate! Here are the **required** lines:
   * **pkgname:** The internal name of the package. This needs to remain the same for updates that become available for the package.
   * **pkgver:** The version of the package. If this number is higher than the one currently installed, Batocera will offer the user to update the package in the store. The only acceptable format for this is ''X.Y.Z-R'', following pacman's conventions.
-  * **pkgdesc:** The description.
+  * **pkgdesc:** The package's displayed name, following by a short description. This will be what appears in the content downloader. You only have one line of text, around 80 characters, so keep it brief!
-  * **arch:** What platforms should this package be available to? Most packages are fine to leave this as "any", but some may only work on x86_64 for example.
+  * **arch:** What platforms should this package be available to? Most packages are fine to leave this as "any", but some may only work on x86_64 for example. Available archs are: ''any x86_64 x86 armv7l aarch64''. Multiple archs cannot be specified, they must be made as separate packages.
   * **group:** What category should the store show this under? If you are creating a package for a specific [[:systems|system]], it must be prefixed with ''sys-'', eg. ''sys-megadrive'' for [[systems:megadrive|Megadrive/Genesis]]. For the other groups, [[#available_groups|read below]].
 The remaining lines are optional, but can provide extra information to users choosing to install them:
   * **packager:** The author of the package.
-  * **url:** URL for the user to go to if they desire more information.
+  * **url:** URL for the user to go to if they desire more information. For freeware, generally links to the page the download can be made manually.
 <WRAP center round important>
@@ Line 122: / Line 126: @@
 gamelist = nes
 <game>
-  <path>./Alter_Ego.nes</path>
+		<path>./Alter_Ego.nes</path>
-  <name>Alter Ego</name>
+		<name>Alter Ego</name>
-  <desc>Freeware puzzle game for NES, a port of the original (by Denis Grachev for the ZX Spectrum). Swap positions with your 'alter ego' to move about the level and obtain all the bouncing pixels.</desc>
+		<desc>Freeware puzzle game for NES, a port of the original (by Denis Grachev for the ZX Spectrum). Swap positions with your 'alter ego' to move about the level and obtain all the bouncing pixels.</desc>
-  <rating>0.6</rating>
+		<rating>0.6</rating>
-  <releasedate>20110827T000000</releasedate>
+		<releasedate>20110827T000000</releasedate>
-  <developer>Shiru</developer>
+		<developer>Shiru</developer>
-  <publisher></publisher>
+		<publisher></publisher>
-  <genre>Puzzle</genre>
+		<genre>Puzzle</genre>
-  <players>1</players>
+		<players>1</players>
-  <image>./images/Alter_Ego.png</image>
+		<image>./images/Alter_Ego.png</image>
-  <manual>./manuals/Alter_Ego-manual.pdf</manual>
+		<manual>./manuals/Alter_Ego-manual.pdf</manual>
 </game>
 </file>
+<WRAP center round important>
+The ''gamelist = <system shortname>'' here is important. Don't forget to edit it appropriately for your system in question!
+</WRAP>
 === exec ===
@@ Line 142: / Line 150: @@
 <WRAP center round info>
 Only interpreters that takes a ''-c'' argument for commands are available. For example, ''exec = /bin/bash'' or ''exec = /usr/bin/python'', which are both used heavily by Batocera for its internal functions.
+</WRAP>
+<WRAP center round important>
+This is called via the Python ''subprocess'' module, which has some limitations on what you can/can't do in bash. For instance:
+  * Pipes (''|'') are completely unsupported.
+  * Anything that could result in ''stdout'' being written to will also be output, even if the user is not viewing that terminal.
+  * Any interactivity that reads from ''stdin'' will fail.
+  * If a command continually runs in the background then the installation will never complete.
 </WRAP>
@@ Line 172: / Line 188: @@
 <code>
-/userdata/system/package/nes-alterego/
+/userdata/system/package/nes-alter-ego/
                          ├─ userdata/
                          │  └─ roms/
@@ Line 181: / Line 197: @@
                          │        │  └─ Alter_Ego-manual.pdf
                          │        └─ Alter_Ego.nes
-                         ├─ package.txt
+                         ├─ .PKGINFO
                          └─ .BATOEXEC
 </code>
@@ Line 187: / Line 203: @@
 ==== Create the package ====
-Batocera uses a custom tool to create its packages: ''batocera-makepkg''.
+Batocera uses a custom tool to create its packages: [[https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/utils/pacman/batocera-makepkg|batocera-makepkg]].
 To use it:
@@ Line 202: / Line 218: @@
 ''batocera-makepkg'' will not overwrite already existing packages with the same name.
+<WRAP center round info>
+''batocera-makepkg'' will generate some necessary files in the package's source folder, such as if you had used ''.BATOEXEC'' it will create the ''userdata/system/pacman/batoexec/nes-alter-ego_0'' file which is a copy of the ''.BATOEXEC''. These files can be completely ignored, as they will be updated with any edits made to the source files should any [[#updating_your_package|new version of the package]] be made.
+</WRAP>
 ==== Installing your package ====
-If you'd like to test installing your package, you can do so with the following command:
+If you'd like to test [[:updates_and_downloads#install_remove_and_manage_packages|installing your package]], you can do so with the following command:
 <code>
@@ Line 216: / Line 236: @@
 pacman -U /userdata/system/package/nes-alter-ego-1.0.0-1-any.pkg.tar.zst
 </code>
+==== Updating your package ====
+If you kept the original package files, it is simple: make your adjustments and increment the version number however you see fit.
+<file - .PKGINFO>
+pkgname = nes-alter-ego
+pkgver = 1.0.1-1
+pkgdesc = Alter Ego - A freeware puzzle game by Shiru, Kulor, Denis Grachev.
+arch = any
+group = sys-nes
+packager = your_name
+url = https://wiki.batocera.org/start
+</file>
+<WRAP center round info>
+The ''.PKGINFO'' will now contain the ''size'' and ''builddate'' tags. These are updated automatically upon compilation, so don't worry about them.
+</WRAP>
+You may notice that in your ''userdata/'' folder for the package, there are additional folders and files that you had not placed there yourself. These have been automatically generated by ''batocera-makepkg'' (such as if you had used ''.BATOEXEC'' it will create the ''userdata/system/pacman/batoexec/nes-alter-ego_0'' file which is a copy of the ''.BATOEXEC'') and can be safely ignored; they will be updated along with the rest of your package.
+When ready, follow the instructions from the [[#create_the_package|Create the package section above]]. If you receive an error that the package already exists, that means you forgot to increase the package version number or that you have already compiled it.
+<WRAP center round important>
+When updating packages, you **must** increment the version number, even for minor changes. Otherwise, it may cause corruption if the user has the same numbered package installed upon attempting to update to a newer version.
+</WRAP>
+==== Remove your package ====
+When you're done testing or just want a clean slate to work with. Do note however, a ZST file is not actually required to remove a package. Simply enter the name (''pkgname'') of the installed package in the following command:
+<code>
+pacman -R <pkgname>
+</code>
+This is version independent.
+For example:
+<code>
+pacman -R nes-alter-ego
+</code>
+which would result in:
+<code>
+checking dependencies...
+Packages (1) nes-alter-ego-1.0.0-1
+Total Removed Size:  1.33 MiB
+:: Do you want to remove these packages? [Y/n]
+</code>
+Press ''[Y]'' followed by ''[Enter]'' to complete the removal.
+<WRAP center round tip>
+To see a list of installed packages and their version numbers, run ''%%pacman -Q%%''.
+</WRAP>
+===== Hosting your own repository =====
+It is possible to [[:pacman_package_manager|host your own repository]] to test downloading and installing packages via ''batocera-store''.
 ===== Troubleshooting =====
@@ Line 223: / Line 308: @@
 Most likely you didn't change the current working directory to the folder of the package you wanted to create. By default, the current working directory will be in ''/userdata/system'', so all the folders and files in there will be added to your package.
-Run ''%%cd /userdata/system/package/nes-alterego%%'' if you were following the example above and try again.
+Run ''%%cd /userdata/system/package/nes-alter-ego%%'' if you were following the example above and try again.
 ==== How can I see what's in the package? ====