diff --git a/installation_policies/1.md b/installation_policies/1.md deleted file mode 100644 index 77c61ac..0000000 --- a/installation_policies/1.md +++ /dev/null @@ -1,9 +0,0 @@ -1. Implement the default behavior described below. Each package can decide whether XSDK mode is the default mode.4 - - 1. `--dis/enable-xsdk-defaults` - 2. `USE_XSDK_DEFAULTS=[YES,NO]` - ----- - -4 For packages like Trilinos that need to maintain backward compatibility over consecutive releases, -`USE_XSDK_DEFAULTS` may be `FALSE` by default. diff --git a/installation_policies/10.md b/installation_policies/10.md deleted file mode 100644 index 2a01533..0000000 --- a/installation_policies/10.md +++ /dev/null @@ -1,7 +0,0 @@ -10. Determine other package libraries and include directories. - - 1. `--with- --with--lib="linkable list of libraries” --with--include=”list of include directories”` - 2. `TPL_ENABLE_=[YES,NO]` - -Packages must provide a way for a user to specify a dependent package to use. Packages are free to locate a package on the file system if none is specifically provided by the user. If the user does provide one, however, it must be used; if it is not able to be used, then an error must be generated. A package cannot silently substitute a different installation. - diff --git a/installation_policies/11.md b/installation_policies/11.md deleted file mode 100644 index 797a152..0000000 --- a/installation_policies/11.md +++ /dev/null @@ -1,2 +0,0 @@ -11. In the XSDK mode, XSDK projects should not rely on users providing any library path information in environmental -variables such as `LD_LIBRARY_PATH`. diff --git a/installation_policies/12.md b/installation_policies/12.md deleted file mode 100644 index 3cbb0a0..0000000 --- a/installation_policies/12.md +++ /dev/null @@ -1,2 +0,0 @@ -12. After packages are configured, they can be compiled, installed and "smoke" tested with the following commands: `make ; -[sudo] make install ; make test_install`. diff --git a/installation_policies/13.md b/installation_policies/13.md deleted file mode 100644 index d43bdfb..0000000 --- a/installation_policies/13.md +++ /dev/null @@ -1,2 +0,0 @@ -13. After an install the package should provide a machine-readable output to show provenance, that is, what compilers were -used and what libraries were linked with, as well as other build configuration information, so that users with problems can send the information directly to developers. diff --git a/installation_policies/2.md b/installation_policies/2.md deleted file mode 100644 index cb4d6c3..0000000 --- a/installation_policies/2.md +++ /dev/null @@ -1,5 +0,0 @@ -2. Identify location to install package. Multiple "versions" of packages, such as debug and release, can be installed by -using different prefix directories. - - 1. `--prefix=directory` - 2. `CMAKE_INSTALL_PREFIX=directory` diff --git a/installation_policies/3.md b/installation_policies/3.md deleted file mode 100644 index 050303d..0000000 --- a/installation_policies/3.md +++ /dev/null @@ -1,28 +0,0 @@ -3. Select compilers5 and compiler flags. - - 1. If the compilers (and or flags) are explicitly set on input, use those: - - 1. `CC=`, `CXX=`, `FC=`, `CPP`, `FFLAGS`, `FCFLAGS`, `CFLAGS`, `CXXFLAGS`, `CPPFLAGS`, `LDFLAGS` - - 2. `CMAKE_C_COMPILER=`, `CMAKE_CXX_COMPILER=`, `CMAKE_Fortran_COMPILER=`, `CMAKE_C_FLAGS=" ...”`, `CMAKE_CXX_FLAGS=”...”`, `CMAKE_Fortran_FLAGS=”...”` - - 2. If the compilers and/or flags are not explicitly set on input but are set in the environment variables - `FC`, `CC`, `CXX`, `CPP`6, `FFLAGS`, `FCFLAGS`, `CFLAGS`, `CXXFLAGS`, `CPPFLAGS`,7 - `LDFLAGS`, then the compilers and flags must be set to these. If both `FFLAGS` and `FCFLAGS` are set, then they - need to be the same or it is an error. - - 3. If the compilers and/or compiler flags are not explicitly passed in or defined in the environment variables listed - above, then the package is free to try to find compilers on the system and set the compiler flags consistent with the - other settings defined below (e.g., shared libraries vs. static libraries, debug vs. non-debug).8 - ------ - -5 Packages must support using the MPI compiler wrappers for these arguments. - -6 The environment variable CPP is not supported by raw CMake. - -7 The environment variable CPPFLAGS is not supported by raw CMake. - -8 All CMake projects should use the same built-in CMake algorithm to find the default compilers, so even when no -explicit compilers or flags are set they should use the same compilers and flags. Also, raw CMake projects will append -compiler flags based on the build type. See "Selecting compiler and linker options". diff --git a/installation_policies/4.md b/installation_policies/4.md deleted file mode 100644 index 3c5f2d7..0000000 --- a/installation_policies/4.md +++ /dev/null @@ -1,5 +0,0 @@ -4. Create libraries with debugging information and possible additional error checking (default is debug in XSDK mode). - - 1. `--dis/enable-debug` - - 2. `CMAKE_BUILD_TYPE=[Debug,Release]` diff --git a/installation_policies/5.md b/installation_policies/5.md deleted file mode 100644 index 107f19b..0000000 --- a/installation_policies/5.md +++ /dev/null @@ -1,5 +0,0 @@ -5. Select option used for indicating whether to build shared libraries (default is shared in XSDK mode). - - 1. `--dis/enable-shared (configure)` - - 2. `BUILD_SHARED_LIBS=[YES,NO]` diff --git a/installation_policies/6.md b/installation_policies/6.md deleted file mode 100644 index 0fa7fa5..0000000 --- a/installation_policies/6.md +++ /dev/null @@ -1,5 +0,0 @@ -6. Build interface for a particular additional language. - - 1. `--dis/enable-` - - 2. `XSDK_ENABLE_=[YES,NO]` diff --git a/installation_policies/7.md b/installation_policies/7.md deleted file mode 100644 index e6ae393..0000000 --- a/installation_policies/7.md +++ /dev/null @@ -1,6 +0,0 @@ -7. Determine precision for packages that build only for one precision (default is double). Packages that handle all -precisions automatically are free to ignore this option. - - 1. `--with-precision=[single,double,quad]` - - 2. `XSDK_PRECISION=[SINGLE,DOUBLE,QUAD]` diff --git a/installation_policies/8.md b/installation_policies/8.md deleted file mode 100644 index ddfe418..0000000 --- a/installation_policies/8.md +++ /dev/null @@ -1,6 +0,0 @@ -8. Determine index size for packages that build only for one index size (default is 32). Packages that handle all index sizes -automatically are free to ignore this option. - - 1. `--with-index-size=[32,64]` - - 2. `XSDK_INDEX_SIZE=[32,64]` diff --git a/installation_policies/9.md b/installation_policies/9.md deleted file mode 100644 index 232d678..0000000 --- a/installation_policies/9.md +++ /dev/null @@ -1,7 +0,0 @@ -9. Set location of BLAS and LAPACK libraries (default is to locate one on the system automatically). - - 1. `--with-blas-lib="linkable list of libraries” --with-lapack-lib=”linkable list of libraries”` -- it is fine to use - -L and -l flags in the lists - - 2. `TPL_BLAS_LIBRARIES="linkable list of libraries”`, `TPL_LAPACK_LIBRARIES=”linkable list of libraries”` -- should not use - -L or -l flags in the lists diff --git a/installation_policies/I1.md b/installation_policies/I1.md new file mode 100644 index 0000000..933d654 --- /dev/null +++ b/installation_policies/I1.md @@ -0,0 +1,13 @@ +# I1 + +Implement the default behavior described below. Each package can decide whether +XSDK mode is the default mode.^4^ + +1. `--dis/enable-xsdk-defaults` +2. `USE_XSDK_DEFAULTS=[YES,NO]` + +---- + +^4^ For packages like Trilinos that need to maintain backward compatibility +over consecutive releases, +`USE_XSDK_DEFAULTS` may be `FALSE` by default. diff --git a/installation_policies/I10.md b/installation_policies/I10.md new file mode 100644 index 0000000..0b0714c --- /dev/null +++ b/installation_policies/I10.md @@ -0,0 +1,14 @@ +# I10 + +Determine other package libraries and include directories. + +1. `--with- --with--lib="linkable list of libraries” +--with--include=”list of include directories”` +2. `TPL_ENABLE_=[YES,NO]` + +Packages must provide a way for a user to specify a dependent package to use. +Packages are free to locate a package on the file system if none is +specifically provided by the user. If the user does provide one, however, it +must be used; if it is not able to be used, then an error must be generated. A +package cannot silently substitute a different installation. + diff --git a/installation_policies/I11.md b/installation_policies/I11.md new file mode 100644 index 0000000..66cef14 --- /dev/null +++ b/installation_policies/I11.md @@ -0,0 +1,4 @@ +# I11 + +In the XSDK mode, XSDK projects should not rely on users providing any library +path information in environmental variables such as `LD_LIBRARY_PATH`. diff --git a/installation_policies/I12.md b/installation_policies/I12.md new file mode 100644 index 0000000..cc7ca87 --- /dev/null +++ b/installation_policies/I12.md @@ -0,0 +1,5 @@ +# I12 + +After packages are configured, they can be compiled, installed and "smoke" +tested with the following commands: `make ; +[sudo] make install ; make test_install`. diff --git a/installation_policies/I13.md b/installation_policies/I13.md new file mode 100644 index 0000000..c9f102c --- /dev/null +++ b/installation_policies/I13.md @@ -0,0 +1,6 @@ +# I13 + +After an install the package should provide a machine-readable output to show +provenance, that is, what compilers were used and what libraries were linked +with, as well as other build configurationinformation, so that users with +problems can send the information directly to developers. diff --git a/installation_policies/I2.md b/installation_policies/I2.md new file mode 100644 index 0000000..0321722 --- /dev/null +++ b/installation_policies/I2.md @@ -0,0 +1,8 @@ +# I2 + +Identify location to install package. Multiple "versions" of packages, such as +debug and release, can be installed by using different prefix directories. + +1. `--prefix=directory` +2. `CMAKE_INSTALL_PREFIX=directory` + diff --git a/installation_policies/I3.md b/installation_policies/I3.md new file mode 100644 index 0000000..402902f --- /dev/null +++ b/installation_policies/I3.md @@ -0,0 +1,40 @@ +# I3 + +Select compilers^5^ and compiler flags. + +1. If the compilers (and or flags) are explicitly set on input, use those: + + 1. `CC=`, `CXX=`, `FC=`, `CPP`, `FFLAGS`, `FCFLAGS`, +`CFLAGS`, `CXXFLAGS`, `CPPFLAGS`, `LDFLAGS` + + 2. `CMAKE_C_COMPILER=`, `CMAKE_CXX_COMPILER=`, +`CMAKE_Fortran_COMPILER=`, `CMAKE_C_FLAGS=" ...”`, +`CMAKE_CXX_FLAGS=”...”`, `CMAKE_Fortran_FLAGS=”...”` + +2. If the compilers and/or flags are not explicitly set on input but are +set in the environment variables + `FC`, `CC`, `CXX`, `CPP`^6^, `FFLAGS`, `FCFLAGS`, `CFLAGS`, `CXXFLAGS`, +`CPPFLAGS`,^7^ `LDFLAGS`, then the compilers and flags must be set to these. +If both `FFLAGS` and `FCFLAGS` are set, then they need to be the same or it +is an error. + +3. If the compilers and/or compiler flags are not explicitly passed in or +defined in the environment variables listed above, then the package is free +to try to find compilers on the system and set the compiler flags consistent +with the other settings defined below (e.g., shared libraries vs. static libraries, +debug vs. non-debug).^8^ + +----- + +^5^ Packages must support using the MPI compiler wrappers for these arguments. + +^6^ The environment variable CPP is not supported by raw CMake. + +^7^ The environment variable CPPFLAGS is not supported by raw CMake. + +^8^ All CMake projects should use the same built-in CMake algorithm to find the +default compilers, so even when no +explicit compilers or flags are set they should use the same compilers and +flags. Also, raw CMake projects will append +compiler flags based on the build type. See "Selecting compiler and linker +options". diff --git a/installation_policies/I4.md b/installation_policies/I4.md new file mode 100644 index 0000000..4886eec --- /dev/null +++ b/installation_policies/I4.md @@ -0,0 +1,9 @@ +# I4 + +Create libraries with debugging information and possible additional error +checking (default is debug in XSDK mode). + +1. `--dis/enable-debug` + +2. `CMAKE_BUILD_TYPE=[Debug,Release]` + diff --git a/installation_policies/I5.md b/installation_policies/I5.md new file mode 100644 index 0000000..2b6098f --- /dev/null +++ b/installation_policies/I5.md @@ -0,0 +1,9 @@ +# I5 + +Select option used for indicating whether to build shared libraries (default is +shared in XSDK mode). + +1. `--dis/enable-shared (configure)` + +2. `BUILD_SHARED_LIBS=[YES,NO]` + diff --git a/installation_policies/I6.md b/installation_policies/I6.md new file mode 100644 index 0000000..ecf0e6c --- /dev/null +++ b/installation_policies/I6.md @@ -0,0 +1,8 @@ +# I6 + +Build interface for a particular additional language. + +1. `--dis/enable-` + +2. `XSDK_ENABLE_=[YES,NO]` + diff --git a/installation_policies/I7.md b/installation_policies/I7.md new file mode 100644 index 0000000..58ecdc5 --- /dev/null +++ b/installation_policies/I7.md @@ -0,0 +1,10 @@ +# I7 + +Determine precision for packages that build only for one precision (default is +double). Packages that handle all precisions automatically are free to ignore +this option. + +1. `--with-precision=[single,double,quad]` + +2. `XSDK_PRECISION=[SINGLE,DOUBLE,QUAD]` + diff --git a/installation_policies/I8.md b/installation_policies/I8.md new file mode 100644 index 0000000..d2e3ecf --- /dev/null +++ b/installation_policies/I8.md @@ -0,0 +1,10 @@ +# I8 + +Determine index size for packages that build only for one index size (default +is 32). Packages that handle all index sizes automatically are free to ignore +this option. + +1. `--with-index-size=[32,64]` + +2. `XSDK_INDEX_SIZE=[32,64]` + diff --git a/installation_policies/I9.md b/installation_policies/I9.md new file mode 100644 index 0000000..3ca3e16 --- /dev/null +++ b/installation_policies/I9.md @@ -0,0 +1,13 @@ +# I9 + +Set location of BLAS and LAPACK libraries (default is to locate one on the +system automatically). + +1. `--with-blas-lib="linkable list of libraries” +--with-lapack-lib=”linkable list of libraries”` -- it is fine to use +-L and -l flags in the lists + +2. `TPL_BLAS_LIBRARIES="linkable list of libraries”`, +`TPL_LAPACK_LIBRARIES=”linkable list of libraries”` -- should not use +-L or -l flags in the lists + diff --git a/installation_policies/README.md b/installation_policies/README.md index 7df19f7..ea3bd4b 100644 --- a/installation_policies/README.md +++ b/installation_policies/README.md @@ -1,8 +1,9 @@ -# +![](/res/xsdk-logo.png) Draft document generated by the IDEAS xSDK project. -We are actively soliciting suggestions from the community at https://xsdk.info/policies. +We are actively soliciting suggestions from the community at +[github.com/xsdk-project/xsdk-community-policies](https://github.com/xsdk-project/xsdk-community-policies). # xSDK Community Installation Policies @@ -16,76 +17,103 @@ Version 0.5.0, June 27, 2019 ## Motivation -Combinations of multiple software packages developed by different groups have become essential for large-scale computational -science, where the capabilities needed for modeling, simulation, and analysis are broader than any single team has resources -to address. The often-tedious trial-and-error process of obtaining, configuring, and installing any single tool may arguably -be manageable. From the perspective of an end-user application scientist, however, handling each tool’s installation -idiosyncrasies can easily become overwhelming when dealing with several packages in combination. Worse, such problems are -compounded by the need for consistency among packages to be used within the same application in terms of compiler, compiler -version, exotic compiler optimization options, and common third-party packages such as BLAS and HDF5. +Combinations of multiple software packages developed by different groups have +become essential for large-scale computational science, where the capabilities +needed for modeling, simulation, and analysis are broader than any single team +has resources to address. The often-tedious trial-and-error process of +obtaining, configuring, and installing any single tool may arguably be +manageable. From the perspective of an end-user application scientist, however, +handling each tool’s installation idiosyncrasies can easily become overwhelming +when dealing with several packages in combination. Worse, such problems are +compounded by the need for consistency among packages to be used within the same +application in terms of compiler, compiler version, exotic compiler optimization +options, and common third-party packages such as BLAS and HDF5. ## Goal -A key aspect of work in the [IDEAS software productivity project][3] is developing an -Extreme-scale Scientific Software Development Kit ([xSDK](http://xsdk.info)). As an initial step in this work, our goal is -to define and implement a standard subset1 of configure and CMake2 options for xSDK and -other HPC packages in order to make the configuration and installation process as efficient as possible on standard Linux -distributions and Mac OS, as well as on target machines at DOE computing facilities (ALCF, NERSC, OLCF). Note that we are -not requiring that all packages use the same installation software, merely that they follow the same standard procedure -with the same option names for installation. This approach provides maximum flexibility for each package to select the -most suitable toolchain to use for its package. +A key aspect of work in the [IDEAS software productivity project][3] is +developing an Extreme-scale Scientific Software Development Kit +([xSDK](http://xsdk.info)). As an initial step in this work, our goal is to +define and implement a standard subset^1^ of configure and CMake^2^ options for +xSDK and other HPC packages in order to make the configuration and installation +process as efficient as possible on standard Linux distributions and Mac OS, as +well as on target machines at DOE computing facilities (ALCF, NERSC, OLCF). Note +that we are not requiring that all packages use the same installation software, +merely that they follow the same standard procedure with the same option names +for installation. This approach provides maximum flexibility for each package to +select the most suitable toolchain to use for its package. ## Impact -Development of a standard xSDK package installation interface is a foundational step toward the seamless combined use of -multiple xSDK libraries. The impact of this work is that all xSDK packages will have standard configuration and build -instructions, as well as a tester to ensure that all functionality works properly. In addition, because new packages in the -xSDK will follow the same standard, it is possible to make the installations "scriptable," that is, to write tools to install -many packages automatically. This work is part of the [xSDK Community Package Policies][4]. +Development of a standard xSDK package installation interface is a foundational +step toward the seamless combined use of multiple xSDK libraries. The impact of +this work is that all xSDK packages will have standard configuration and build +instructions, as well as a tester to ensure that all functionality works +properly. In addition, because new packages in the xSDK will follow the same +standard, it is possible to make the installations "scriptable," that is, to +write tools to install many packages automatically. This work is part of the +[xSDK Community Package Policies][4]. -## xSDK Standard Configure and CMake Options3 +## xSDK Standard Configure and CMake Options^3^ -1. [Implement the xSDK defaults option.](/installation_policies/1.md) +**I1.** [Implement the xSDK defaults option.](/installation_policies/I1.md) -2. [Identify location to install package.](/installation_policies/2.md) +**I2.** [Identify location to install package.](/installation_policies/I2.md) -3. [Select compilers and compiler flags.](/installation_policies/3.md) +**I3.** [Select compilers and compiler flags.](/installation_policies/I3.md) -4. [Create libraries with debugging information and possible additional error checking.](/installation_policies/4.md) +**I4.** [Create libraries with debugging information and possible additional +error checking.](/installation_policies/I4.md) -5. [Select option used for indicating whether to build shared libraries.](/installation_policies/5.md) +**I5.** [Select option used for indicating whether to build shared +libraries.](/installation_policies/I5.md) -6. [Build interface for a particular additional language.](/installation_policies/6.md) +**I6.** [Build interface for a particular additional +language.](/installation_policies/I6.md) -7. [Determine precision for packages that build only for one precision. Packages that handle all precisions automatically are free to ignore this option.](/installation_policies/7.md) +**I7.** [Determine precision for packages that build only for one precision. +Packages that handle all precisions automatically are free to ignore this +option.](/installation_policies/I7.md) -8. [Determine index size for packages that build only for one index size. Packages that handle all precisions automatically are free to ignore this option.](/installation_policies/8.md) +**I8.** [Determine index size for packages that build only for one index size. +Packages that handle all precisions automatically are free to ignore this +option.](/installation_policies/I8.md) -9. [Set location of BLAS and LAPACK libraries.](/installation_policies/9.md) +**I9.** [Set location of BLAS and LAPACK +libraries.](/installation_policies/I9.md) -10. [Determine other package libraries and include directories.](/installation_policies/10.md) +**I10.** [Determine other package libraries and include +directories.](/installation_policies/I10.md) -11. [In the XSDK mode, XSDK projects should not rely on users providing any library path information in environmental variables.](/installation_policies/11.md) +**I11.** [In the XSDK mode, XSDK projects should not rely on users providing any +library path information in environmental +variables.](/installation_policies/I11.md) -12. [Provide commands for compiling, installing, and "smoke" testing.](/installation_policies/12.md) +**I12.** [Provide commands for compiling, installing, and "smoke" +testing.](/installation_policies/I12.md) -13. [Package should provide a machine-readable output to show provenance.](/installation_policies/13.md) +**I13.** [Package should provide a machine-readable output to show +provenance.](/installation_policies/I13.md) +For further discussion and examples of the xSDK standard Configure and CMake +options see +[discussions_and_examples.md](/installation_policies/discussion_and_examples.md). -For further discussion and examples of the xSDK standard Configure and CMake options see [discussions_and_examples.md](/installation_policies/discussion_and_examples.md). +## Changes -+ Changes in version 0.5.0, June 27, 2019: - + Changed installation policies 13 and 10 and examples in 10 +Changes in version 0.5.0, June 27, 2019: changed installation policies 13 and 10 and examples in 10 ## Authors -This document was prepared by Roscoe Bartlett, Jason Sarich, and Barry Smith, with key input from Todd Gamblin. We thank -xSDK software developers and the IDEAS team for insightful discussion about issues and approaches. +This document was prepared by Roscoe Bartlett, Jason Sarich, and Barry Smith, +with key input from Todd Gamblin. We thank xSDK software developers and the +IDEAS team for insightful discussion about issues and approaches. ## Acknowledgement -This material is based upon work supported by the U.S. Department of Energy Office of Science, Advanced Scientific Computing -Research and Biological and Environmental Research programs. +This material is based upon work supported by the U.S. Department of Energy +Office of Science, Advanced Scientific Computing Research and Biological and +Environmental Research programs. ----- @@ -93,13 +121,16 @@ Research and Biological and Environmental Research programs. [//]: # "Main body footnotes" -1 Packages are free to support their own additional options, but using the standard options should be all that -is needed to get correct builds. +^1^ Packages are free to support their own additional options, but using the +standard options should be all that is needed to get correct builds. -2 A subset of these standard behaviors is implemented in the XSDKDefaults.cmake module and is demonstrated and tested in the CMake project https://github.com/bartlettroscoe/XSDKCMakeProj. +^2^ A subset of these standard behaviors is implemented in the +XSDKDefaults.cmake module and is demonstrated and tested in the CMake project +https://github.com/bartlettroscoe/XSDKCMakeProj. -3 This standard is related only to arguments to CMake and GNU Autoconf; there is no requirement regarding the make -system used (for example, that it be GNU make) nor that the make system accepts any particular arguments, such as `make +^3^ This standard is related only to arguments to CMake and GNU Autoconf; there +is no requirement regarding the make system used (for example, that it be GNU +make) nor that the make system accepts any particular arguments, such as `make LIBS+=-lz`. diff --git a/installation_policies/discussion_and_examples.md b/installation_policies/discussion_and_examples.md index ab3e534..62bce73 100644 --- a/installation_policies/discussion_and_examples.md +++ b/installation_policies/discussion_and_examples.md @@ -1,76 +1,107 @@ ## Discussion and Examples -For configure we are trying to match as closely as possible the GNU autoconf and CMake standards and conventions. +For configure we are trying to match as closely as possible the GNU autoconf and +CMake standards and conventions. 1. `--prefix=/usr/local/; cmake -DCMAKE_INSTALL_PREFIX=/usr/local` 2. `CC=/usr/local/bin/mpicc ./configure` - * The reason to support environmental variables is that Linux package managers use environmental variables to set the compiler options, not command line arguments. + * The reason to support environmental variables is that Linux package +managers use environmental variables to set the compiler options, not command +line arguments. - * When reading environmental variables, the configure output should clearly show which variables are being used. + * When reading environmental variables, the configure output should clearly +show which variables are being used. -3. `./configure CC=/usr/bin/mpicc; cmake -DCMAKE_C_COMPILER=/usr/bin/mpicc -DCMAKE_CXX_FLAGS="-O3 -Wall”` +3. `./configure CC=/usr/bin/mpicc; cmake -DCMAKE_C_COMPILER=/usr/bin/mpicc +-DCMAKE_CXX_FLAGS="-O3 -Wall”` * With CMake projects, compiler flags are passed to the compiler as follows: - `${CMAKE__COMPILER> ${CMAKE__FLAGS} ${CMAKE__FLAGS_}` - Therefore, `CMAKE__FLAGS` never overrides the build type (e.g., `DEBUG`, `RELEASE`) specific compiler flags. + `${CMAKE__COMPILER> ${CMAKE__FLAGS} + ${CMAKE__FLAGS_}` Therefore, `CMAKE__FLAGS` + never overrides the build type (e.g., `DEBUG`, `RELEASE`) specific compiler + flags. 4. `./configure --disable-debug; cmake -DCMAKE_BUILD_TYPE=RELEASE ` - * `Debug` is the default because it helps users while developing (writing) their code, which is most of the time. + * `Debug` is the default because it helps users while developing (writing) +their code, which is most of the time. - * The optimized/release version may or may not contain debug symbols. Although the consensus is that including debug - symbols is a good idea for deeply templated C++ libraries, the object size can become very large. Therefore, we do not - require such symbols. + * The optimized/release version may or may not contain debug symbols. +Although the consensus is that including debug symbols is a good idea for deeply +templated C++ libraries, the object size can become very large. Therefore, we do +not require such symbols. 5. `./configure --disable-shared; cmake -DBUILD_SHARED_LIBS=FALSE ` - * Shared is the default because linking against the libraries is dramatically faster. + * Shared is the default because linking against the libraries is +dramatically faster. 6. `./configure --disable-cxx --enable-fc ; cmake -DXSDK_ENABLE_CXX=FALSE ` - * The default is to have C and C++ enabled and Fortran disabled. Packages that do not use Fortran (or C++) are free to - ignore that flag. + * The default is to have C and C++ enabled and Fortran disabled. Packages +that do not use Fortran (or C++) are free to ignore that flag. 7. `./configure --with-precision=single` - * If a package automatically supports multiple versions, it can ignore this option. + * If a package automatically supports multiple versions, it can ignore this +option. 8. `./configure --with-index-size=64` - * If a package automatically supports multiple versions, it can ignore this option. + * If a package automatically supports multiple versions, it can ignore this +option. 9. `./configure --with-lapack-lib="-llapack -lblas”` - * Packages are free to locate a BLAS/LAPACK installation on the file system if none is specifically provided by the user. - If the user does provide one, however, it **must** be used; if it is not able to be used, then an error must be - generated. A package cannot silently substitute a different installation. - -10. `./configure --with-x --with-metis-lib=/usr/local/lib/libmetis.a --with-metis-include=/usr/local/include` - - * In CMake, the analogous approach would be `cmake -DTPL_ENABLE_METIS=ON -DTPL_METIS_INCLUDE_DIRS=/usr/local/include -DTPL_METIS_LIBRARIES=/usr/local/lib/libmetis.a`. However, a package may use CMake's `find_package()` command to load a dependent library as long as the package provides a way for a user to specify an installation of the dependent library to use, *and* the package guarantees that the specified installation is not substituted. + * Packages are free to locate a BLAS/LAPACK installation on the file system +if none is specifically provided by the user. If the user does provide one, +however, it **must** be used; if it is not able to be used, then an error must +be generated. A package cannot silently substitute a different installation. + +10. `./configure --with-x --with-metis-lib=/usr/local/lib/libmetis.a +--with-metis-include=/usr/local/include` + + * In CMake, the analogous approach would be `cmake -DTPL_ENABLE_METIS=ON +-DTPL_METIS_INCLUDE_DIRS=/usr/local/include +-DTPL_METIS_LIBRARIES=/usr/local/lib/libmetis.a`. However, a package may use +CMake's `find_package()` command to load a dependent library as long as the +package provides a way for a user to specify an installation of the dependent +library to use, *and* the package guarantees that the specified installation is +not substituted. - * Packages are free to locate a package on the file system if none is specifically provided by the user. If the user does provide one, however, it **must** be used; if it is not able to be used, then an error must be generated. A package -cannot silently substitute a different installation. + * Packages are free to locate a package on the file system if none is +specifically provided by the user. If the user does provide one, however, it +**must** be used; if it is not able to be used, then an error must be generated. +A package cannot silently substitute a different installation. - * There does not exist any CMake standard allowing an external user to set what external package dependencies should be enabled or disabled when configuring. Therefore, this is a TriBITS/Trilinos standard is which calls external packages "TPL"s and therefore the name `TPL_ENABLE_`. - - * MPI is never considered a ``, and xSDK packages do not need to support `--with-mpi-lib` and `--with-mpi-include`. In fact, we recommend against it. + * There does not exist any CMake standard allowing an external user to set +what external package dependencies should be enabled or disabled when +configuring. Therefore, this is a TriBITS/Trilinos standard is which calls +external packages "TPL"s and therefore the name `TPL_ENABLE_`. + + * MPI is never considered a ``, and xSDK packages do not need to +support `--with-mpi-lib` and `--with-mpi-include`. In fact, we recommend against +it. -11. In order for linking of applications with a multitude of libraries without users needing to set LD_LIBRARY_PATH, -each package likely needs to manage how it handles the rpath linker options when building its libraries. +11. In order for linking of applications with a multitude of libraries without +users needing to set LD_LIBRARY_PATH, each package likely needs to manage how it +handles the rpath linker options when building its libraries. - * Packages are also free to have configure modes that require setting LD_LIBRARY_PATH. + * Packages are also free to have configure modes that require setting +LD_LIBRARY_PATH. -12. Note that the `make test_install` is run **after** the `make install` and utilizes the **installed** versions of of the -library. This type of test is often called a *smoke test*, as it verifies that at least something can be built and run using -the installed library. It can consist of one or several distinct tests but should not require parallelism nor take more than -a couple of minutes. +12. Note that the `make test_install` is run **after** the `make install` and +utilizes the **installed** versions of of the library. This type of test is +often called a *smoke test*, as it verifies that at least something can be built +and run using the installed library. It can consist of one or several distinct +tests but should not require parallelism nor take more than a couple of minutes. -13. This information is useful for debugging; it can, for example, be emailed to the package developer when problems arise. +13. This information is useful for debugging; it can, for example, be emailed to +the package developer when problems arise. - * The "pkgconfig" format and the “module” are two examples of such representations. Both are unfortunately neither - complete nor fully standard. + * The "pkgconfig" format and the “module” are two examples of such +representations. Both are unfortunately neither complete nor fully standard. * We may want to develop an extension of the pkgconfig standard diff --git a/installation_policies/pdf/01.md b/installation_policies/pdf/01.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/installation_policies/pdf/01.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/installation_policies/pdf/02.md b/installation_policies/pdf/02.md new file mode 120000 index 0000000..96b280c --- /dev/null +++ b/installation_policies/pdf/02.md @@ -0,0 +1 @@ +../I1.md \ No newline at end of file diff --git a/installation_policies/pdf/03.md b/installation_policies/pdf/03.md new file mode 120000 index 0000000..6a5df72 --- /dev/null +++ b/installation_policies/pdf/03.md @@ -0,0 +1 @@ +../I2.md \ No newline at end of file diff --git a/installation_policies/pdf/04.md b/installation_policies/pdf/04.md new file mode 120000 index 0000000..3603c6b --- /dev/null +++ b/installation_policies/pdf/04.md @@ -0,0 +1 @@ +../I3.md \ No newline at end of file diff --git a/installation_policies/pdf/05.md b/installation_policies/pdf/05.md new file mode 120000 index 0000000..9a0adef --- /dev/null +++ b/installation_policies/pdf/05.md @@ -0,0 +1 @@ +../I4.md \ No newline at end of file diff --git a/installation_policies/pdf/06.md b/installation_policies/pdf/06.md new file mode 120000 index 0000000..badbfa6 --- /dev/null +++ b/installation_policies/pdf/06.md @@ -0,0 +1 @@ +../I5.md \ No newline at end of file diff --git a/installation_policies/pdf/07.md b/installation_policies/pdf/07.md new file mode 120000 index 0000000..269c4a4 --- /dev/null +++ b/installation_policies/pdf/07.md @@ -0,0 +1 @@ +../I6.md \ No newline at end of file diff --git a/installation_policies/pdf/08.md b/installation_policies/pdf/08.md new file mode 120000 index 0000000..0f5b6b2 --- /dev/null +++ b/installation_policies/pdf/08.md @@ -0,0 +1 @@ +../I7.md \ No newline at end of file diff --git a/installation_policies/pdf/09.md b/installation_policies/pdf/09.md new file mode 120000 index 0000000..0b488c2 --- /dev/null +++ b/installation_policies/pdf/09.md @@ -0,0 +1 @@ +../I8.md \ No newline at end of file diff --git a/installation_policies/pdf/10.md b/installation_policies/pdf/10.md new file mode 120000 index 0000000..1f945f2 --- /dev/null +++ b/installation_policies/pdf/10.md @@ -0,0 +1 @@ +../I9.md \ No newline at end of file diff --git a/installation_policies/pdf/11.md b/installation_policies/pdf/11.md new file mode 120000 index 0000000..2d6030e --- /dev/null +++ b/installation_policies/pdf/11.md @@ -0,0 +1 @@ +../I10.md \ No newline at end of file diff --git a/installation_policies/pdf/12.md b/installation_policies/pdf/12.md new file mode 120000 index 0000000..b3cbdeb --- /dev/null +++ b/installation_policies/pdf/12.md @@ -0,0 +1 @@ +../I11.md \ No newline at end of file diff --git a/installation_policies/pdf/13.md b/installation_policies/pdf/13.md new file mode 120000 index 0000000..33e4f5e --- /dev/null +++ b/installation_policies/pdf/13.md @@ -0,0 +1 @@ +../I12.md \ No newline at end of file diff --git a/installation_policies/pdf/Makefile b/installation_policies/pdf/Makefile new file mode 100644 index 0000000..8ec66ff --- /dev/null +++ b/installation_policies/pdf/Makefile @@ -0,0 +1,14 @@ +# Create a PDF of the xSDK community policies. +# Depends on pandoc and the python package panflute: +# --- See https://pandoc.org/installing.html for information on installing pandoc. +# --- Run `pip install panflute` to obtain panflute. +# To generate the pdf just run `make`. +# +# Author: Cody Balos (@balos1) + +all: + pandoc *.md \ + -F fixlinks.py \ + -f markdown-implicit_figures \ + -V linkcolor:blue \ + -o xsdk-installation-policies.pdf diff --git a/installation_policies/pdf/fixlinks.py b/installation_policies/pdf/fixlinks.py new file mode 100644 index 0000000..3e7b3ca --- /dev/null +++ b/installation_policies/pdf/fixlinks.py @@ -0,0 +1,27 @@ +""" + Pandoc filter that uses panflute. + Converts policy file links to section links in the PDF. Also fix image absolute link(s). + Author: Cody Balos (@balos1) +""" + +import panflute as pf +import re + +def action(elem, doc): + # fix policy links + if isinstance(elem, pf.Link): + url = elem.url + match = re.search('/installation_policies/(.+?)\.md', url) + if match: + found = match.group(1).lower() + elem.url = f'#{found}' + + # fix image links with absolute path + if isinstance(elem, pf.Image): + url = elem.url + if url.startswith('/'): + elem.url = f'../..{url}' + +if __name__ == '__main__': + pf.run_filter(action) + diff --git a/installation_policies/pdf/xsdk-installation-policies.pdf b/installation_policies/pdf/xsdk-installation-policies.pdf new file mode 100644 index 0000000..aaf9a27 Binary files /dev/null and b/installation_policies/pdf/xsdk-installation-policies.pdf differ diff --git a/package_policies/M1.md b/package_policies/M1.md index 8f2adb4..4b8f15d 100644 --- a/package_policies/M1.md +++ b/package_policies/M1.md @@ -1,14 +1,19 @@ -**M1.** Each xSDK-compatible package must support either the **community GNU Autoconf or CMake -options**3 as defined in the following document: +# M1 -[xSDK Community Installation Policies: GNU Autoconf and CMake Options](./community-installation-policies.md). +Each xSDK-compatible package must support either the **community GNU Autoconf or +CMake options**^3^ as defined in the following document: -The goal of this policy is to enable individual users, computing centers, and package managers (such -as [Spack](https://spack.io/)) to install the package in a way that is compatible with -other xSDK packages on the same system. It is understood that managing all the dependencies for a variety -of packages is nontrivial and is not resolved by standard options. +[xSDK Community Installation Policies: GNU Autoconf and CMake +Options](./community-installation-policies.md). + +The goal of this policy is to enable individual users, computing centers, and +package managers (such as [Spack](https://spack.io/)) to install the package in +a way that is compatible with other xSDK packages on the same system. It is +understood that managing all the dependencies for a variety of packages is +nontrivial and is not resolved by standard options. ----- -3 Note that the package is free to use any mechanism, for example Python as PETSc does, to implement -the options but to users they should appear as if a CMake or GNU Autoconf configure package. +^3^ Note that the package is free to use any mechanism, for example Python as +PETSc does, to implement the options but to users they should appear as if a +CMake or GNU Autoconf configure package. diff --git a/package_policies/M10.md b/package_policies/M10.md index ce1fed0..bac4aab 100644 --- a/package_policies/M10.md +++ b/package_policies/M10.md @@ -1,4 +1,7 @@ -**M10.** It is mandatory that each package have an xSDK-accessible **repository** (not necessarily -publicly available), where the development version of the package is available. Support for taking **pull -requests** is also recommended since this will greatly ease the effort among the development teams to -improve interoperability and quickly provide bug fixes. +# M10 + +It is mandatory that each package have an xSDK-accessible **repository** (not +necessarily publicly available), where the development version of the package is +available. Support for taking **pull requests** is also recommended since this +will greatly ease the effort among the development teams to improve +interoperability and quickly provide bug fixes. diff --git a/package_policies/M11.md b/package_policies/M11.md index ce721ca..4553eba 100644 --- a/package_policies/M11.md +++ b/package_policies/M11.md @@ -1,17 +1,23 @@ -**M11**. No package should have hardwired print or I/O statements that cannot be turned off through a -programmatic interface6; output should never be hard-wired to stdout or stderr. It is recommended -that packages provide a way for users to turn on output and allow them to direct where it goes.7 -Also, packages may print to stdout by default but only on one process (i.e., root rank “0”). But packages -may also be completely silent by default (and require that users turn on outputting in the appropriate way). +# M11 + +No package should have hardwired print or I/O statements that cannot be turned +off through a programmatic interface^6^; output should never be hard-wired to +stdout or stderr. It is recommended that packages provide a way for users to +turn on output and allow them to direct where it goes.^7^ Also, packages may +print to stdout by default but only on one process (i.e., root rank “0”). But +packages may also be completely silent by default (and require that users turn +on outputting in the appropriate way). ------ -6 Packages should not exclusively use environmental variables as a programmatic interface since other -packages that may be controlling the simulation process cannot set such environmental variables. There must -be an API that can be called from with the source code. It is fine to also support using environmental variables, -but that cannot be the only way. +^6^ Packages should not exclusively use environmental variables as a +programmatic interface since other packages that may be controlling the +simulation process cannot set such environmental variables. There must be an API +that can be called from with the source code. It is fine to also support using +environmental variables, but that cannot be the only way. -7 For example, allowing users to control output in a C++ package means that the package must accept an -arbitrary std::ostream object and all output should go to that object. In C, the package should accept a FILE -object to which it can direct its output. +^7^ For example, allowing users to control output in a C++ package means that +the package must accept an arbitrary std::ostream object and all output should +go to that object. In C, the package should accept a FILE object to which it can +direct its output. diff --git a/package_policies/M12.md b/package_policies/M12.md index b649f46..558e349 100644 --- a/package_policies/M12.md +++ b/package_policies/M12.md @@ -1,12 +1,17 @@ -**M12.** If a package imports software that is externally developed and maintained,8 then it must allow -installing, building, and linking against an outside copy of that software. Acceptable ways to -accomplish this include (1) forsaking the internal copied version and using an externally provided -implementation or (2) changing the file names and namespaces of all global symbols to allow the -internal copy and the external copy to coexist in the same downstream libraries and programs. +# M12 + +If a package imports software that is externally developed and maintained,^8^ +then it must allow installing, building, and linking against an outside copy of +that software. Acceptable ways to accomplish this include (1) forsaking the +internal copied version and using an externally provided implementation or (2) +changing the file names and namespaces of all global symbols to allow the +internal copy and the external copy to coexist in the same downstream libraries +and programs. ------ -8 For example, some projects import source for some routines from BLAS and LAPACK. The Trilinos Teuchos -package imported an early version of the boost::any class. Also, Trilinos has its own copy of an older version of -SparseSuite. In the latter two cases, new file names and namespaces were created for the imported software to -allow coexistence with the (updated) external versions. +^8^ For example, some projects import source for some routines from BLAS and +LAPACK. The Trilinos Teuchos package imported an early version of the boost::any +class. Also, Trilinos has its own copy of an older version of SparseSuite. In +the latter two cases, new file names and namespaces were created for the +imported software to allow coexistence with the (updated) external versions. diff --git a/package_policies/M13.md b/package_policies/M13.md index f7c4e70..866eb32 100644 --- a/package_policies/M13.md +++ b/package_policies/M13.md @@ -1,4 +1,7 @@ -**M13.** When configured with a prefix, a package must install its headers and libraries under -`/include/` and `/lib/`, respectively. In addition, the library and header file names -should not have the version number embedded (except for shared libraries that can have -soname versions and symlinks like `lib.so -> lib.so.X -> lib.so.X.Y.Z`). +# M13 + +When configured with a prefix, a package must install its headers and libraries +under `/include/` and `/lib/`, respectively. In +addition, the library and header file names should not have the version number +embedded (except for shared libraries that can have soname versions and symlinks +like `lib.so -> lib.so.X -> lib.so.X.Y.Z`). diff --git a/package_policies/M14.md b/package_policies/M14.md index 6dab399..b57ac1e 100644 --- a/package_policies/M14.md +++ b/package_policies/M14.md @@ -1,2 +1,5 @@ -**M14.** All xSDK-compatible packages must be buildable using 64 bit pointers (this is commonly the -default). It is not required that they be buildable with 32 bit pointers. +# M14 + +All xSDK-compatible packages must be buildable using 64 bit pointers (this is +commonly the default). It is not required that they be buildable with 32 bit +pointers. diff --git a/package_policies/M15.md b/package_policies/M15.md index 42d1648..6c87d81 100644 --- a/package_policies/M15.md +++ b/package_policies/M15.md @@ -1,3 +1,5 @@ -**M15:** All xSDK compatibility changes should be sustainable (i.e, they should go into -the regular development and release versions of the package and should not be in a private -release/branch that is provided only for xSDK releases). +# M15 + +All xSDK compatibility changes should be sustainable (i.e, they should go +into the regular development and release versions of the package and should +not be in a private release/branch that is provided only for xSDK releases). diff --git a/package_policies/M16.md b/package_policies/M16.md index f64d5d3..9f72846 100644 --- a/package_policies/M16.md +++ b/package_policies/M16.md @@ -1,9 +1,12 @@ -**M16.** The package must support production-quality installation compatible with the xSDK install tool -and xSDK metapackage.9 +# M16 + +The package must support production-quality installation compatible with the +xSDK install tool and xSDK metapackage.^9^ ------ -9 Beginning with the xSDK 0.2.0-alpha release in April 2017, the xSDK community has adopted ​ Spack​ as the -xSDK install tool. All xSDK compatible packages must support portable installation as part of the current xSDK -Spack metapackage. +^9^ Beginning with the xSDK 0.2.0-alpha release in April 2017, the xSDK +community has adopted Spack as the xSDK install tool. All xSDK compatible +packages must support portable installation as part of the current xSDK Spack +metapackage. diff --git a/package_policies/M2.md b/package_policies/M2.md index 82eef61..267b0c1 100644 --- a/package_policies/M2.md +++ b/package_policies/M2.md @@ -1,5 +1,9 @@ -**M2.** Each xSDK-compatible package must provide a **comprehensive test suite** that can be run by -users and does not require the purchase of commercial software. It is recommended that at least a -significant subset of the test suite will complete within a few hours on standard workstation-level -hardware. It is also recommended that at least a significant subset of the tests be runnable in -batch-only environments, that is, systems that require the use of PBS or other submission scripts. +# M2 + +Each xSDK-compatible package must provide a **comprehensive test suite** that +can be run by users and does not require the purchase of commercial software. It +is recommended that at least a significant subset of the test suite will +complete within a few hours on standard workstation-level hardware. It is also +recommended that at least a significant subset of the tests be runnable in +batch-only environments, that is, systems that require the use of PBS or other +submission scripts. diff --git a/package_policies/M3.md b/package_policies/M3.md index 4c6f598..b5baeb0 100644 --- a/package_policies/M3.md +++ b/package_policies/M3.md @@ -1,10 +1,14 @@ -**M3.** Each xSDK-compatible package that utilizes MPI must restrict its MPI operations to MPI -communicators that are provided to it and not use directly MPI_COMM_WORLD. The package should -use configure tests or version tests to detect MPI 3 features that may not be available; it -should not be assumed that a full MPI 3 implementation is available. The package can -change the MPI error-handling mode by default but should have an option to prevent it from changing -the MPI error handling (which may have been set by another package or the application). The -package should also behave appropriately regardless of the MPI error handling being used. There is -no requirement that the package provide a sequential (non-MPI) version, although this functionality is -welcome, too. If the package provides a sequential version, there is no requirement that it be +# M3 + +Each xSDK-compatible package that utilizes MPI must restrict its MPI operations +to MPI communicators that are provided to it and not use directly +MPI_COMM_WORLD. The package should use configure tests or version tests to +detect MPI 3 features that may not be available; it should not be assumed that a +full MPI 3 implementation is available. The package can change the MPI +error-handling mode by default but should have an option to prevent it from +changing the MPI error handling (which may have been set by another package or +the application). The package should also behave appropriately regardless of the +MPI error handling being used. There is no requirement that the package provide +a sequential (non-MPI) version, although this functionality is welcome, too. If +the package provides a sequential version, there is no requirement that it be compatible or usable with other xSDK-compatible packages running without MPI. diff --git a/package_policies/M4.md b/package_policies/M4.md index bc5cb65..3a9936a 100644 --- a/package_policies/M4.md +++ b/package_policies/M4.md @@ -1,15 +1,19 @@ -**M4.** Each package team must do a “best effort” at **portability to common platforms**, including -standard Linux distributions, and common compiler toolchains such as GNU, Clang,4 and vendor -compilers. **Further portability requirements for xSDK subsets may be conditionally applied -based on sponsor requirements**.5 Support for Apple Mac OS and Microsoft Windows Visual Studio +# M4 + +Each package team must do a “best effort” at **portability to common +platforms**, including standard Linux distributions, and common compiler +toolchains such as GNU, Clang,^4^ and vendor compilers. **Further portability +requirements for xSDK subsets may be conditionally applied based on sponsor +requirements**.^5^ Support for Apple Mac OS and Microsoft Windows Visual Studio is recommended. ------- -4 This does not mean that xSDK packages and all their dependencies cannot have a dependency of Fortran, -merely that the C and C++ portions of the packages and their dependencies should be compilable with the -Clang compilers. +^4^ This does not mean that xSDK packages and all their dependencies cannot have +a dependency of Fortran, merely that the C and C++ portions of the packages and +their dependencies should be compilable with the Clang compilers. -5 For example, xSDK packages that receive funding from the mathematical libraries component of the U.S. -Department of Energy (DOE) Exascale Computing Project (ECP) must support portability to target machines at -the computing facilities ALCF, NERSC, and OLCF. +^5^ For example, xSDK packages that receive funding from the mathematical +libraries component of the U.S. Department of Energy (DOE) Exascale Computing +Project (ECP) must support portability to target machines at the computing +facilities ALCF, NERSC, and OLCF. diff --git a/package_policies/M5.md b/package_policies/M5.md index 2fa5d8a..e821ffa 100644 --- a/package_policies/M5.md +++ b/package_policies/M5.md @@ -1,5 +1,6 @@ -**M5.** Each package team must provide a documented, reliable way to **contact the development -team**; the mode of contact may be by email or a website. The package teams should **not** require -users to join a generic mailing list (and hence receive irrelevant email) in order to report bugs or -request assistance. +# M5 +Each package team must provide a documented, reliable way to **contact the +development team**; the mode of contact may be by email or a website. The +package teams should **not** require users to join a generic mailing list (and +hence receive irrelevant email) in order to report bugs or request assistance. diff --git a/package_policies/M6.md b/package_policies/M6.md index b627558..c1679a1 100644 --- a/package_policies/M6.md +++ b/package_policies/M6.md @@ -1,7 +1,10 @@ -**M6.** Each package should **respect the decisions made by other previously called packages** -regarding system resources and settings. For example, each package may provide an API for -changing the floating-point exception (FPE) and signal handlers, and even set them in a particular -way by default, but there must be a way to prevent the change. Because it is impossible to determine -the current state of the FPE and signal handlers and thus restore them to the current state after -changing them, it is recommended that the xSDK packages adopt a common protocol for pushing and -popping FPE and signal handlers. +# M6 + +Each package should **respect the decisions made by other previously called +packages** regarding system resources and settings. For example, each package +may provide an API for changing the floating-point exception (FPE) and signal +handlers, and even set them in a particular way by default, but there must be a +way to prevent the change. Because it is impossible to determine the current +state of the FPE and signal handlers and thus restore them to the current state +after changing them, it is recommended that the xSDK packages adopt a common +protocol for pushing and popping FPE and signal handlers. diff --git a/package_policies/M7.md b/package_policies/M7.md index fe6ec37..997c75c 100644 --- a/package_policies/M7.md +++ b/package_policies/M7.md @@ -1,14 +1,20 @@ -**M7.** The xSDK collaboration has a strong preference for packages to use an OSI-approved, -**permissive open-source license** (e.g., MIT or BSD 3-Clause). All new packages will be required to -use such a license. Current packages using other licenses are encouraged to relicense, where -possible. Required dependencies must use an OSI-approved license that is considered compatible -with the preferred permissive licenses for distribution purposes (see https://en.wikipedia.org/wiki/License_compatibility). -Non-critical optional dependencies can use any OSI-approved license. +# M7 -RATIONALE: The choice of a permissive open-source -license is friendlier to use by commercial entities. Note that strong copyleft licenses (e.g., GPL) are not considered -compatible with permissive licenses. Weaker copyleft licenses (e.g., LGPL or GPL v2 with runtime -exception) can be considered compatible for xSDK distribution purposes. Licenses that restrict -commercial use are not acceptable in the xSDK. ​ In the future, xSDK leadership reserves the right to -define a build where packages with weaker copyleft licenses (e.g., LGPL or GPL v2 with runtime -exception) are optional, so that users who wish to avoid these restrictions can do so. +The xSDK collaboration has a strong preference for packages to use an +OSI-approved, **permissive open-source license** (e.g., MIT or BSD 3-Clause). +All new packages will be required to use such a license. Current packages using +other licenses are encouraged to relicense, where possible. Required +dependencies must use an OSI-approved license that is considered compatible with +the preferred permissive licenses for distribution purposes (see +https://en.wikipedia.org/wiki/License_compatibility). Non-critical optional +dependencies can use any OSI-approved license. + +RATIONALE: The choice of a permissive open-source license is friendlier to use +by commercial entities. Note that strong copyleft licenses (e.g., GPL) are not +considered compatible with permissive licenses. Weaker copyleft licenses (e.g., +LGPL or GPL v2 with runtime exception) can be considered compatible for xSDK +distribution purposes. Licenses that restrict commercial use are not acceptable +in the xSDK. In the future, xSDK leadership reserves the right to define a build +where packages with weaker copyleft licenses (e.g., LGPL or GPL v2 with runtime +exception) are optional, so that users who wish to avoid these restrictions can +do so. diff --git a/package_policies/M8.md b/package_policies/M8.md index 05c4e44..879fae1 100644 --- a/package_policies/M8.md +++ b/package_policies/M8.md @@ -1,6 +1,10 @@ -**M8.** Each package must provide **a runtime API**, for example a function call, to return the **current -version number** of the software and indicate what configure/CMAKE and compiler options were used -to build the package. For development versions of the software, each package must provide the -current commit ID in the repository. With this information users should be able to rebuild the package -in the same state. We do not currently require that version information for all dependent packages be -provided, so it may not be possible to rebuild the entire software stack in the same state. +# M8 + +Each package must provide **a runtime API**, for example a function call, to +return the **current version number** of the software and indicate what +configure/CMAKE and compiler options were used to build the package. For +development versions of the software, each package must provide the current +commit ID in the repository. With this information users should be able to +rebuild the package in the same state. We do not currently require that version +information for all dependent packages be provided, so it may not be possible to +rebuild the entire software stack in the same state. diff --git a/package_policies/M9.md b/package_policies/M9.md index ab69f65..9ebf21a 100644 --- a/package_policies/M9.md +++ b/package_policies/M9.md @@ -1,6 +1,10 @@ -**M9.** Each package should use a **limited and well-defined symbol, macro, library, and include file -name space**. For example, there should be no publicly visible include files such as utils.h, or package -named libutil.a or macros name YES or TRUE. Namespacing of include files can be handled either by -prepending each include file with a package name, for example , or by placing and -referencing all include files in a subdirectory with a package name, for example . Note -that using a -I/XXX/ and referencing via would not be acceptable namespacing. +# M9 + +Each package should use a **limited and well-defined symbol, macro, library, and +include file name space**. For example, there should be no publicly visible +include files such as utils.h, or package named libutil.a or macros name YES or +TRUE. Namespacing of include files can be handled either by prepending each +include file with a package name, for example , or by placing and +referencing all include files in a subdirectory with a package name, for example +. Note that using a -I/XXX/ and referencing via would not be +acceptable namespacing. diff --git a/package_policies/R1.md b/package_policies/R1.md index 948a7c7..ef3becd 100644 --- a/package_policies/R1.md +++ b/package_policies/R1.md @@ -1,4 +1,6 @@ -**R1.** It is recommended that each package have a **public repository**, for example at GitHub or -Bitbucket, where the development version of the package is available. Support for taking **pull -requests** is also recommended since this will ease greatly the effort for users to provide -improvements to the packages. +# R1 + +It is recommended that each package have a **public repository**, for example at +GitHub or Bitbucket, where the development version of the package is available. +Support for taking **pull requests** is also recommended since this will ease +greatly the effort for users to provide improvements to the packages. diff --git a/package_policies/R2.md b/package_policies/R2.md index 637971b..62819b6 100644 --- a/package_policies/R2.md +++ b/package_policies/R2.md @@ -1,2 +1,4 @@ -**R2.** It is recommended that all packages make it possible to run their test suite under valgrind -in order to test for memory corruption issues. +# R2 + +It is recommended that all packages make it possible to run their test suite +under valgrind in order to test for memory corruption issues. diff --git a/package_policies/R3.md b/package_policies/R3.md index 8e4403d..abe4908 100644 --- a/package_policies/R3.md +++ b/package_policies/R3.md @@ -1,11 +1,15 @@ -**R3.** It is recommended that each package **adopt and document a consistent system for -propagating/returning error conditions/exceptions** and provide an API for changing the behavior. -For example, all routines may, by default, return an error code with the option of changing it to -generate an abort on the error (for running in the debugger). No package should have hardwired calls -to abort, exit, or MPI_Abort(). Also, no package should have hardwired print statements for error -conditions. Each package should document which error codes/exceptions are recoverable, which may -result in lost resources (for example, unfreed memory), and which indicate that the process may be in -an undefined or totally broken state (for example, after a segmentation violation). It is the -responsibility of the calling routine not to simply continue the computation when a “hard” error is -returned; the calling routine will likely, by default, call an abort, but again that should be possible to -override. +# R3 + +It is recommended that each package **adopt and document a consistent system for +propagating/returning error conditions/exceptions** and provide an API for +changing the behavior. For example, all routines may, by default, return an +error code with the option of changing it to generate an abort on the error (for +running in the debugger). No package should have hardwired calls to abort, exit, +or MPI_Abort(). Also, no package should have hardwired print statements for +error conditions. Each package should document which error codes/exceptions are +recoverable, which may result in lost resources (for example, unfreed memory), +and which indicate that the process may be in an undefined or totally broken +state (for example, after a segmentation violation). It is the responsibility of +the calling routine not to simply continue the computation when a “hard” error +is returned; the calling routine will likely, by default, call an abort, but +again that should be possible to override. diff --git a/package_policies/R4.md b/package_policies/R4.md index a830496..1257fd2 100644 --- a/package_policies/R4.md +++ b/package_policies/R4.md @@ -1,7 +1,10 @@ -**R4.** It is recommended that each package **free all system resources it has acquired** as soon as -they are no longer needed. This recommendation includes closing open files, freeing memory, freeing -MPI communicators, and freeing MPI data types created by the package. In particular, it is crucial that -xSDK compatible code not have any growing memory leaks (such as leaking memory during every -timestep). Any resources created by the package that should be freed by the user, rather than by the -package, must be fully documented. Valgrind can be used to locate when these resources are -mistakenly not released. +# R4 + +It is recommended that each package **free all system resources it has +acquired** as soon as they are no longer needed. This recommendation includes +closing open files, freeing memory, freeing MPI communicators, and freeing MPI +data types created by the package. In particular, it is crucial that xSDK +compatible code not have any growing memory leaks (such as leaking memory during +every timestep). Any resources created by the package that should be freed by +the user, rather than by the package, must be fully documented. Valgrind can be +used to locate when these resources are mistakenly not released. diff --git a/package_policies/R5.md b/package_policies/R5.md index 53fec38..366e63c 100644 --- a/package_policies/R5.md +++ b/package_policies/R5.md @@ -1,3 +1,5 @@ -**R5.** It is recommended that each package provide a **mechanism to export its ordered list of library -dependencies** so that any other package or executable linking to the package knows to include these -dependencies when linking. +# R5 + +It is recommended that each package provide a **mechanism to export its ordered +list of library dependencies** so that any other package or executable linking +to the package knows to include these dependencies when linking. diff --git a/package_policies/R6.md b/package_policies/R6.md index c42bedf..908d398 100644 --- a/package_policies/R6.md +++ b/package_policies/R6.md @@ -1,4 +1,6 @@ -**R6.** Each package should document the **versions of packages with which it can work or upon -which it depends**, including software external to the xSDK, preferably in a machine-readable form. -The developers of xSDK member packages will coordinate the needed versions of various packages -for each xSDK release. +# R6 + +Each package should document the **versions of packages with which it can work +or upon which it depends**, including software external to the xSDK, preferably +in a machine-readable form. The developers of xSDK member packages will +coordinate the needed versions of various packages for each xSDK release. diff --git a/package_policies/R7.md b/package_policies/R7.md index bd1b366..ccda449 100644 --- a/package_policies/R7.md +++ b/package_policies/R7.md @@ -1,16 +1,28 @@ -**R7.** It is recommended that each package should have a README or README.md, a SUPPORT or SUPPORT.md, a LICENSE or LICENSE.md, and a CHANGELOG or CHANGELOG.md file in its top directory. -The README file should contain at least the following information: +# R7 + +It is recommended that each package should have a README or README.md, a SUPPORT +or SUPPORT.md, a LICENSE or LICENSE.md, and a CHANGELOG or CHANGELOG.md file in +its top directory. The README file should contain at least the following +information: - a **brief** description of the package -- information on how to install the package or a link to a file (e.g. INSTALL, INSTALL.md or similar) or a website with the installation information +- information on how to install the package or a link to a file (e.g. INSTALL, +INSTALL.md or similar) or a website with the installation information - a link to the package webpage (if there is one) -The LICENSE file should contain the full text of the license. If the full text can be found in a different directory or via a link to a website it is sufficient to provide a link to the full text in the file. +The LICENSE file should contain the full text of the license. If the full text +can be found in a different directory or via a link to a website it is +sufficient to provide a link to the full text in the file. + +The SUPPORT file should contain the contact information that is required by +community policy **M5** to be able to get help. -The SUPPORT file should contain the contact information that is required by community policy **M5** to be able to get help. +The CHANGELOG file should contain important changes or a link to a file or +webpage with this information, but not each individual commit message. -The CHANGELOG file should contain important changes or a link to a file or webpage with this information, but not each individual commit message. +If providing additional information, e.g. on how to contribute, authorship, code +of conduct, etc, it is recommended to consider suggestions in +https://github.com/kmindi/special-files-in-repository-root/blob/master/README.md -If providing additional information, e.g. on how to contribute, authorship, code of conduct, etc, it is recommended to consider suggestions in https://github.com/kmindi/special-files-in-repository-root/blob/master/README.md diff --git a/package_policies/README.md b/package_policies/README.md index 650a168..5047095 100644 --- a/package_policies/README.md +++ b/package_policies/README.md @@ -1,8 +1,9 @@ -# +![](/res/xsdk-logo.png) Draft document generated by the IDEAS xSDK project. -We are actively soliciting suggestions from the community at https://xsdk.info/policies. +We are actively soliciting suggestions from the community at +[github.com/xsdk-project/xsdk-community-policies](https://github.com/xsdk-project/xsdk-community-policies). # xSDK Community Package Policies @@ -14,36 +15,40 @@ Version 0.5.0, June 27, 2019 ## Background -A key aspect of work in the [IDEAS Scientific Software Productivity Project][1] is developing an Extreme-scale -Scientific Software Development Kit ([xSDK][2]) — a collection of related and complementary software elements -that provide the building blocks, tools, models, processes, and related artifacts for rapid and efficient -development of high-quality applications. As an initial step in creating xSDK, we have written the -following draft xSDK package community policies to help address challenges in interoperability and -sustainability of software developed by diverse groups at different institutions. +A key aspect of work in the [IDEAS Scientific Software Productivity Project][1] +is developing an Extreme-scale Scientific Software Development Kit ([xSDK][2]) — +a collection of related and complementary software elements that provide the +building blocks, tools, models, processes, and related artifacts for rapid and +efficient development of high-quality applications. As an initial step in +creating xSDK, we have written the following draft xSDK package community +policies to help address challenges in interoperability and sustainability of +software developed by diverse groups at different institutions. ## Goal -Develop a set of **xSDK community policies** that a software library/framework (henceforth -referred to as package)1 must satisfy in order to to be **xSDK compatible** . The designation of a -package being xSDK compatible informs potential users that the package can be easily used with -other xSDK libraries and components and thus helps to address issues in long-term sustainability2 +Develop a set of **xSDK community policies** that a software library/framework +(henceforth referred to as package)^1^ must satisfy in order to to be **xSDK +compatible** . The designation of a package being xSDK compatible informs +potential users that the package can be easily used with other xSDK libraries +and components and thus helps to address issues in long-term sustainability^2^ and interoperability among packages. -We consider two categories of xSDK packages: **xSDK compatible** packages and **xSDK member** -packages. We also consider two levels of xSDK compatibility: **mandatory policies** and -**recommended policies**. +We consider two categories of xSDK packages: **xSDK compatible** packages and +**xSDK member** packages. We also consider two levels of xSDK compatibility: +**mandatory policies** and **recommended policies**. -+ A package will be declared **xSDK compatible** once the xSDK team has determined that the -**package satisfies the mandatory xSDK policies** listed below. In addition to the required -policies, we specify **recommended xSDK policies** that further help to address issues in -software interoperability. ++ A package will be declared **xSDK compatible** once the xSDK team has +determined that the **package satisfies the mandatory xSDK policies** listed +below. In addition to the required policies, we specify **recommended xSDK +policies** that further help to address issues in software interoperability. -+ Similarly, a package can become an **xSDK member package** if (1) it is an xSDK-compatible -package, *and* (2) it uses or can be used by another package in xSDK, and the connecting -interface is regularly tested for regressions. ++ Similarly, a package can become an **xSDK member package** if (1) it is an +xSDK-compatible package, *and* (2) it uses or can be used by another package in +xSDK, and the connecting interface is regularly tested for regressions. -Initially the requirements and process are informally presented; over time, if needed, we can begin to -formalize them. Currently, xSDK includes seventeen popular numerical libraries: +Initially the requirements and process are informally presented; over time, if +needed, we can begin to formalize them. Currently, xSDK includes seventeen +popular numerical libraries: 1. [AMReX][13] 2. [DTK][14] @@ -68,87 +73,113 @@ and two applications packages: 1. [Alquimia][10] 2. [PFLOTRAN][11], -which satisfy the required policies. Over the longer term, -xSDK may expand to incorporate additional packages, depending on community needs and contributions. +which satisfy the required policies. Over the longer term, xSDK may expand to +incorporate additional packages, depending on community needs and contributions. ## xSDK Mandatory Policies -**M1.** [Support xSDK community GNU Autoconf or CMake options.](/package_policies/M1.md) +**M1.** [Support xSDK community GNU Autoconf or CMake +options.](/package_policies/M1.md) -**M2.** [Provide a comprehensive test suite for correctness of installation verification.](/package_policies/M2.md) +**M2.** [Provide a comprehensive test suite for correctness of installation +verification.](/package_policies/M2.md) -**M3.** [Employ user-provided MPI communicator (no MPI_COMM_WORLD). Don't assume a full MPI 3 -implementation without checking. Provide an option to prevent any changes to MPI error-handling if it is -changed by default.](/package_policies/M3.md) +**M3.** [Employ user-provided MPI communicator (no MPI_COMM_WORLD). Don't assume +a full MPI 3 implementation without checking. Provide an option to prevent any +changes to MPI error-handling if it is changed by +default.](/package_policies/M3.md) -**M4.** [Give best effort at portability to key architectures (standard Linux distributions, GNU, Clang, -vendor compilers, and target machines at ALCF, NERSC, OLCF).](/package_policies/M4.md) +**M4.** [Give best effort at portability to key architectures (standard Linux +distributions, GNU, Clang, vendor compilers, and target machines at ALCF, NERSC, +OLCF).](/package_policies/M4.md) -**M5.** [Provide a documented, reliable way to contact the development team.](/package_policies/M5.md) +**M5.** [Provide a documented, reliable way to contact the development +team.](/package_policies/M5.md) -**M6.** [Respect system resources and settings made by other previously called packages (e.g. signal handling).](/package_policies/M6.md) +**M6.** [Respect system resources and settings made by other previously called +packages (e.g. signal handling).](/package_policies/M6.md) **M7.** [Come with an open source (BSD style) license.](/package_policies/M7.md) -**M8.** [Provide a runtime API to return the current version number of the software.](/package_policies/M8.md) +**M8.** [Provide a runtime API to return the current version number of the +software.](/package_policies/M8.md) -**M9.** [Use a limited and well-defined symbol, macro, library, and include file name space.](/package_policies/M9.md) +**M9.** [Use a limited and well-defined symbol, macro, library, and include file +name space.](/package_policies/M9.md) -**M10.** [Provide an xSDK team accessible repository (not necessarily publicly available).](/package_policies/M10.md) +**M10.** [Provide an xSDK team accessible repository (not necessarily publicly +available).](/package_policies/M10.md) -**M11.** [Have no hardwired print or IO statements that cannot be turned off.](/package_policies/M11.md) +**M11.** [Have no hardwired print or IO statements that cannot be turned +off.](/package_policies/M11.md) -**M12.** [For external dependencies, allow installing, building, and linking against an outside copy of external software.](/package_policies/M12.md) +**M12.** [For external dependencies, allow installing, building, and linking +against an outside copy of external software.](/package_policies/M12.md) -**M13.** [Install headers and libraries under `/include` and `/lib`.](/package_policies/M13.md) +**M13.** [Install headers and libraries under `/include` and +`/lib`.](/package_policies/M13.md) -**M14.** [Be buildable using 64 bit pointers. 32 bit is optional.](/package_policies/M14.md) +**M14.** [Be buildable using 64 bit pointers. 32 bit is +optional.](/package_policies/M14.md) -**M15.** [All xSDK compatibility changes should be sustainable.](/package_policies/M15.md) +**M15.** [All xSDK compatibility changes should be +sustainable.](/package_policies/M15.md) -**M16.** [The package must support production-quality installation compatible with the xSDK install tool -and xSDK metapackage.](/package_policies/M16.md) +**M16.** [The package must support production-quality installation compatible +with the xSDK install tool and xSDK metapackage.](/package_policies/M16.md) ## xSDK Recommended Policies -In addition to the required xSDK policies listed above, the following capabilities are also recommended. +In addition to the required xSDK policies listed above, the following +capabilities are also recommended. **R1.** [Have a public repository](/package_policies/R1.md). -**R2.** [Possible to run test suite under valgrind in order to test for memory corruption issues.](/package_policies/R2.md) +**R2.** [Possible to run test suite under valgrind in order to test for memory +corruption issues.](/package_policies/R2.md) -**R3.** [Adopt and document consistent system for error conditions/exceptions.](/package_policies/R3.md) +**R3.** [Adopt and document consistent system for error +conditions/exceptions.](/package_policies/R3.md) -**R4.** [Free all system resources acquired as soon as they are no longer needed.](/package_policies/R4.md) +**R4.** [Free all system resources acquired as soon as they are no longer +needed.](/package_policies/R4.md) -**R5.** [Provide a mechanism to export ordered list of library dependencies.](/package_policies/R5.md) +**R5.** [Provide a mechanism to export ordered list of library +dependencies.](/package_policies/R5.md) -**R6.** [Document versions of packages that it works with or depends upon, preferably in machine-readable form.](/package_policies/R6.md) +**R6.** [Document versions of packages that it works with or depends upon, +preferably in machine-readable form.](/package_policies/R6.md) + +**R7.** [Have README, SUPPORT, LICENSE, and CHANGELOG files in top +directory.](/package_policies/R7.md) -**R7.** [Have README, SUPPORT, LICENSE, and CHANGELOG files in top directory.](/package_policies/R7.md) ## History of the xSDK Community Policies -The original version of this document was prepared in 2015 by Barry Smith with key input from Roscoe Bartlett -and feedback from members of the IDEAS project. Over time, revisions have been introduced based on discussions -with the broader computational science community and developers of an expanding collection of xSDK member -packages. We thank all xSDK package developers, the IDEAS team, and the scientific computing community for -insightful discussion about issues and approaches. +The original version of this document was prepared in 2015 by Barry Smith with +key input from Roscoe Bartlett and feedback from members of the IDEAS project. +Over time, revisions have been introduced based on discussions with the broader +computational science community and developers of an expanding collection of +xSDK member packages. We thank all xSDK package developers, the IDEAS team, and +the scientific computing community for insightful discussion about issues and +approaches. + Changes in version 0.5.0, June 27, 2019: - + Added new policy R7, which recommends the inclusion of various information files in the top directory - + Dropped the requirement to detect MPI 2 features in M3 - + Made various editorial changes in M5, M13, M15, and R2 for clarification or to fix typos. + * Added new policy R7, which recommends the inclusion of various information +files in the top directory + * Dropped the requirement to detect MPI 2 features in M3 Made various + * Editorial changes in M5, M13, M15, and R2 for clarification or +to fix typos + Changes in version 0.4.0, July 27, 2018: - + Split policy M4 into 2 parts: M4 (portability to common platforms) and new policy R6 -(package should document the versions of packages with which it can work on on which it depends). See + * Split policy M4 into 2 parts: M4 (portability to common platforms) and new +policy R6 (package should document the versions of packages with which it can +work on on which it depends). See https://github.com/xsdk-project/xsdk-issues/issues/55 - + Revision to M7: language about open source licensing requirements. See + * Revision to M7: language about open source licensing requirements. See https://github.com/xsdk-project/xsdk-issues/issues/56 - + New section on history of policies and summary of changes, misc minor edits -+ Changes in version 0.3.0, November 6, 2017: added 2 new policies (M15 and M16), changed -naming convention to follow xSDK release number, minor typo edits -+ Changes in version 0.3, December 2, 2016: clear definition of xSDK member packages, misc -minor edits + * New section on history of policies and summary of changes, misc minor edits ++ Changes in version 0.3.0, November 6, 2017: added 2 new policies (M15 and M16), +changed naming convention to follow xSDK release number, minor typo edits ++ Changes in version 0.3, December 2, 2016: clear definition of xSDK member packages, misc minor edits + Changes in version 0.2, January 28, 2016: minor edit + Version 0.1, November 10, 2015: original version @@ -158,21 +189,24 @@ See the [xSDK FAQ list][12]. ## Acknowledgment -This material is based upon work supported by the U.S. Department of Energy, Office of Science, Advanced Scientific -Computing Research and Biological and Environmental Research programs. +This material is based upon work supported by the U.S. Department of Energy, +Office of Science, Advanced Scientific Computing Research and Biological and +Environmental Research programs. ----- [//]: # "Main body footnotes" -1 For the purpose of this document, the term *package* refers to a collection of source code -(possibly containing C, Fortran, or C++) that can generate zero or more shared or static libraries, zero -or more include files, zero or more Fortran modules, and possibly other auxiliary artifacts, including -executables, and whose functionality can be used by other packages and by application codes. A software -artifact that generates only an executable is, by this definition, not an xSDK package; that is, xSDK -packages are libraries, frameworks, and domain components. +^1^ For the purpose of this document, the term *package* refers to a collection +of source code (possibly containing C, Fortran, or C++) that can generate zero +or more shared or static libraries, zero or more include files, zero or more +Fortran modules, and possibly other auxiliary artifacts, including executables, +and whose functionality can be used by other packages and by application codes. +A software artifact that generates only an executable is, by this definition, +not an xSDK package; that is, xSDK packages are libraries, frameworks, and +domain components. -2 See, for example, "Self-Sustaining Software" as outlined in +^2^ See, for example, "Self-Sustaining Software" as outlined in http://trac.trilinos.org/wiki/TribitsLifecycleModelOverview#self_sustaining_software. @@ -181,7 +215,7 @@ http://trac.trilinos.org/wiki/TribitsLifecycleModelOverview#self_sustaining_soft [1]: http://www.ideas-productivity.org/ [2]: http://xsdk.info/ [3]: https://computation.llnl.gov/project/linear_solvers/ -[4]: http://icl.utk.edu/magma +[4]: http://icl.utk.edu/magma [5]: http://mfem.org/ [6]: http://www.mcs.anl.gov/petsc/ [7]: https://computation.llnl.gov/projects/sundials diff --git a/package_policies/pdf/01.md b/package_policies/pdf/01.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/package_policies/pdf/01.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/package_policies/pdf/02.md b/package_policies/pdf/02.md new file mode 120000 index 0000000..fe2490d --- /dev/null +++ b/package_policies/pdf/02.md @@ -0,0 +1 @@ +../M1.md \ No newline at end of file diff --git a/package_policies/pdf/03.md b/package_policies/pdf/03.md new file mode 120000 index 0000000..d634c08 --- /dev/null +++ b/package_policies/pdf/03.md @@ -0,0 +1 @@ +../M2.md \ No newline at end of file diff --git a/package_policies/pdf/04.md b/package_policies/pdf/04.md new file mode 120000 index 0000000..67498cb --- /dev/null +++ b/package_policies/pdf/04.md @@ -0,0 +1 @@ +../M3.md \ No newline at end of file diff --git a/package_policies/pdf/05.md b/package_policies/pdf/05.md new file mode 120000 index 0000000..799975f --- /dev/null +++ b/package_policies/pdf/05.md @@ -0,0 +1 @@ +../M4.md \ No newline at end of file diff --git a/package_policies/pdf/06.md b/package_policies/pdf/06.md new file mode 120000 index 0000000..4a600cf --- /dev/null +++ b/package_policies/pdf/06.md @@ -0,0 +1 @@ +../M5.md \ No newline at end of file diff --git a/package_policies/pdf/07.md b/package_policies/pdf/07.md new file mode 120000 index 0000000..fe487da --- /dev/null +++ b/package_policies/pdf/07.md @@ -0,0 +1 @@ +../M6.md \ No newline at end of file diff --git a/package_policies/pdf/08.md b/package_policies/pdf/08.md new file mode 120000 index 0000000..9213470 --- /dev/null +++ b/package_policies/pdf/08.md @@ -0,0 +1 @@ +../M7.md \ No newline at end of file diff --git a/package_policies/pdf/09.md b/package_policies/pdf/09.md new file mode 120000 index 0000000..511e1e3 --- /dev/null +++ b/package_policies/pdf/09.md @@ -0,0 +1 @@ +../M8.md \ No newline at end of file diff --git a/package_policies/pdf/10.md b/package_policies/pdf/10.md new file mode 120000 index 0000000..69cfcc8 --- /dev/null +++ b/package_policies/pdf/10.md @@ -0,0 +1 @@ +../M9.md \ No newline at end of file diff --git a/package_policies/pdf/11.md b/package_policies/pdf/11.md new file mode 120000 index 0000000..8c8848c --- /dev/null +++ b/package_policies/pdf/11.md @@ -0,0 +1 @@ +../M10.md \ No newline at end of file diff --git a/package_policies/pdf/12.md b/package_policies/pdf/12.md new file mode 120000 index 0000000..6f7c96b --- /dev/null +++ b/package_policies/pdf/12.md @@ -0,0 +1 @@ +../M11.md \ No newline at end of file diff --git a/package_policies/pdf/13.md b/package_policies/pdf/13.md new file mode 120000 index 0000000..8df916f --- /dev/null +++ b/package_policies/pdf/13.md @@ -0,0 +1 @@ +../M12.md \ No newline at end of file diff --git a/package_policies/pdf/14.md b/package_policies/pdf/14.md new file mode 120000 index 0000000..95548f6 --- /dev/null +++ b/package_policies/pdf/14.md @@ -0,0 +1 @@ +../M13.md \ No newline at end of file diff --git a/package_policies/pdf/15.md b/package_policies/pdf/15.md new file mode 120000 index 0000000..8e9212a --- /dev/null +++ b/package_policies/pdf/15.md @@ -0,0 +1 @@ +../M14.md \ No newline at end of file diff --git a/package_policies/pdf/16.md b/package_policies/pdf/16.md new file mode 120000 index 0000000..2eb47bd --- /dev/null +++ b/package_policies/pdf/16.md @@ -0,0 +1 @@ +../M15.md \ No newline at end of file diff --git a/package_policies/pdf/17.md b/package_policies/pdf/17.md new file mode 120000 index 0000000..aefc209 --- /dev/null +++ b/package_policies/pdf/17.md @@ -0,0 +1 @@ +../M16.md \ No newline at end of file diff --git a/package_policies/pdf/18.md b/package_policies/pdf/18.md new file mode 120000 index 0000000..42175b3 --- /dev/null +++ b/package_policies/pdf/18.md @@ -0,0 +1 @@ +../R1.md \ No newline at end of file diff --git a/package_policies/pdf/19.md b/package_policies/pdf/19.md new file mode 120000 index 0000000..4be5632 --- /dev/null +++ b/package_policies/pdf/19.md @@ -0,0 +1 @@ +../R2.md \ No newline at end of file diff --git a/package_policies/pdf/20.md b/package_policies/pdf/20.md new file mode 120000 index 0000000..ffbcb9b --- /dev/null +++ b/package_policies/pdf/20.md @@ -0,0 +1 @@ +../R3.md \ No newline at end of file diff --git a/package_policies/pdf/21.md b/package_policies/pdf/21.md new file mode 120000 index 0000000..d8f80e0 --- /dev/null +++ b/package_policies/pdf/21.md @@ -0,0 +1 @@ +../R4.md \ No newline at end of file diff --git a/package_policies/pdf/22.md b/package_policies/pdf/22.md new file mode 120000 index 0000000..313631f --- /dev/null +++ b/package_policies/pdf/22.md @@ -0,0 +1 @@ +../R5.md \ No newline at end of file diff --git a/package_policies/pdf/23.md b/package_policies/pdf/23.md new file mode 120000 index 0000000..2bdcc68 --- /dev/null +++ b/package_policies/pdf/23.md @@ -0,0 +1 @@ +../R6.md \ No newline at end of file diff --git a/package_policies/pdf/24.md b/package_policies/pdf/24.md new file mode 120000 index 0000000..b601a3b --- /dev/null +++ b/package_policies/pdf/24.md @@ -0,0 +1 @@ +../R7.md \ No newline at end of file diff --git a/package_policies/pdf/Makefile b/package_policies/pdf/Makefile new file mode 100644 index 0000000..aa86670 --- /dev/null +++ b/package_policies/pdf/Makefile @@ -0,0 +1,14 @@ +# Create a PDF of the xSDK community policies. +# Depends on pandoc and the python package panflute: +# --- See https://pandoc.org/installing.html for information on installing pandoc. +# --- Run `pip install panflute` to obtain panflute. +# To generate the pdf just run `make`. +# +# Author: Cody Balos (@balos1) + +all: + pandoc *.md \ + -F fixlinks.py \ + -f markdown-implicit_figures \ + -V linkcolor:blue \ + -o xsdk-community-policies.pdf diff --git a/package_policies/pdf/fixlinks.py b/package_policies/pdf/fixlinks.py new file mode 100644 index 0000000..e910412 --- /dev/null +++ b/package_policies/pdf/fixlinks.py @@ -0,0 +1,27 @@ +""" + Pandoc filter that uses panflute. + Converts policy file links to section links in the PDF. Also fix image absolute link(s). + Author: Cody Balos (@balos1) +""" + +import panflute as pf +import re + +def action(elem, doc): + # fix policy links + if isinstance(elem, pf.Link): + url = elem.url + match = re.search('/package_policies/(.+?)\.md', url) + if match: + found = match.group(1).lower() + elem.url = f'#{found}' + + # fix image links with absolute path + if isinstance(elem, pf.Image): + url = elem.url + if url.startswith('/'): + elem.url = f'../..{url}' + +if __name__ == '__main__': + pf.run_filter(action) + diff --git a/package_policies/pdf/xsdk-community-policies.pdf b/package_policies/pdf/xsdk-community-policies.pdf new file mode 100644 index 0000000..45ec8ab Binary files /dev/null and b/package_policies/pdf/xsdk-community-policies.pdf differ diff --git a/res/xsdk-logo.png b/res/xsdk-logo.png index 038c482..2aadd60 100644 Binary files a/res/xsdk-logo.png and b/res/xsdk-logo.png differ