# spiral-software **Repository Path**: wangyanhai/spiral-software ## Basic Information - **Project Name**: spiral-software - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-01-25 - **Last Updated**: 2024-10-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README SPIRAL ====== This is the source tree for SPIRAL. It builds and runs on Windows, Linux, and macOS. ## Building SPIRAL ### Prerequisites #### C Compiler and Build Tools 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**. #### CMake 3 Use the most recent version of CMake 3 available for your platform. You can download CMake from [cmake.org](http://cmake.org/download/). #### Python 3 The SPIRAL Profiler requires **Python 3**, which you can get from [python.org](http://python.org/downloads/). ### Building on Linux, macOS, and Other Unix-Like Systems 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. #### Debug Version on Linux/Unix 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**. ### Building on Windows 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](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) 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. #### Building 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: 1. Start Visual Studio Installer 2. Select **Modify** button 3. Select **Individual Components** (the components already installed are listed under *Installation Details* to the right) 4. 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...) 5. If you add any components select the **Modify** button to download and install the required packages. #### Building SPIRAL with cmake **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 [options] [--[native-options]] ``` Typical options used with the command are: ``` Project directory to build --target Build instead of the default target(s) --config For multi-configuration tools, choose --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 ``` ## Testing SPIRAL 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). ### Running Tests on Linux/Unix All tests can be run using **make test** from the `` 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 ``` ### Disabling 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 ``` ### Running Tests on Windows **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 ` option; where ` ` 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 ``` ### Debugging Failed Tests Should a test fail you can view the complete test inputs/outputs generated during the test run. Beneath the `` 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**. Spiral Profiler -------------- 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. ### SPIRAL Documentation The SPIRAL user manual is online and may be found at [SPIRAL User Manual](https://spiral-software.github.io/spiral-software/). 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: ``/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).