From 7bd5c0781aa50b7673a0a598f4997584d0f1d4f8 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Thu, 11 Jul 2019 22:50:20 +0200 Subject: [PATCH] Misc fixes for helper page --- packaging_apps_helpers.md | 246 +++++++++++++++----------------------- 1 file changed, 97 insertions(+), 149 deletions(-) diff --git a/packaging_apps_helpers.md b/packaging_apps_helpers.md index 1f97ff1b..71cb32f7 100644 --- a/packaging_apps_helpers.md +++ b/packaging_apps_helpers.md @@ -342,17 +342,13 @@
ynh_install_app_dependencies
-
Define and install dependencies with a equivs control file -This helper can/should only be called once per app
+
Define and install dependencies with a equivs control file

- Usage: ynh_install_app_dependencies dep [dep [...]] - You can give a choice between some package with this syntax : "dep1|dep2" - Example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5" - This mean in the dependence tree : dep1 & dep2 & (dep3 | dep4 | dep5) + Usage: ynh_install_app_dependencies dep [dep [...]]

@@ -361,7 +357,7 @@ This helper can/should only be called once per app
    -
  • dep : the package name to install in dependence
    • +
  • dep : the package name to install in dependence. Writing "dep3|dep4|dep5" can be used to specify alternatives. For example : dep1 dep2 "dep3|dep4|dep5" will require to install dep1 and dep 2 and (dep3 or dep4 or dep5).
@@ -374,7 +370,7 @@ This helper can/should only be called once per app

Details:

- Requires YunoHost version 2.6.4 or higher.

+ This helper can/should only be called once per app

example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"

Requires YunoHost version 2.6.4 or higher.

@@ -478,12 +474,12 @@ This helper can/should only be called once per app

Details:

- Note: this helper could be used in backup hook or in backup script inside an
app package

Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it
creates the parent destination directory

If DEST is ended by a slash it complete this path with the basename of SRC.

Example in the context of a wordpress app

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# => This line will be added into CSV file
# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf"

#Deprecated usages (maintained for retro-compatibility)
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"

Requires YunoHost version 2.4.0 or higher.

+ This helper can be used both in a system backup hook, and in an app backup script

Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it
creates the parent destination directory

If DEST is ended by a slash it complete this path with the basename of SRC.

Example in the context of a wordpress app

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# => This line will be added into CSV file
# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf"

#Deprecated usages (maintained for retro-compatibility)
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"

ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"

Requires YunoHost version 2.4.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -497,7 +493,7 @@ This helper can/should only be called once per app
ynh_restore
-
Restore all files linked to the restore hook or to the restore app script
+
Restore all files that were previously backuped in a core backup script or app backup script
@@ -519,7 +515,7 @@ This helper can/should only be called once per app

- Dude, show me the code ! + Dude, show me the code !

@@ -595,7 +591,7 @@ This helper can/should only be called once per app

- Dude, show me the code ! + Dude, show me the code !

@@ -642,7 +638,7 @@ This helper can/should only be called once per app

- Dude, show me the code ! + Dude, show me the code !

@@ -656,9 +652,7 @@ This helper can/should only be called once per app
ynh_backup_if_checksum_is_different
-
Verify the checksum and backup the file if it's different -This helper is primarily meant to allow to easily backup personalised/manually -modified config files.
+
Verify the checksum and backup the file if it's different
@@ -690,12 +684,12 @@ modified config files.

Details:

- $app should be defined when calling this helper

Requires YunoHost version 2.6.4 or higher.

+ This helper is primarily meant to allow to easily backup personalised/manually
modified config files.

Requires YunoHost version 2.6.4 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -742,7 +736,7 @@ modified config files.

- Dude, show me the code ! + Dude, show me the code !

@@ -782,7 +776,7 @@ ynh_abort_if_errors

- Dude, show me the code ! + Dude, show me the code !

@@ -822,7 +816,7 @@ ynh_abort_if_errors

- Dude, show me the code ! + Dude, show me the code !

@@ -956,14 +950,13 @@ ynh_abort_if_errors
ynh_die
-
Print a message to stderr and exit -usage: ynh_die --message=MSG [--ret_code=RETCODE]
+
Print a message to stderr and exit

- Usage: + Usage: ynh_die --message=MSG [--ret_code=RETCODE]

@@ -979,7 +972,7 @@ usage: ynh_die --message=MSG [--ret_code=RETCODE]

- Dude, show me the code ! + Dude, show me the code !

@@ -1015,7 +1008,7 @@ usage: ynh_die --message=MSG [--ret_code=RETCODE]

- Dude, show me the code ! + Dude, show me the code !

@@ -1062,7 +1055,7 @@ usage: ynh_die --message=MSG [--ret_code=RETCODE]

- Dude, show me the code ! + Dude, show me the code !

@@ -1109,7 +1102,7 @@ usage: ynh_die --message=MSG [--ret_code=RETCODE]

- Dude, show me the code ! + Dude, show me the code !

@@ -1129,10 +1122,8 @@ usage: ynh_die --message=MSG [--ret_code=RETCODE]

- Usage: ynh_exec_err command to execute -ynh_exec_err "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. -If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed. + Usage: ynh_exec_err your_command +ynh_exec_err "your_command | other_command"

@@ -1154,12 +1145,12 @@ If the command to execute uses double quotes, they have to be escaped or they wi

Details:

- Requires YunoHost version 3.2.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1179,10 +1170,8 @@ If the command to execute uses double quotes, they have to be escaped or they wi

- Usage: ynh_exec_warn command to execute -ynh_exec_warn "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. -If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed. + Usage: ynh_exec_warn your_command +ynh_exec_warn "your_command | other_command"

@@ -1204,12 +1193,12 @@ If the command to execute uses double quotes, they have to be escaped or they wi

Details:

- Requires YunoHost version 3.2.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1229,10 +1218,8 @@ If the command to execute uses double quotes, they have to be escaped or they wi

- Usage: ynh_exec_warn_less command to execute -ynh_exec_warn_less "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. -If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed. + Usage: ynh_exec_warn_less your_command +ynh_exec_warn_less "your_command | other_command"

@@ -1254,12 +1241,12 @@ If the command to execute uses double quotes, they have to be escaped or they wi

Details:

- Requires YunoHost version 3.2.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1279,10 +1266,8 @@ If the command to execute uses double quotes, they have to be escaped or they wi

- Usage: ynh_exec_quiet command to execute -ynh_exec_quiet "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. -If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed. + Usage: ynh_exec_quiet your_command +ynh_exec_quiet "your_command | other_command"

@@ -1304,12 +1289,12 @@ If the command to execute uses double quotes, they have to be escaped or they wi

Details:

- Requires YunoHost version 3.2.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1329,10 +1314,8 @@ If the command to execute uses double quotes, they have to be escaped or they wi

- Usage: ynh_exec_fully_quiet command to execute -ynh_exec_fully_quiet "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. -If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed. + Usage: ynh_exec_fully_quiet your_command +ynh_exec_fully_quiet "your_command | other_command"

@@ -1354,12 +1337,12 @@ If the command to execute uses double quotes, they have to be escaped or they wi

Details:

- Requires YunoHost version 3.2.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1379,8 +1362,7 @@ If the command to execute uses double quotes, they have to be escaped or they wi

- Usage: ynh_print_OFF -WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging. + Usage: ynh_print_OFF

@@ -1391,12 +1373,12 @@ WARNING: You should be careful with this helper, and never forget to use ynh_pri

Details:

- Requires YunoHost version 3.2.0 or higher.

+ WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging.

Requires YunoHost version 3.2.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -1432,7 +1414,7 @@ WARNING: You should be careful with this helper, and never forget to use ynh_pri

- Dude, show me the code ! + Dude, show me the code !

@@ -1444,11 +1426,11 @@ WARNING: You should be careful with this helper, and never forget to use ynh_pri
-
-
increment_progression=0
+
+
ynh_script_progression
Print a message as INFO and show progression during an app script
-
+

@@ -1492,7 +1474,7 @@ The execution time is given for the duration since the previous call. So the wei

- Dude, show me the code ! + Dude, show me the code !

@@ -1529,7 +1511,7 @@ The execution time is given for the duration since the previous call. So the wei

- Dude, show me the code ! + Dude, show me the code !

@@ -1580,7 +1562,7 @@ The execution time is given for the duration since the previous call. So the wei

- Dude, show me the code ! + Dude, show me the code !

@@ -1600,9 +1582,8 @@ The execution time is given for the duration since the previous call. So the wei

- Usage: ynh_debug_exec command to execute -ynh_debug_exec "command to execute | following command" -In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe. + Usage: ynh_debug_exec your_command +ynh_debug_exec "your_command | other_command"

@@ -1624,12 +1605,12 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

Details:

- Requires YunoHost version 3.5.0 or higher.

+ When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.5.0 or higher.

- Dude, show me the code ! + Dude, show me the code !

@@ -2390,35 +2371,6 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w -
-
-
-
export
-
N_PREFIX is the directory of n, it needs to be loaded as a environment variable.
-
-
-
-

- - Usage: - -

- - - - - -

- Dude, show me the code ! -

- -
-
- -
- - -
@@ -2465,9 +2417,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Usage: ynh_install_nodejs --nodejs_version=nodejs_version - If possible, prefer to use major version number (e.g. 8 instead of 8.10.0). - The crontab will handle the update of minor versions when needed. + Usage: ynh_install_nodejs --nodejs_version=nodejs_version

@@ -2476,7 +2426,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w
    -
  • -n, --nodejs_version : Version of node to install.
    • +
  • -n, --nodejs_version : Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed.
@@ -2494,7 +2444,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2530,7 +2480,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2668,10 +2618,22 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w -

- Example: ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;" example: ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql -

+

+ Examples:

    + + + ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;" + +
    + + + ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql + +
    + +
+

@@ -2682,7 +2644,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2733,7 +2695,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2784,7 +2746,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2839,7 +2801,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2879,7 +2841,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2919,7 +2881,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -2974,7 +2936,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -3018,7 +2980,7 @@ In case of use of pipes, you have to use double quotes. Otherwise, this helper w

- Dude, show me the code ! + Dude, show me the code !

@@ -3048,7 +3010,7 @@ Please always call this script in install and restore scripts

- Dude, show me the code ! + Dude, show me the code !

@@ -3912,11 +3874,7 @@ Please always call this script in install and restore scripts

- Usage: ynh_systemd_action [-n service_name] [-a action] [ [-l "line to match"] [-p log_path] [-t timeout] [-e length] ] - If not defined it don't wait until the service is completely started. - WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your - `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure - of the script. The script will then hang forever. + Usage: ynh_systemd_action [-n service_name] [-a action] [ [-l "line to match"] [-p log_path] [-t timeout] [-e length] ]

@@ -3933,7 +3891,7 @@ Please always call this script in install and restore scripts -
  • -l, --line_match= : Line to match - The line to find in the log to attest the service have finished to boot.
    • +
  • -l, --line_match= : Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started. WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure of the script. The script will then hang forever.
    • @@ -3956,7 +3914,7 @@ Please always call this script in install and restore scripts

    - Dude, show me the code ! + Dude, show me the code !

    @@ -3986,7 +3944,7 @@ Please always call this script in install and restore scripts

    - Dude, show me the code ! + Dude, show me the code !

    @@ -4762,11 +4720,7 @@ Please always call this script in install and restore scripts
    ynh_app_upstream_version
    -
    Read the upstream version from the manifest -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
    +
    Read the upstream version from the manifest
    @@ -4794,12 +4748,12 @@ In the last example it return 4.3-2

    Details:

    - Requires YunoHost version 3.5.0 or higher.

    + 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

    Requires YunoHost version 3.5.0 or higher.

    - Dude, show me the code ! + Dude, show me the code !

    @@ -4813,11 +4767,7 @@ In the last example it return 4.3-2
    ynh_app_package_version
    -
    Read package version from the manifest -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
    +
    Read package version from the manifest
    @@ -4845,12 +4795,12 @@ In the last example it return 3

    Details:

    - Requires YunoHost version 3.5.0 or higher.

    + 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

    Requires YunoHost version 3.5.0 or higher.

    - Dude, show me the code ! + Dude, show me the code !

    @@ -4864,9 +4814,7 @@ In the last example it return 3
    ynh_check_app_version_changed
    -
    Checks the app version to upgrade with the existing app version and returns: -- UPGRADE_APP if the upstream app version has changed -- UPGRADE_PACKAGE if only the YunoHost package has changed
    +
    Checks the app version to upgrade with the existing app version and returns:
    @@ -4883,12 +4831,12 @@ In the last example it return 3

    Details:

    - It stops the current script without error if the package is up-to-date

    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 set the variable YNH_FORCE_UPGRADE before.
    example: sudo YNH_FORCE_UPGRADE=1 yunohost app upgrade MyApp

    Requires YunoHost version 3.5.0 or higher.

    + - UPGRADE_APP if the upstream app version has changed
    - UPGRADE_PACKAGE if only the YunoHost package has changed

    It stops the current script without error if the package is up-to-date

    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 set the variable YNH_FORCE_UPGRADE before.
    example: sudo YNH_FORCE_UPGRADE=1 yunohost app upgrade MyApp

    Requires YunoHost version 3.5.0 or higher.

    - Dude, show me the code ! + Dude, show me the code !