Tutorial setup
If you have not done the prior sections, you’ll need to start the docker image:
docker run -it ghcr.io/spack/tutorial:isc26
and then set Spack up like this:
git clone --depth=2 --branch=releases/v1.2 https://github.com/spack/spack
. spack/share/spack/setup-env.sh
spack mirror add --unsigned tutorial /mirror
spack bootstrap now
spack compiler find
See the Basic Installation Tutorial for full details on setup.
For more help, join us in the #tutorial channel on Slack – get an invitation at slack.spack.io
Package Creation Tutorial¶
This tutorial walks you through the steps for creating and debugging a simple Spack package.
We will develop and debug a package using an iterative approach to gain more experience with additional Spack commands.
For consistency, we will create a package for mpileaks (https://github.com/LLNL/mpileaks), an MPI debugging tool.
What is a Spack Package?¶
Spack packages are installation scripts, which are essentially recipes for building (and testing) software.
They define properties and behavior of the build, such as:
where to find and how to retrieve the software;
its dependencies;
options (variants) for building from source;
known build constraints (conflicts);
known requirements (requires); and
They can also define checks of the installed software that can be performed after the installation.
Once we’ve specified a package’s recipe, users can ask Spack to build the software with different features on any of the supported systems.
Getting Started¶
In order to avoid modifying your Spack installation with the package we are creating, let’s create and add a package repository just for this tutorial using the following commands:
$ spack repo create $HOME/my_pkgs tutorial
==> Created repo with namespace 'tutorial'.
==> To register it with spack, run this command:
spack repo add /home/spack/my_pkgs/spack_repo/tutorial
$ spack repo add $HOME/my_pkgs/spack_repo/tutorial
==> Added repo to config with name 'tutorial'.
Doing this ensures changes we make here do not adversely affect other parts of the tutorial.
Now let’s look at the available repositories using spack repo list:
$ spack repo list
[+] tutorial v2.5 /home/spack/my_pkgs/spack_repo/tutorial
[+] builtin v2.2 /home/spack/.spack/package_repos/fncqgg4/repos/spack_repo/builtin
Notice we now have two repositories: tutorial and builtin.
We can see how they are configured using spack config get repos:
$ spack config get repos
repos:
tutorial: /home/spack/my_pkgs/spack_repo/tutorial
builtin:
git: https://github.com/spack/spack-packages.git
Notice the tutorial repository points to a local path, while the builtin repository is fetched from its remote git location.
You can find out more about repositories at Package Repositories and the command at spack repo.
Creating the Package File¶
Note
Before proceeding, make sure your SPACK_EDITOR, VISUAL, or EDITOR environment variable is set to the name or path of your preferred text editor.
Details can be found at Controlling the Editor.
Suppose you want to install software that depends on mpileaks but found Spack did not already have a built-in package for it. This means you are going to have to create one.
Spack’s create command builds a new package from a template by taking the location of the package’s source code and using it to:
create a package skeleton; and
open the file in your editor of choice.
The mpileaks source code is available in a tarball in the software’s repository (https://github.com/LLNL/mpileaks).
Spack will look at the contents of the tarball and generate a package when we run spack create with the URL:
$ spack create --name tutorial-mpileaks --namespace tutorial https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz
==> Using specified package name: 'tutorial-mpileaks'
[100%] 336.09 KB @ 4.5 MB/s
==> This package looks like it uses the autoreconf build system
==> Created template for tutorial-mpileaks package
==> Created package file: /home/spack/my_pkgs/spack_repo/tutorial/packages/tutorial_mpileaks/package.py
You should now be in your text editor of choice, with the package.py file open for editing.
Your package.py file should reside in the tutorial-mpileaks subdirectory of your tutorial repository’s packages directory, i.e., $HOME/my_pkgs/spack_repo/tutorial/packages/tutorial_mpileaks/package.py.
Take a moment to look over the file.
As we can see from the skeleton contents, the Spack template:
provides the required Spack copyright and license;
provides boilerplate information on the commands for installing and editing the package;
imports and inherits from the inferred build system package;
provides a docstring template;
provides an example homepage URL;
shows how to specify a list of package maintainers;
provides a template for the license;
specifies the version directive with the checksum;
lists the inferred language and other build dependencies;
provides a skeleton for another dependency;
provides a preliminary implementation of the autoreconf method; and
provides a skeleton configure_args method.
Note
The maintainers directive holds a comma-separated list of GitHub user names for those accounts willing to be notified when a change is made to the package. They will also be given an opportunity to review the changes. This information is useful for developers who maintain a Spack package for their own software and/or rely on software maintained by others.
The areas we need to modify are highlighted in the figure below.
# Copyright Spack Project Developers. See COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)
# ----------------------------------------------------------------------------
# If you submit this package back to Spack as a pull request,
# please first remove this boilerplate and all FIXME comments.
#
# This is a template package file for Spack. We've put "FIXME"
# next to all the things you'll want to change. Once you've handled
# them, you can save this file and test your package like this:
#
# spack install tutorial-mpileaks
#
# You can edit this file again by typing:
#
# spack edit tutorial-mpileaks
#
# See the Spack documentation for more information on packaging.
# ----------------------------------------------------------------------------
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack.package import *
class TutorialMpileaks(AutotoolsPackage):
"""FIXME: Put a proper description of your package here."""
# FIXME: Add a proper url for your package's homepage here.
homepage = "https://www.example.com"
url = "https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz"
# FIXME: Add a list of GitHub accounts to
# notify when the package is updated.
# maintainers("github_user1", "github_user2")
# FIXME: Add the SPDX identifier of the project's license below.
# See https://spdx.org/licenses/ for a list. Upon manually verifying
# the license, set checked_by to your Github username.
license("UNKNOWN", checked_by="github_user1")
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
depends_on("c", type="build")
depends_on("cxx", type="build")
depends_on("fortran", type="build")
depends_on("autoconf", type="build")
depends_on("automake", type="build")
depends_on("libtool", type="build")
depends_on("m4", type="build")
# FIXME: Add additional dependencies if required.
# depends_on("foo")
def autoreconf(self, spec, prefix):
# FIXME: Modify the autoreconf method as necessary
autoreconf("--install", "--verbose", "--force")
def configure_args(self):
# FIXME: Add arguments other than --prefix
# FIXME: If not needed delete this function
args = []
return args
Tip
We generally recommend you use the project-prepared archive url, when available, instead of the GitHub-generated Source code (tar.gz) since those tend to be less volatile in the face of GitHub shasum algorithm changes.
In this case, that would mean copying the url labeled mpileaks-1.0.tar.gz under the v1.0 release assets, or simply https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz.
The sha256 is different since the file has build customizations.
A key difference is the presence of autogen.sh, which is a convenience script Autotools projects can create to customize their reconfiguration process.
If you choose to use that URL, you should replace the more general call to autoreconf() with an invocation of the autogen.sh script.
An example of setting up and using the script can be found in the sos package.
Since we are providing a url, we can confirm the checksum, or sha256, calculation.
Exit your editor to return to the command line and use the spack checksum command:
$ spack checksum tutorial-mpileaks 1.0
==> Found 1 version of tutorial-mpileaks
[100%] 339.70 KB @ 2.5 MB/s
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
where the entire version directive is provided for your convenience.
Before proceeding with changes, let’s see what Spack does with the skeleton by trying to install the package using the spack install command:
$ spack install tutorial-mpileaks
[ ] 5txfucc tutorial-mpileaks@1.0 fetching from build cache (0s)
[ ] 5txfucc tutorial-mpileaks@1.0 no binary available (0s)
[ ] r4lhaok gmake@4.4.1 fetching from build cache (0s)
[ ] ohmdb2l less@692 fetching from build cache (0s)
[ ] k25xiih readline@8.3 fetching from build cache (0s)
[ ] r4lhaok gmake@4.4.1 relocating (0s)
[ ] 27d4iyp berkeley-db@18.1.40 fetching from build cache (0s)
[ ] ohmdb2l less@692 relocating (0s)
[ ] phcmfqk libsigsegv@2.15 fetching from build cache (0s)
[ ] punbqrx findutils@4.10.0 fetching from build cache (0s)
[ ] mguwetc file@5.46 fetching from build cache (0s)
[ ] k25xiih readline@8.3 relocating (0s)
[ ] 27d4iyp berkeley-db@18.1.40 relocating (0s)
[ ] phcmfqk libsigsegv@2.15 relocating (0s)
[ ] punbqrx findutils@4.10.0 relocating (0s)
[+] r4lhaok gmake@4.4.1 /home/spack/spack/opt/spack/linux-x86_64_v3/gmake-4.4.1-r4lhaokbvyicys3x6yxyhtxucmgzo7kh (0s)
[ ] mguwetc file@5.46 relocating (0s)
[+] ohmdb2l less@692 /home/spack/spack/opt/spack/linux-x86_64_v3/less-692-ohmdb2lfmv2mghjfr7o22nlbaue23m6o (0s)
[+] phcmfqk libsigsegv@2.15 /home/spack/spack/opt/spack/linux-x86_64_v3/libsigsegv-2.15-phcmfqkiobbdxotapv2famdv4vk5yvs7 (0s)
[+] k25xiih readline@8.3 /home/spack/spack/opt/spack/linux-x86_64_v3/readline-8.3-k25xiihp5dun6qwe3e5ouzdigwr5yuvz (0s)
[+] 27d4iyp berkeley-db@18.1.40 /home/spack/spack/opt/spack/linux-x86_64_v3/berkeley-db-18.1.40-27d4iypucirxwepjeco5bulvrej5l3bu (1s)
[+] mguwetc file@5.46 /home/spack/spack/opt/spack/linux-x86_64_v3/file-5.46-mguwetco632vycva2piy7hmqoc26acsq (1s)
[ ] y6uqrto m4@1.4.21 fetching from build cache (1s)
[+] punbqrx findutils@4.10.0 /home/spack/spack/opt/spack/linux-x86_64_v3/findutils-4.10.0-punbqrxx5vrhjry7gtdadymv34ryapi2 (1s)
[ ] cq4dkuc gdbm@1.26 fetching from build cache (1s)
[ ] y6uqrto m4@1.4.21 relocating (1s)
[ ] cq4dkuc gdbm@1.26 relocating (1s)
[ ] 3gdq456 libtool@2.5.4 fetching from build cache (0s)
[ ] 3gdq456 libtool@2.5.4 relocating (0s)
[+] y6uqrto m4@1.4.21 /home/spack/spack/opt/spack/linux-x86_64_v3/m4-1.4.21-y6uqrtoi6sjdfvvyxgmifksxwktsyx3t (1s)
[+] cq4dkuc gdbm@1.26 /home/spack/spack/opt/spack/linux-x86_64_v3/gdbm-1.26-cq4dkucz57w6rd7gnkhgbzfqz4snldpy (1s)
[ ] bvphs3b perl@5.42.0 fetching from build cache (0s)
[+] 3gdq456 libtool@2.5.4 /home/spack/spack/opt/spack/linux-x86_64_v3/libtool-2.5.4-3gdq456decrkzdhi7hwf3ndgvixvmu3n (0s)
[ ] bvphs3b perl@5.42.0 relocating (0s)
[+] bvphs3b perl@5.42.0 /home/spack/spack/opt/spack/linux-x86_64_v3/perl-5.42.0-bvphs3b3jahsyypadzj7kwfb23egjgb5 (0s)
[ ] yhkgfai automake@1.18.1 fetching from build cache (0s)
[ ] jo3eg4r autoconf@2.72 fetching from build cache (0s)
[ ] yhkgfai automake@1.18.1 relocating (0s)
[ ] jo3eg4r autoconf@2.72 relocating (0s)
[+] yhkgfai automake@1.18.1 /home/spack/spack/opt/spack/linux-x86_64_v3/automake-1.18.1-yhkgfaibmqj5ww5wfesjkdtrwpndwdtm (0s)
[+] jo3eg4r autoconf@2.72 /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj (0s)
[ ] 5txfucc tutorial-mpileaks@1.0 staging (0s)
[ ] 5txfucc tutorial-mpileaks@1.0 autoreconf (0s)
[ ] 5txfucc tutorial-mpileaks@1.0 configure (3s)
[x] 5txfucc tutorial-mpileaks@1.0 failed: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c-usu4vg6q.log (4s)
-- lines 1 to 7 --
> /home/spack/spack/lib/spack/spack/build_environment.py:490: SpackAPIWarning: when setting environment variable SPACK_DEBUG_LOG_DIR=None: value is of type `NoneType`, but `str` was expected. This is deprecated and will be an error in Spack v1.0
env.set(SPACK_DEBUG_LOG_DIR, spack.paths.spack_working_dir)
==> No patches needed for tutorial-mpileaks
==> tutorial-mpileaks: Executing phase: 'autoreconf'
==> [2026-06-19-08:14:27.539121] /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoreconf --install --verbose --force
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
-- lines 18 to 46 --
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoconf --force
> configure.ac:9: warning: 'AM_CONFIG_HEADER': this macro is obsolete.
> configure.ac:9: You should use the 'AC_CONFIG_HEADERS' macro instead.
> aclocal.m4:708: AM_CONFIG_HEADER is expanded from...
> configure.ac:9: the top level
> configure.ac:38: warning: The macro 'AC_PROG_LIBTOOL' is obsolete.
> configure.ac:38: You should run autoupdate.
> m4/libtool.m4:100: AC_PROG_LIBTOOL is expanded from...
> configure.ac:38: the top level
> configure.ac:47: warning: The macro 'AC_HEADER_STDC' is obsolete.
> configure.ac:47: You should run autoupdate.
> /tmp/root/spack-stage/spack-stage-autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/spack-src/lib/autoconf/headers.m4:663: AC_HEADER_STDC is expanded from...
> configure.ac:47: the top level
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
> configure.ac:26: installing 'config/compile'
> configure.ac:19: installing 'config/missing'
> src/Makefile.am:14: warning: 'INCLUDES' is the old name for 'AM_CPPFLAGS' (or '*_CPPFLAGS')
src/Makefile.am: installing 'config/depcomp'
autoreconf: Leaving directory '.'
==> tutorial-mpileaks: Executing phase: 'configure'
==> [2026-06-19-08:14:30.242239] Find (max depth = None): ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c/spack-src'] ['configure']
==> [2026-06-19-08:14:30.242759] Find complete: ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c/spack-src'] ['configure']
==> [2026-06-19-08:14:30.243009] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c/spack-src/configure [replacing "^(\s*if test x-L = )("\$p" \|\|\s*)$"]
-- lines 85 to 93 --
checking for mpipgcc... no
Checking whether not-found responds to '-showme:compile'... no
Checking whether not-found responds to '-showme'... no
Checking whether not-found responds to '-compile-info'... no
Checking whether not-found responds to '-show'... no
/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c/spack-src/configure: line 6213: Echo: command not found
> configure: error: unable to locate adept-utils installation
Command exited with status 1:
/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c/spack-src/configure --prefix=/home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c
==> Error: The following packages failed to install:
tutorial-mpileaks@1.0/5txfucci42vvbfv3pw52fe2sf463qo7c: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-5txfucci42vvbfv3pw52fe2sf463qo7c-usu4vg6q.log
The build was unsuccessful.
The error indicates configure is unable to find the installation location of a dependency.
We will now fill in the provided placeholders and customize the package for the software as we:
document key information about this package;
add dependencies; and
add the configuration arguments needed to build the package.
Adding Package Documentation¶
First, let’s fill in the documentation.
Bring tutorial-mpileaks’ package.py file back up in your editor with the spack edit command:
$ spack edit tutorial-mpileaks
Let’s make the following changes:
remove the boilerplate comments between and including the dashed lines at the top;
replace the first
FIXMEcomment with a description ofmpileaksin the docstring;replace the
homepageproperty with the correct link;uncomment the
maintainersdirective and replace the placeholder with your GitHub user name; andreplace the
licenseof the project with the correct name and the placeholder with your GitHub user name.
Tip
It helps to have the mpileaks repository up in your browser since you can copy-and-paste some of the values from it.
Note
We will exclude the Copyright clause and license identifier in the remainder of the package snippets here to reduce the length of the tutorial documentation; however, the copyright is required for packages contributed back to Spack.
Now make the changes and additions to your package.py file.
The resulting package should contain the following information, omitting the copyright and license:
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack.package import *
class TutorialMpileaks(AutotoolsPackage):
"""Tool to detect and report leaked MPI objects like MPI_Requests and MPI_Datatypes."""
homepage = "https://github.com/LLNL/mpileaks"
url = "https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz"
maintainers("adamjstewart")
license("BSD", checked_by="adamjstewart")
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
depends_on("c", type="build")
depends_on("cxx", type="build")
depends_on("fortran", type="build")
depends_on("autoconf", type="build")
depends_on("automake", type="build")
depends_on("libtool", type="build")
depends_on("m4", type="build")
# FIXME: Add additional dependencies if required.
# depends_on("foo")
def autoreconf(self, spec, prefix):
# FIXME: Modify the autoreconf method as necessary
autoreconf("--install", "--verbose", "--force")
def configure_args(self):
# FIXME: Add arguments other than --prefix
# FIXME: If not needed delete this function
args = []
return args
At this point we’ve only updated key documentation within the package. It won’t help us build the software; however, the information is now available for review.
Let’s enter the spack info command for the package:
$ spack info --phases tutorial-mpileaks
AutotoolsPackage: tutorial-mpileaks
Description:
Tool to detect and report leaked MPI objects like MPI_Requests and
MPI_Datatypes.
Homepage: https://github.com/LLNL/mpileaks
Preferred version:
1.0 https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz
Safe versions:
1.0 https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz
Deprecated versions:
None
Variants:
build_system [autotools] autotools
Build systems supported by the package
Installation Phases:
autoreconf configure build install
Build Dependencies:
autoconf automake c cxx fortran gmake gnuconfig libtool m4
Link Dependencies:
None
Run Dependencies:
None
Licenses:
BSD
Take a moment to look over the output. You should see the information derived from the package now includes the description, homepage, maintainer, and license we provided.
Also notice it shows:
the preferred version derived from the code;
the default
AutotoolsPackageinstallation phases;the gmake and gnuconfig build dependencies inherited from
AutotoolsPackage; andboth link and run dependencies are currently
None.
As we fill in more information about the package, the spack info command will become more informative.
Note
More information on this build system package is provided in AutotoolsPackage.
The full list of build systems known to Spack can be found at Build Systems.
Now we’re ready to start filling in the build recipe.
Tip
Refer to the style guide for Spack’s guidelines.
Adding Dependencies¶
First we’ll add the dependencies determined by reviewing documentation in the software’s repository (https://github.com/LLNL/mpileaks).
We can see from the README file’s instructions, mpileaks software relies on three third-party libraries:
mpi,adept-utils, andcallpath.
Note
Fortunately, all of these dependencies are built-in packages in Spack; otherwise, we would have to create packages for them as well.
Bring tutorial-mpileaks’ package.py file back up with the spack edit command:
$ spack edit tutorial-mpileaks
and add the dependencies by specifying them using the depends_on directive as shown below:
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack.package import *
class TutorialMpileaks(AutotoolsPackage):
"""Tool to detect and report leaked MPI objects like MPI_Requests and MPI_Datatypes."""
homepage = "https://github.com/LLNL/mpileaks"
url = "https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz"
maintainers("adamjstewart")
license("BSD", checked_by="adamjstewart")
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
depends_on("c", type="build")
depends_on("cxx", type="build")
depends_on("fortran", type="build")
depends_on("autoconf", type="build")
depends_on("automake", type="build")
depends_on("libtool", type="build")
depends_on("m4", type="build")
depends_on("mpi")
depends_on("adept-utils")
depends_on("callpath")
def autoreconf(self, spec, prefix):
# FIXME: Modify the autoreconf method as necessary
autoreconf("--install", "--verbose", "--force")
def configure_args(self):
# FIXME: Add arguments other than --prefix
# FIXME: If not needed delete this function
args = []
return args
Adding dependencies tells Spack that it must ensure those packages are installed before it can build our package.
Note
The mpi dependency is different from the other two in that it is a virtual dependency.
That means Spack must satisfy the dependency with a package that provides the mpi interface, such as openmpi or mvapich2.
We call such packages providers since they implement the virtual dependency’s interface.
Let’s check that dependencies are effectively built when we try to install tutorial-mpileaks:
$ spack install tutorial-mpileaks
[ ] 52pdqqj boost@1.72.0 fetching from build cache (0s)
[ ] rji2bti libdwarf@2.3.0 fetching from build cache (0s)
[ ] qqik7au elfutils@0.194 fetching from build cache (0s)
[ ] ftcprn4 libiberty@2.46.0 fetching from build cache (0s)
[ ] rji2bti libdwarf@2.3.0 relocating (0s)
[ ] tf2gxcs intel-tbb@2023.0.0 fetching from build cache (0s)
[ ] 52pdqqj boost@1.72.0 relocating (0s)
[ ] ftcprn4 libiberty@2.46.0 relocating (0s)
[ ] qqik7au elfutils@0.194 relocating (0s)
[ ] tf2gxcs intel-tbb@2023.0.0 relocating (0s)
[+] ftcprn4 libiberty@2.46.0 /home/spack/spack/opt/spack/linux-x86_64_v3/libiberty-2.46.0-ftcprn47kvuxpcbvjd5vif65cwsjvlbs (0s)
[+] rji2bti libdwarf@2.3.0 /home/spack/spack/opt/spack/linux-x86_64_v3/libdwarf-2.3.0-rji2bticj7x5325wtwkqpshluismdgnd (0s)
[+] tf2gxcs intel-tbb@2023.0.0 /home/spack/spack/opt/spack/linux-x86_64_v3/intel-tbb-2023.0.0-tf2gxcsr5vyiegaieu6kjw2mrhnm265k (0s)
[+] qqik7au elfutils@0.194 /home/spack/spack/opt/spack/linux-x86_64_v3/elfutils-0.194-qqik7au6w4bh7xtueccxmiemdstoof2i (0s)
[+] 52pdqqj boost@1.72.0 /home/spack/spack/opt/spack/linux-x86_64_v3/boost-1.72.0-52pdqqjhv3llivj6z7zj57d3ob3vfblp (1s)
[ ] naehq6l adept-utils@1.0.1 fetching from build cache (0s)
[ ] kurk3h3 dyninst@13.0.0 fetching from build cache (0s)
[ ] naehq6l adept-utils@1.0.1 relocating (0s)
[ ] kurk3h3 dyninst@13.0.0 relocating (0s)
[+] naehq6l adept-utils@1.0.1 /home/spack/spack/opt/spack/linux-x86_64_v3/adept-utils-1.0.1-naehq6ldodlwm7gjgdnccsxchnuphuep (0s)
[+] kurk3h3 dyninst@13.0.0 /home/spack/spack/opt/spack/linux-x86_64_v3/dyninst-13.0.0-kurk3h3kbsklm4kfem6iwuwr422fvspl (0s)
[ ] xksxwmq callpath@1.0.4 fetching from build cache (0s)
[ ] xksxwmq callpath@1.0.4 relocating (0s)
[+] xksxwmq callpath@1.0.4 /home/spack/spack/opt/spack/linux-x86_64_v3/callpath-1.0.4-xksxwmqijjrelztluyq5oilu4tqkyxf6 (0s)
[ ] olkbps3 tutorial-mpileaks@1.0 fetching from build cache (0s)
[ ] olkbps3 tutorial-mpileaks@1.0 no binary available (1s)
[ ] olkbps3 tutorial-mpileaks@1.0 staging (0s)
[ ] olkbps3 tutorial-mpileaks@1.0 autoreconf (1s)
[ ] olkbps3 tutorial-mpileaks@1.0 configure (4s)
[x] olkbps3 tutorial-mpileaks@1.0 failed: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije-3tcl7zd7.log (4s)
-- lines 1 to 7 --
> /home/spack/spack/lib/spack/spack/build_environment.py:490: SpackAPIWarning: when setting environment variable SPACK_DEBUG_LOG_DIR=None: value is of type `NoneType`, but `str` was expected. This is deprecated and will be an error in Spack v1.0
env.set(SPACK_DEBUG_LOG_DIR, spack.paths.spack_working_dir)
==> No patches needed for tutorial-mpileaks
==> tutorial-mpileaks: Executing phase: 'autoreconf'
==> [2026-06-19-08:14:41.833830] /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoreconf --install --verbose --force
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
-- lines 18 to 46 --
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoconf --force
> configure.ac:9: warning: 'AM_CONFIG_HEADER': this macro is obsolete.
> configure.ac:9: You should use the 'AC_CONFIG_HEADERS' macro instead.
> aclocal.m4:708: AM_CONFIG_HEADER is expanded from...
> configure.ac:9: the top level
> configure.ac:38: warning: The macro 'AC_PROG_LIBTOOL' is obsolete.
> configure.ac:38: You should run autoupdate.
> m4/libtool.m4:100: AC_PROG_LIBTOOL is expanded from...
> configure.ac:38: the top level
> configure.ac:47: warning: The macro 'AC_HEADER_STDC' is obsolete.
> configure.ac:47: You should run autoupdate.
> /tmp/root/spack-stage/spack-stage-autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/spack-src/lib/autoconf/headers.m4:663: AC_HEADER_STDC is expanded from...
> configure.ac:47: the top level
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
> configure.ac:26: installing 'config/compile'
> configure.ac:19: installing 'config/missing'
> src/Makefile.am:14: warning: 'INCLUDES' is the old name for 'AM_CPPFLAGS' (or '*_CPPFLAGS')
src/Makefile.am: installing 'config/depcomp'
autoreconf: Leaving directory '.'
==> tutorial-mpileaks: Executing phase: 'configure'
==> [2026-06-19-08:14:44.659730] Find (max depth = None): ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src'] ['configure']
==> [2026-06-19-08:14:44.660326] Find complete: ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src'] ['configure']
==> [2026-06-19-08:14:44.660557] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure [replacing "^(\s*if test x-L = )("\$p" \|\|\s*)$"]
-- lines 78 to 86 --
checking whether the compiler supports GNU C++... yes
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ accepts -g... yes
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ option to enable C++11 features... none needed
checking dependency style of /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++... gcc3
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc... /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc
Checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc responds to '-showme:compile'... yes
> configure: error: unable to locate adept-utils installation
Command exited with status 1:
/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure --prefix=/home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije
==> Error: The following packages failed to install:
tutorial-mpileaks@1.0/olkbps3ghmpiiy4dserbxgj5hlsm5ije: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije-3tcl7zd7.log
Note
This command may take a while to run and may produce more output if you don’t already have an MPI installed or configured in Spack.
While Spack was unable to install our package, we do see that it identified and built all of our dependencies. It found that:
the
openmpipackage will satisfy ourmpidependency;adept-utilsis a concrete dependency; andcallpathis a concrete dependency.
At this point we need to debug the build problem to determine why Spack cannot install the software.
Debugging Package Builds¶
Our tutorial-mpileaks package is still not building due to an error in the configure phase related to adept-utils.
Experienced Autotools developers will likely already see the problem and its solution.
Let’s take this opportunity to use Spack features to investigate the problem. Our options for proceeding are:
review the build log; and
build the package manually.
Reviewing the Build Log¶
The build log might yield some clues, so let’s look at the contents of the spack-build-out.txt file at the path recommended above by our failed installation:
$ cat /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-build-out.txt
/home/spack/spack/lib/spack/spack/build_environment.py:490: SpackAPIWarning: when setting environment variable SPACK_DEBUG_LOG_DIR=None: value is of type `NoneType`, but `str` was expected. This is deprecated and will be an error in Spack v1.0
env.set(SPACK_DEBUG_LOG_DIR, spack.paths.spack_working_dir)
==> No patches needed for tutorial-mpileaks
==> tutorial-mpileaks: Executing phase: 'autoreconf'
==> [2026-06-19-08:14:41.833830] /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoreconf --install --verbose --force
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force -I m4
autoreconf: configure.ac: tracing
autoreconf: running: libtoolize --copy --force
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'config'.
libtoolize: copying file 'config/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.
libtoolize: copying file 'm4/libtool.m4'
libtoolize: copying file 'm4/ltoptions.m4'
libtoolize: copying file 'm4/ltsugar.m4'
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoconf --force
configure.ac:9: warning: 'AM_CONFIG_HEADER': this macro is obsolete.
configure.ac:9: You should use the 'AC_CONFIG_HEADERS' macro instead.
aclocal.m4:708: AM_CONFIG_HEADER is expanded from...
configure.ac:9: the top level
configure.ac:38: warning: The macro 'AC_PROG_LIBTOOL' is obsolete.
configure.ac:38: You should run autoupdate.
m4/libtool.m4:100: AC_PROG_LIBTOOL is expanded from...
configure.ac:38: the top level
configure.ac:47: warning: The macro 'AC_HEADER_STDC' is obsolete.
configure.ac:47: You should run autoupdate.
/tmp/root/spack-stage/spack-stage-autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/spack-src/lib/autoconf/headers.m4:663: AC_HEADER_STDC is expanded from...
configure.ac:47: the top level
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
configure.ac:26: installing 'config/compile'
configure.ac:19: installing 'config/missing'
src/Makefile.am:14: warning: 'INCLUDES' is the old name for 'AM_CPPFLAGS' (or '*_CPPFLAGS')
src/Makefile.am: installing 'config/depcomp'
autoreconf: Leaving directory '.'
==> tutorial-mpileaks: Executing phase: 'configure'
==> [2026-06-19-08:14:44.659730] Find (max depth = None): ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src'] ['configure']
==> [2026-06-19-08:14:44.660326] Find complete: ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src'] ['configure']
==> [2026-06-19-08:14:44.660557] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure [replacing "^(\s*if test x-L = )("\$p" \|\|\s*)$"]
==> [2026-06-19-08:14:44.674514] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure [replacing "^(\s*test x-R = )("\$p")(; then\s*)$"]
==> [2026-06-19-08:14:44.685908] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure [replacing "^(\s*test \$p = "-R")(; then\s*)$"]
==> [2026-06-19-08:14:44.697427] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure [replacing "lt_cv_apple_cc_single_mod=no"]
==> [2026-06-19-08:14:44.709950] /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure --prefix=/home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije
checking metadata... no
checking installation directory variables... yes
checking for a BSD-compatible install... /usr/bin/install -c
checking whether sleep supports fractional seconds... yes
checking filesystem timestamp resolution... 0.01
checking whether build environment is sane... yes
checking for a race-free mkdir -p... /usr/bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking xargs -n works... yes
checking whether UID '1001' is supported by ustar format... yes
checking whether GID '1001' is supported by ustar format... yes
checking how to create a ustar tar archive... gnutar
checking for gcc... /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether the compiler supports GNU C... yes
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc accepts -g... yes
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc option to enable C11 features... none needed
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc understands -c and -o together... yes
checking whether make supports the include directive... yes (GNU style)
checking dependency style of /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc... gcc3
checking whether the compiler supports GNU C++... yes
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ accepts -g... yes
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ option to enable C++11 features... none needed
checking dependency style of /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++... gcc3
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc... /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc
Checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc responds to '-showme:compile'... yes
configure: error: unable to locate adept-utils installation
Command exited with status 1:
/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije/spack-src/configure --prefix=/home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ije
In this case the error conveniently appears on the last line of the log and the output from spack install.
Here we also see a number of checks performed by the configure command.
Most importantly, the last line is very clear: configure: error: unable to locate adept-utils installation.
In other words, the installation path of the adept-utils dependency cannot be found.
Note
Spack automatically adds standard include and library directories to the compiler’s search path but it is not uncommon for this information to not get picked up.
Some software, like mpileaks, requires the paths to be explicitly provided on the command line.
Let’s investigate further from the staged build directory.
Building Manually¶
First let’s try to build the package manually to see if we can figure out how to solve the problem.
Let’s move to the build directory using the spack cd command:
$ spack cd tutorial-mpileaks
You should now be in the appropriate stage directory since this command moves us into the working directory of the last attempted build.
If not, you can cd into the directory above that contained the spack-build-out.txt file then into its spack-src subdirectory.
Now let’s ensure the environment is properly set up using the spack build-env command:
$ spack build-env tutorial-mpileaks bash
This command spawned a new shell containing the same environment that Spack used to build the tutorial-mpileaks package.
(Feel free to substitute your favorite shell for bash.)
Note
If you are running using an AWS instance, you’ll want to substitute your home directory for /home/spack below.
From here we can manually re-run the build using the configure command with the --prefix option that Spack passed in the failed build.
If you aren’t sure, check the appropriate line under Executing phase: 'configure' in the build log in Reviewing the Build Log.
$ ./configure --prefix=$HOME/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-olkbps3ghmpiiy4dserbxgj5hlsm5ij
checking metadata... no
checking installation directory variables... yes
checking for a BSD-compatible install... /usr/bin/install -c
checking whether sleep supports fractional seconds... yes
checking filesystem timestamp resolution... 0.01
checking whether build environment is sane... yes
checking for a race-free mkdir -p... /usr/bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking xargs -n works... yes
checking whether UID '1001' is supported by ustar format... yes
checking whether GID '1001' is supported by ustar format... yes
checking how to create a ustar tar archive... gnutar
checking for gcc... /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether the compiler supports GNU C... yes
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc accepts -g... yes
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc option to enable C11 features... none needed
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc understands -c and -o together... yes
checking whether make supports the include directive... yes (GNU style)
checking dependency style of /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/gcc... gcc3
checking whether the compiler supports GNU C++... yes
checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ accepts -g... yes
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++ option to enable C++11 features... none needed
checking dependency style of /home/spack/spack/opt/spack/linux-x86_64_v3/compiler-wrapper-1.1.0-mmywg7x4myxvxepmqe5go3ppxirmuijp/libexec/spack/gcc/g++... gcc3
checking for /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc... /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc
Checking whether /home/spack/spack/opt/spack/linux-x86_64_v3/openmpi-5.0.10-qfut5qqwp2fzaq3ymgk7nxvjv3qyrvml/bin/mpicc responds to '-showme:compile'... yes
configure: error: unable to locate adept-utils installation
Unfortunately we get the same results as before and the output does not provide any additional information that can help us with the build.
Given that this is a simple package built with configure and we know that installation directories need to be specified, we can use the command’s --help to see what options are available for the software.
$ ./configure --help
`configure' configures mpileaks 1.0 to adapt to many kinds of systems.
Usage: ./configure [OPTION]... [VAR=VALUE]...
To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE. See below for descriptions of some of the useful variables.
Defaults for the options are specified in brackets.
Configuration:
-h, --help display this help and exit
--help=short display options specific to this package
--help=recursive display the short help of all the included packages
-V, --version display version information and exit
-q, --quiet, --silent do not print `checking...' messages
--cache-file=FILE cache test results in FILE [disabled]
-C, --config-cache alias for `--cache-file=config.cache'
-n, --no-create do not create output files
--srcdir=DIR find the sources in DIR [configure dir or `..']
Installation directories:
--prefix=PREFIX install architecture-independent files in PREFIX
[/usr/local]
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
[PREFIX]
By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc. You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.
For better control, use the options below.
Fine tuning of the installation directories:
--bindir=DIR user executables [EPREFIX/bin]
--sbindir=DIR system admin executables [EPREFIX/sbin]
--libexecdir=DIR program executables [EPREFIX/libexec]
--sysconfdir=DIR read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR modifiable single-machine data [PREFIX/var]
--libdir=DIR object code libraries [EPREFIX/lib]
--includedir=DIR C header files [PREFIX/include]
--oldincludedir=DIR C header files for non-gcc [/usr/include]
--datarootdir=DIR read-only arch.-independent data root [PREFIX/share]
--datadir=DIR read-only architecture-independent data [DATAROOTDIR]
--infodir=DIR info documentation [DATAROOTDIR/info]
--localedir=DIR locale-dependent data [DATAROOTDIR/locale]
--mandir=DIR man documentation [DATAROOTDIR/man]
--docdir=DIR documentation root [DATAROOTDIR/doc/mpileaks]
--htmldir=DIR html documentation [DOCDIR]
--dvidir=DIR dvi documentation [DOCDIR]
--pdfdir=DIR pdf documentation [DOCDIR]
--psdir=DIR ps documentation [DOCDIR]
Program names:
--program-prefix=PREFIX prepend PREFIX to installed program names
--program-suffix=SUFFIX append SUFFIX to installed program names
--program-transform-name=PROGRAM run sed PROGRAM on installed program names
System types:
--build=BUILD configure for building on BUILD [guessed]
--host=HOST cross-compile to build programs to run on HOST [BUILD]
Optional Features:
--disable-option-checking ignore unrecognized --enable/--with options
--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
--disable-dependency-tracking speeds up one-time build
--enable-dependency-tracking do not reject slow dependency extractors
--enable-shared[=PKGS] build shared libraries [default=yes]
--enable-static[=PKGS] build static libraries [default=yes]
--enable-fast-install[=PKGS]
optimize for fast installation [default=yes]
--disable-libtool-lock avoid locking (might break parallel builds)
Optional Packages:
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--with-adept-utils=PATH Specify adept-utils path
--with-callpath=PATH Specify libcallpath path
--with-stack-start-c=value
Specify integer number for MPILEAKS_STACK_START for
C code
--with-stack-start-fortran=value
Specify integer number for MPILEAKS_STACK_START for
FORTRAN code
--with-pic try to use only PIC/non-PIC objects [default=use
both]
--with-gnu-ld assume the C compiler uses GNU ld [default=no]
Some influential environment variables:
CC C compiler command
CFLAGS C compiler flags
LDFLAGS linker flags, e.g. -L<lib dir> if you have libraries in a
nonstandard directory <lib dir>
LIBS libraries to pass to the linker, e.g. -l<library>
CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I<include dir> if
you have headers in a nonstandard directory <include dir>
CXX C++ compiler command
CXXFLAGS C++ compiler flags
CPP C preprocessor
CXXCPP C++ preprocessor
Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations.
Report bugs to <moody20@llnl.gov>.
The output shows that you can specify the paths for the two concrete dependencies with the following options:
--with-adept-utils=PATH--with-callpath=PATH
Let’s leave the spawned shell and return to the Spack repository directory:
$ exit
$ cd $SPACK_ROOT
Now that we know what arguments to provide, we can update the recipe.
Specifying Configure Arguments¶
We now know which options we need to pass to configure, but how do we know where to find the installation paths for the package’s dependencies from within the package.py file?
Fortunately, we can query the package’s concrete Spec instance.
The self.spec property holds the package’s directed acyclic graph (DAG) of its dependencies.
Each dependency’s Spec, accessed by name, has a prefix property containing its installation path.
So let’s add the configuration arguments for specifying the paths to the two concrete dependencies in the configure_args method of our package.
Bring tutorial-mpileaks’ package.py file back up with the spack edit command:
$ spack edit tutorial-mpileaks
and add the --with-adept-utils and --with-callpath arguments in the configure_args method as follows:
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack.package import *
class TutorialMpileaks(AutotoolsPackage):
"""Tool to detect and report leaked MPI objects like MPI_Requests and MPI_Datatypes."""
homepage = "https://github.com/LLNL/mpileaks"
url = "https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz"
maintainers("adamjstewart")
license("BSD", checked_by="adamjstewart")
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
depends_on("c", type="build")
depends_on("cxx", type="build")
depends_on("fortran", type="build")
depends_on("autoconf", type="build")
depends_on("automake", type="build")
depends_on("libtool", type="build")
depends_on("m4", type="build")
depends_on("mpi")
depends_on("adept-utils")
depends_on("callpath")
def autoreconf(self, spec, prefix):
autoreconf("--install", "--verbose", "--force")
def configure_args(self):
args = [
f"--with-adept-utils={self.spec['adept-utils'].prefix}",
f"--with-callpath={self.spec['callpath'].prefix}",
]
return args
Since this is an AutotoolsPackage, the arguments returned from the method will automatically get passed to configure during the build.
Now let’s try the build again:
$ spack install tutorial-mpileaks
[ ] 5smq7eq tutorial-mpileaks@1.0 fetching from build cache (0s)
[ ] 5smq7eq tutorial-mpileaks@1.0 no binary available (0s)
[ ] 5smq7eq tutorial-mpileaks@1.0 staging (0s)
[ ] 5smq7eq tutorial-mpileaks@1.0 autoreconf (0s)
[ ] 5smq7eq tutorial-mpileaks@1.0 configure (3s)
[ ] 5smq7eq tutorial-mpileaks@1.0 build (5s)
[ ] 5smq7eq tutorial-mpileaks@1.0 install (7s)
[+] 5smq7eq tutorial-mpileaks@1.0 /home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-5smq7equpaqqthqmmb5k4ysmlppr5y5w (7s)
Success!
All we needed to do was add the path arguments for the two concrete packages for configure to perform a simple build.
Is that all we can do to help other users build our software?
Adding Variants¶
Suppose we want to expose the software’s optional features in the package? We can do this by adding build-time options using package variants.
Recall from configure’s help output for tutorial-mpileaks that the software has several optional features and packages that we could support in Spack.
Two stand out for tutorial purposes because they both take integers, as opposed to allowing them to be enabled or disabled.
Optional Features:
--disable-option-checking ignore unrecognized --enable/--with options
--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
--disable-dependency-tracking speeds up one-time build
--enable-dependency-tracking do not reject slow dependency extractors
--enable-shared[=PKGS] build shared libraries [default=yes]
--enable-static[=PKGS] build static libraries [default=yes]
--enable-fast-install[=PKGS]
optimize for fast installation [default=yes]
--disable-libtool-lock avoid locking (might break parallel builds)
Optional Packages:
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--with-adept-utils=PATH Specify adept-utils path
--with-callpath=PATH Specify libcallpath path
--with-stack-start-c=value
Specify integer number for MPILEAKS_STACK_START for
C code
--with-stack-start-fortran=value
Specify integer number for MPILEAKS_STACK_START for
FORTRAN code
--with-pic try to use only PIC/non-PIC objects [default=use
both]
--with-gnu-ld assume the C compiler uses GNU ld [default=no]
According to the software’s documentation (https://github.com/LLNL/mpileaks), the integer values for the --with-stack-start-* options represent the numbers of calls to shave off of the top of the stack traces for each language, effectively reducing the noise of internal mpileaks library function calls in generated traces.
For simplicity, we’ll use one variant to supply the value for both arguments.
Supporting this optional feature will require two changes to the package:
add a variant directive; and
change the configure options to use the value.
Let’s add the variant to expect an int value with a default of 0.
Setting the default to 0 effectively disables the option.
Change configure_args to retrieve the value and add the corresponding configure arguments when a non-zero value is provided by the user.
Bring tutorial-mpileaks’ package.py file back up with the spack edit command:
$ spack edit tutorial-mpileaks
and add the variant directive and associated arguments as follows:
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack.package import *
class TutorialMpileaks(AutotoolsPackage):
"""Tool to detect and report leaked MPI objects like MPI_Requests and MPI_Datatypes."""
homepage = "https://github.com/LLNL/mpileaks"
url = "https://github.com/LLNL/mpileaks/archive/refs/tags/v1.0.tar.gz"
maintainers("adamjstewart")
license("BSD", checked_by="adamjstewart")
version("1.0", sha256="24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9")
variant(
"stackstart",
values=int,
default="0",
description="Specify the number of stack frames to truncate",
)
depends_on("c", type="build")
depends_on("cxx", type="build")
depends_on("fortran", type="build")
depends_on("autoconf", type="build")
depends_on("automake", type="build")
depends_on("libtool", type="build")
depends_on("m4", type="build")
depends_on("mpi")
depends_on("adept-utils")
depends_on("callpath")
def autoreconf(self, spec, prefix):
autoreconf("--install", "--verbose", "--force")
def configure_args(self):
args = [
f"--with-adept-utils={self.spec['adept-utils'].prefix}",
f"--with-callpath={self.spec['callpath'].prefix}",
]
stackstart = int(self.spec.variants["stackstart"].value)
if stackstart:
args.extend(
[
f"--with-stack-start-c={stackstart}",
f"--with-stack-start-fortran={stackstart}",
]
)
return args
Notice that the variant directive is translated into a variants dictionary in self.spec.
Also note that the value provided by the user is accessed by the entry’s value property.
Now run the installation again with the --verbose install option – to get more output during the build – and the new stackstart package option:
$ spack install --verbose tutorial-mpileaks stackstart=4
[ ] uqw7gjz tutorial-mpileaks@1.0 fetching from build cache (0s)
[ ] uqw7gjz tutorial-mpileaks@1.0 no binary available (0s)
/home/spack/spack/lib/spack/spack/build_environment.py:490: SpackAPIWarning: when setting environment variable SPACK_DEBUG_LOG_DIR=None: value is of type `NoneType`, but `str` was expected. This is deprecated and will be an error in Spack v1.0
env.set(SPACK_DEBUG_LOG_DIR, spack.paths.spack_working_dir)
[ ] uqw7gjz tutorial-mpileaks@1.0 staging (0s)
==> Using cached archive: /home/spack/spack/var/spack/cache/_source-cache/archive/24/24c706591bdcd84541e19389a9314813ce848035ee877e213d528b184f4b43f9.tar.gz
==> No patches needed for tutorial-mpileaks
[ ] uqw7gjz tutorial-mpileaks@1.0 autoreconf (0s)
==> tutorial-mpileaks: Executing phase: 'autoreconf'
==> [2026-06-19-08:15:04.132963] /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoreconf --install --verbose --force
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force -I m4
autoreconf: configure.ac: tracing
autoreconf: running: libtoolize --copy --force
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'config'.
libtoolize: copying file 'config/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.
libtoolize: copying file 'm4/libtool.m4'
libtoolize: copying file 'm4/ltoptions.m4'
libtoolize: copying file 'm4/ltsugar.m4'
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoconf --force
configure.ac:9: warning: 'AM_CONFIG_HEADER': this macro is obsolete.
configure.ac:9: You should use the 'AC_CONFIG_HEADERS' macro instead.
aclocal.m4:708: AM_CONFIG_HEADER is expanded from...
configure.ac:9: the top level
configure.ac:38: warning: The macro 'AC_PROG_LIBTOOL' is obsolete.
configure.ac:38: You should run autoupdate.
m4/libtool.m4:100: AC_PROG_LIBTOOL is expanded from...
configure.ac:38: the top level
configure.ac:47: warning: The macro 'AC_HEADER_STDC' is obsolete.
configure.ac:47: You should run autoupdate.
/tmp/root/spack-stage/spack-stage-autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/spack-src/lib/autoconf/headers.m4:663: AC_HEADER_STDC is expanded from...
configure.ac:47: the top level
autoreconf: running: /home/spack/spack/opt/spack/linux-x86_64_v3/autoconf-2.72-jo3eg4rjvufc6kzkann5rfyufgoc4lbj/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
configure.ac:26: installing 'config/compile'
configure.ac:19: installing 'config/missing'
src/Makefile.am:14: warning: 'INCLUDES' is the old name for 'AM_CPPFLAGS' (or '*_CPPFLAGS')
src/Makefile.am: installing 'config/depcomp'
autoreconf: Leaving directory '.'
[ ] uqw7gjz tutorial-mpileaks@1.0 configure (3s)
==> tutorial-mpileaks: Executing phase: 'configure'
==> [2026-06-19-08:15:06.999128] Find (max depth = None): ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src'] ['configure']
==> [2026-06-19-08:15:06.999445] Find complete: ['/tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src'] ['configure']
==> [2026-06-19-08:15:06.999596] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src/configure [replacing "^(\s*if test x-L = )("\$p" \|\|\s*)$"]
==> [2026-06-19-08:15:07.012575] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src/configure [replacing "^(\s*test x-R = )("\$p")(; then\s*)$"]
==> [2026-06-19-08:15:07.024255] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src/configure [replacing "^(\s*test \$p = "-R")(; then\s*)$"]
==> [2026-06-19-08:15:07.035820] FILTER FILE: /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src/configure [replacing "lt_cv_apple_cc_single_mod=no"]
==> [2026-06-19-08:15:07.048639] /tmp/spack/spack-stage/spack-stage-tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o/spack-src/configure --prefix=/home/spack/spack/opt/spack/linux-x86_64_v3/tutorial-mpileaks-1.0-uqw7gjziuodsipdlhmg3lqtdx7shub3o --with-adept-utils=/home/spack/spack/opt/spack/linux-x86_64_v3/adept-utils-1.0.1-naehq6ldodlwm7gjgdnccsxchnuphuep --with-callpath=/home/spack/spack/opt/spack/linux-x86_64_v3/callpath-1.0.4-xksxwmqijjrelztluyq5oilu4tqkyxf6 --with-stack-start-c=4 --with-stack-start-fortran=4
Notice the addition of the two stack start arguments in the configure command at the end of the emphasized line after tutorial-mpileaks’ Executing phase: 'configure'.
Note
Not all packages have such simple options.
Fortunately, Autotools is one of several base packages with helper functions to simplify setting arguments tied to boolean, single- and multi-valued variants.
Querying the Spec Object¶
As packages evolve and are ported to different systems, build recipes often need to change as well.
This is where the package’s Spec comes in.
Previously, we’ve looked at getting the paths for dependencies and values of variants from the Spec; however, there is more to consider.
The package’s self.spec property allows you to query information about the package build, such as:
how a package’s dependencies were built;
what compiler was used;
what version of a package is being installed; and
what variants were specified (implicitly or explicitly).
Examples of common queries are provided below.
Querying Spec Versions¶
You can customize the build based on the version of the package, compiler, and dependencies using version constraints. Examples of each customization are:
Am I building my package with version
1.1or greater?
if self.spec.satisfies("@1.1:"):
# Do things needed for version 1.1 or newer
...
Am I building with a
gccversion up to5.0?
if self.spec.satisfies("%gcc@:5.0"):
# Add arguments specific to gcc's up to 5.0
...
Is my
dyninstdependency at least version8.0?
if self.spec["dyninst"].satisfies("@8.0:"):
# Use newest dyninst options
...
Querying Spec Names¶
If the build has to be customized to the concrete version of a virtual dependency, you can use the name property of the Spec.
For example:
Is
openmpithe MPI implementation I’m building with?
if self.spec["mpi"].name == "openmpi":
# Do openmpi things
...
Querying Variants¶
Adjusting build options based on enabled variants can be done by querying the Spec itself, such as:
Am I building with the
debugvariant?
if "+debug" in self.spec:
# Add -g option to configure flags
...
These are just a few examples of Spec queries.
Spack has thousands of built-in packages that can serve as examples to guide the development of your package.
Tip
You can find these packages under the spack/spack-packages repository’s repos/spack_repo/builtin/packages directory.
Or use spack pkg grep to perform a query.
For example, to find the paths to all AutotoolsPackage packages in your configured repositories, you can enter spack pkg grep AutotoolsPackage | sed "s/:.*//g" | sort -u at the command line.
Multiple Build Systems¶
There are cases where software actively supports two build systems, changes build systems as it evolves, or needs different build systems on different platforms. Spack allows you to write a single, concise recipe for these cases that generally require minor changes to the package structure.
Let’s take a look at a simplified package for uncrustify, which is a source code beautifier.
This software builds with Autotools up through version 0.63 but switches to CMake at version 0.64.
Therefore Uncrustify needs to import and inherit from both CMakePackage and AutotoolsPackage.
We also need to explicitly specify the build_system directive, and add conditional dependencies accordingly:
from spack_repo.builtin.build_systems.autotools import AutotoolsPackage
from spack_repo.builtin.build_systems.cmake import CMakePackage
from spack.package import *
class Uncrustify(CMakePackage, AutotoolsPackage):
"""Source Code Beautifier for C, C++, C#, ObjectiveC, Java, and others."""
homepage = "http://uncrustify.sourceforge.net/"
git = "https://github.com/uncrustify/uncrustify"
url = "https://sourceforge.net/projects/uncrustify/files/uncrustify/uncrustify-0.69/uncrustify-0.69.tar.gz"
license("GPL-2.0-or-later")
version("0.69", commit="a7a8fb35d653e0b49e1c86f2eb8a2970025d5989")
version("0.64", commit="1d7d97fb637dcb05ebc5fe57ee1020e2a659210d")
version("0.63", commit="44ce0f156396b79ddf3ed9242023a14e9665b76f")
depends_on("c", type="build")
depends_on("cxx", type="build")
build_system(
conditional("cmake", when="@0.64:"),
conditional("autotools", when="@:0.63"),
default="cmake",
)
with when("build_system=autotools"):
depends_on("automake", type="build")
depends_on("autoconf", type="build")
depends_on("libtools", type="build")
As we saw with tutorial-mpileaks, each spec has a build_system variant that specifies the build system it uses.
In most cases that variant has a single allowed value, inherited from the corresponding base package - so, usually, you don’t have to think about it.
When your package supports more than one build system though, you have to explicitly declare which ones are allowed and under what conditions.
In the example above it’s cmake for version 0.64 and higher and autotools for version 0.63 and lower.
The build_system variant can also be used to declare other properties which are conditional on the build system being selected.
For instance, above we use the when context manager to declare that autotools builds depend on automake, autoconf, and libtools being installed first.
The other relevant difference, compared to previous recipes we have seen so far, is that the code prescribing the installation procedure will live in two separate classes:
# Be sure to include the corresponding imports at the top of the package.
from spack_repo.builtin.build_systems import autotools, cmake
...
class CMakeBuilder(cmake.CMakeBuilder):
def cmake_args(self):
pass
class AutotoolsBuilder(autotools.AutotoolsBuilder):
def configure_args(self):
pass
Depending on the spec, and more specifically on the value of the build_system directive, a Builder object will be instantiated from one of the two classes when an installation is requested from a user.
Cleaning Up¶
Before leaving this tutorial, let’s ensure that our work does not interfere with your Spack instance or future sections of the tutorial. Undo the work we’ve done here by entering the following commands:
$ spack uninstall -ay tutorial-mpileaks
==> Successfully uninstalled tutorial-mpileaks@1.0 build_system=autotools platform=linux os=ubuntu26.04 target=x86_64_v3/5smq7eq
==> Successfully uninstalled tutorial-mpileaks@1.0 build_system=autotools stackstart=4 platform=linux os=ubuntu26.04 target=x86_64_v3/uqw7gjz
$ spack repo remove tutorial
==> Removed repository 'tutorial' from scope 'user'.
$ rm -rf $HOME/my_pkgs
More information¶
This tutorial module only scratches the surface of defining Spack package recipes. The packaging guide, split over four sections, covers packaging topics more thoroughly:
testing; and
advanced topics, such as multiple build systems and external detection.
Additional information on key topics can be found in the embedded keys above and at the links below.
Testing an installation¶
Build-time tests: for sanity checks and pre-/post-
buildand orinstallphase tests.Stand-alone tests: for tests that can run against any installed Spack package.
Using other build systems¶
Build Systems: for the full list of built-in build systems.
Spack Package Build Systems tutorial: for tutorials on common build systems.
Multiple Build Systems: for a reference on writing packages with multiple build systems.
Package Class Architecture: for more insight on the inner workings of
PackageandBuilderclasses.The GDAL Package: for an example of a complex package that extends Python while supporting two build systems.
Making a package externally detectable¶
Making a package externally discoverable: for making a package discoverable using the
spack external findcommand.