This is the source tree for SPIRAL. It builds and runs on Windows, Linux, and macOS.
SPIRAL builds on Linux/Unix with gcc and make, on Windows it builds with Visual Studio.
For macOS SPIRAL requires version 10.14 (Mojave) or later of macOS, with a compatible version of Xcode and and Xcode Command Line Tools.
Use the most recent version of CMake 3 available for your platform. You can download CMake from cmake.org.
The SPIRAL Profiler requires Python 3, which you can get from python.org.
From the top directory of the SPIRAL source tree:
mkdir build
cd build
cmake ..
make install
A number of the tests and examples in the release require a GPU in order to work. If the system you are building for has no GPU support (i.e., no CUDA toolkit is installed) these examples/tests will be skipped.
NOTE: Even if your system has no CUDA support spiral can still generate CUDA code (it just cannot be compiled and tested).
Use the spiral script in the bin directory to start SPIRAL. You can run it from that directory
or set your path to include it and run spiral from elsewhere. The actual executable is
gap/bin/gap, but it must be started with the spiral script in order to intialize and run
correctly.
NOTE: The spiral script is automatically created, with defaults appropriate to your environment, during the build process, at the install step.
To build a debug version of SPIRAL for use with gdb, from the top directory:
mkdir buildd
cd buildd
cmake -DCMAKE_BUILD_TYPE=Debug ..
make install
This will put the executable, gapd, in gap/bin. Use the spirald script to run SPIRAL
in gdb.
In the top directory of the SPIRAL source tree, make a directory called build. From a terminal window in the build directory enter one of the following commands, depending on your version of Visual Studio. See the CMake documentation if your version isn't shown here.
cmake .. (for Visual Studio 2019)
cmake -G "Visual Studio 14 2015" -A x64 ..
cmake -G "Visual Studio 15 2017" -A x64 ..
When CMake is finished, the software can be built either using cmake or with Visual Studio.
Open the new SPIRAL.sln in the build directory with Visual Studio. Select the Release or Debug configuration, then right click on INSTALL in the Solution Explorer window and select Build from the popup menu.
Use spiral.bat to launch Spiral. You can create a shortcut to it (right click -> Create
shortcut) and move the shortcut to a convenient location, like the Desktop, renaming it if you
desire. Then you can edit the shortcut's properties (right click -> Properties) and set Start
in to some directory other than the repository root. The Start in directory is the default
location for SPIRAL to write generated files. You can also add the top bin directory of the SPIRAL
source tree to your path and run the batch script as spiral from a command window or script.
To debug SPIRAL on Windows, build and install the Debug version, use spiral_debug.bat to start SPIRAL, then in Visual Studio use Debug->Attach to Process... to connect the debugger to gapd.exe.
There are a few pre-requisites for Visual Studio to be able to correctly run the profiler from SPIRAL. These may be checked/configured as follows:
- Start Visual Studio Installer
- Select Modify button
- Select Individual Components (the components already installed are listed under Installation Details to the right)
- Ensure (or add) the following components:
- Python language support
- MSVC v142 - VS 2019 C++ x64/x86 build tools
- Python 3 64-bit (3.7.X)
- C++ CMake tools for Windows
- Windows 10 SDK (10.0.NNNNN...)
- If you add any components select the Modify button to download and install the required packages.
cmake can be used to start the toolchain to build the solution from a cmd window, instead of
starting the Visual Studio IDE. After running the cmake command to configure the build system
(i.e., cmake .. or other variant as discussed above), run the following:
cmake --build <dir> [options] [--[native-options]]
Typical options used with the command are:
<dir> Project directory to build
--target <tgt> Build <tgt> instead of the default target(s)
--config <cfg> For multi-configuration tools, choose <cfg>
--clean-first Build target "clean" first, then build
--verbose Enable verbose output
For example, the following commands will build the Release version on Windows using the default VS 2019 compiler and install the binary and batch scripts:
cmake ..
cmake --build . --config Release --target install
SPIRAL is released with a suite of self-tests. The tests are automatically configured and made available when CMake configures the installation. Normally, all tests are configured; however, if a platform does not provide required support for a test it will not be configured (e.g., X86/SIMD tests are not configured for ARM processor).
All tests can be run using make test from the <build> folder, as follows:
cd build
make test
The CMake test driver program, ctest, can be used to exercise control
over which tests are run. You can run a specific named test, tests matching a
specific type, or all tests using ctest. A couple of examples are shown
here (refer to the CMake/ctest documetation for a full explanation of all
options). The -L and -R options take a regular expression argument to
identify which tests to run. -L matches against a label associated to
each test, while -R matches against the name of the test.
cd build
ctest -R Simple-FFT # Run the test matching the name "Simple-FFT"
ctest -R [.]*FFT[.]* # Run all test(s) with "FFT" in the name
ctest -L Basic # Run all test(s) with label "Basic"
ctest # Run all tests
It is possible to disable the setup of tests when configuring the installation with CMake. There are five categories of tests: Basic, Advanced, Scalar-Transforms, OpenMP, and X86-SIMD. Each category of test may be turned off by adding a define on the cmake command line, as follows:
-DTESTS_RUN_BASIC=OFF # Turn off basic tests
-DTESTS_RUN_ADVANCED=OFF # Turn off Advanced tests
-DTESTS_RUN_SCALAR_TRANSFORMS=OFF # Turn off FFT tests
-DTESTS_RUN_OPENMP=OFF # Turn off Search tests
-DTEST_RUN_X86_SIMD=OFF # Turn off X86-SIMD tests
make is genarally not available on Windows, so we need to use ctest in
order to run the tests. For Windows ctest needs to be informed which
configuration was built, using the -C <config> option; where <config>
is typically Release or Debug. Other than this caveat, tests are configured, run, or
inhibited exactly the same on Windows as Linux/Unix. For example:
cd build
ctest -C Release -R Simple-FFT # Run the test matching the name "Simple-FFT" on Release build
ctest -C Release -R [.]*FFT[.]* # Run all test(s) with "FFT" in the name on Release build
ctest -C Debug -L Basic # Run all test(s) with label "Basic" on Debug build
ctest -C Release # Run all tests on Release build
Should a test fail you can view the complete test inputs/outputs generated
during the test run. Beneath the <build> folder is a Testing/Temporary
folder where ctest logs all the generated information. The data for the
last test run is contained in the file LastTest.log. A record of failed
tests is available in the file LastTestFailed.log.
The performance measurement functionality is in the profiler subdirectory. It has the mechanisms for asynchronously measuring code performance. Refer to the README in the profiler directory.
The interface from SPIRAL to the profiler is in namespaces/spiral/profiler.
Several tests rely in the profiler to build and measure performance in order to arrive at a "good" solution. A basic functionality test for the profiler is run as part of the basic tests. If this test is not successful then later, more advanced, tests depening on profiler will be skipped.
NOTE: linux differentiates between skipped and failed tests and summarizes those results appropriately. However, Windows does not and reports skipped tests as passed. In order to avoid skipped tests being reported as passed, the convention is to output a message indicating skipping test and then mark it failed. An inspection of the file LastTest.log will identify those tests that were skipped vs failed.
The SPIRAL user manual is online and may be found at SPIRAL User Manual.
The SPIRAL documentation is found in the docs folder of the spiral-software tree. It is
automatically pulled down whenever the repository is cloned or forked. The documentation can be
built by specifying SPIRAL_MAKE_DOCS to cmake when building and then making
either the Sphinx or install target, e.g., by specifying:
cmake -DSPIRAL_MAKE_DOCS=True ..
make Sphinx
or on Windows:
cmake -DSPIRAL_MAKE_DOCS=True ..
cmake --build . --config Release --target Sphinx
There are however some pre-requisites before the documentation can be built. Checks for these are made before attempting to build the documentation locally and building is skipped if any of the pre-requisites are missing. The pre-requisites include Sphinx, breathe, and the read-the-docs theme sphinx_rtd_theme (all of which may be installed using pip).
If the documentation is built locally it is available in the build folder at location:
<build>/docs/sphinx/index.html.
The online documentation pages are updated when a push is made to to master branch of SPIRAL (i.e., typically when a release is made).