From 72da2ad8e3a40f2237f37af911eb069b14b356aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Wed, 3 Mar 2021 10:59:29 +0100 Subject: [PATCH] helper doc fixes : utils --- data/helpers.d/utils | 135 ++++++++++++++++++++----------------------- 1 file changed, 64 insertions(+), 71 deletions(-) diff --git a/data/helpers.d/utils b/data/helpers.d/utils index 487ec41db..28b1e5a1d 100644 --- a/data/helpers.d/utils +++ b/data/helpers.d/utils @@ -48,9 +48,8 @@ ynh_exit_properly () { # usage: ynh_abort_if_errors # # This configure the rest of the script execution such that, if an error occurs -# or if an empty variable is used, the execution of the script stops -# immediately and a call to `ynh_clean_setup` is triggered if it has been -# defined by your script. +# or if an empty variable is used, the execution of the script stops immediately +# and a call to `ynh_clean_setup` is triggered if it has been defined by your script. # # Requires YunoHost version 2.6.4 or higher. ynh_abort_if_errors () { @@ -63,45 +62,37 @@ ynh_abort_if_errors () { # # usage: ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] # | arg: -d, --dest_dir= - Directory where to setup sources -# | arg: -s, --source_id= - Name of the app, if the package contains more than one app +# | arg: -s, --source_id= - Name of the source, defaults to `app` # -# The file conf/app.src need to contains: +# This helper will read `conf/${source_id}.src`, download and install the sources. # +# The src file need to contains: +# ``` # SOURCE_URL=Address to download the app archive # SOURCE_SUM=Control sum -# # (Optional) Program to check the integrity (sha256sum, md5sum...) -# # default: sha256 +# # (Optional) Program to check the integrity (sha256sum, md5sum...). Default: sha256 # SOURCE_SUM_PRG=sha256 -# # (Optional) Archive format -# # default: tar.gz +# # (Optional) Archive format. Default: tar.gz # SOURCE_FORMAT=tar.gz -# # (Optional) Put false if sources are directly in the archive root -# # default: true -# # Instead of true, SOURCE_IN_SUBDIR could be the number of sub directories -# # to remove. +# # (Optional) Put false if sources are directly in the archive root. Default: true +# # Instead of true, SOURCE_IN_SUBDIR could be the number of sub directories to remove. # SOURCE_IN_SUBDIR=false -# # (Optionnal) Name of the local archive (offline setup support) -# # default: ${src_id}.${src_format} +# # (Optionnal) Name of the local archive (offline setup support). Default: ${src_id}.${src_format} # SOURCE_FILENAME=example.tar.gz -# # (Optional) If it set as false don't extract the source. +# # (Optional) If it set as false don't extract the source. Default: true # # (Useful to get a debian package or a python wheel.) -# # default: true # SOURCE_EXTRACT=(true|false) +# ``` # -# Details: -# This helper downloads sources from SOURCE_URL if there is no local source -# archive in /opt/yunohost-apps-src/APP_ID/SOURCE_FILENAME -# -# Next, it checks the integrity with "SOURCE_SUM_PRG -c --status" command. -# -# If it's ok, the source archive will be uncompressed in $dest_dir. If the -# SOURCE_IN_SUBDIR is true, the first level directory of the archive will be -# removed. -# If SOURCE_IN_SUBDIR is a numeric value, 2 for example, the 2 first level -# directories will be removed -# -# Finally, patches named sources/patches/${src_id}-*.patch and extra files in -# sources/extra_files/$src_id will be applied to dest_dir +# The helper will: +# - Check if there is a local source archive in `/opt/yunohost-apps-src/$APP_ID/$SOURCE_FILENAME` +# - Download `$SOURCE_URL` if there is no local archive +# - Check the integrity with `$SOURCE_SUM_PRG -c --status` +# - Uncompress the archive to `$dest_dir`. +# - If `$SOURCE_IN_SUBDIR` is true, the first level directory of the archive will be removed. +# - If `$SOURCE_IN_SUBDIR` is a numeric value, the N first level directories will be removed. +# - Patches named `sources/patches/${src_id}-*.patch` will be applied to `$dest_dir` +# - Extra files in `sources/extra_files/$src_id` will be copied to dest_dir # # Requires YunoHost version 2.6.4 or higher. ynh_setup_source () { @@ -211,17 +202,17 @@ ynh_setup_source () { # Curl abstraction to help with POST requests to local pages (such as installation forms) # -# example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2" -# # usage: ynh_local_curl "page_uri" "key1=value1" "key2=value2" ... -# | arg: page_uri - Path (relative to $path_url) of the page where POST data will be sent +# | arg: page_uri - Path (relative to `$path_url`) of the page where POST data will be sent # | arg: key1=value1 - (Optionnal) POST key and corresponding value # | arg: key2=value2 - (Optionnal) Another POST key and corresponding value # | arg: ... - (Optionnal) More POST keys and values # +# example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2" +# # For multiple calls, cookies are persisted between each call for the same app # -# $domain and $path_url should be defined externally (and correspond to the domain.tld and the /path (of the app?)) +# `$domain` and `$path_url` should be defined externally (and correspond to the domain.tld and the /path (of the app?)) # # Requires YunoHost version 2.6.4 or higher. ynh_local_curl () { @@ -250,7 +241,7 @@ ynh_local_curl () { # Wait untils nginx has fully reloaded (avoid curl fail with http2) sleep 2 - + local cookiefile=/tmp/ynh-$app-cookie.txt touch $cookiefile chown root $cookiefile @@ -262,20 +253,22 @@ ynh_local_curl () { # Create a dedicated config file from a template # +# usage: ynh_add_config --template="template" --destination="destination" +# | arg: -t, --template= - Template config file to use +# | arg: -d, --destination= - Destination of the config file +# # examples: # ynh_add_config --template=".env" --destination="$final_path/.env" # ynh_add_config --template="../conf/.env" --destination="$final_path/.env" # ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf" # -# usage: ynh_add_config --template="template" --destination="destination" -# | arg: -t, --template= - Template config file to use -# | arg: -d, --destination= - Destination of the config file -# # The template can be by default the name of a file in the conf directory -# of a YunoHost Package, a relative path or an absolute path -# The helper will use the template $template to generate a config file -# $destination by replacing the following keywords with global variables +# of a YunoHost Package, a relative path or an absolute path. +# +# The helper will use the template `template` to generate a config file +# `destination` by replacing the following keywords with global variables # that should be defined before calling this helper : +# ``` # __PATH__ by $path_url # __NAME__ by $app # __NAMETOCHANGE__ by $app @@ -283,15 +276,18 @@ ynh_local_curl () { # __FINALPATH__ by $final_path # __PHPVERSION__ by $YNH_PHP_VERSION # __YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH -# +# ``` # And any dynamic variables that should be defined before calling this helper like: +# ``` # __DOMAIN__ by $domain # __APP__ by $app # __VAR_1__ by $var_1 # __VAR_2__ by $var_2 +# ``` # # The helper will verify the checksum and backup the destination file # if it's different before applying the new template. +# # And it will calculate and store the destination file checksum # into the app settings when configuration is done. # @@ -556,16 +552,17 @@ ynh_read_manifest () { jq ".$manifest_key" "$manifest" --raw-output } -# Read the upstream version from the manifest, or from the env variable $YNH_APP_MANIFEST_VERSION if not given +# Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION` # # usage: ynh_app_upstream_version [--manifest="manifest.json"] # | arg: -m, --manifest= - Path of the manifest to read # | ret: the version number of the upstream app # -# The version number in the manifest is defined by ~ynh -# For example : 4.3-2~ynh3 -# This include the number before ~ynh -# In the last example it return 4.3-2 +# If the `manifest` is not specified, the envvar `$YNH_APP_MANIFEST_VERSION` will be used. +# +# The version number in the manifest is defined by `~ynh`. +# +# For example, if the manifest contains `4.3-2~ynh3` the function will return `4.3-2` # # Requires YunoHost version 3.5.0 or higher. ynh_app_upstream_version () { @@ -593,10 +590,9 @@ ynh_app_upstream_version () { # | arg: -m, --manifest= - Path of the manifest to read # | ret: the version number of the package # -# The version number in the manifest is defined by ~ynh -# For example : 4.3-2~ynh3 -# This include the number after ~ynh -# In the last example it return 3 +# The version number in the manifest is defined by `~ynh`. +# +# For example, if the manifest contains `4.3-2~ynh3` the function will return `3` # # Requires YunoHost version 3.5.0 or higher. ynh_app_package_version () { @@ -613,18 +609,16 @@ ynh_app_package_version () { # Checks the app version to upgrade with the existing app version and returns: # -# - UPGRADE_PACKAGE if only the YunoHost package has changed -# - UPGRADE_APP otherwise +# usage: ynh_check_app_version_changed +# | ret: `UPGRADE_APP` if the upstream version changed, `UPGRADE_PACKAGE` otherwise. # # This helper should be used to avoid an upgrade of an app, or the upstream part # of it, when it's not needed # -# To force an upgrade, even if the package is up to date, -# you have to use the parameter --force (or -F). -# example: sudo yunohost app upgrade MyApp --force -# -# usage: ynh_check_app_version_changed -# +# You can force an upgrade, even if the package is up to date, with the `--force` (or `-F`) argument : +# ``` +# sudo yunohost app upgrade --force +# ``` # Requires YunoHost version 3.5.0 or higher. ynh_check_app_version_changed () { local return_value=${YNH_APP_UPGRADE_TYPE} @@ -638,24 +632,23 @@ ynh_check_app_version_changed () { } # Compare the current package version against another version given as an argument. -# This is really useful when we need to do some actions only for some old package versions. +# +# usage: ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version +# | arg: --comparison - Comparison type. Could be : `lt` (lower than), `le` (lower or equal), `eq` (equal), `ne` (not equal), `ge` (greater or equal), `gt` (greater than) +# | arg: --version - The version to compare. Need to be a version in the yunohost package version type (like `2.3.1~ynh4`) +# | ret: 0 if the evaluation is true, 1 if false. # # example: ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 -# This example will check if the installed version is lower than (lt) the version 2.3.2~ynh1 # -# Generally you might probably use it as follow in the upgrade script +# This helper is usually used when we need to do some actions only for some old package versions. # +# Generally you might probably use it as follow in the upgrade script : +# ``` # if ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 # then # # Do something that is needed for the package version older than 2.3.2~ynh1 # fi -# -# usage: ynh_compare_current_package_version --comparison lt|le|eq|ne|ge|gt -# | arg: --comparison - Comparison type. Could be : lt (lower than), le (lower or equal), -# | eq (equal), ne (not equal), ge (greater or equal), gt (greater than) -# | arg: --version - The version to compare. Need to be a version in the yunohost package version type (like 2.3.1~ynh4) -# -# Return 0 if the evaluation is true. 1 if false. +# ``` # # Requires YunoHost version 3.8.0 or higher. ynh_compare_current_package_version() {