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

Some packages are not suitable for inclusion in the Community repository.

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

The same rules above may apply to other software at the discretion of maintainers.

0001

Packages which are binaries must contain the suffix '-bin' to reflect this fact. Similarly, packages which pull from git should contain the suffix '-git'. The version of git packages must 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 should 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:  cp "file" "$1/usr/bin/file"
Good: cp file "$1/usr/bin/file"

0209

Quote entire strings instead of variables.

Bad:  cp -f cat "$1"/usr/bin/cat
Good: cp -f cat "$1/usr/bin/cat"

0210

Align arguments in blocks of command calls.

Bad:

cp file.h "$1/usr/include/file.h"
cp libfile.so "$1/usr/lib/libfile.so"

Good:

cp file.h     "$1/usr/include/file.h"
cp libfile.so "$1/usr/lib/libfile.so"

0211

Use mkdir and cp instead of install.

Bad:

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

Good:

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

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.

0214

Always use printf. Do not use echo.

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 preferred 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

If dependency is unneeded, then it must be removed.

1202

Some packages are assumed to always be available. Such dependency must be removed.

Examples: gcc, make, musl.

1203

Build-time dependencies must be marked as 'make' dependencies.

Examples: autoconf, automake, cmake, meson.

1204

Runtime dependencies must not be marked as 'make' dependencies.

1205

The depends file must be sorted.

1206

If depends file is empty, then it must 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

Package version must be latest upstream version.

1602

Use 'git' in place of '9999'.

1603

The version file must contain 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.