search

thomasms / toast

Testing Or ASsertion Toolkit - Fortran unit testing library
BSD 3-Clause "New" or "Revised" License
6 stars 2 forks source link

Q: How to use TOAST within an existing CMake project? #1

Open apthorpe opened 4 years ago

apthorpe commented 4 years ago

I'm working on revitalizing some legacy scientific code using CMake as my build system and I'm trying to understand how to integrate TOAST into my project. I have attached proof-of-concept code TOAST_cmake_integration.zip but I'd like your assessment on how TOAST should be integrated into an existing project.

If TOAST was previously installed, I'd typically use find_package() in my project to detect the required TOAST artifacts (libraries, header and module files, etc.) and set compilation and link variables accordingly. I might have to write FindTOAST.cmake, but there are plenty of examples on how to do that and it's not usually very complex.

In cases where TOAST isn't already installed, I'd use CMake's ExternalProject feature to retrieve, build, and install the package within my project's build tree, then set compilation and link variables as if find_package() was used. This allows me to use the external code without caring whether it was installed at the system level or freshly retrieved and built.

Since TOAST doesn't actually install, the retrieve-and-build process is more complicated and brittle but I've managed to make it work on Linux (I will be testing it on Windows and OSX shortly...)

That covers the upstream side of making sure that TOAST resources are available. The next issue was to determine which resources were necessary and how to configure my test application to build and link with them. I used examples/example1/CMakeLists.txt as guidance and managed to get my test application to correctly build and run properly under CTest. For simplicity I used examples/example1/example.F90 as my test application; that was sufficient for a proof-of-concept.

Having explained all that, the attached zip archive contains two files. BuildTOAST.cmake performs the download, build, and artifact location steps. TOAST_test_fragment.cmake illustrates how to build unit test applications and run them under CTest and is meant to be integrated with a project's top-level CMakeLists.txt file.

Another method of integrating TOAST is via git subprojects but I avoid doing that for a few reasons. Philosophically, I treat git as purely a revision control system and not as part of the build system. I really don't want git as a build dependency and while it's used in BuildTOAST.cmake, ExternalProject works just as well with other version control systems, local archives, and even local unpacked source directories. This is important when building code on systems with limited network accessibility; I work on chemical and nuclear safety projects and environments I support often don't allow code to be pulled straight from github, etc. Just FYI in case you were wondering why I didn't add TOAST as a git subproject.

Anyway, I've been looking for a unit testing framework for Fortran that's simpler and less focused on HPC than pFUnit, maintained (unlike FRUIT and fUnit), and standalone (unlike ftnunit) so I was very happy I discovered TOAST. I have made TOAST work with my project but I'm wondering if there's an easier/better way to integrate it with my CMake project without using git subprojects.

thomasms commented 4 years ago

Hi there, nice to know someone is using this. I built this because I was frustrated with pfUnit (too complex and seemed not the right way to things) and fruit is nice but not rich enough. Unfortunately, I don't have time to maintain this much anymore, but there is potential to improve it still. And indeed the first thing is probably the need for a FindTOAST.cmake.

I always just add it as a submodule but I do agree with your comments. Feel free to make a pull request to add the FindTOAST.cmake.

apthorpe commented 4 years ago

I've built additional CMake infrastructure and tutorial docs since I originally posted this issue. There are some further packaging issues I want to take care of, but I'll send along a pull request shortly for review. Overall TOAST has been working well for my limited needs and it compares favorably to other Fortran test frameworks I've evaluated; thanks for making it public.

apthorpe commented 4 years ago

Submitted a PR ( #2 ) which addresses a number of issues regarding installation and integration as well as testing of the TOAST library itself. The package naming scheme should refer to the specific compiler used since .mod files are compiler-dependent; regardless, the install() commands added to CMakeLists.txt implement the make install target. I set finclude/toast as the installation directory for the .mod files; if you change that directory, please review FindTOAST.cmake and BuildTOAST.cmake. There seems to be no standard for where these files should be stored and I saw the finclude/<library name> convention used by another project; feel free to change it to something that makes more sense. The main requirement is that TOAST_MODULE_DIR be set consistently by FindTOAST.cmake and BuildTOAST.cmake.