PACKAGE STYLE GUIDE

This document is a style guide which will double as documentation for a possible package linter in the future. Every package in the Official Repositories and the Community repository adheres to this style guide.

NOTE: Exceptions are made where it makes sense.

MAINTAINERSHIP

GENERAL

0000

Package is not suitable for inclusion in the Community repository. The same rules above may apply to other software at the discretion of the BDFL.

Examples: ConsoleKit, dbus, electron, gettext, gtk2, intltool, libsn, logind, pam, pipewire, polkit, pulseaudio, systemd, wayland and all Desktop Environments.

0001

No new packages shall use Python 2 as it will be removed once Chromium drops it as a dependency.

0002

Packages which are binaries should contain the suffix '-bin' to reflect this fact. Similarly, packages which pull from git should contain the suffix '-git'. The version of git packages should also be set to 'git'.

BUILD

0200

This guide should be used alongside shellcheck and not in place of it.

0201

All shell code must pass the shellcheck linter. Any false-positives or intended behavior must have a rationale attached with the exclusion.

# Disable warning as CFLAGS must work this way.
# shellcheck disable=2086
"${CC:-cc}" $CFLAGS ...

0202

Use 4 spaces for indentation.

0203

Lines should not exceed 80 characters in length.

0204

All packages must use the POSIX shell shebang with '-e' to exit on error. Additionally, '-ef' can be used if word-splitting is required.

There must also be a blank line directly below the shebang.

#!/bin/sh -e

# Code starts here.

0205

All comments must start with a capital letter and use proper spelling, grammar and punctuation.

# This is a comment.

0206

Leave comments to explain why the code is needed and not what it does.

Bad:

# Create a directory.
mkdir -p "$1/usr/bin"

Good:

# 'make install' doesn't create the directory.
mkdir -p "$1/usr/bin"

0207

Avoid adding braces around variables if unneeded.

Bad:  printf '%s\n' "${var}"
Good: printf '%s\n' "$var"
Good: printf '%s\n' "${var}.${var2}"

0208

Avoid quotes when unneeded.

Bad:  [ "$var" = "test" ]
Good: [ "$var" = test ]

Bad:  install -Dm755 "file" "$1/usr/bin/file"
Good: install -Dm755 file "$1/usr/bin/file"

0209

Quote entire strings instead of variables.

Bad:  install -Dm644 cat "$1"/usr/bin/cat
Good: install -Dm644 cat "$1/usr/bin/cat"

0210

Align arguments in blocks of command calls.

Bad:

install -D file.h "$1/usr/include/file.h"
install -D libfile.so "$1/usr/lib/libfile.so"

Good:

install -D file.h     "$1/usr/include/file.h"
install -D libfile.so "$1/usr/lib/libfile.so"

0211

Use install instead of ...

Bad:

mkdir -p "$1/usr/bin"
cp ls "$1/usr/bin/"

Good:

install -Dm755 ls "$1/usr/bin/ls"

NOTE: since Dylan wrote this style guide, he changed opinions on this point since install isn't POSIX. Both styles are accepted in the community repo.

0212

Prefer $CC to ...

Bad:  gcc -o file file.c
Good: "${CC:-cc}" -o file file.c

0213

Always use -p with mkdir.

GNU AUTOTOOLS

0400

Use the following style:

./configure \
    --prefix=/usr \
    --more_args_here

make
make DESTDIR="$1" install

0401

Avoid running ./autogen.sh, autoreconf or similar tools prior to starting the build process. If there are no pre-generated configure or Makefiles, an alternate source must be sought.

An exception can be made for packages in which no such source exists. If autogen.sh or autoreconf are required, prefer autoreconf.

MESON

0600

Use the following style:

export DESTDIR="$1"

meson \
    --prefix=/usr \
    -Dexample=false \
    . output

ninja -C output
ninja -C output install

CMAKE

0800

Use the following style:

export DESTDIR="$1"

cmake -B build \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DFLAG=1

cmake --build   build
cmake --install build

MAKE

1000

Use one of the following style when applicable:

make
make DESTDIR="$1" PREFIX=/usr install


make PREFIX=/usr
make DESTDIR="$1" install


make PREFIX=/usr
make DESTDIR="$1" PREFIX=/usr install

For packages which require a few variables be set, prefer this style.

make \
    PREFIX=/usr \
    SBINDIR=/usr/bin \
    OPT="$CFLAGS"

make \
    DESTDIR="$1" \
    PREFIX=/usr \
    install

For packages which require the variables be set for all calls to make, prefer this style.

mk() {
    make \
         PREFIX=/usr \
         DESTDIR="$1" \
         EXAMPLE=1 \
         "$@"
}

mk
mk install

RUST

1050

Use the following style:

cargo build --release

install -Dm755 target/release/rg "$1/usr/bin/rg"

GO

1100

Use the following style:


export GOPATH="$PWD/go"
export GO111MODULE=on

go build \
    -modcacherw \
    -trimpath

install -Dm755 lazygit "$1/usr/bin/lazygit"

Note: If the directory 'vendor' is available in the root directory of the source, the preffered method is to omit GOPATH and GO111MODULE and use:


go build \
   -mod=vendor \
   -further-options

to prevent cluttering $HOME and enable offline building.

PYTHON

1150

Use the following style:

python setup.py build
python setup.py install --prefix=/usr --root="$1"

DEPENDS

1201

This dependency is unneeded and can be removed.

1202

This dependency is implicit. Some packages are assumed to always be available. This dependency can be removed.

Examples: gcc, make, musl.

1203

This dependency needs 'make' as it is only required during build time.

Common Examples: autoconf, automake, cmake, meson.

1204

This dependency doesn't need 'make' as it is required during runtime.

1205

The depends list must be sorted.

1206

The depends file is empty and should be removed.

SOURCES

1401

Use a HTTPS source if at all possible.

1402

Don't specify patches remotely. Store them as a part of the package's repository files.

Bad:  https://example.com/fix-build.patch
Good: patches/fix-build.patch

1403

Don't use a git repository in place of a release tarball unless it makes sense to do so.

1404

Drop www. and .git from all sources if possible.

VERSION

1601

Version doesn't match upstream.

1602

Use 'git' in place of '9999'.

1603

Missing relative version number.

Bad:  1.0.0
Good: 1.0.0 1

PATCHES

1800

Use the following style:

patch -p1 < patch.patch

# If there is more than one patch.
for patch in *.patch; do
    patch -p1 < "$patch"
done

1801

All patches should use the same strip amount. If this is not possible, modify the patches. Strip amount is controlled by the -p flag.