From ff363fd32a241ff0d0b4e36a74131224d961f5b2 Mon Sep 17 00:00:00 2001 From: Zach Atkins Date: Fri, 28 Jun 2024 13:56:56 -0700 Subject: [PATCH 1/4] Add homebrew-based build instructions for apple silicon --- .../configs/macos_sonoma_aarch64/spack.yaml | 128 +++++++++ src/docs/sphinx/quickstart.rst | 261 +++--------------- 2 files changed, 166 insertions(+), 223 deletions(-) create mode 100644 scripts/spack/configs/macos_sonoma_aarch64/spack.yaml diff --git a/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml b/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml new file mode 100644 index 0000000000..5d0cc22ddd --- /dev/null +++ b/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml @@ -0,0 +1,128 @@ + +spack: + # add package specs to the `specs` list + view: true + concretizer: + unify: true + packages: + all: + compiler: [clang, gcc] + providers: + blas: [netlib-lapack] + lapack: [netlib-lapack] + mpi: [openmpi] + mpi: + buildable: false + openmpi: + buildable: false + externals: + - spec: openmpi@5.0.3_1 + prefix: /opt/homebrew + netlib-lapack: + buildable: false + externals: + - spec: netlib-lapack@3.12.0 + prefix: /opt/homebrew/opt/lapack + autoconf: + buildable: false + externals: + - spec: autoconf@2.72 + prefix: /opt/homebrew + automake: + buildable: false + externals: + - spec: automake@1.16.5 + prefix: /opt/homebrew + bzip2: + buildable: false + externals: + - spec: bzip2@1.0.8 + prefix: /opt/homebrew/opt/bzip2 + cmake: + version: [3.29.6] + buildable: false + externals: + - spec: cmake@3.29.5 + prefix: /opt/homebrew + gettext: + buildable: false + externals: + - spec: gettext@0.22.5 + prefix: /opt/homebrew + graphviz: + buildable: false + externals: + - spec: graphviz@11.0.0 + prefix: /opt/homebrew + libtool: + buildable: false + externals: + - spec: libtool@2.4.7 + prefix: /opt/homebrew + libx11: + buildable: false + externals: + - spec: libx11@1.8.9 + prefix: /opt/homebrew + llvm: + version: [18.1.8] + buildable: false + externals: + - spec: llvm+clang@18.1.8 + prefix: /opt/homebrew/opt/llvm + m4: + buildable: false + externals: + - spec: m4@1.4.19 + prefix: /opt/homebrew/opt/m4 + perl: + buildable: false + externals: + - spec: perl@5.34.1~cpanm+opcode+open+shared+threads + prefix: /usr + pkg-config: + buildable: false + externals: + - spec: pkg-config@0.29.2_3 + prefix: /opt/homebrew + python: + buildable: false + externals: + - spec: python@3.12.4+bz2+crypt+ctypes+dbm+lzma+nis+pyexpat~pythoncmd+readline+sqlite3+ssl~tkinter+uuid+zlib + prefix: /opt/homebrew/opt/python + tar: + buildable: false + externals: + - spec: tar@3.5.3 + prefix: /usr + readline: + buildable: false + externals: + - spec: readline@8.2.10 + prefix: /opt/homebrew + unzip: + buildable: false + externals: + - spec: unzip@6.0 + prefix: /usr + zlib: + buildable: false + externals: + - spec: zlib@1.3.1 + prefix: /opt/homebrew + + compilers: + - compiler: + spec: clang@=18.1.8 + paths: + cc: /opt/homebrew/opt/llvm/bin/clang + cxx: /opt/homebrew/opt/llvm/bin/clang++ + f77: /opt/homebrew/bin/gfortran-14 + fc: /opt/homebrew/bin/gfortran-14 + flags: {} + operating_system: sonoma + target: aarch64 + modules: [] + environment: {} + extra_rpaths: + - /opt/homebrew/lib/gcc/14 diff --git a/src/docs/sphinx/quickstart.rst b/src/docs/sphinx/quickstart.rst index 0ed457d6d3..0ea3bb8ba0 100644 --- a/src/docs/sphinx/quickstart.rst +++ b/src/docs/sphinx/quickstart.rst @@ -269,256 +269,71 @@ must be specified using either: ``python3 scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/linux_ubuntu_18/spack.yaml --prefix=../path/to/install`` -Building Serac dependencies on MacOS ------------------------------------- - +Building Serac Dependencies on MacOS with Homebrew +--------------------------------------------------- .. warning:: - These instructions are in development. + These instructions are in development, but have been tested for M2 MacBooks. -Meeting base dependency requirements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One way to install the required depedencies is with the MacPorts package manager. -Install the required ports as follows: +Installing base dependencies using Homebrew +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Install the following packages using Homebrew. .. code-block:: bash + $ brew install autoconf automake bzip2 clingo cmake gcc gettext gnu-sed graphviz hwloc lapack libx11 llvm m4 make ninja open-mpi openblas pkg-config python readline spack zlib - $ sudo port install clang-12 openmpi-clang12 gcc12 bzip2 cmake autoconf automake gettext graphviz pkgconfig xorg-libX11 lapack readline zlib - -(Note: The port ``gcc12`` is included only to have a fortran compiler.) - -Activate the particular compiler packages with MacPorts: - +If you plan to install the developer tools, you should also run .. code-block:: bash + $ brew install cppcheck doxygen llvm@14 + $ ln -s /opt/homebrew/opt/llvm@14/bin/clang-format /opt/homebrew/bin/clang-format - $ sudo port select clang mp-clang-12 - $ sudo port select mpi openmpi-clang12-fortran - $ sudo port select gcc mp-gcc12 - -This step tells MacPorts to make symbolic links in your path so that, for example, the command ``clang`` will invoke the compiler installed by the MacPorts package and not the one shipped by Apple. -It also sets up a set of symlinks so that Clang, GCC, and the MPI wrappers all work without you having to muck with environment variables to locate header files and libraries. -It may be possible to skip this step and give full paths to your compilers in ``spack.yaml`` nested under ``compilers:`` (instead of the -symlinks ``/opt/local/bin/clang``, etc.), but we haven't tried this. - -.. note:: - If you want to remove these symlinks, use the ``port select`` command with ``none`` as the desired port; e.g., ``sudo port select clang none`` - -While building ParMetis, Spack invokes the MPI compiler wrapper with the ``mpic++`` command, but MacPorts does not create this particular synonym for OpenMPI. -It does create ``mpicxx``. This can be solved by making a symlink: +If you have installed Homebrew using the default installation prefix, most packages will be accessible through the prefix ``/opt/homebrew``. +Some packages are not linked into this prefix to prevent conflicts with MacOS-provided versions. +These will only be accessible via the prefix ``/opt/homebrew/opt/[package-name]``. +Homebrew will warn about such packages after installing them. +In order for the correct compilers to be used for the installation, you should also add the bin directory for LLVM clang to your path in your ``.bash_profile``, ``.bashrc``, or ``.zshrc``, etc. +This is also useful for a few additional packages: .. code-block:: bash - - $ cd /opt/local/bin - $ sudo ln -s mpicxx mpic++ - -MacPorts will automatically update the ``mpicxx`` symlink in ``/opt/local/bin`` to point to the correct executable when you use the ``port select`` command to activate a partiular MPI package. -By making ``mpic++`` point to ``mpicxx``, this command will also automatically point to the correct executable if you change the global MPI package through MacPorts in the future. - -The Serac build scripts will install the ``clingo`` package in your Python environment (and may even *uninstall* it if it finds it with a version it considers too old). -If you don't want the install to modify your Python environment, you may wish to conisder using tools like -`virtual environments `_ or `conda `_ to isolate this change. + $ export PATH="/opt/homebrew/opt/llvm/bin:/opt/homebrew/opt/m4/bin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH" Configuring Spack ^^^^^^^^^^^^^^^^^ - -Next, you must tailor the Spack configuration file. We will modify the ``spack.yaml`` file in ``scripts/spack/configs/darwin/``. -Instead of modifying them directly, you may wish to copy these files to another location outside of the Serac repo, use them as templates for the customization, and use the ``--spack-env-file`` option to use them when invoking uberenv as described above. - -Example ``spack.yaml``: - -.. code-block:: yaml - - spack: - packages: - all: - compiler: [clang, gcc] - providers: - blas: [netlib-lapack] - lapack: [netlib-lapack] - mpi: [openmpi] - - mpi: - buildable: false - openmpi: - externals: - - spec: openmpi@4.1.4 - prefix: /opt/local - - netlib-lapack: - buildable: false - externals: - - spec: netlib-lapack@3.10.1 - prefix: /opt/local - autoconf: - buildable: false - externals: - - spec: autoconf@2.71 - prefix: /opt/local - automake: - buildable: false - externals: - - spec: automake@1.16.5 - prefix: /opt/local - bzip2: - buildable: false - externals: - - spec: bzip2@1.0.8 - prefix: /opt/local - cmake: - version: [3.22.4] - buildable: false - externals: - - spec: cmake@3.22.4 - prefix: /opt/local - gettext: - buildable: false - externals: - - spec: gettext@0.21 - prefix: /opt/local - graphviz: - buildable: false - externals: - - spec: graphviz@2.50.0 - prefix: /opt/local - libtool: - buildable: false - externals: - - spec: libtool@2.4.6 - prefix: /opt/local - libx11: - buildable: false - externals: - - spec: libx11@1.8.1 - prefix: /opt/local - m4: - buildable: false - externals: - - spec: m4@1.4.6 - prefix: /usr - perl: - buildable: false - externals: - - spec: perl@v5.30.2 - prefix: /usr - pkg-config: - buildable: false - externals: - - spec: pkg-config@0.29.2 - prefix: /opt/local - tar: - buildable: false - externals: - - spec: tar@3.3.2 - prefix: /usr - readline: - buildable: false - externals: - - spec: readline@8.1.2.000 - prefix: /opt/local - unzip: - buildable: false - externals: - - spec: unzip@6.0 - prefix: /usr - zlib: - buildable: false - externals: - - spec: zlib@1.2.12 - prefix: /opt/local - - compilers: - - compiler: - environment: {} - extra_rpaths: [] - flags: {} - modules: [] - operating_system: bigsur - paths: - cc: /opt/local/bin/clang - cxx: /opt/local/bin/clang++ - f77: /opt/local/bin/gfortran - fc: /opt/local/bin/gfortran - spec: clang@12.0.1 - target: x86_64 - -NOTES: - -* The ``operating_system`` field should be set according to your macOS version. (For example, ``mojave``, ``catalina``, ``bigsur``, ``monterey``, ``ventura``). -* By default, MacPorts installs packages in ``/opt/local``; the above ``paths`` need to be adjusted if you choose a different location. - This of course applies to the packages in ``spack.yaml`` as well. -* As noted above, the ``port select ...`` commands will set which version of clang gets invoked by the executables ``/opt/local/bin/clang``, etc. - The paths above are thus valid only if you activated the ``clang`` package that matches the compiler spec. - Alternatively, you could set the full name and path of the executables of the desired compilers if you don't want the operation of - Spack to be influenced by your MacPorts settings. -* You should set ``spec`` to the actual version of the compiler you installed. -* The ``target`` entry should be set to ``x86_64`` or ``m1`` depending on which architecture your machine uses. -* The version specs should be set to the actual versions of the packages you have, which will not neccesarily be the same as the above. - This can be discovered for the packages installed with MacPorts using the following command: - +In order to build Serac, we must define a ``spack.yaml`` file which tells Spack what packages we have installed. +You will likely need to update the versions of packages in the provided example script ``scripts/spack/configs/macos_sonoma_aarch64/spack.yaml`` to match the versions installed by Homebrew. +The versions for all installed packages can be listed via: .. code-block:: bash + $ brew list --versions +Note that the version format output by the above command is not the same as that expected by Spack, so be sure to add an ``@`` symbol between the package name and version string. - $ port info clang-12 openmpi-clang12 gcc12 bzip2 autoconf automake gettext graphviz pkgconfig xorg-libX11 lapack readline zlib - -* Use the version number provided, taking the values up to, but excluding, any underscore. -* The packages not installed by MacPorts are the ones that have ``/usr`` as the prefix. - The versions already present on the system are sufficient for the build. - -The above Spack settings and MacPorts packages will cover the basic installation of Serac. -If you want to build the optional devtools, you should install the additional packages with MacPorts: - -.. code-block: bash - - $ sudo port install cppcheck doxygen - -Then, append the following to ``spack.yaml`` nested under ``packages:``: +If you are not using an M2 or M3 Mac, you will need to change the ``target`` for the compiler to ``x86_64`` or ``m1`` for Intel and M1-based Macs, respectively. +Similarly, you need to set the ``operating_system`` to the proper value if you are not using ``sonoma`` (MacOS 14.X). +If you want to install the devtools, you should also add the following under ``packages`` in the ``spack.yaml`` files. .. code-block:: yaml - + # optional, for dev tools cppcheck: - version: [2.3] + version: [2.14.2] buildable: false externals: - - spec: cppcheck@2.3 - prefix: /usr/local + - spec: cppcheck@2.14.1 + prefix: /opt/homebrew + # optional, for dev tools doxygen: - version: [1.8.13] - buildable: false - externals: - - spec: doxygen@1.8.13 - prefix: /usr/local - llvm: - version: [10.0.0] - buildable: false - externals: - - spec: llvm+clang@10.0.0 - prefix: - python: + version: [1.11.0] buildable: false externals: - - spec: python@3.9 - prefix: - -Notes: - -* LLVM/Clang is needed for the style check tools. - The *exact* version 10.0.0 is apparently highly recommended, since other versions may format the code slightly differently, - which will mean that pull requests formatted with them may trigger style errors in the CI checks. -* The placeholders ```` and ```` need to be filled in with actual paths. - See the following two notes. -* LLVM 10.0.0 has been superseded as the version for llvm-10; so this package is not easily installable with MacPorts. - You must build it yourself and then point to the build location. -* For ````, specify the the virtual environment directory created above. + - spec: doxygen@1.11.0 + prefix: /opt/homebrew Building dependencies ^^^^^^^^^^^^^^^^^^^^^ -The invocation of ``uberenv.py`` is slightly modified from the standard instructions above in order to force the use of the -MacPorts-installed MPI: +The invocation of ``uberenv.py`` is slightly modified from the standard instructions above in order to force the use of the Homebrew-installed MPI and compilers: .. code-block:: bash + $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="%clang@18.1.8 ^openmpi@5.0.3_1" - $ ./scripts/uberenv/uberenv.py --prefix=../path/for/TPLs --spec="%clang@12.0.1 ^openmpi@4.1.4" +Note: If you want to build with PETSc, you should instead use the command -Notice the caret with the MPI spec. -Without this, current versions of Spack ignore the ``spack.yaml`` file and try to build a version of MPI from source. -You can add additional specs as noted in the section `Building Serac's Dependencies via Spack/uberenv`. +.. code-block:: bash + $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="++petsc %clang@18.1.8 ^openmpi@5.0.3_1 ^petsc+tetgen+scalapack+strumpack" From b1bcd5230f2f2d4169978e6371e46d98a5a41c92 Mon Sep 17 00:00:00 2001 From: Zach Atkins Date: Mon, 1 Jul 2024 11:45:49 -0700 Subject: [PATCH 2/4] Update scripts/spack/configs/macos_sonoma_aarch64/spack.yaml Use `::` to prevent use of other compilers Co-authored-by: Chris White --- scripts/spack/configs/macos_sonoma_aarch64/spack.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml b/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml index 5d0cc22ddd..93054b73c6 100644 --- a/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml +++ b/scripts/spack/configs/macos_sonoma_aarch64/spack.yaml @@ -111,7 +111,8 @@ spack: - spec: zlib@1.3.1 prefix: /opt/homebrew - compilers: + # The "::" removes all found/known compilers from Spack except for these. + compilers:: - compiler: spec: clang@=18.1.8 paths: From 1e4a44f611091137ce0482f9f44b6796d2cedc9e Mon Sep 17 00:00:00 2001 From: Zach Atkins Date: Mon, 1 Jul 2024 11:59:30 -0700 Subject: [PATCH 3/4] Fix code block formatting --- src/docs/sphinx/quickstart.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/docs/sphinx/quickstart.rst b/src/docs/sphinx/quickstart.rst index 0ea3bb8ba0..beefb1ebb2 100644 --- a/src/docs/sphinx/quickstart.rst +++ b/src/docs/sphinx/quickstart.rst @@ -278,11 +278,15 @@ Installing base dependencies using Homebrew ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Install the following packages using Homebrew. + .. code-block:: bash + $ brew install autoconf automake bzip2 clingo cmake gcc gettext gnu-sed graphviz hwloc lapack libx11 llvm m4 make ninja open-mpi openblas pkg-config python readline spack zlib If you plan to install the developer tools, you should also run + .. code-block:: bash + $ brew install cppcheck doxygen llvm@14 $ ln -s /opt/homebrew/opt/llvm@14/bin/clang-format /opt/homebrew/bin/clang-format @@ -293,7 +297,9 @@ Homebrew will warn about such packages after installing them. In order for the correct compilers to be used for the installation, you should also add the bin directory for LLVM clang to your path in your ``.bash_profile``, ``.bashrc``, or ``.zshrc``, etc. This is also useful for a few additional packages: + .. code-block:: bash + $ export PATH="/opt/homebrew/opt/llvm/bin:/opt/homebrew/opt/m4/bin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH" Configuring Spack @@ -301,23 +307,27 @@ Configuring Spack In order to build Serac, we must define a ``spack.yaml`` file which tells Spack what packages we have installed. You will likely need to update the versions of packages in the provided example script ``scripts/spack/configs/macos_sonoma_aarch64/spack.yaml`` to match the versions installed by Homebrew. The versions for all installed packages can be listed via: + .. code-block:: bash + $ brew list --versions + Note that the version format output by the above command is not the same as that expected by Spack, so be sure to add an ``@`` symbol between the package name and version string. If you are not using an M2 or M3 Mac, you will need to change the ``target`` for the compiler to ``x86_64`` or ``m1`` for Intel and M1-based Macs, respectively. Similarly, you need to set the ``operating_system`` to the proper value if you are not using ``sonoma`` (MacOS 14.X). If you want to install the devtools, you should also add the following under ``packages`` in the ``spack.yaml`` files. + .. code-block:: yaml + # optional, for dev tools cppcheck: version: [2.14.2] buildable: false externals: - - spec: cppcheck@2.14.1 + - spec: cppcheck@2.14.2 prefix: /opt/homebrew - # optional, for dev tools doxygen: version: [1.11.0] buildable: false @@ -331,9 +341,11 @@ Building dependencies The invocation of ``uberenv.py`` is slightly modified from the standard instructions above in order to force the use of the Homebrew-installed MPI and compilers: .. code-block:: bash + $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="%clang@18.1.8 ^openmpi@5.0.3_1" Note: If you want to build with PETSc, you should instead use the command .. code-block:: bash + $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="++petsc %clang@18.1.8 ^openmpi@5.0.3_1 ^petsc+tetgen+scalapack+strumpack" From 30d039051b7b900e851295d23aa8729188c575a1 Mon Sep 17 00:00:00 2001 From: Zach Atkins Date: Mon, 1 Jul 2024 12:48:22 -0700 Subject: [PATCH 4/4] Update src/docs/sphinx/quickstart.rst Co-authored-by: Chris White --- src/docs/sphinx/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sphinx/quickstart.rst b/src/docs/sphinx/quickstart.rst index beefb1ebb2..9617a8b6dd 100644 --- a/src/docs/sphinx/quickstart.rst +++ b/src/docs/sphinx/quickstart.rst @@ -348,4 +348,4 @@ Note: If you want to build with PETSc, you should instead use the command .. code-block:: bash - $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="++petsc %clang@18.1.8 ^openmpi@5.0.3_1 ^petsc+tetgen+scalapack+strumpack" + $ ./scripts/uberenv/uberenv.py --spack-env-file=scripts/spack/configs/macos_sonoma_aarch64/spack.yaml --prefix=../path/to/install --spec="+petsc %clang@18.1.8 ^openmpi@5.0.3_1 ^petsc+tetgen+scalapack+strumpack"