From d9c97062c181ef43d14c6a54e419586b72bba7d4 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Wed, 8 Jan 2025 15:07:24 +0100 Subject: [PATCH] revise landing page with overview of changes in EasyBuild v5.0 --- .../backwards-incompatible-changes.md | 57 ----------- .../changes-in-default-configuration.md | 29 +++--- docs/easybuild-v5/deprecated-functionality.md | 11 +-- docs/easybuild-v5/enhancements.md | 10 +- docs/easybuild-v5/index.md | 94 +++++++++++++++++-- docs/easybuild-v5/overview-of-changes.md | 29 ------ docs/easybuild-v5/policies.md | 5 - docs/easybuild-v5/python36-required.md | 28 ++++++ docs/easybuild-v5/removed-functionality.md | 25 +++++ docs/easybuild-v5/run_shell_cmd.md | 2 +- docs/python-2-3-compatibility.md | 4 +- docs/roles/contributors.md | 2 +- docs/roles/developers.md | 2 +- docs/roles/end-users.md | 2 +- docs/roles/maintainers.md | 2 +- docs/roles/user-support.md | 2 +- mkdocs.yml | 4 + 17 files changed, 178 insertions(+), 130 deletions(-) delete mode 100644 docs/easybuild-v5/backwards-incompatible-changes.md delete mode 100644 docs/easybuild-v5/overview-of-changes.md delete mode 100644 docs/easybuild-v5/policies.md create mode 100644 docs/easybuild-v5/python36-required.md create mode 100644 docs/easybuild-v5/removed-functionality.md diff --git a/docs/easybuild-v5/backwards-incompatible-changes.md b/docs/easybuild-v5/backwards-incompatible-changes.md deleted file mode 100644 index c39fa5be9..000000000 --- a/docs/easybuild-v5/backwards-incompatible-changes.md +++ /dev/null @@ -1,57 +0,0 @@ -# Backwards-incompatible changes in EasyBuild v5.0 - -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* - -A number of *backwards-incompatible* changes are being made in EasyBuild v5.0: - -* [Support for Python 2.7 is removed, Python 3.6+ is required][py36] -* [Deprecated EasyBuild bootstrap script is removed][bootstrap_script] -* [Experimental support for the `.yeb` easyconfig format is removed][yeb] - ---- - -## Support for Python 2.7 is removed, Python 3.6+ is required {: #py36 } - -EasyBuild 5.0 requires Python >= 3.6 to run. - -Running EasyBuild with Python 2.7 or a Python 3 version older than Python 3.6 is no longer supported. - -Trying to run EasyBuild with a Python version that is too old will result in an error: - -```log -ERROR: No compatible 'python' command found via $PATH (EasyBuild requires Python 3.6+) -``` - -Python 2.7 has been [end-of-life since 1 Jan 2020](https://www.python.org/doc/sunset-python-2), -and dropping compatibility with Python 2.7 and Python 3.5 enabled some significant code cleanup -(see [easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)). - -The [results of the 6th EasyBuild User Survey (2022)](https://easybuild.io/user_survey) show that the impact of -this breaking change on the EasyBuild community should be very limited, since: - -* Only ~13% of survey participants were still running EasyBuild on top of Python 2.7; -* No survey participants reported using Python 3.5; -* Over 85% of survey participants reported using Python 3.6, or a more recent version of Python 3; -* Only 3 out of 118 survey participants (~2.5%) reported that dropping support for running EasyBuild - on top of Python 2 would be *problematic* for them; - -Along with actively removing code that was only required to retain compatibility with Python 2.7 or 3.5, -the `easybuild.tools.py2vs3` module that was introduced to facilitate supporting both Python 2.7 and Python 3 -has been deprecated (see also [here](deprecated-functionality.md#py2vs3)). - ---- - -## Deprecated EasyBuild bootstrap script is removed {: #bootstrap_script } - -The EasyBuild bootstrap script has been removed (see [easybuild-framework PR #4233](https://github.com/easybuilders/easybuild-framework/pull/4233)). - -Please see the [installation page](../installation.md) for the suggested methods for installing EasyBuild. - ---- - -## Experimental support for the .yeb easyconfig format is removed {: #yeb } - -Support for the experimental `.yeb` easyconfig format has been removed (see [easybuild-framework PR #4237](https://github.com/easybuilders/easybuild-framework/pull/4237)). - -This format allowed easyconfigs to be specified in YAML. However, there has been no recent development of this -format and little suggestion that anyone was using it at all. diff --git a/docs/easybuild-v5/changes-in-default-configuration.md b/docs/easybuild-v5/changes-in-default-configuration.md index e71551c20..8f0cfc41d 100644 --- a/docs/easybuild-v5/changes-in-default-configuration.md +++ b/docs/easybuild-v5/changes-in-default-configuration.md @@ -1,17 +1,17 @@ # Changes in default configuration in EasyBuild v5.0 -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* +*(for a full overview of changes in EasyBuild v5.0, see [here](index.md))* -Various changes in default configuration included in EasyBuild v5.0, including: +The default value for several EasyBuild configuration settings has been changed in EasyBuild v5.0: -* [Enable RPATH linking by default][rpath] -* [Enable `--trace` by default][trace] +- [RPATH linking is enabled by default (`--rpath`)](rpath) +- [Trace output is enabled by default (`--trace`)](trace) --- ## Enable RPATH linking by default {: #rpath } -[RPATH linking][rpath_support] is enabled by default in EasyBuild v5.0 (see [easybuild-framework PR #4448](https://github.com/easybuilders/easybuild-framework/pull/4448)). +[RPATH linking][rpath_support] is enabled by default in EasyBuild v5.0. The benefits for enabling RPATH are explained in [Why RPATH?][rpath_support_why]. @@ -20,31 +20,34 @@ will continue to be appended by the environment module files EasyBuild generates unless it is configured to filter these variables (via `--filter-env-vars`, see also [Relation to `$LD_LIBRARY_PATH`][rpath_support_LD_LIBRARY_PATH]). +The RPATH part of the EasyBuild sanity check has been relaxed (by default, +to allow for installing software that uses RPATH linking on top of existing software installations that do not use RPATH. +The RPATH sanity check can be made strict again via the `strict-rpath-sanity-check` EasyBuild configuration setting. + To disable RPATH linking, either: -* Use the `--disable-rpath` command line option; -* Set the `$EASYBUILD_DISABLE_RPATH` environment variable; -* Disable RPATH linking in an EasyBuild [configuration file](../configuration.md#configuration_file): +- Use the `--disable-rpath` command line option; +- Set the `$EASYBUILD_DISABLE_RPATH` environment variable; +- Disable RPATH linking in an EasyBuild [configuration file](../configuration.md#configuration_file): ``` ini [override] rpath=0 ``` - --- ## Enable `--trace` by default {: #trace } -The [`--trace` option](../tracing-progress.md) is enabled by default (see [easybuild-framework PR #4250](https://github.com/easybuilders/easybuild-framework/pull/4250)). +The [`--trace` option](../tracing-progress.md) is enabled by default. This makes the output produced by the `eb` command more informative, by providing more information about what's going on in the background. To disable trace output, either: -* Use the `--disable-trace` command line option; -* Set the `$EASYBUILD_DISABLE_TRACE` environment variable; -* Disable trace mode in a [configuration file](../configuration.md#configuration_file): +- Use the `--disable-trace` command line option; +- Set the `$EASYBUILD_DISABLE_TRACE` environment variable; +- Disable trace mode in a [configuration file](../configuration.md#configuration_file): ``` ini [override] diff --git a/docs/easybuild-v5/deprecated-functionality.md b/docs/easybuild-v5/deprecated-functionality.md index ffb3df187..714e89533 100644 --- a/docs/easybuild-v5/deprecated-functionality.md +++ b/docs/easybuild-v5/deprecated-functionality.md @@ -1,11 +1,11 @@ # Deprecated functionality in EasyBuild v5.0 -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* +*(for a full overview of changes in EasyBuild v5.0, see [here](index.md))* Some functionality is being deprecated in EasyBuild v5.0, and will no longer be supported in EasyBuild v6.0: -* [`run_cmd` and `run_cmd_qa` functions][run_cmd] -* [`easybuild.tools.py2vs3` module][py2vs3] +- [`run_cmd` and `run_cmd_qa` functions][run_cmd] +- [`easybuild.tools.py2vs3` module][py2vs3] If you trigger any deprecated functionality when using EasyBuild v5.0, a warning message will be printed. @@ -13,7 +13,8 @@ If you trigger any deprecated functionality when using EasyBuild v5.0, a warning ## `run_cmd` and `run_cmd_qa` functions {: #run_cmd } -The `run_cmd` and `run_cmd_qa` functions will be deprecated. +The `run_cmd` and `run_cmd_qa` functions have been deprecated, +and are scheduled to be removed in EasyBuild v6.0. You should migrate to the new [`run_shell_cmd`](run_shell_cmd.md) function instead. @@ -22,8 +23,6 @@ You should migrate to the new [`run_shell_cmd`](run_shell_cmd.md) function inste ## `easybuild.tools.py2vs3` module {: #py2vs3 } -[easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229) - The following table lists the changes required to replace imports from the the `py2vs3` module. | `from easybuild.tools.py2vs3 import ...` | Replacement | diff --git a/docs/easybuild-v5/enhancements.md b/docs/easybuild-v5/enhancements.md index 4c5be7c85..efb3223f4 100644 --- a/docs/easybuild-v5/enhancements.md +++ b/docs/easybuild-v5/enhancements.md @@ -1,12 +1,12 @@ # Enhancements in EasyBuild v5.0 -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* +*(for a full overview of changes in EasyBuild v5.0, see [here](index.md))* Various significant enhancements are included in EasyBuild v5.0, including: -* [`run_shell_cmd` function][run_shell_cmd] -* [Granular exit codes][granular_exit_codes] -* [Reproducible tarballs][reproducible_tarballs] +- [`run_shell_cmd` function][run_shell_cmd] +- [Granular exit codes][granular_exit_codes] +- [Reproducible tarballs][reproducible_tarballs] --- @@ -14,6 +14,7 @@ Various significant enhancements are included in EasyBuild v5.0, including: See dedicated page on the new [`run_shell_cmd` function](run_shell_cmd.md). + ## Granular exit codes { : #granular_exit_codes } EasyBuild v5 now uses a range of ~50 exit codes instead of just 0 for normal @@ -27,6 +28,7 @@ EasyBuild will always return its own exit codes on termination. Other exit codes from external processes executed through `run_shell_cmd` or HTTP response status codes are reported in the corresponding logs. + ## Reproducible tarballs { : #reproducible_tarballs} EasyBuild can now generate reproducible tarballs of sources cloned from Git diff --git a/docs/easybuild-v5/index.md b/docs/easybuild-v5/index.md index c7b05f915..dbce72cf2 100644 --- a/docs/easybuild-v5/index.md +++ b/docs/easybuild-v5/index.md @@ -1,13 +1,91 @@ # EasyBuild v5.0 +A high-level overview of changes in EasyBuild version 5.0 is listed below. + +Click on a particular item for more information. + +!!! warning "EasyBuild version 5.0.0 is not released yet" + + EasyBuild v5.0.0 is still under active development via the `5.0.x` branches in the EasyBuild GitHub repositories. + + Shortly before the release of EasyBuild v5.0.0, the `5.0.x` branches will be collapsed in the corresponding + `develop` branches, and the `5.0.x` branches will then only be used as a staging area for additional EasyBuild + v5.0.x releases. + + The overview below is known to be incomplete, and will be gradually completed as we approach + the release of EasyBuild v5.0.0. + +--- + +## Breaking changes {: #breaking-changes } + +EasyBuild v5.0 includes a number of backwards-incompatible changes: + +- [Python 3.6+ is required to run EasyBuild v5.0.0](python36-required.md) + +See also the [overview of removed functionality](#removed-functionality) below. + + +--- + +## Changes in default configuration + +The default value for several EasyBuild configuration settings has been changed in EasyBuild v5.0: + +- [RPATH linking is enabled by default (`--rpath`)](changes-in-default-configuration.md#rpath) +- [Trace output is enabled by default (`--trace`)](changes-in-default-configuration.md#trace) + + +--- + +## Enhancements + +Various significant enhancements are included in EasyBuild v5.0, including: + +- [`run_shell_cmd` function](run_shell_cmd.md) +- [Granular exit codes](enhancements.md#granular_exit_codes) +- [Reproducible tarballs](enhancements.md#reproducible_tarballs) + + +--- + +## Removed functionality {: #removed-functionality } + +Functionality that was deprecated a while ago has been removed: + +- [EasyBuild bootstrap script is removed](removed-functionality.md#bootstrap_script) +- [Experimental support for `.yeb` easyconfig format is removed](removed-functionality.md#yeb) + + +--- + +## Deprecated functionality {: #deprecated-functionality } + +Some functionality is being deprecated in EasyBuild v5.0, and will no longer be supported in EasyBuild v6.0: + +- [`run_cmd` and `run_cmd_qa` functions](deprecated-functionality.md#run_cmd) +- [`easybuild.tools.py2vs3` module](deprecated-functionality.md#py2vs3) + + +--- + +## Other changes + +*(coming soon)* + + +--- + +## FAQ + +*(coming soon)* + + +--- + +## Other links - [Beta releases and release candidates](release-candidates.md) -- [Overview of changes](overview-of-changes.md) - - [Backwards-incompatible changes](backwards-incompatible-changes.md) - - [Changes in default configuration](changes-in-default-configuration.md) - - [Enhancements](enhancements.md) - - [`run_shell_cmd` function](run_shell_cmd.md) - - [Deprecated functionality](deprecated-functionality.md) - - [Policies](policies.md) -- [GitHub Project board](https://github.com/orgs/easybuilders/projects/18) +- [GitHub Project board for EasyBuild v5.0](https://github.com/orgs/easybuilders/projects/18) - [Talk on EasyBuild 5.0 at EasyBuild User Meeting 2023](https://easybuild.io/eum23/#easybuild5) +- [Talk on EasyBuild 5.0 at EasyBuild User Meeting 2024](https://easybuild.io/eum24/#eb5) diff --git a/docs/easybuild-v5/overview-of-changes.md b/docs/easybuild-v5/overview-of-changes.md deleted file mode 100644 index 9ab66bda3..000000000 --- a/docs/easybuild-v5/overview-of-changes.md +++ /dev/null @@ -1,29 +0,0 @@ -# Overview of changes in EasyBuild version 5.0 - -!!! warning - EasyBuild 5.0 is currently still under development, via the `5.0.x` branches in the EasyBuild GitHub repositories. - - We intend to update this section of the documentation regularly as the planned changes are being implemented. - -This page provides a concise overview of the most prominent changes in EasyBuild version 5.0, -which can be categorized as: - -* [Enhancements](enhancements.md) -* [Changes in default configuration](changes-in-default-configuration.md) -* [Backward-incompatible changes](backwards-incompatible-changes.md) -* [Deprecated functionality](deprecated-functionality.md) -* [Policies](policies.md) - -For in-depth details on a particular change, see the pull requests that are linked -from each of the subsections linked above. - -At the [EasyBuild User Meeting 2023](https://easybuild.io/eum23), Simon Branford set out the -[roadmap for EasyBuild v5.0](https://easybuild.io/eum23/#easybuild5). - -To track the progress on the development of EasyBuild v5.0, -see the [GitHub Project board for EasyBuild v5.0](https://github.com/orgs/easybuilders/projects/18). - -!!! note - This section covers the major planned changes. - - It is not intended to be a *complete* list of all changes that are planned for EasyBuild v5.0. diff --git a/docs/easybuild-v5/policies.md b/docs/easybuild-v5/policies.md deleted file mode 100644 index 773f922c4..000000000 --- a/docs/easybuild-v5/policies.md +++ /dev/null @@ -1,5 +0,0 @@ -# Policies related to EasyBuild v5.0 - -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* - -Starting with EasyBuild v5.0, we will enforce the new [toolchain support policy](../policies/toolchains.md). diff --git a/docs/easybuild-v5/python36-required.md b/docs/easybuild-v5/python36-required.md new file mode 100644 index 000000000..90c4dbce9 --- /dev/null +++ b/docs/easybuild-v5/python36-required.md @@ -0,0 +1,28 @@ +# Python 3.6+ is required to run EasyBuild v5.0.0 + +EasyBuild 5.0 requires Python >= 3.6 to run. + +Running EasyBuild with Python 2.7 or a Python 3 version older than Python 3.6 is no longer supported. + +Trying to run EasyBuild with a Python version that is too old will result in an error: + +```log +ERROR: No compatible 'python' command found via $PATH (EasyBuild requires Python 3.6+) +``` + +Python 2.7 has been [end-of-life since 1 Jan 2020](https://www.python.org/doc/sunset-python-2), +and dropping compatibility with Python 2.7 and Python 3.5 enabled some significant code cleanup +(see [easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)). + +The [results of the 6th EasyBuild User Survey (2022)](https://easybuild.io/user_survey) show that the impact of +this breaking change on the EasyBuild community should be very limited, since: + +- Only ~13% of survey participants were still running EasyBuild on top of Python 2.7; +- No survey participants reported using Python 3.5; +- Over 85% of survey participants reported using Python 3.6, or a more recent version of Python 3; +- Only 3 out of 118 survey participants (~2.5%) reported that dropping support for running EasyBuild + on top of Python 2 would be *problematic* for them; + +Along with actively removing code that was only required to retain compatibility with Python 2.7 or 3.5, +the `easybuild.tools.py2vs3` module that was introduced to facilitate supporting both Python 2.7 and Python 3 +has been deprecated (see also [here](deprecated-functionality.md#py2vs3)). diff --git a/docs/easybuild-v5/removed-functionality.md b/docs/easybuild-v5/removed-functionality.md new file mode 100644 index 000000000..4d79d94d0 --- /dev/null +++ b/docs/easybuild-v5/removed-functionality.md @@ -0,0 +1,25 @@ +# Removed functionality in EasyBuild v5.0 + +*(for a full overview of changes in EasyBuild v5.0, see [here](index.md))* + +Functionality that was deprecated a while ago has been removed: + +- [EasyBuild bootstrap script is removed][bootstrap_script] +- [Experimental support for `.yeb` easyconfig format is removed][yeb] + +--- + +## Deprecated EasyBuild bootstrap script is removed {: #bootstrap_script } + +The EasyBuild bootstrap script has been removed (see [easybuild-framework PR #4233](https://github.com/easybuilders/easybuild-framework/pull/4233)). + +Please see the [installation page](../installation.md) for the suggested methods for installing EasyBuild. + +--- + +## Experimental support for `.yeb` easyconfig format is removed {: #yeb } + +Support for the experimental `.yeb` easyconfig format has been removed (see [easybuild-framework PR #4237](https://github.com/easybuilders/easybuild-framework/pull/4237)). + +This format allowed easyconfigs to be specified in YAML. However, there has been no recent development of this +format and little suggestion that anyone was using it at all. diff --git a/docs/easybuild-v5/run_shell_cmd.md b/docs/easybuild-v5/run_shell_cmd.md index b6ce7fdd0..5ed11cd2a 100644 --- a/docs/easybuild-v5/run_shell_cmd.md +++ b/docs/easybuild-v5/run_shell_cmd.md @@ -1,6 +1,6 @@ # `run_shell_cmd` function -*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))* +*(for a full overview of changes in EasyBuild v5.0, see [here](index.md))* In EasyBuild v5.0, a new function named `run_shell_cmd` is introduced to run shell commands. diff --git a/docs/python-2-3-compatibility.md b/docs/python-2-3-compatibility.md index e630b9812..2c8634aa6 100644 --- a/docs/python-2-3-compatibility.md +++ b/docs/python-2-3-compatibility.md @@ -5,8 +5,8 @@ compatible with both Python versions 2 and 3. More specifically, the following Python versions are currently supported: - Python 2.6.x (support was removed in EasyBuild v4.4.0) -- Python 2.7.x ([support will be removed in EasyBuild v5.0.0](easybuild-v5/overview-of-changes.md)) -- Python 3.5.x ([support will be removed in EasyBuild v5.0.0](easybuild-v5/overview-of-changes.md)) +- Python 2.7.x ([support will be removed in EasyBuild v5.0.0](easybuild-v5/index.md)) +- Python 3.5.x ([support will be removed in EasyBuild v5.0.0](easybuild-v5/index.md)) - Python 3.6.x - Python 3.7.x - Python 3.8.x (requires EasyBuild v4.1.0) diff --git a/docs/roles/contributors.md b/docs/roles/contributors.md index 36188c807..17a6a3b88 100644 --- a/docs/roles/contributors.md +++ b/docs/roles/contributors.md @@ -4,7 +4,7 @@ Changes coming in EasyBuild 5.0 relevant to EasyBuild contributors. -*(for a complete overview, see [here](../easybuild-v5/overview-of-changes.md))* +*(for a complete overview, see [here](../easybuild-v5/index.md))* ### Framework & easyblocks diff --git a/docs/roles/developers.md b/docs/roles/developers.md index 523500791..4f26b79fb 100644 --- a/docs/roles/developers.md +++ b/docs/roles/developers.md @@ -4,6 +4,6 @@ Changes coming in EasyBuild 5.0 relevant to EasyBuild developers. -*(for a complete overview, see [here](../easybuild-v5/overview-of-changes.md))* +*(for a complete overview, see [here](../easybuild-v5/index.md))* ... diff --git a/docs/roles/end-users.md b/docs/roles/end-users.md index 96b5cddc0..3722e0a96 100644 --- a/docs/roles/end-users.md +++ b/docs/roles/end-users.md @@ -4,7 +4,7 @@ Changes coming in EasyBuild 5.0 relevant to EasyBuild users. -*(for a complete overview, see [here](../easybuild-v5/overview-of-changes.md))* +*(for a complete overview, see [here](../easybuild-v5/index.md))* ... diff --git a/docs/roles/maintainers.md b/docs/roles/maintainers.md index ce97db490..8d70c7963 100644 --- a/docs/roles/maintainers.md +++ b/docs/roles/maintainers.md @@ -4,6 +4,6 @@ Changes coming in EasyBuild 5.0 relevant to EasyBuild maintainers. -*(for a complete overview, see [here](../easybuild-v5/overview-of-changes.md))* +*(for a complete overview, see [here](../easybuild-v5/index.md))* * ... diff --git a/docs/roles/user-support.md b/docs/roles/user-support.md index b4b4bfc76..59a542389 100644 --- a/docs/roles/user-support.md +++ b/docs/roles/user-support.md @@ -4,6 +4,6 @@ Changes coming in EasyBuild 5.0 relevant to user support teams. -*(for a complete overview, see [here](../easybuild-v5/overview-of-changes.md))* +*(for a complete overview, see [here](../easybuild-v5/index.md))* * ... diff --git a/mkdocs.yml b/mkdocs.yml index 392d40f36..7f1eed009 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,6 +127,7 @@ nav: - Installing Lmod: installing-lmod-without-root-permissions.md - Removed functionality: removed-functionality.md - Useful scripts: useful-scripts.md + - EasyBuild v5.0: easybuild-v5/index.md markdown_extensions: # add attributes to html elements @@ -201,7 +202,10 @@ plugins: - redirects: redirect_maps: # redirect removed pages to sensible alternative + easybuild-v5/backwards-incompatible-changes/: easybuild-v5/index.md + easybuild-v5/overview-of-changes/: easybuild-v5/index.md easybuild-v5/proposed-changes/: easybuild-v5/index.md + easybuild-v5/policies/: policies/toolchains.md # redirects for original EasyBuild documentation to avoid broken URLs en/latest/Archived-easyconfigs.html: archived-easyconfigs.md en/latest/Backup_modules.html: backup-modules.md