First PKGBUILD, comments are welcomed

thesilentboatman · 2014-02-06 22:24:46

Hi,

I adopted the orphan package Selfoss and modified the PKGBUILD and .install files. Since this is my first one, I thought I post it here first. So if anybody has any input I would really appreciate it.

The two big differences between my PKGBUILD and the original is that I moved the config file to /etc/selfoss/.. and that I keep the old data folder (on upgrades). I keep the data folder because the selfoss homepage states that you should on upgrades

Upload all new files and folders excluding the data folder

My main concern is this folder thing (which I do in the .install file). My suspicion is that I maybe don't need to restore the old data folder. I made some quick tests, and it looked like pacman kept everything that had been added or modified after the last install. But I really don't know when or how pacman will change stuff on a upgrade. So I started looking for answers. First on the wiki, like on pages about ABS, PKGBUILD, creating packages and the Arch packaging standards and then on the forum. But I didn't find it..

Anyhow, here's my PKGBUILD and .install . Thanks in advance!

PKGBUILD

# Maintainer: Maxim Andersson <thesilentboatman@gmail.com>
# Contributor: Tetsumaki <http://goo.gl/YMBdA>

pkgname=selfoss
pkgver=2.9
pkgrel=1
pkgdesc="The new multipurpose rss reader, live stream, mashup, aggregation web application"
arch=('any')
url="http://selfoss.aditu.de/"
license=('GPL3')
depends=('php>=5.3')
optdepends=('apache: is depedency if you do not use lighttpd or nginx'
            'lighttpd'
            'nginx'
            'mariadb: is depedency if you do not use postgresql or sqlite'
            'postgresql'
            'sqlite'
            'php-sqlite: is dependacy if you use sqlite'
            'wget: for automatic updating feeds with cron'
            'curl: for automatic updating feeds with cron')
conflicts=('selfoss-git')
backup=('etc/webapps/selfoss/config.ini')
install=${pkgname}.install
source=("http://selfoss.aditu.de/${pkgname}-${pkgver}.zip"
        "${pkgname}.install")
sha256sums=('9bf3642c7de146c1a89c336ad5fc77e1823d125d7dbfed9060c6c7c2cdc8ec39'
            'f59a0de2ee13d83a263a8f1a0c25ee3542e1981d6ead19af299999818975e142')

package() {
  rm -rf README.md ${pkgname}-${pkgver}.zip

  install -d "${pkgdir}"/usr/share/webapps/${pkgname}
  cp -rf . "${pkgdir}"/usr/share/webapps/${pkgname}/

  # move config to etc
  install -d "${pkgdir}"/etc/webapps/${pkgname}
  sed '4,$s/^/;/' "${pkgdir}"/usr/share/webapps/${pkgname}/defaults.ini > "${pkgdir}"/etc/webapps/${pkgname}/config.ini

  chmod 755 "${pkgdir}"/usr/share/webapps/${pkgname}/{data/cache,data/favicons,data/logs,data/sqlite,data/thumbnails,public}
  chown -R http: "${pkgdir}"/usr/share/webapps/${pkgname}
}

# vim:set ts=2 sw=2 et:

selfoss.install

link_config() {
        ln -sf /etc/webapps/selfoss/config.ini /usr/share/webapps/selfoss/config.ini
        chown http: /usr/share/webapps/selfoss/config.ini
}

post_install() {
        link_config

        echo ""
        echo "==> Installed in : /usr/share/webapps/selfoss"
        echo "==> Change RewriteBase in .htaccess"
        echo "==> Check http://selfoss.aditu.de/ for details."
        echo ""
        echo "==> Config is now at /etc/webapps/selfoss/config.ini"
        echo ""
}


pre_upgrade() {
        # save old config (from pkgbuild 2.8)
        [[ -f /usr/share/webapps/selfoss/config.ini && ! -f /etc/webapps/selfoss/config.ini ]] \
                && install -Dm644 /usr/share/webapps/selfoss/config.ini /etc/webapps/selfoss/config.ini

        [[ -f /usr/share/webapps/selfoss/config.ini && -f /etc/webapps/selfoss/config.ini ]] \
                && install -Dm644 /usr/share/webapps/selfoss/config.ini /etc/webapps/selfoss/config.ini.backup

        # temporarily backup data folder
        rm -rf /tmp/data
        cp -rf /usr/share/webapps/selfoss/data /tmp/ 2> /dev/null
}

post_upgrade() {
        link_config

        # restore data folder
        if [[ -d /tmp/data ]]; then
                rm -rf /usr/share/webapps/selfoss/data
                cp -rf /tmp/data /usr/share/webapps/selfoss/
        fi

        rm -f /usr/share/webapps/selfoss/public/{all.css,all.js}
        [[ -d /usr/share/webapps/selfoss/data/icons ]] \
                && mv -f /usr/share/webapps/selfoss/data/{icons,favicons}

        echo ""
        echo "==> For a clean update:"
        echo "==> Change RewriteBase in .htaccess"
        echo "==> Refresh your browser cache (CTRL+R in most cases)"
        echo "==> Check http://selfoss.aditu.de/ for details."
        echo ""
        echo "==> Config is now at /etc/webapps/selfoss/config.ini"
        echo ""
}

For reference, here's the AUR page with the old PKGBUILD.

Scimmia · 2014-02-06 22:56:53

Overall, pretty good. With a disclaimer that I know nothing about the software in question, I'll bring up a couple of issues:

1. cp -rf should be cp -a. This preserves permissions and other things better.
2. cp -rf . "${pkgdir}"/usr/share/webapps/${pkgname}/ copies the symlink for the install file. The simplest solution is to leave the install file out of the source array, it doesn't need to be there.
3. You're making a symlink in the install file, why not do that in the package function? An untracked file in /usr/share should be avoided if possible.
4. What's up with the backup of /usr/share/webapps/selfoss/data to /tmp/data? It appears the files in that dir would be untracked, so pacman should leave them alone.

Xyne · 2014-02-07 00:20:01

Some remarks:

A main package should not conflict with its own VCS version or other derivative packages. It is the responsibility of the derivatives to conflict with the main package. Otherwise you end up having to keep track of all of the derivatives in the main package.
All optdeps must include a message explaining what they do.
You should cd in the source directory explicitly in the package function.
Modification of source files should be done in a separate prepare function.
You should not need to delete source files. You are currently doing this to lazily copy the entire source directory to the package directory.
The install script should not create untracked files.

thesilentboatman · 2014-02-07 14:27:18

Thanks for your comments!

Scimmia wrote:

1. cp -rf should be cp -a. This preserves permissions and other things better.
2. cp -rf . "${pkgdir}"/usr/share/webapps/${pkgname}/ copies the symlink for the install file. The simplest solution is to leave the install file out of the source array, it doesn't need to be there.
3. You're making a symlink in the install file, why not do that in the package function? An untracked file in /usr/share should be avoided if possible.

Xyne wrote:

A main package should not conflict with its own VCS version or other derivative packages. It is the responsibility of the derivatives to conflict with the main package. Otherwise you end up having to keep track of all of the derivatives in the main package.
The install script should not create untracked files.

All good points. I will change it.

Xyne wrote:

All optdeps must include a message explaining what they do.

Is there a standard way/best practices for adding optdep-messages when the user should choose one of them? Like for this package you have to choose a server (apache, lighttpd..) and then a database (mariadb, sqlite..).

Xyne wrote:

You should cd in the source directory explicitly in the package function.

Don't you start out in the source directory when you start the package function?

Xyne wrote:

Modification of source files should be done in a separate prepare function.

Ok, so I should put my chmod/chown in the prepare function, right? I'm uncertain what more I should put there? The linking to the config file? Should most of the code be in the prepare function, and maybe only keeping this in package()?

install -d "${pkgdir}"/usr/share/webapps/${pkgname}
cp -rf . "${pkgdir}"/usr/share/webapps/${pkgname}/

Sorry about the confusion about this..

Xyne wrote:

You should not need to delete source files. You are currently doing this to lazily copy the entire source directory to the package directory.

Scimmia wrote:

4. What's up with the backup of /usr/share/webapps/selfoss/data to /tmp/data? It appears the files in that dir would be untracked, so pacman should leave them alone.

Sorry for being a bit slow , but are you saying that if a application creates/modifies files (like logs and databases) in ${pkgdir} then pacman will not remove them on upgrades?

Xyne · 2014-02-07 15:09:15

thesilentboatman wrote:

Xyne wrote:
You should cd in the source directory explicitly in the package function.
Don't you start out in the source directory when you start the package function?

If you can point to official documentation from the Pacman devs that guarantees that this will not change in the future then that is fine. Until then, it is best practice to be explicit rather than rely on current coincidences.

thesilentboatman wrote:

Xyne wrote:
Modification of source files should be done in a separate prepare function.
Ok, so I should put my chmod/chown in the prepare function, right? I'm uncertain what more I should put there? The linking to the config file? Should most of the code be in the prepare function, and maybe only keeping this in package()?

By modification I mean commands such as "sed" that change the source. Permissions and ownership modifications should remain in the package functions but should be limited to files in $pkgdir. The former is source data. The latter is metadata. Of course, if you ever need to change permissions to make the source files functional (e.g. chmod +x on some configuration executable), then that should be done in the prepare function as well.

thesilentboatman wrote:

Xyne wrote:
You should not need to delete source files. You are currently doing this to lazily copy the entire source directory to the package directory.
Scimmia wrote:
4. What's up with the backup of /usr/share/webapps/selfoss/data to /tmp/data? It appears the files in that dir would be untracked, so pacman should leave them alone.
Sorry for being a bit slow , but are you saying that if a application creates/modifies files (like logs and databases) in ${pkgdir} then pacman will not remove them on upgrades?

Pacman only tracks files that are in the $pkgdir. Anything created by an install script is untracked and will be left on the system after the package is removed unless it is removed with the install script as well. Untracked files cannot be matched to their "owning package" with "pacman -Qo /path/to/file" and will appear as orphaned files on the system.

Loc files, databases and configuration files that are subject to user changes should be included in $pkgdir and added to the "backup" array in the PKGBUILD. This will preserve current modified copies on the system when the package is upgraded by installing the new, unmodified file with a ".pacnew" extension. The user can then merge changes as necessary.

Normally though I would say that dynamically generated content such as databases should be created at run time in a dedicated data directory that is entirely managed by the user (e.g. XDG_DATA_HOME), but this depends on upstream design and is not a packaging issue.

Scimmia · 2014-02-07 16:38:02

thesilentboatman wrote:

Scimmia wrote:
4. What's up with the backup of /usr/share/webapps/selfoss/data to /tmp/data? It appears the files in that dir would be untracked, so pacman should leave them alone.
Sorry for being a bit slow , but are you saying that if a application creates/modifies files (like logs and databases) in ${pkgdir} then pacman will not remove them on upgrades?

In this case, that dir only contains some subdirs and no files in the package. When the program creates those files, they will be untracked (bad, but unavoidable). When pacman goes to upgrade, it will remove the files it knows about, leaving those untracked files in place. It will then install the new files, again, leaving the untracked files in place. It does not force remove the entire dir. The whole backup to /tmp seems like a waste unless there's something I'm missing.

Really, the dir in question should be in /var somwhere, or maybe the entire installation should be in /srv?

thesilentboatman · 2014-02-08 00:45:52

Xyne wrote:

If you can point to official documentation from the Pacman devs that guarantees that this will not change in the future then that is fine. Until then, it is best practice to be explicit rather than rely on current coincidences.

Got it! Good point.

Xyne wrote:

By modification I mean commands such as "sed" that change the source. Permissions and ownership modifications should remain in the package functions but should be limited to files in $pkgdir. The former is source data. The latter is metadata. Of course, if you ever need to change permissions to make the source files functional (e.g. chmod +x on some configuration executable), then that should be done in the prepare function as well.

Ok, I think I understand it. source data/metadata. But in my case with the sed line, since it doesn't modify any source content but creates a new file, then it should be in package(), right?

Scimmia wrote:

Really, the dir in question should be in /var somwhere, or maybe the entire installation should be in /srv?

Yes, I was thinking about putting it in /var/lib/selfoss. This is exactly how tt-rss (a similar webapp) did it.

Xyne · 2014-02-08 02:21:00

thesilentboatman wrote:

Ok, I think I understand it. source data/metadata. But in my case with the sed line, since it doesn't modify any source content but creates a new file, then it should be in package(), right?

yes

progandy · 2014-02-08 05:09:20

You rely on the installscript too much. Please do ln -s and chown during package(). Don't move the data folder during pre/postinstall. Install the default data to .../example.data, then mention this in a post_install message and remind the user to merge/copy it to .../data.
If you really want to move the config to etc, try to use a short path like /etc/selfoss.ini or /etc/selfoss/config.ini. I don't see the need for an unnecessary deep directory structure.
You might want to use the backup-array for both config locations and let the user move his config manually.

Last edited by progandy (2014-02-08 05:12:28)

thesilentboatman · 2014-02-09 07:54:26

progandy wrote:

You rely on the installscript too much. Please do ln -s and chown during package(). Don't move the data folder during pre/postinstall. Install the default data to .../example.data, then mention this in a post_install message and remind the user to merge/copy it to .../data.
If you really want to move the config to etc, try to use a short path like /etc/selfoss.ini or /etc/selfoss/config.ini. I don't see the need for an unnecessary deep directory structure.
You might want to use the backup-array for both config locations and let the user move his config manually.

Thanks for your reply!

Yes, I will move the linking to package. About the long etc path, I used /etc/webapps because they use it on the the wiki page: Web Application Package Guidelines.

progandy · 2014-02-09 08:04:24

thesilentboatman wrote:

Yes, I will move the linking to package. About the long etc path, I used /etc/webapps because they use it on the the wiki page: Web Application Package Guidelines.

So the path is somewhat standardized and used by different packages. Then the directory structure makes sense.

thesilentboatman · 2014-02-09 23:32:12

Ok, so here's how my PKGBUILD and .install looks like now.

PKGBUILD

# Maintainer: Maxim Andersson <thesilentboatman@gmail.com>
# Contributor: Tetsumaki <http://goo.gl/YMBdA>

pkgname=selfoss
pkgver=2.9
pkgrel=1
pkgdesc="The new multipurpose rss reader, live stream, mashup, aggregation web application"
arch=('any')
url="http://selfoss.aditu.de/"
license=('GPL3')
depends=('php>=5.3')
optdepends=('apache: server, depedency if not using lighttpd or nginx'
            'lighttpd: server, depedency if not using apache or nginx'
            'nginx: server, depedency if not using lighttpd or apache'
            'mariadb: database, depedency if not using postgresql or sqlite'
            'postgresql: database, depedency if not using mariadb or sqlite'
            'sqlite: database, depedency if not using postgresql or mariadb'
            'php-sqlite: dependency if using sqlite'
            'wget: for automatic updating feeds with cron'
            'curl: for automatic updating feeds with cron')
backup=('etc/webapps/selfoss/config.ini')
install=${pkgname}.install
source=("http://selfoss.aditu.de/${pkgname}-${pkgver}.zip")
sha256sums=('9bf3642c7de146c1a89c336ad5fc77e1823d125d7dbfed9060c6c7c2cdc8ec39')

package() {
  rm -rf "${srcdir}"/{README.md,${pkgname}-${pkgver}.zip}

  install -d "${pkgdir}"/usr/share/webapps/${pkgname}
  cp -af "${srcdir}"/. "${pkgdir}"/usr/share/webapps/${pkgname}/

  # create config in /etc
  install -d "${pkgdir}"/etc/webapps/${pkgname}
  sed '4,$s/^/;/' "${pkgdir}"/usr/share/webapps/${pkgname}/defaults.ini > "${pkgdir}"/etc/webapps/${pkgname}/config.ini
  ln -sf /etc/webapps/${pkgname}/config.ini "${pkgdir}"/usr/share/webapps/${pkgname}/config.ini

  chmod 755 "${pkgdir}"/usr/share/webapps/${pkgname}/{data/cache,data/favicons,data/logs,data/sqlite,data/thumbnails,public}
  chown -R http: "${pkgdir}"/usr/share/webapps/${pkgname}
}

# vim:set ts=2 sw=2 et:

.install

post_install() {
        echo ""
        echo "==> Installed in : /usr/share/webapps/selfoss"
        echo "==> Change RewriteBase in .htaccess"
        echo "==> Check http://selfoss.aditu.de/ for details."
        echo ""
        echo "==> Config is now at /etc/webapps/selfoss/config.ini"
        echo ""
}


pre_upgrade() {
        # save old untracked config (from pkgbuild 2.8) and make it tracked
        [[ -f /usr/share/webapps/selfoss/config.ini && ! -h /usr/share/webapps/selfoss/config.ini ]] \
                && install -Dm644 /usr/share/webapps/selfoss/config.ini /etc/webapps/selfoss/config.ini
}

post_upgrade() {

        rm -f /usr/share/webapps/selfoss/public/{all.css,all.js}

        echo ""
        echo "==> For a clean update:"
        echo "==> Change RewriteBase in .htaccess"
        echo "==> Refresh your browser cache (CTRL+R in most cases)"
        echo "==> Check http://selfoss.aditu.de/ for details."
        echo ""
        echo "==> Config is now at /etc/webapps/selfoss/config.ini"
        echo ""
}

pre_remove() {
        # remove untracked files
        find /usr/share/webapps/selfoss/data/ -type f -exec rm -f '{}' ';' 2> /dev/null
        rm -f /usr/share/webapps/selfoss/public/{all.css,all.js}
}

Thanks for all the time you spent explainting stuff! Really appreciate it. Can't wait to adopt a new PKGBUILD or maybe make a new one

The only thing I wasn't able to do was to put the data directory in /var/lib/. On upgrades pacman complained about the new link (ln -s /var/lib/.. data), because it was already tracking a directory with the same name ('data'). But that's no big deal.

Last edited by thesilentboatman (2014-02-10 17:13:22)

Arch Linux

#1 2014-02-06 22:24:46

First PKGBUILD, comments are welcomed

#2 2014-02-06 22:56:53

Re: First PKGBUILD, comments are welcomed

#3 2014-02-07 00:20:01

Re: First PKGBUILD, comments are welcomed

#4 2014-02-07 14:27:18

Re: First PKGBUILD, comments are welcomed

#5 2014-02-07 15:09:15

Re: First PKGBUILD, comments are welcomed

#6 2014-02-07 16:38:02

Re: First PKGBUILD, comments are welcomed

#7 2014-02-08 00:45:52

Re: First PKGBUILD, comments are welcomed

#8 2014-02-08 02:21:00

Re: First PKGBUILD, comments are welcomed

#9 2014-02-08 05:09:20

Re: First PKGBUILD, comments are welcomed

#10 2014-02-09 07:54:26

Re: First PKGBUILD, comments are welcomed

#11 2014-02-09 08:04:24

Re: First PKGBUILD, comments are welcomed

#12 2014-02-09 23:32:12

Re: First PKGBUILD, comments are welcomed

Board footer