Skip to content

Commit

Permalink
Extend readme with meson related infos
Browse files Browse the repository at this point in the history
  • Loading branch information
aradi committed Feb 25, 2024
1 parent fefcab1 commit 040dcf1
Show file tree
Hide file tree
Showing 12 changed files with 214 additions and 65 deletions.
61 changes: 42 additions & 19 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,20 @@ name: CI
on:
push:
branches: [main]
paths-ignore: ['LICENSE', 'README.rst']
pull_request:
branches: [main]
paths-ignore: ['LICENSE', 'README.rst']
workflow_dispatch:

env:
BUILD_DIR: _build
INSTALL_DIR: _install
EXPORT_BUILD_DIR: _build_export

jobs:

#
# Builds and tests with CMake
# Test project on Ubuntu with Intel ifx compiler
#
ubuntu-ifx:

Expand All @@ -36,44 +37,66 @@ jobs:
echo "FC=ifx" >> ${GITHUB_ENV}
echo "FPM_FC=ifx" >> ${GITHUB_ENV}
- name: Setup CMake
uses: jwlawson/[email protected]

- name: Setup Ninja
uses: ashutoshvarma/[email protected]
- name: Setup build tools
run: |
pip install cmake fpm meson ninja
- name: Build Fortuno
run: |
source /opt/intel/oneapi/setvars.sh
cmake -B ${BUILD_DIR} -G Ninja -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}
cmake --build ${BUILD_DIR}
cmake --install ${BUILD_DIR}
rm -rf ${BUILD_DIR}
- name: Test CMake export
run: |
source /opt/intel/oneapi/setvars.sh
CMAKE_PREFIX_PATH=${INSTALL_DIR} cmake -B ${EXPORT_BUILD_DIR} -G Ninja test/export
cmake --build ${EXPORT_BUILD_DIR}
${EXPORT_BUILD_DIR}/testapp
CMAKE_PREFIX_PATH=${INSTALL_DIR} cmake -B ${BUILD_DIR} -G Ninja test/export
cmake --build ${BUILD_DIR}
${BUILD_DIR}/testapp
rm -rf ${BUILD_DIR}
- name: Test PkgConfig export
run: |
source /opt/intel/oneapi/setvars.sh
export LD_LIBRARY_PATH="${INSTALL_DIR}/lib:${LD_LIBRARY_PATH}"
export PKG_CONFIG_PATH="${INSTALL_DIR}/lib/pkgconfig:${PKG_CONFIG_PATH}"
export LD_LIBRARY_PATH="${PWD}/${INSTALL_DIR}/lib:${LD_LIBRARY_PATH}"
export PKG_CONFIG_PATH="${PWD}/${INSTALL_DIR}/lib/pkgconfig:${PKG_CONFIG_PATH}"
cflags="$(pkg-config --cflags fortuno)"
lflags="$(pkg-config --libs fortuno)"
ifx ${cflags} ${lflags} -o testapp test/export/app/testapp.f90
mkdir ${BUILD_DIR}
pushd ${BUILD_DIR}
ifx ${cflags} ${lflags} -o testapp ../test/export/app/testapp.f90
./testapp
rm ./testapp
- name: Setup fpm
uses: fortran-lang/setup-fpm@v5
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
popd
rm -rf ${BUILD_DIR}
- name: Test fpm export
run: |
source /opt/intel/oneapi/setvars.sh
cd test/export
fpm run testapp
- name: Test meson PkgConfig export
run: |
source /opt/intel/oneapi/setvars.sh
export PKG_CONFIG_PATH="${PWD}/${INSTALL_DIR}/lib/pkgconfig:${PKG_CONFIG_PATH}"
cd test/export
meson setup -Dfortuno_subproject=false ${BUILD_DIR}
ninja -C ${BUILD_DIR}
${BUILD_DIR}/testapp
rm -rf ./${BUILD_DIR}
- name: Test meson subproject export
run: |
source /opt/intel/oneapi/setvars.sh
FORTUNO_DIR=${PWD}
GIT_REV=$(git rev-parse HEAD)
cd test/export
mkdir subprojects
echo -e "[wrap-git]\ndirectory=fortuno\n" > subprojects/fortuno.wrap
echo -e "url=file://${FORTUNO_DIR}\nrevision=${GIT_REV}\n" >> subprojects/fortuno.wrap
meson setup -Dfortuno_subproject=true ${BUILD_DIR}
ninja -C ${BUILD_DIR}
${BUILD_DIR}/testapp
rm -rf subprojects ${BUILD_DIR}
107 changes: 62 additions & 45 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ special pre-processor.

- parallel unit testing for MPI- and coarray-parallel projects, and

- seamless integration with the `fpm <https://fpm.fortran-lang.org/>`_ and
`CMake <https://cmake.org/>`_ build systems.
- integration with the `fpm <https://fpm.fortran-lang.org/>`_, `CMake
<https://cmake.org/>`_ and `Meson <https://mesonbuild.com/>`_ build systems.

Detailed **documentation** is available on the `Fortuno documentation
<https://fortuno.readthedocs.io>`_ page. You can also have a look at the
Expand All @@ -38,11 +38,22 @@ The development can be followed and joined at the `Fortuno project
Quickstart
==========

The following instructions demonstrate how to add unit testing via Fortuno to an
existing project, which uses fpm, CMake or Meson as build system. If you are not
familiar with any of these build systems, visit the `Fortuno documentation
<https://fortuno.readthedocs.io>`_ for a step-by-step guide starting from
scratch.

In the examples below, we will assume that your library has a module ``mylib``,
which provides a function ``factorial()`` for calculating the factorial of
integers. Adapt those names to your actual library and routine names.


Obtaining Fortuno
-----------------

The easiest way to obtain Fortuno is to download and to build it as part of your
project's build process. The actual steps depend on your build system.
The easiest way to obtain Fortuno is to download and build it as part of your
project's build process. The actual steps depend on your build system:

* **fpm:** Register Fortuno as a development dependency by adding the following
lines to your ``fpm.toml`` file::
Expand All @@ -61,6 +72,21 @@ project's build process. The actual steps depend on your build system.
)
FetchContent_MakeAvailable(Fortuno)

* **Meson:** Create the file ``fortuno.wrap`` in the ``subprojects/`` folder
of your project (create the folder, if it does not exist yet) with following
content::

[wrap-git]
directory=fortuno
url=https://github.com/fortuno-repos/fortuno
revision=main

Register Fortuno as a subproject by adding the following to your main
``meson.build`` file::

fortuno_subproject = subproject('fortuno')
fortuno_dep = fortuno_subproject.get_variable('fortuno_dep')


Writing unit tests
------------------
Expand All @@ -70,11 +96,11 @@ arguments. Additional to the unit test subroutines, you only need a minimal
amount of code to register the tests in the test framework and to provide access
to them via a command line test driver app.

Given a hypothetical library ``mylib`` providing a function ``factorial()`` for
calculating the factorial of integers, the minimal test program checking the
results for two different input values could look as follows::
Given the hypothetical library ``mylib`` providing the function ``factorial()``,
the minimal test program checking the results for two different input values
could look as follows::

! testapp.f90
! file: testapp.f90

!> Test app driving Fortuno unit tests.
program testapp
Expand All @@ -88,7 +114,7 @@ results for two different input values could look as follows::
call execute_serial_cmd_app(&
testitems=[&
test("factorial_0", test_factorial_0),&
test("factorial_1", test_factorial_1),&
test("factorial_1", test_factorial_1)&
]&
)

Expand All @@ -112,7 +138,7 @@ results for two different input values could look as follows::
Bulding the test-driver app
---------------------------

In order to run the unit tests, the test driver app must be built with your
In order to run the unit tests, you must build the test driver app with your
build system:

* **fpm:** If you stored the test-driver app source (``testapp.f90``) in the
Expand All @@ -121,11 +147,11 @@ build system:

fpm build

* **CMake:** Register ``testapp.f90`` for compilation and add the
``Fortuno::Fortuno`` target as dependency in the relevant ``CMakeLists.txt``
file. You would, of course, also have to specify your library (e.g. ``mylib``)
as dependency. Additionally, register the executable as a test, so that it can
be executed via ``ctest``::
* **CMake:** Add the executable ``testapp`` with ``testapp.f90`` as source and
the target ``Fortuno::Fortuno`` as dependency in the ``CMakeLists.txt`` file.
Add also the target name of your library (e.g. ``mylib``) as dependency.
Additionally, register the executable as a test, so that it can be executed
via ``ctest``::

add_executable(testapp testapp.f90)
target_link_libraries(testapp PRIVATE mylib Fortuno::Fortuno)
Expand All @@ -140,6 +166,22 @@ build system:
cmake -B _build
cmake --build _build

* **Meson:** Add an executable ``testapp`` with ``testapp.f90`` as source and
``fortuno_dep`` as dependency in the ``meson.build`` file. Add also your
library (e.g. ``mylib_dep``) as dependency::

testapp_exe = executable(
'testapp',
sources: ['testapp.f90'],
dependencies: [mylib_dep, fortuno_dep],
)
test('factorial', testapp_exe)

Build your project as usual::

meson setup _build
ninja -C _build


Running the tests
-----------------
Expand All @@ -154,9 +196,9 @@ You run the units tests by executing the test app:

ctest --verbose --test-dir _build

You might omit the ``--verbose`` option to suppress the detailed console
output of Fortuno. You will only see the final result of the testing procedure
then.
* **Meson:** Run the unit tests with ::

meson test -v -C _build

The result is communicated via the testapp's exit code to the build framework
(zero for success, and non-zero for failure). Additionally, Fortuno logs details
Expand All @@ -174,36 +216,11 @@ to the console::
=== Succeeded ===


The behavior of the test app can be influenced using command line options. In
order to get a list of the registered tests, run the ``testapp`` executable with
the `-l` option::

fpm test testapp -- -l # with fpm

_build/test/testapp -l # with CMake assuming testapp.f90 is in the test/ subfolder

With the test app as defined above, you should obtain ::

factorial_0
factorial_1

It is also possible to select (or deselect) the tests to run by passing their
names as command line arguments (prefixed by ``~`` for deselection)::

# Run only the test 'factorial_0'
fpm test testapp -- factorial_0

# Run all tests except 'factorial_0'
fpm test testapp -- ~factorial_0


Further information
--------------------

This quickstart contains only as much information as strictly necessary for
starting with Fortuno. Please check out the `Fortuno documentation
<https://fortuno.readthedocs.io>`_ for further use cases, examples and more
detailed explanations.
Check out the `Fortuno documentation <https://fortuno.readthedocs.io>`_ for more
detailed explanations, further features and use cases.


Known issues
Expand Down
19 changes: 19 additions & 0 deletions example/meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
example_mylib_lib = library(
'mylib',
sources: ['mylib.f90'],
install: false
)
example_mylib_dep = declare_dependency(
link_with: example_mylib_lib,
)

example_testapp_exe = executable(
'testapp',
sources: [
'fixtured_tests.f90',
'simple_tests.f90',
'testapp.f90',
],
dependencies: [example_mylib_dep, fortuno_dep],
install: false,
)
31 changes: 31 additions & 0 deletions meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
project(
'fortuno',
'fortran',
version: '0.1.0',
)

sources = []
subdir('src')

# Intel compiler (as of 2024.0.2) crashes when building the library with optimization turned on.
if meson.get_compiler('fortran').get_id() == 'intel-llvm'
fortran_args = ['-O0']
else
fortran_args = []
endif

fortuno_lib = library(
meson.project_name(),
sources: sources,
version: meson.project_version(),
fortran_args: fortran_args
)

fortuno_dep = declare_dependency(
link_with: fortuno_lib,
)

build_examples = get_option('build_examples')
if build_examples
subdir('example')
endif
1 change: 1 addition & 0 deletions meson_options.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
option('build_examples', type: 'boolean', value: false, description: 'Build examples')
14 changes: 14 additions & 0 deletions src/fortuno/meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
sources += files(
'argumentparser.f90',
'basetypes.f90',
'checkers.f90',
'consolelogger.f90',
'testcmdapp.f90',
'testcontext.f90',
'testdriver.f90',
'testinfo.f90',
'testlogger.f90',
'utils.f90',
'version.f90',
)
subdir('serial')
10 changes: 10 additions & 0 deletions src/fortuno/serial/meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
sources += files(
'serialbasetypes.f90',
'serialcase.f90',
'serialcmdapp.f90',
'serialconlogger.f90',
'serialcontext.f90',
'serialdriver.f90',
'serialglobalctx.f90',
'serialsuite.f90',
)
4 changes: 4 additions & 0 deletions src/meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
sources += files(
'fortuno.f90'
)
subdir('fortuno')
2 changes: 1 addition & 1 deletion test/export/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
cmake_minimum_required(VERSION 3.22...3.28)

project(
Fortuno_Export
Fortuno_Test_Export
VERSION 0.1.0
DESCRIPTION "Testing the CMake build info exported by Fortuno"
LANGUAGES Fortran
Expand Down
3 changes: 3 additions & 0 deletions test/export/app/meson.build
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
sources += files(
'testapp.f90'
)
Loading

0 comments on commit 040dcf1

Please sign in to comment.