From 9dd2a8eb354445c7fd525fddf673440c36ec7485 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 2 Sep 2022 13:59:25 -0400 Subject: [PATCH 1/5] Adjust wording of LLVM prerequisite --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/prereqs.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/rst/usingchapel/prereqs.rst b/doc/rst/usingchapel/prereqs.rst index 8291a6e9da58..d56f663a4bc4 100644 --- a/doc/rst/usingchapel/prereqs.rst +++ b/doc/rst/usingchapel/prereqs.rst @@ -37,9 +37,10 @@ for using Chapel: * CMake is available and ``cmake`` runs version 3.13.4 or later. * The LLVM backend is now the default and it is easiest to use it with - a system-wide installation of LLVM. LLVM 11,12,13 and 14 are currently - supported. If a system-wide installation of LLVM 11/12/13/14 is not - available, you can use the bundled LLVM or disable LLVM support (see + a system-wide installation of LLVM. LLVM and clang versions 11, 12, + 13 and 14 are currently supported. If a system-wide installation of + LLVM and clang with one of those versions is not available, you can + use the bundled LLVM or disable LLVM support (see :ref:`readme-chplenv.CHPL_LLVM`). In addition, several optional components have additional requirements: From f994031f363388d56d10fe01be22656a551e889e Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 2 Sep 2022 13:59:46 -0400 Subject: [PATCH 2/5] Clarify quickstart llvm behavior --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/QUICKSTART.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/rst/usingchapel/QUICKSTART.rst b/doc/rst/usingchapel/QUICKSTART.rst index 7e1465377d41..06fe7b5c9c6f 100644 --- a/doc/rst/usingchapel/QUICKSTART.rst +++ b/doc/rst/usingchapel/QUICKSTART.rst @@ -89,20 +89,22 @@ rebuild Chapel from source in a different configuration: * Open up a new shell to avoid inheriting the previous environment settings. -* The Quickstart configuration described above sets ``CHPL_LLVM=none`` - for simplicity and to save time. This causes the Chapel compiler to - use its C back-end, which is not the preferred option; as of Chapel - 1.25, LLVM is the default back-end, which needs to be available for +* The Quickstart configuration attempts to detect if you have a + compatable system installation of LLVM and clang. If you do not, it + will ``CHPL_LLVM=none`` for simplicity and to save time. This causes + the Chapel compiler to use its C back-end, which is not the preferred + option; LLVM is the default back-end, which needs to be available for full functionality. There are a few options for using LLVM: - - ensure that you have a compatible version of LLVM installed on - your system and set ``CHPL_LLVM=system`` (or leave it unset and - Chapel should find it if it's in your path.) Currently compatible - versions are LLVM-11, LLVM-12, LLVM-13, and LLVM-14. + - Ensure that you have a compatible version of LLVM installed on + your system and set ``CHPL_LLVM=system``. Once you have it working, + you can leave ``CHPL_LLVM`` unset and Chapel should detect it if it + is in your path. See :ref:`readme-prereqs` for details on the + currently supported LLVM versions. - - set ``CHPL_LLVM=bundled`` to have Chapel build and use the bundled - version of LLVM (note that building the bundled version of LLVM - can take a long time and requires CMake version 3.13.4 or higher) + - Or, set ``CHPL_LLVM=bundled`` to have Chapel build and use the bundled + version of LLVM. Note that building the bundled version of LLVM + can take a long time and requires CMake version 3.13.4 or higher. - set ``CHPL_LLVM=none`` to continue using the C back-end rather than LLVM From bed23be7edc25929185e2ade7c3f3192ddfeba4d Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 2 Sep 2022 14:00:21 -0400 Subject: [PATCH 3/5] Update CHPL_LLVM section & split out sub-vars and add documentation for CHPL_LLVM_SUPPORT --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/chplenv.rst | 81 +++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 19 deletions(-) diff --git a/doc/rst/usingchapel/chplenv.rst b/doc/rst/usingchapel/chplenv.rst index fff8a74ef950..1071dc5516bf 100644 --- a/doc/rst/usingchapel/chplenv.rst +++ b/doc/rst/usingchapel/chplenv.rst @@ -754,9 +754,11 @@ CHPL_LLVM Value Description ============== ====================================================== bundled use the llvm/clang distribution in third-party - system find a compatible LLVM in system libraries; - note: the LLVM must be a version supported by Chapel + system find a compatible LLVM and clang in system libraries; + but note that it must be a version supported by Chapel none do not support llvm/clang-related features + (but note that the LLVM Support library will still + be used -- see ``CHPL_LLVM_SUPPORT`` below) unset indicates that no reasonable default has been inferred, requiring the user to intentionally select another option @@ -767,32 +769,73 @@ CHPL_LLVM * ``none`` on linux32 where Chapel LLVM support is not yet implemented * ``bundled`` if you've already built the bundled llvm in `third-party/llvm` - * ``system`` if a compatible system-wide installation of LLVM is detected + * ``system`` if a compatible system-wide installation of LLVM and + clang is detected * ``unset`` otherwise If CHPL_LLVM is ``unset`` you will need to either add a system-wide installation of LLVM or set ``CHPL_LLVM`` to ``bundled`` or ``none``. See :ref:`readme-prereqs` for more information about currently - supported LLVM versions. + supported LLVM versions and how to install them. If you are having + trouble getting the build system to recognize your system install of + LLVM, try setting ``CHPL_LLVM=system`` and ``CHPL_LLVM_CONFIG`` as + well in order to get an error message that may help you to diagnose + the problem. - **CHPL_LLVM_CONFIG** +.. _readme-chplenv.CHPL_LLVM_SUPPORT: + +CHPL_LLVM_SUPPORT +~~~~~~~~~~~~~~~~~ + + This variable indicates where to find the LLVM support library. The + LLVM support library is required to build the ``chpl`` compiler. It + can only have two values: + + ============== ====================================================== + Value Description + ============== ====================================================== + bundled build the LLVM support library from source using + the bundled version in third-party + system use a system-wide install of LLVM to get the + LLVM support library + ============== ====================================================== + + If unset, ``CHPL_LLVM_SUPPORT`` defaults to the same value as + ``CHPL_LLVM`` if ``CHPL_LLVM=system`` or ``CHPL_LLVM=bundled``. + Otherwise: + + * ``system`` if a compatible system-wide installation of LLVM is detected + * ``bundled`` otherwise + +.. _readme-chplenv.CHPL_LLVM_CONFIG: + +CHPL_LLVM_CONFIG +~~~~~~~~~~~~~~~~ In some cases, it is useful to be able to select a particular LLVM - installation for use with ``CHPL_LLVM=system``. In that event, in - addition to setting ``CHPL_LLVM=system``, you can set - ``CHPL_LLVM_CONFIG`` to the llvm-config command from the LLVM - installation you wish to use. - - **CHPL_LLVM_GCC_PREFIX** - - Additionally, in some cases, the configured ``clang`` will not work - correctly without a ``--gcc-toolchain`` flag. The Chapel compiler - tries to infer this flag but it does not always do so correctly. As a - result, it is sometimes necessary to override it. You can set - ``CHPL_LLVM_GCC_PREFIX`` to ``none`` to disable passing the - ``--gcc-toolchain`` flag; or you can set it to a directory to pass to - ``clang`` with the ``--gcc-toolchain`` flag. + installation for use with ``CHPL_LLVM=system`` or with + ``CHPL_LLVM_SUPPORT=system``. In that event, in addition to setting + one of those variables, you can set ``CHPL_LLVM_CONFIG`` to the + llvm-config command from the LLVM installation you wish to use. + + Inspecting the value of this variable from ``printchplenv --all`` can + also help to identify problems with detection of a system install of + LLVM and clang. + +.. _readme-chplenv.CHPL_LLVM_GCC_PREFIX: + +CHPL_LLVM_GCC_PREFIX +~~~~~~~~~~~~~~~~~~~~ + + In some cases, the configured ``clang`` will not work correctly + without a ``--gcc-toolchain`` flag. The Chapel compiler tries to infer + this flag based upon the ``gcc`` currently available in your ``PATH`` + but sometimes that strategy does not work. As a result, it is + sometimes necessary to indicate the path to the GCC libraries. You + can set ``CHPL_LLVM_GCC_PREFIX`` to ``none`` to disable passing the + ``--gcc-toolchain`` flag; or you can set it to a particular directory + to pass to ``clang`` with the ``--gcc-toolchain`` flag. .. _readme-chplenv.CHPL_UNWIND: From b27322b7da86f32d6b59034f494b0c3eb18f7e51 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 2 Sep 2022 15:32:42 -0400 Subject: [PATCH 4/5] Responding to review feedback --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/QUICKSTART.rst | 6 +++--- doc/rst/usingchapel/chplenv.rst | 7 ++++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/rst/usingchapel/QUICKSTART.rst b/doc/rst/usingchapel/QUICKSTART.rst index 06fe7b5c9c6f..94b8db30ef9a 100644 --- a/doc/rst/usingchapel/QUICKSTART.rst +++ b/doc/rst/usingchapel/QUICKSTART.rst @@ -89,9 +89,9 @@ rebuild Chapel from source in a different configuration: * Open up a new shell to avoid inheriting the previous environment settings. -* The Quickstart configuration attempts to detect if you have a - compatable system installation of LLVM and clang. If you do not, it - will ``CHPL_LLVM=none`` for simplicity and to save time. This causes +* The Quickstart configuration attempts to detect if you have a compatable + system installation of LLVM and clang. If you do not, it will set + ``CHPL_LLVM=none`` for simplicity and to save time. This causes the Chapel compiler to use its C back-end, which is not the preferred option; LLVM is the default back-end, which needs to be available for full functionality. There are a few options for using LLVM: diff --git a/doc/rst/usingchapel/chplenv.rst b/doc/rst/usingchapel/chplenv.rst index 1071dc5516bf..f6d8919b7d91 100644 --- a/doc/rst/usingchapel/chplenv.rst +++ b/doc/rst/usingchapel/chplenv.rst @@ -779,9 +779,10 @@ CHPL_LLVM See :ref:`readme-prereqs` for more information about currently supported LLVM versions and how to install them. If you are having trouble getting the build system to recognize your system install of - LLVM, try setting ``CHPL_LLVM=system`` and ``CHPL_LLVM_CONFIG`` as - well in order to get an error message that may help you to diagnose - the problem. + LLVM, try setting ``CHPL_LLVM=system`` and set ``CHPL_LLVM_CONFIG`` to + the `llvm-config` command from the LLVM version you have installed. + Temporarily setting these can help produce a different error message + that may may help you to diagnose the problem. .. _readme-chplenv.CHPL_LLVM_SUPPORT: From b9b183fe132a3c62eef3025e320588c1d5eb9386 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 2 Sep 2022 16:08:11 -0400 Subject: [PATCH 5/5] Fix quoting --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/chplenv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rst/usingchapel/chplenv.rst b/doc/rst/usingchapel/chplenv.rst index f6d8919b7d91..b6dd609bee4a 100644 --- a/doc/rst/usingchapel/chplenv.rst +++ b/doc/rst/usingchapel/chplenv.rst @@ -780,7 +780,7 @@ CHPL_LLVM supported LLVM versions and how to install them. If you are having trouble getting the build system to recognize your system install of LLVM, try setting ``CHPL_LLVM=system`` and set ``CHPL_LLVM_CONFIG`` to - the `llvm-config` command from the LLVM version you have installed. + the ``llvm-config`` command from the LLVM version you have installed. Temporarily setting these can help produce a different error message that may may help you to diagnose the problem.