YunoHost/yunohost
1
0
Fork 0
mirror of https://github.com/YunoHost/yunohost.git synced 2024-09-03 20:06:10 +02:00
Code Issues Projects Releases Packages Wiki Activity

helper doc fixes : utils

Browse source
This commit is contained in:
Salamandar 2021-03-03 10:59:29 +01:00
parent 3699648265
commit 72da2ad8e3
1 changed files with 64 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

135
data/helpers.d/utils
View file

@ -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 <upstreamversion>~ynh<packageversion>
# 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 `<upstreamversion>~ynh<packageversion>`.
#
# 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 <upstreamversion>~ynh<packageversion>
# 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 `<upstreamversion>~ynh<packageversion>`.
#
# 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 <appname> --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 <X~ynhY>
# | 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() {