-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Deploying to gh-pages from @ 07ca5b9 🚀
- Loading branch information
0 parents
commit 8e32f1a
Showing
72 changed files
with
10,844 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| # Sphinx build info version 1 | ||
| # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
| config: 48662ac6cc854ec2c56a6fe03393a76b | ||
| tags: 645f666f9bcd5a90fca523b33c5a78b7 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| # This workflow will install Python dependencies, run tests and lint with a variety of Python versions | ||
| # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions | ||
|
|
||
| name: Tests | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ main ] | ||
| pull_request: | ||
| branches: [ main ] | ||
|
|
||
| jobs: | ||
| unit-tests: | ||
| runs-on: ubuntu-latest | ||
| env: | ||
| SPACK_MANAGER: ${{github.workspace}} | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| python-version: [3.7, 3.8, 3.9] | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| submodules: recursive | ||
| - name: Set up Python ${{ matrix.python-version }} | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: ${{ matrix.python-version }} | ||
| - name: Run unit tests | ||
| run: ./run_tests.sh | ||
| style-checks: | ||
| runs-on: ubuntu-latest | ||
| env: | ||
| SPACK_MANAGER: ${{github.workspace}} | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| python-version: [3.7] | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| submodules: recursive | ||
| - name: Set up Python ${{ matrix.python-version }} | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: ${{ matrix.python-version }} | ||
| - name: Install dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| python -m pip install flake8 pytest | ||
| if [ -f requirements.txt ]; then pip install -r requirements.txt; fi | ||
| - name: Link scripts with flake8 | ||
| run: | | ||
| # flake8 on scripts that aren't spack extensions | ||
| flake8 . | ||
| - name: Spack Style | ||
| run: | | ||
| # check our spack extension with spack's style guide | ||
| source start.sh | ||
| spack style spack-scripting | ||
| concretization-basic: | ||
| runs-on: ${{matrix.os}} | ||
| env: | ||
| SPACK_MANAGER: ${{github.workspace}} | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| python-version: [3.7] | ||
| os: [ubuntu-latest, macos-latest] | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| submodules: recursive | ||
| - name: Set up Python ${{ matrix.python-version }} | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: ${{ matrix.python-version }} | ||
| - name: Install dependencies | ||
| run: | | ||
| if [ -f requirements.txt ]; then pip install -r requirements.txt; fi | ||
| - name: Run concretization tests | ||
| run: | | ||
| source start.sh | ||
| # test and make sure the solver is working for env using clingo | ||
| spack solve exawind 1> /dev/null | ||
| tests/ci_config_concretization.py -y env-templates/exawind_basic.yaml | ||
| concretization-matrix: | ||
| runs-on: ${{matrix.os}} | ||
| env: | ||
| SPACK_MANAGER: ${{github.workspace}} | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| python-version: [3.7] | ||
| os: [ubuntu-latest] | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| submodules: recursive | ||
| - name: Set up Python ${{ matrix.python-version }} | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: ${{ matrix.python-version }} | ||
| - name: Install dependencies | ||
| run: | | ||
| if [ -f requirements.txt ]; then pip install -r requirements.txt; fi | ||
| - name: Run concretization tests | ||
| run: | | ||
| source start.sh | ||
| # test and make sure the solver is working for env using clingo | ||
| spack solve exawind 1> /dev/null | ||
| tests/ci_config_concretization.py -y env-templates/exawind_matrix.yaml |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| General Information | ||
| =================== | ||
|
|
||
| This section is for documenting the general concepts of how Spack-Manager works, | ||
| and documentation that is applicable to all users of this software. | ||
|
|
||
| .. toctree:: | ||
| :glob: | ||
| :maxdepth: 2 | ||
|
|
||
| spack_manager_structure | ||
| spack_features | ||
| history |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # History and inspirations for Spack-Manager | ||
|
|
||
| Spack-Manager was created due to the challenges of building the complicated [Exawind](https://github.com/Exawind) software stack. | ||
| The Exawind codes have a relatively large number of TPL's and are designed to run on modern HPC architecture, which is currently a moving target. | ||
| These factors naturally lead toward using [Spack](https://github.com/spack/spack) to manage the build dependencies. | ||
|
|
||
| Arguably the most common use case for Spack is software deployment. | ||
| This was the original use for Exawind developers, and a few different extra scripts were maintained for managing the build process for Exawind software. | ||
| However, during the Exawind project Spack also released features geared toward development. | ||
| This sparked the idea for the central question behind Spack-Manager: **how much of our process can we reasonably extend into the Spack ecosystem?** | ||
|
|
||
| Initial evaluations of Spack's develop features were that there was potential, but also room to grow. | ||
| These features have since improved, but the other tenant of Spack-Manager was determined from this trial period: **end products need to live as independent from Spack as possible**. | ||
| This really comes down to the fact that Exawind stack was constantly changing and growing, along with Spack itself. | ||
| In reality the entire HPC and computing landscape is changing dramatically, and so our development frameworks need to be moving together, but still have room to independently flex as thing evolve. | ||
| In this sense Spack-Manager acts as a buffer in between the larger Spack project, and the invidual software projects that are using Spack-Manager to curate their development process. | ||
|
|
||
| Spack-Manager's development obtained a lot of inspiration from the [Exawind-Builder](https://github.com/Exawind/exawind-builder) project. | ||
| Spack-Manager has sought to emulate some of the key features of Exawind-Builder such as the ability to use pre-configured binaries, and to allow users to quickly switch between caches. | ||
| Exawind-Builder was a tool principly designed for developers, and Spack-Manager strives to extend that user scope to the entire range of software users. | ||
|
|
||
| Exawind-Builder is also another example of a tool built on-top of Spack. | ||
| However, the strategies of Spack-Manager and Exawind-Builder differ slightly in that Exawind-Builder sought to go around Spack's missing features through additional bash scripting and environment configurations, while Spack-Manager seeks to predominately extend Spack using the Spack ecosystem for these scenarios. | ||
| Both sides have pro's and con's. | ||
| Choosing to go around Spack makes it easier to customize things with fewer limitations, but it also requires additional code, interfaces and maintenance. | ||
| Choosing to conform to Spack infrastructure means accepting some of the limitations and growing pains of the Spack API, but also reducing the amount of infrastructure that needs to be maintained. | ||
| This is constantly becoming less of a sacrifice due to the quality of work done by the Spack development team. | ||
|
|
||
| Spack-Manager is intended to be agile, and adapt to changes in Spack by embracing new features in Spack, and contributing back everything it can to the Spack project. | ||
| In this sense we are able to harness the pro's of Spack, while still customizing our workflow and influencing the growth of Spack in the future. | ||
|
|
||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,155 @@ | ||
| # Important Spack Features | ||
|
|
||
| ## Spack Specs | ||
|
|
||
| In Spack the idea of a _spec_ is very important. Specs are descriptors of particular aspects or configurations of a package or packages. | ||
| Specs can completely general, merely denoted the name of a package, or they can very specific such as specifying the name of the package with a particular version, with a particular compiler and compiler version, with specific options called _variants_, as well as constraints on dependencies of the package. | ||
| Spack's documentation has much more information on specs [here](https://spack.readthedocs.io/en/latest/basic_usage.html#specs-dependencies), but we summarize them here as it is important to utilizing Spack. | ||
| Specs are a loose or general form of a configuration for a package. However, Spack is very exact it how it will build and satisfy your requested spec. | ||
| It does this through the process of _concretization_. Concretization maps a spec, no matter how general or specific, into an _exact_ graph of | ||
| how Spack will build and fulfill the spec. A command for understanding this process is the `spack spec` command. Using `spack spec` | ||
| will report to the user how Spack will create a concrete graph or DAG of the package on its dependencies. For example: | ||
|
|
||
| ``` | ||
| % spack spec zlib | ||
| Input spec | ||
| -------------------------------- | ||
| zlib | ||
|
|
||
| Concretized | ||
| -------------------------------- | ||
| [email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
| ``` | ||
|
|
||
| Here we intend to install the zlib package which has no dependencies. If we specify nothing but `zlib`, this is the configuration Spack has solved | ||
| in which it will fulfill the installation of zlib. We can be more specific about our request. Looking at what compilers are available for us in Spack | ||
| we can use: | ||
| ``` | ||
| % spack compilers | ||
| ==> Available compilers | ||
| -- apple-clang catalina-x86_64 ---------------------------------- | ||
| [email protected] | ||
|
|
||
| -- gcc catalina-x86_64 ------------------------------------------ | ||
| [email protected] | ||
| ``` | ||
|
|
||
| Here we are on a MacOS computer and we have two compilers available. If I prefer `zlib` be installed using gcc, one can use: | ||
| ``` | ||
| % spack spec zlib%gcc | ||
| Input spec | ||
| -------------------------------- | ||
| zlib%gcc | ||
|
|
||
| Concretized | ||
| -------------------------------- | ||
| [email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
| ``` | ||
|
|
||
| Notice Spack honored our compiler constraint request. Spack reports the concretized spec in a manner that continues to itself be a spec: | ||
| ``` | ||
| % spack spec [email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
| Input spec | ||
| -------------------------------- | ||
| [email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
|
|
||
| Concretized | ||
| -------------------------------- | ||
| [email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
| ``` | ||
|
|
||
| Therefore using the `spec` command helps us to understand specs and what Spack will do with a spec before we use them in other commands. | ||
| Here is an example of a more complicated package: | ||
| ``` | ||
| % spack spec amr-wind | ||
| Input spec | ||
| -------------------------------- | ||
| amr-wind | ||
|
|
||
| Concretized | ||
| -------------------------------- | ||
| amr-wind@main%[email protected]~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~doc+ncurses+openssl+ownlibs~qt build_type=Release arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~symlinks+termlib abi=none arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~docs certs=system arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+cpanm+shared+threads arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+cxx~docs+stl patches=b231fcc4d5cff05e5c3a4814f6a5af0e9a966428dc2176540d2c05aff41de522 arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~debug~pic+shared arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] libs=shared,static arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+optimize+pic+shared arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~complex~cuda~debug+int64~internal-superlu~mixedint+mpi~openmp+shared~superlu-dist~unified-memory arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~external-blas~ipo+lapacke+shared~xblas build_type=Release arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~atomics~cuda~cxx~cxx_exceptions+gpfs~internal-hwloc~java~legacylaunchers~lustre~memchecker~pmi~pmix+romio~singularity~sqlite3+static~thread_multiple+vt+wrapper-rpath fabrics=none schedulers=none arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~cairo~cuda~gl~libudev+libxml2~netloc~nvml~opencl~pci~rocm+shared arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~python arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~pic libs=shared,static arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+openssl arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~dap~fsync~hdf4~jna+mpi+parallel-netcdf+pic+shared patches=2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53 arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+cxx~fortran+hl~ipo~java+mpi+shared~szip~threadsafe+tools api=default build_type=RelWithDebInfo patches=2a1e3118d7d3d7411820e567b03530de96a46385304017f8e548408aa1cfbfc0 arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]+sigsegv patches=9dc5fbd0d5cb1037ab1e6d0ecc74a30df218d0a94bdd5a02759a97f62daca573,bfdffa7c2eb01021d5849b36972c069693654ad826c1a20b53534009a4ec7a89 arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected] arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~burstbuffer+cxx+fortran+pic+shared arch=darwin-catalina-skylake | ||
| ``` | ||
|
|
||
| It is obvious concretized specs can get large quite quickly. However, Spack is very good at standing on it's own without requirements | ||
| from the existing system. Therefore it can be quite straightforward to build complicated packages on many machines. However, it can also be argued | ||
| that this situation involves many packages with Spack will build that may already exist on the machine. While this is fair, we typically solve | ||
| this by specifying `externals` which make Spack aware of packages already existing on the system and utilizing them in its DAG. Spack-manager | ||
| has machine-specific configurations provided by its contributors for this purpose. Obtaining a configuration for Spack for the specific machine | ||
| and specific project will save the user of Spack a lot of time. | ||
|
|
||
| In our previous concretized DAG, `amr-wind` has dependencies on packages. Dependencies in specs are denoted with `^`. We can use this to constrain dependencies we would like to request. | ||
| For example here we put a constraint on the cmake version: | ||
| ``` | ||
| % spack spec amr-wind ^[email protected] | ||
| Input spec | ||
| -------------------------------- | ||
| amr-wind | ||
| ^[email protected] | ||
|
|
||
| Concretized | ||
| -------------------------------- | ||
| amr-wind@main%[email protected]~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~doc+ncurses+openssl+ownlibs~qt build_type=Release patches=1c540040c7e203dd8e27aa20345ecb07fe06570d56410a24a266ae570b1c4c39,bf695e3febb222da2ed94b3beea600650e4318975da90e4a71d6f31a6d5d8c3d,e51119dd387aa3eb2f21fee730d3aa8b5480301c5e2e3a33bd86f4f7d8903861 arch=darwin-catalina-skylake | ||
| ^[email protected]%[email protected]~symlinks+termlib abi=none arch=darwin-catalina-skylake | ||
| ... | ||
| ``` | ||
| Concretization is an NP-hard problem, so solving the DAG is not instantaneous, and it is very much an active area of research. Spack has | ||
| gone through one iteration thus far of updating its concretization strategy. This is the difference between the "original" concretizer and the newer clingo concretizer. | ||
|
|
||
| Another important idea in Spack is describing the configuration of a particular package involving a complicated DAG into a succint string for the installation directory of the package for example. To do this, Spack collapses several properties of the DAG into a _hash_. Spack then uses this hash to provide a short form mapping for a particular package and its full description. Spack is a very powerful database of software installations and can be queried to understand the exact state of each package and pinpointing a specific package in which the user is interested. We leave these to the Spack documentation to continue. | ||
|
|
||
|
|
||
| ## Spack Commands | ||
|
|
||
| Spack has many commands, many of which have great information when adding `-h` to them. Here we list a few of the most important commands for using within Spack-Manager. | ||
|
|
||
| - `spack spec -I <spec> `: solve the DAG for the spec and show packages in the DAG that are already installed | ||
| - `spack location -i <spec> `: used for finding the specific location of an installed package | ||
| - `spack concretize -f `: force an activated environment to undergo concretization | ||
| - `spack install `: install all packages listed in an environment's `spack.yaml` file | ||
| - `spack uninstall <spec>`: uninstall specific spec | ||
| - `spack uninstall --dependencies -a -y <spec>`: uninstall everything related to a general spec (`-a`) and all its dependencies without confirming | ||
| - `spack cd -b <spec> `: change to build directory of package | ||
| - `spack env activate -d <path> ` or `spacktivate -d <path>`: activate a Spack environment at specified path | ||
| - `spack develop <spec> `: develop source code in a package locally | ||
| - `spack help --all `: list all available Spack commands | ||
| - `spack list <string>`: list all available Spack packages matching the string | ||
| - `spack find <spec>`: query Spack's database of installed packages | ||
| - `spack find -Lvd <spec>`: list the hashes, variants, and dependencies of the provided spec | ||
| - `spack stage <spec> && spack cd <spec>`: download the package's source code and extract it for browsing | ||
| - `spack docs`: open the online spack documentation in a browser | ||
| - `spack -d <spack subcommand>`: get debug info on exactly what Spack is doing when it fails | ||
| - `spack config blame packages`: show exactly where Spack is obtaining its preferences for things like concretization | ||
| - `spack compilers`: list the compilers in which Spack is aware | ||
|
|
||
|
|
||
| ## Spack Knowledgebase | ||
|
|
||
| In each package installation directory in `spack/opt` Spack keeps a `.spack` directory which contains information on exactly how the package was built. |
Oops, something went wrong.