From 8753d5e903f1270bb06f83a690f099ae5dca35b2 Mon Sep 17 00:00:00 2001 From: Luca Di Maio Date: Wed, 1 May 2024 18:09:55 +0200 Subject: [PATCH] all: improve function docs Signed-off-by: Luca Di Maio --- distrobox | 6 ++- distrobox-assemble | 34 ++++++++++------ distrobox-create | 73 +++++++++++++++++++-------------- distrobox-enter | 39 +++++++++--------- distrobox-ephemeral | 21 +++++++++- distrobox-export | 87 ++++++++++++++++++++++------------------ distrobox-generate-entry | 6 ++- distrobox-host-exec | 6 ++- distrobox-init | 31 ++++++++++---- distrobox-list | 6 ++- distrobox-rm | 36 ++++++++++------- distrobox-stop | 6 ++- distrobox-upgrade | 6 ++- install | 2 +- 14 files changed, 229 insertions(+), 130 deletions(-) diff --git a/distrobox b/distrobox index d44ee8c10a..41097eb34e 100755 --- a/distrobox +++ b/distrobox @@ -24,9 +24,13 @@ set -o nounset version="1.7.1.0" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/distrobox-assemble b/distrobox-assemble index 63523179b3..5db6b18401 100755 --- a/distrobox-assemble +++ b/distrobox-assemble @@ -231,16 +231,18 @@ if [ ! -e "${input_file}" ]; then exit 1 fi -# Create distrobox with parameters parsed from ini file. +# run_distrobox will create distrobox with parameters parsed from ini file. # Arguments: -# name = name of the distrobox. +# name: name of the distrobox. # Expected global variables: -# boxname = string name of the target container -# tmpfile = string name of the tmpfile to read -# delete = bool delete container -# replace = bool replace container -# dryrun = bool dryrun (only print, no execute) -# verbose = bool verbose +# boxname: string name of the target container +# tmpfile: string name of the tmpfile to read +# delete: bool delete container +# replace: bool replace container +# dryrun: bool dryrun (only print, no execute) +# verbose: bool verbose +# Expected env variables: +# None # Outputs: # execution of the proper distrobox-create command. run_distrobox() { @@ -445,9 +447,13 @@ run_distrobox() { fi } -# Sanitize an input, add single/double quotes and escapes +# sanitize_variable will sanitize an input, add single/double quotes and escapes # Arguments: -# a value string +# variable: string +# Expected global variables: +# None +# Expected env variables: +# None # Outputs: # a value string sanitized sanitize_variable() { @@ -464,11 +470,13 @@ sanitize_variable() { echo "${variable}" } -# Parse input file and call distrobox-create accordingly +# parse_file will read and parse input file and call distrobox-create accordingly # Arguments: -# path of the manifest file to parse +# file: stirng path of the manifest file to parse # Expected global variables: -# tmpfile = string name of the tmpfile to read +# tmpfile: string name of the tmpfile to read +# Expected env variables: +# None # Outputs: # None parse_file() { diff --git a/distrobox-create b/distrobox-create index 2906ec318b..a253333233 100755 --- a/distrobox-create +++ b/distrobox-create @@ -153,9 +153,15 @@ fi [ "${verbose}" = "true" ] && verbose=1 [ "${verbose}" = "false" ] && verbose=0 -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: string distrobox version +# container_image_default: string default container image to use +# container_name_default: string default container name to use +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { @@ -225,12 +231,14 @@ Compatibility: EOF } -# Print list of compatible images to stdou, caching locally in a file. +# show_compatibility will print the list of compatible images to stdout, caching locally in a file. # Arguments: # None # Expected global variables: -# app_cache_dir = cache dir to write to -# version = distrobox version +# app_cache_dir: cache dir to write to +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_compatibility() { @@ -554,12 +562,15 @@ if [ -z "${distrobox_entrypoint_path}" ] || [ -z "${distrobox_export_path}" ]; t exit 127 fi -# Clone a container as a snapshot. +# get_clone_image will return the image name of a cloned existing container taken +# as input. # Arguments: # None # Expected global variables: -# container_manager = string container manager to use -# container_clone = string container name to clone +# container_manager: string container manager to use +# container_clone: string container name to clone +# Expected env variables: +# None # Outputs: # prints the image name of the newly cloned container get_clone_image() { @@ -598,32 +609,34 @@ get_clone_image() { return 0 } -# Generate Podman or Docker command to execute. +# generate_create_command will produce a Podman or Docker command to execute. # Arguments: # None # Expected global variables: -# container_manager = string container manager to use -# container_name = string container name -# container_image = string container image -# container_manager_additional_flags = string container manager additional flags to use -# container_hostname = string container hostname -# container_additional_packages = string additional packages -# container_pre_init_hook = string pre init hooks -# container_init_hook = string init hooks -# container_user_home = string user's home path -# container_user_name = string user's username -# container_user_uid = string user's UID -# container_user_gid = string user's GID -# container_home_prefix = string container's custom home prefix -# container_user_custom_home = string container's custom home path -# init = bool initful -# nvidia = bool nvidia integration -# rootful = bool rootful -# unshare_devsys = bool unshare devsys -# unshare_groups = bool unshare groups -# unshare_ipc = bool unshare ipc -# unshare_netns = bool unshare netns -# unshare_process = bool unshare proc +# container_manager: string container manager to use +# container_name: string container name +# container_image: string container image +# container_manager_additional_flags: string container manager additional flags to use +# container_hostname: string container hostname +# container_additional_packages: string additional packages +# container_pre_init_hook: string pre init hooks +# container_init_hook: string init hooks +# container_user_home: string user's home path +# container_user_name: string user's username +# container_user_uid: string user's UID +# container_user_gid: string user's GID +# container_home_prefix: string container's custom home prefix +# container_user_custom_home: string container's custom home path +# init: bool initful +# nvidia: bool nvidia integration +# rootful: bool rootful +# unshare_devsys: bool unshare devsys +# unshare_groups: bool unshare groups +# unshare_ipc: bool unshare ipc +# unshare_netns: bool unshare netns +# unshare_process: bool unshare proc +# Expected env variables: +# None # Outputs: # prints the podman, docker or lilipod command to create the distrobox container generate_create_command() { diff --git a/distrobox-enter b/distrobox-enter index 4f49b33aeb..95b960b5a8 100755 --- a/distrobox-enter +++ b/distrobox-enter @@ -41,15 +41,16 @@ app_cache_dir=${XDG_CACHE_HOME:-"${HOME}/.cache"}/distrobox trap cleanup TERM INT HUP EXIT -# Generate Podman, Docker or Lilipod command to execute. +# cleanup will remove fifo and temp files, and print to stdout +# container's logs in case of error and verbose. # Arguments: # None # Expected global variables: -# container_manager = string container manager to use -# container_name = string container name -# app_cache_dir = string cache dire to write file into -# logs_pid = string pid of the podman/docker logs process -# verbose = bool verbose +# container_manager: string container manager to use +# container_name: string container name +# app_cache_dir: string cache dire to write file into +# logs_pid: string pid of the podman/docker logs process +# verbose: bool verbose # Expected env variables: # None # Outputs: @@ -151,13 +152,13 @@ fi [ "${verbose}" = "true" ] && verbose=1 [ "${verbose}" = "false" ] && verbose=0 -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None # Expected global variables: -# version = string distrobox version +# version: distrobox version # Expected env variables: -# USER +# None # Outputs: # print usage with examples. show_help() { @@ -341,19 +342,19 @@ if [ "${rootful}" -ne 0 ]; then container_manager="${distrobox_sudo_program-} ${container_manager}" fi -# Generate Podman, Docker or Lilipod command to execute. +# generate_enter_command will produce a Podman, Docker or Lilipod command to execute to enter the container. # Arguments: # None # Expected global variables: -# container_manager = string container manager to use -# container_name = string container name -# container_manager_additional_flags = string container manager additional flags to use -# container_command = string container command to execute -# container_home = string container's home path -# container_path = string container's default PATH variable -# headless = bool headless mode -# skip_workdir = bool skip workdir -# verbose = bool verbose +# container_manager: string container manager to use +# container_name: string container name +# container_manager_additional_flags: string container manager additional flags to use +# container_command: string container command to execute +# container_home: string container's home path +# container_path: string container's default PATH variable +# headless: bool headless mode +# skip_workdir: bool skip workdir +# verbose: bool verbose # unshare_groups # distrobox_enter_path # Expected env variables: diff --git a/distrobox-ephemeral b/distrobox-ephemeral index 9b2b3a40ac..5ab7a00e3e 100755 --- a/distrobox-ephemeral +++ b/distrobox-ephemeral @@ -86,9 +86,13 @@ done [ "${verbose}" = "true" ] && verbose=1 [ "${verbose}" = "false" ] && verbose=0 -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { @@ -202,7 +206,7 @@ if [ "${rootful}" -ne 0 ]; then extra_flags="${extra_flags} --root" fi -# Generate distrobox-create command to execute. +# generate_ephemeral_create_command will produce a distrobox-create command to execute. # Arguments: # None # Expected global variables: @@ -210,6 +214,8 @@ fi # name = string container name # extra_flags = string extra flags to inject # create_flags = string create extra flags to inject +# Expected env variables: +# None # Outputs: # prints the distrobox-create command handling special flags generate_ephemeral_create_command() { @@ -237,6 +243,17 @@ generate_ephemeral_create_command() { printf "%s" "${result_command}" } +# cleanup will ensure we remove the ephemeral container +# Arguments: +# None +# Expected global variables: +# name: string the name of the container +# extra_flags: string extra flags to append to the distrobox command +# distrobox_path: string path to the distrobox script +# Expected env variables: +# None +# Outputs: +# None cleanup() { trap - TERM INT HUP # shellcheck disable=SC2086 diff --git a/distrobox-export b/distrobox-export index 17e9a32409..df1660f86f 100755 --- a/distrobox-export +++ b/distrobox-export @@ -67,7 +67,7 @@ done # Arguments: # None # Expected global variables: -# version: string distrobox version +# version: distrobox version # Expected env variables: # None # Outputs: @@ -311,20 +311,23 @@ else exported_app_label=" ${exported_app_label}" fi -# Print generated script from template +# generate_script will generate a script from template. This script will wrap the +# exported binary in order to ensure it will be executed in the right container. # Arguments: -# none it will use the ones set up globally +# None +# Expected global variables: +# CONTAINER_ID: id of the current container +# container_command_suffix: string to postpone to the command to launch +# container_name: string name of this container +# dest_path: string path where to export the binary +# enter_flags: string extra flags to append to the distrobox enter command +# exported_bin: string path to the binary to export +# exported_delete: bool delete the binary exported +# extra_flags: string extra flags to append to the exported app command +# rootful: bool if this is a rootful container +# sudo_prefix: string sudo command to prepend to the exported command # Expected env variables: -# CONTAINER_ID = id of the current container -# container_command_suffix = string to postpone to the command to launch -# container_name = string name of this container -# dest_path = string path where to export the binary -# enter_flags = string extra flags to append to the distrobox enter command -# exported_bin = string path to the binary to export -# exported_delete = bool delete the binary exported -# extra_flags = string extra flags to append to the exported app command -# rootful = bool if this is a rootful container -# sudo_prefix = string sudo command to prepend to the exported command +# None # Outputs: # print generated script. generate_script() { @@ -343,18 +346,20 @@ EOF return $? } -# Export binary to destination directory. +# export_binary will export selected binary to destination directory. # the following function will use generate_script to create a shell script in # dest_path that will execute the exported binary in the selected distrobox. # # Arguments: -# none it will use the ones set up globally +# None +# Expected global variables: +# CONTAINER_ID: id of the current container +# container_name: string name of this container +# dest_path: string path where to export the binary +# exported_bin: string path to the binary to export +# exported_delete: bool delete the binary exported # Expected env variables: -# CONTAINER_ID = id of the current container -# container_name = string name of this container -# dest_path = string path where to export the binary -# exported_bin = string path to the binary to export -# exported_delete = bool delete the binary exported +# None # Outputs: # a generated_script in dest_path # or error code. @@ -403,23 +408,25 @@ export_binary() { return 3 } -# Export graphical application to the host. +# export_application will export input graphical application to the host. # the following function will scan the distrobox for desktop and icon files for # the selected application. It will then put the needed icons in the host's icons # directory and create a new .desktop file that will execute the selected application # in the distrobox. # # Arguments: -# none it will use the ones set up globally +# None +# Expected global variables: +# CONTAINER_ID: id of the current container +# container_command_prefix: string to prepend to the command to launch +# container_name: string name of this container +# exported_app: string name of the app to export +# exported_app_label: string label to use to mark the exported app +# exported_delete: bool if we want to delete or not +# extra_flags: string extra flags to append to the exported app command +# host_home: home path ofr the host, where to search desktop files # Expected env variables: -# CONTAINER_ID = id of the current container -# container_command_prefix = string to prepend to the command to launch -# container_name = string name of this container -# exported_app = string name of the app to export -# exported_app_label = string label to use to mark the exported app -# exported_delete = bool if we want to delete or not -# extra_flags = string extra flags to append to the exported app command -# host_home = home path ofr the host, where to search desktop files +# None # Outputs: # needed icons in /run/host/$host_home/.local/share/icons # needed desktop files in /run/host/$host_home/.local/share/applications @@ -602,14 +609,16 @@ export_application() { fi } -# List exported applications in canonical directories. +# list_exported_applications will print all exported applications in canonical directories. # the following function will list exported desktop files from this container. # # Arguments: -# none +# None +# Expected global variables: +# host_home: home path ofr the host, where to search desktop files +# CONTAINER_ID: id of the current container # Expected env variables: -# host_home = home path ofr the host, where to search desktop files -# CONTAINER_ID = id of the current container +# None # Outputs: # a list of exported apps # or error code. @@ -636,15 +645,17 @@ list_exported_applications() { done } -# List exported binaries. +# list_exported_binaries will print all exported binaries. # the following function will list exported desktop files from this container. # If no export-path is specified, it searches in the default path. # # Arguments: -# none +# None +# Expected global variables: +# dest_path: destination path where to search binaries +# CONTAINER_ID: id of the current container # Expected env variables: -# dest_path = destination path where to search binaries -# CONTAINER_ID = id of the current container +# None # Outputs: # a list of exported apps # or error code. diff --git a/distrobox-generate-entry b/distrobox-generate-entry index de1e3358ea..ced28d10d1 100755 --- a/distrobox-generate-entry +++ b/distrobox-generate-entry @@ -81,9 +81,13 @@ done [ "${verbose}" = "true" ] && verbose=1 [ "${verbose}" = "false" ] && verbose=0 -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/distrobox-host-exec b/distrobox-host-exec index 9dfc7306ac..13c3200662 100755 --- a/distrobox-host-exec +++ b/distrobox-host-exec @@ -33,9 +33,13 @@ sudo_command="" verbose=0 version="1.7.1.0" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/distrobox-init b/distrobox-init index be94756902..01efd65974 100755 --- a/distrobox-init +++ b/distrobox-init @@ -50,9 +50,14 @@ rootful=0 upgrade=0 verbose=0 version="1.7.1.0" -# Print usage to stdout. + +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { @@ -207,9 +212,13 @@ if stat /run/host/etc/shadow > /dev/null && rootful=1 fi -# Print mount flags considered "locked". +# get_locked_mount_flags will print mount flags considered "locked". # Arguments: -# src (path to the file/directory) +# src: path to the file/directory +# Expected env variables: +# None +# Expected global variables: +# None # Outputs: # Comma-separated list of locked mount flags get_locked_mount_flags() { @@ -252,6 +261,10 @@ get_locked_mount_flags() { # busybox systems, and we need the path even for broken links. # Arguments: # source file +# Expected env variables: +# None +# Expected global variables: +# None # Outputs: # original path the link is pointing init_readlink() { @@ -259,11 +272,15 @@ init_readlink() { ls -l "${1}" | grep -Eo '\->.*' | cut -d' ' -f2- | sed 's|\.\./|/|g' } -# Bind mount or error. +# mount_bind will perform a bind mount for inputs or error # Arguments: -# source_dir -# target_dir -# mount_flags -> optional +# source_dir: string what to mount +# target_dir: string where to mount +# mount_flags: list of mount flags -> optional +# Expected env variables: +# None +# Expected global variables: +# None # Outputs: # No output if all ok # Error if not diff --git a/distrobox-list b/distrobox-list index af6473d354..dad30bdcfc 100755 --- a/distrobox-list +++ b/distrobox-list @@ -88,9 +88,13 @@ if [ "$(id -ru)" -ne 0 ]; then fi [ -n "${DBX_CONTAINER_MANAGER}" ] && container_manager="${DBX_CONTAINER_MANAGER}" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/distrobox-rm b/distrobox-rm index 14182259d7..b01ec5fe96 100755 --- a/distrobox-rm +++ b/distrobox-rm @@ -107,9 +107,13 @@ fi container_name_default="my-distrobox" container_name_list="" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { @@ -278,13 +282,15 @@ if [ -z "${container_name_list}" ]; then container_name_list="${container_name_default}" fi -# Delete exported apps and bins for container to delete. +# cleanup_exports will remove exported apps and bins for container to delete. # Arguments: -# container_name = string container name +# container_name: string container name # Expected global variables: -# distrobox_flags = string additional distrobox flags to use +# distrobox_flags: string additional distrobox flags to use +# Expected env variables: +# None # Outputs: -# none. +# None cleanup_exports() { container_name="$1" IFS='ยค' @@ -314,18 +320,20 @@ cleanup_exports() { done } -# Delete containers. +# delete_container will remove input container # Arguments: -# container_name = string container name +# container_name: string container name # Expected global variables: -# container_manager = string container manager to use -# distrobox_flags = string distrobox additional flags -# non_interactive = bool non interactive mode -# force_flag = bool force mode -# rm_home = bool remove home -# verbose = bool verbose +# container_manager: string container manager to use +# distrobox_flags: string distrobox additional flags +# non_interactive: bool non interactive mode +# force_flag: bool force mode +# rm_home: bool remove home +# verbose: bool verbose +# Expected env variables: +# None # Outputs: -# none. +# None delete_container() { container_name="$1" # Inspect the container we're working with. diff --git a/distrobox-stop b/distrobox-stop index 07b2d09d7e..b617510071 100755 --- a/distrobox-stop +++ b/distrobox-stop @@ -102,9 +102,13 @@ fi [ -n "${DBX_SUDO_PROGRAM}" ] && distrobox_sudo_program="${DBX_SUDO_PROGRAM}" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/distrobox-upgrade b/distrobox-upgrade index 3c5237f9be..f9d86578af 100755 --- a/distrobox-upgrade +++ b/distrobox-upgrade @@ -85,9 +85,13 @@ fi # Declare it AFTER config sourcing because we do not want a default name set. container_name="" -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None +# Expected global variables: +# version: distrobox version +# Expected env variables: +# None # Outputs: # print usage with examples. show_help() { diff --git a/install b/install index d1f73be82f..f20347b8f6 100755 --- a/install +++ b/install @@ -23,7 +23,7 @@ next=0 verbose=0 version=1.7.1.0 -# Print usage to stdout. +# show_help will print usage to stdout. # Arguments: # None # Outputs: