Skip to content

Latest commit

 

History

History
265 lines (174 loc) · 9.8 KB

CONTRIBUTING.md

File metadata and controls

265 lines (174 loc) · 9.8 KB
Raw

Proot-Distro Contributor Guide

Proot-Distro is yet another utility for installing Linux distributions on the non-rooted Android device. As the most of existing software projects, this utility created with aim to solve a specific range of tasks using the way preferred by its original author.

This document describes the principles that you must take into account when contributing to the Proot-Distro project.

Disclaimer

DON'T expect:

  • That Proot-Distro will satisfy your needs

  • That Proot-Distro will work flawlessly on your device

  • That all your issues will be resolved by maintainers immediately

  • That all your submitted patches would be accepted

  • That maintainers will teach you how to use Linux distributions

DON'T report bugs for:

  • Distributions

  • Restricted access to distribution hosting service

  • Lack of Internet access

  • Usage of mobile data plan and disk space

DON'T ask for features such as:

  • Support for runtime platforms other than Termux

  • Classical Linux chroot and other things that require rooted device

  • Modified or pre-configured distributions

  • Distributions related to hacking: Kali Linux, Nethunter, Parrot OS, Black Arch, etc

  • Distribution init systems: systemd, openrc, etc

  • Additionally: here goes all stuff that would require me to redesign Proot-Distro from scratch

Design insights

1. General information

1.1 Proot-Distro has a specific, well defined structure which makes it unique and separates from analogous projects. This structure expected to be followed during whole project lifetime. If you have ideas how to restructure the Proot-Distro, then please keep them in your own fork! Customizing sources for your own preferences is not welcome.

Review the proot-distro.sh script to understand how it works and see key parts of the design.

1.2 Proot-Distro is written in Bash script language with using features which are not compatible with POSIX shell. The script itself is monolithic and is not supposed to be split on multiple parts.

1.3 Tabs must be used for indenting code blocks everywhere.

1.4 All features are split on functions. There are 3 types of functions:

  • Commands: implement specific features of Proot-Distro such as install, backup, login the distribution. These functions have following name scheme: command_name().

  • Command help: supplementary functions implementing informational output describing usage of Proot-Distro commands. These functions are named as command_name_help() and are defined AFTER the commands.

  • Utility functions: reusable or very long pieces of code.

1.5 Each command function definition should begin with comment section.

Comment sections logically separate functions on groups and provide a brief overview which part of Proot-Distro is implemented here. The comment must provide a description of how the function works.

Utility functions are allowed to have a very brief description and command help functions.

Command help functions should not have comments. They are self descriptive.

1.6 Code pieces that do non-obvious actions must be commented.

1.7 Functions are not allowed to define global variables. Use keyword local to define the local variables instead.

1.8 Global variables must be defined either at beginning of Proot-Distro script or at the entry point.

1.9 Use of getopt for options handling is considered as non-flexible and thus not allowed.

1.10 The checks for error conditions must be implemented. If error has been encountered, a message should be printed on stderr and further execution should be terminated.

1.11 If error was encountered inside function, exiting should be done using the command return 1 to pass a status code to the caller. Use of exit command is not allowed unless used in script entry point.

1.12 User input in command functions must be validated during the command line arguments handling.

1.13 Use heredocs to write files, especially if their content is long.

1.14 Certain configuration such as plug-in directory path may be set only during installation of the Proot-Distro. Such configuration is treated as persistent and should not be changed by user.

1.15 Proot-Distro uses string place holders to define certain common values for some variables:

  • @TERMUX_APP_PACKAGE@ - sets Termux app package (com.termux).

  • @TERMUX_PREFIX@ - sets the installation prefix path.

  • @TERMUX_HOME@ - sets the Termux home directory path.

It is not allowed to hardcode the mentioned values instead of using the place holder.

2. Informational messages output

2.1 All informational messages are printed in specific format.

2.2 Use function msg to print messages.

2.3 Messages printed by help functions must fit in 76 columns. If the message is too long, split in on multiple lines. This is not relevant to errors and other informational messages. Pay extra attention to keep the message properly indented.

2.4 All messages printable by Proot-Distro script must support colored text through the escape sequences defined below by variables such as ${RED} (red), ${BRED} (bold red text), ${YELLOW}, ${BYELLOW}, etc.

2.5 Proot-Distro operation errors must have bold red color (${BRED}). The key information such as arguments caused an error should be encloded in quotes and highlighted by yellow color (${YELLOW}).

2.6 Messages should be terminated by ${RST} which resets the text colors and other attributes.

2.7 Informational messages produced by Proot-Distro command steps must have the following format:

${BLUE}[${GREEN}*${BLUE}] ${CYAN}Message...${RST}"

2.8 If the step encountered a condition where an error should be printed, the following message format should be used instead:

${BLUE}[${RED}!${BLUE}] ${CYAN}Error or warning message.${RST}

2.9 Warnings about issues happened due to unexpected circumstances rather than due to failure of Proot-Distro actions should be printed in this format:

${BRED}Warning: message.${RST}

Similarly to warnings, the error messages should have this format:

${BRED}Error: message.${RST}

3. Handling distributions

3.1 Proot-Distro script is intended to be distribution-agnostic. That means it treats all distributions equally and handles them in the same way despite the possible differences at level of distribition root file system package.

3.2 Support of specific distribution is enabled by using a plug-in. The plug-in is a Bash script that is sourced by Proot-Distro and has the following format:

DISTRO_NAME="Example"
DISTRO_COMMENT="Example distribution."

TARBALL_STRIP_OPT=1

TARBALL_URL['aarch64']="https://example.com/archive-aarch64.tar.gz"
TARBALL_URL['arm']="https://example.com/archive-armv7.tar.gz"
TARBALL_URL['i686']="https://example.com/archive-i386.tar.gz"
TARBALL_URL['riscv64']="https://example.com/archive-riscv64.tar.gz"
TARBALL_URL['x86_64']="https://example.com/archive-amd64.tar.gz"

TARBALL_SHA256['aarch64']="0000000000000000000000000000000000000000000000000000000000000000"
TARBALL_SHA256['arm']="0000000000000000000000000000000000000000000000000000000000000000"
TARBALL_SHA256['i686']="0000000000000000000000000000000000000000000000000000000000000000"
TARBALL_SHA256['riscv64']="0000000000000000000000000000000000000000000000000000000000000000"
TARBALL_SHA256['x86_64']="0000000000000000000000000000000000000000000000000000000000000000"

 distro_setup() {
   run_proot_cmd touch /etc/hello-world
   run_proot_cmd bash -c "echo '127.0.0.1 hello-world' >> /etc/hosts"
 }

3.3 The variable DISTRO_NAME specifies a full name of distribution such as Ubuntu or Debian (stable). This variable is mandatory.

3.4 The variable TARBALL_URL is a Bash associative array which contains URLs to distribution rootfs tarball for given CPU architectures. This variable is mandatory. The URL should start with proper protocol scheme. For example https://, ftp:// or file://.

3.5 The variable TARBALL_SHA256 is a Bash associative array which contains SHA-256 checksums of rootfs tarballs for given CPU architectures. This variable is mandatory.

3.6 Post-installation steps that may be required for some distributions are defined in distro_setup() function (optional). This function has access to all variables defined by Proot-Distro during the execution of command_install().

3.7 Commands inside distro_setup() that are intended to be executed in distribution environment must be defined as arguments of the command run_proot_cmd.

3.8 Distributions must be adressed by their alias which in fact is a file name of plug-in except the extension part.

3.9 The alias files are located in ${TERMUX_PREFIX}/etc/proot-distro and have extensions .sh or .override.sh.

  • dist.sh name format is used for standard plug-ins.

  • dist2.override.sh name is used to indicate that this is a renamed distribution created by command rename or by the option --override-alias of command install.

3.10 The alias for distribution must be unique and Proot-Distro should take care of that. User should not end with having two plug-ins for same alias, for example ubuntu.sh and ubuntu.override.sh.

3.11 The rootfs for distribution may be extracted only under PRoot session with active link2symlink extension.

4. Project versioning scheme: major.minor.patch

4.1 Major version should be incremented when breaking changes were released. Examples are deprecated features, changed locations of files, command line format changes.

4.2 Minor version is incremented for significant but non-breaking changes such as added new features or upgraded distributions. The minor version is set to 0 when major version was incremented.

4.3 Patch version is incremented for small changes such as bug fixes. It is set to 0 when major or minor versions were incremented.