Merge pull request #44 from ErichZimmer/35-investigate-migrating-to-meson

35 investigate migrating to meson [WIP]

Author: timdewhirst

.github/workflows/build_test.yml

@@ -0,0 +1,52 @@
+name: CMake
+
+on:
+  workflow_dispatch:
+
+  push:
+    branches: [ master ]
+
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+
+    - name: Setup Python
+      uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # v4.7.1
+      with:
+        python-version: '3.11'
+
+    - name: Install rtools (mingw-w64) (see SciPy workflow for more details)
+      run: |
+        if [ "$RUNNER_OS" == "Windows" ]; then
+          choco install rtools -y --no-progress --force --version=4.0.0.20220206
+          echo "c:\rtools40\ucrt64\bin;" >> $env:GITHUB_PATH
+        fi
+      shell: bash
+
+    - name: Install build dependencies from PyPI
+      run: |
+        python -m pip install meson cmake ninja
+
+    - name: Configure Meson
+      # Configure meson to dump all executables in the test directory so Windows would work
+      run: cd ${{github.workspace}} && meson setup builddir
+
+    - name: Build
+      # Build your program with the given configuration
+      run: meson compile -C ${{github.workspace}}/builddir --verbose
+
+    - name: Test
+      working-directory: ${{github.workspace}}/builddir
+      # Execute tests defined by meson test configuration.
+      run: meson test -v

.github/workflows/cmake.yml

@@ -1,6 +1,4 @@
-[submodule "external/vcpkg"]
-	path = external/vcpkg
-	url = https://github.com/microsoft/vcpkg
+
 [submodule "external/pocketfft"]
 	path = external/pocketfft
-	url = https://github.com/hayguen/pocketfft
+	url = https://github.com/mreineck/pocketfft.git

.gitmodules

@@ -1,49 +1,80 @@
-![Build Status](https://github.com/OpenPIV/openpiv-c--qt/actions/workflows/cmake.yml/badge.svg)
+![Build Status](https://github.com/OpenPIV/openpiv-c--qt/actions/workflows/build_test.yml/badge.svg)
 
-# OpenPIV (c++)
+# OpenPIV (c++), a fast, open-source particle image velocimetry (PIV) library
 
-An implementation of a PIV analysis engine in C++ using as few dependencies as possible;
-the implementation requires a c++17 compliant compiler.
+## An implementation of a PIV analysis engine in C++ using as few dependencies as possible; the implementation requires a c++17 compliant compiler.
+
+This project is the result of the collaborative effort of numerous researchers in order to provide one of the fastest PIV software on the market while remaining cross-platform and open-source. The software can do the following:
+
+ * Load images with .tif and .pnm extensions
+ * Save images with .tif and .pnm extensions
+ * Pre-process and modify images
+ * Perform digital PIV analysis including subpixel estimation
+ * and more!
+ 
+Additionally, two examples are provided to demonstrate how the library can be used for background subtraction of images and multi-threaded PIV analysis.
 
 ## Build
 
 There are some external dependencies under external/, so when cloning use:
 
 ```git clone --recursive <path to git repo>```
 
-Building uses cmake and vcpkg, and is simplified by using a vcpkg manifest to specify
-the dependent packages. Vcpkg has some pre-requisites:
+Building uses meson, and is simplified by using meson wrap files to specify the dependent packages. Building has some pre-requisites:
 
 * a compiler (e.g. `apt install build-essentials`)
-* cmake
-* git
+* cmake (optional)
+* python
 * (linux) pkg-config (e.g. `apt install pkg-config`)
 * curl, zip, unzip, tar (e.g. `apt install curl zip unzip tar`)
 * ninja (e.g. `apt install ninja-build`)
+* meson (e.g., pip install --user meson)
+
+Unix users can also use the method used for the Windows build environment as detailed below.
+
+On Windows, the following can be used:
+* install TDM-GCC or any other Windows GNU distribution
+* install miniconda or venv and setup virtual environment
+* pip install cmake (optional)
+* pip install meson
 
 To build:
+* `meson setup builddir` Note, it is good practice to setup --prefix flags so files are not installed on the system.
+* `meson compile -C builddir`
 
-* `cmake -B build -S .`
-* `cmake --build build`
+Meson provides multiple build types such as debug, debugoptimized, and release. To change the build type, use the --buildtype flag. For example, `meson setup builddir --buildtype debugoptimized`.
 
 To run tests:
 
-* `cd build`
-* `ctest`
+* `meson test -C builddir'
 
-To change the build type, add `-DCMAKE_BUILD_TYPE` e.g.
-`cmake -DCMAKE_BUILD_TYPE=RelWithDebugInfo -B build -S .`.
+To get binaries:
+* `meson install -C builddir` if the prefix was set or
+* `meson install -C buildfir --destdir <some directory>` to install in a specific directory.
 
-The binaries are located in the build directory:
+Sometimes you only want the runtime dynamic libraries and executables. Meson comes with a handy targeted installation using the following command:
+ * `meson install -C builddir --tags runtime`
 
-* build
-  * test -> *_test
+Make sure the prefix, or destdir, is set so binaries are not accidentally installed on the system.
+
+The binaries are located the build or installation directory:
+
+Build directory:
+* builddir
   * examples
     * process
     * average_subtract
   * openpiv -> libopenpivcore.so
 
-### Raspberry Pi
+Install directory:
+* prefix/destdir
+  * bindir
+    * libopenpivcore.so
+    * all other dependent shared libraries
+    * process (executable)
+    * average_subtract (executable)
+
+### Raspberry Pi (using deprecated VCPKG build system)
 
 Build times are, as expected, much slower than on a modern Intel CPU, but the code
 will compile. Some observations:
@@ -165,15 +196,18 @@ This is about 230us per interrogation area (7 cores, 3696 interrogation areas, 0
 
 ## Dependencies
 
-These are captured in `vcpkg.json`:
+These are captured in `<dependency>.wrap`:
 
 * c++17 compiler e.g. clang++-5.0, gcc7
-* [vcpkg](https://github.com/Microsoft/vcpkg)
-  * catch2: unit test framework
-  * libtiff: TIFF IO support
+* python3
+* [meson](https://mesonbuild.com/index.html)
   * benchmark: used to run performance benchmarks
-  * async++ (optional): implements c++17 parallel algorithms
+  * catch2: unit test framework
   * cxxopts: nice command line parsing
+  * libtiff: TIFF IO support
+    * libjpeg-turbo
+    * liblzma
+    * zlib
 
 ## Examples
 

CMakeLists.txt

@@ -0,0 +1,12 @@
+avd_sub_exec = executable(
+    'average_subtract',
+    'main.cpp',
+    include_directories: openpiv_include,
+    dependencies: [
+        cxxopts_dep,
+        fmt_dep,
+        thread_dep
+    ],
+    link_with: openpiv_lib,
+    install: true
+)

README.md

@@ -0,0 +1,2 @@
+subdir('average_subtract')
+subdir('process')

cmake/utils.cmake

@@ -0,0 +1,13 @@
+avd_sub_exec = executable(
+    'process',
+    'main.cpp',
+    include_directories: [openpiv_include, pocketfft_include],
+    dependencies: [
+        cxxopts_dep,
+        fmt_dep,
+        thread_dep
+    ],
+    cpp_args: ['-D_USE_MATH_DEFINES'],
+    link_with: openpiv_lib,
+    install: true
+)