commit 51be48438761a042d633e98d98324b211a9f5a5b
parent 345343c9b667fcd00f68e01085059683b4321119
Author: [email protected] <[email protected]>
Date: Mon, 5 Feb 2024 18:48:03 +0000
Update documentation
Diffstat:
11 files changed, 452 insertions(+), 289 deletions(-)
diff --git a/README.md b/README.md
@@ -14,7 +14,15 @@ https://www.kfr.dev
KFR is an open source C++ DSP framework that contains high performance building blocks for DSP, audio, scientific and other applications. It is distributed under dual GPLv2/v3 and [commercial license](https://kfr.dev/purchase).
-## [Installation](docs/docs/installation.md)
+## KFR6
+
+New features, performance improvements, easier setup.
+
+:arrow_right: [What's new in KFR6](docs/docs/whatsnew6.md)
+
+:arrow_right: [Upgrade from a previous version](docs/docs/upgrade6.md)
+
+## Installation
Compiler support:
@@ -23,14 +31,13 @@ Compiler support:
-KFR has no external dependencies except a C++17 compatible standard C++ library.
-CMake is used as build system.
+KFR has no external dependencies except for a C++17-compatible standard C++ library. CMake is used as the build system.
-Clang is highly recommended and proven to provide the best performance for KFR. You can use clang as a drop-in replacement of both GCC on Linux and MSVC on Windows. On macOS clang is the default compiler and included in the official Xcode toolchain.
+Clang is highly recommended and proven to provide the best performance for KFR. You can use Clang as a drop-in replacement for both GCC on Linux and MSVC on Windows. On macOS, Clang is the default compiler and included in the official Xcode toolchain.
-_Note_: Building DFT module requires Clang at this moment due to internal compiler errors and lack of optimization in GCC and MSVC.
+_Note_: Building the DFT module currently requires Clang due to internal compiler errors and a lack of optimization in GCC and MSVC.
-:arrow_right: See [Installation](docs/docs/installation.md) for more details
+:arrow_right: See [Installation](docs/docs/installation.md) docs for more details
## Features
@@ -38,7 +45,7 @@ _Note_: Building DFT module requires Clang at this moment due to internal compil
* Optimized DFT implementation for any size (non-power of two sizes are supported)
* DFT performance is on par with the most performant implementation currently available [See Benchmarks](#benchmark-results)
* Real forward and inverse DFT
-* Multidimensional complex and real DFT
+* [:star2: new in KFR6] Multidimensional complex and real DFT
* Discrete Cosine Transform type II (and its inverse, also called DCT type III)
* Convolution using FFT
* Convolution filter
@@ -65,6 +72,8 @@ _Note_: Building DFT module requires Clang at this moment due to internal compil
### Base
* Tensors (multidimensional arrays)
+* [:star2: new in KFR6] .npy support (reading/writing)
+* [:star2: new in KFR6] Matrix transpose
* Statistical functions
* Random number generation
* Template expressions (See examples)
@@ -91,10 +100,18 @@ _Note_: Building DFT module requires Clang at this moment due to internal compil
* FLAC
* MP3
+### Multiarchitecture
+
+Multiarchitecture mode enables building algorithms for multiple architectures with runtime dispatch to detect the CPU of the target machine and select the best code path.
+
+* [:star2: new in KFR6] Multiarchitecture for DFT, resampling, FIR and IIR filters.
+
### C API
C API is available and includes a subset of KFR features including FFT and filter processing.
+[:star2: new in KFR6] Support for non x86 systems.
+
## Benchmark results
### DFT
@@ -126,13 +143,11 @@ See [fft benchmark](https://github.com/kfrlib/fft-benchmark) for details about b
## Documentation
-Documentation home:
-
-KFR 5 (latest)
+KFR 6 (latest)
https://www.kfrlib.com/docs/latest/
-KFR 4
-https://www.kfrlib.com/docs/v4/
+KFR 5
+https://www.kfrlib.com/docs/v5/
Built with
* [cxxdox - generates markdown docs from C++](https://github.com/kfrlib/cxxdox)
@@ -147,9 +162,8 @@ Built with
`v5` - previous version of KFR (no new features, fixes only)
-
## License
KFR is dual-licensed, available under both commercial and open-source GPL 2+ license.
-If you want to use KFR in a commercial product or a closed-source project, you need to [purchase a Commercial License](https://kfr.dev/purchase-license)
+If you want to use KFR in a commercial product or a closed-source project, you need to [purchase a Commercial License](https://kfr.dev/purchase-license).
diff --git a/docs/docs/capi.md b/docs/docs/capi.md
@@ -4,24 +4,25 @@
Clang is required. See [Installation](installation.md)
+C API is supported on non-x86 platforms.
+C API requires that `KFR_ENABLE_MULTIARCH` be enabled (enabled by default).
+
### Windows
-These commands must be executed in MSVC2019 command prompt.
+These commands must be executed in the MSVC command prompt.
```bash
cd <path_to_kfr_repository>
-mkdir build && cd build
-cmake -GNinja -DENABLE_CAPI_BUILD=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER="<PATH_TO_LLVM_DIR>/bin/clang-cl.exe" ..
-ninja kfr_capi
+cmake -B build -GNinja -DCMAKE_INSTALL_PREFIX=path/to/install/dir -DENABLE_CAPI_BUILD=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER="<PATH_TO_LLVM_DIR>/bin/clang-cl.exe" ..
+ninja -C build install
```
### Linux, macOS, other
+On Linux and macOS, the `CMAKE_POSITION_INDEPENDENT_CODE` CMake option is required for building the C API:
+
```bash
cd <path_to_kfr_repository>
-mkdir build && cd build
-cmake -GNinja -DENABLE_CAPI_BUILD=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ ..
-ninja kfr_capi
+cmake -B build -GNinja -DCMAKE_INSTALL_PREFIX=path/to/install/dir -DENABLE_CAPI_BUILD=ON -DDCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ ..
+ninja -C build install
```
-
-Optionally, you can install the binaries into your system using `ninja install`
diff --git a/docs/docs/clang.md b/docs/docs/clang.md
@@ -0,0 +1,61 @@
+# Installing Clang
+
+## Installing Clang on Linux
+
+Install the latest clang available in your package manager:
+
+`apt` (Ubuntu/Debian):
+```bash
+sudo apt install clang
+```
+
+or install any version from llvm apt:
+```bash
+wget -O - https://apt.llvm.org/llvm.sh | sudo bash -s - 17
+```
+
+### CMake
+
+The following defines are required to instruct CMake on which compiler to use:
+
+```bash
+cmake -DCMAKE_CXX_COMPILER=clang++ ...
+```
+or with specific version:
+```bash
+cmake -DCMAKE_CXX_COMPILER=clang++-17 ...
+```
+
+### make
+
+Set `CXX=clang++` or `CXX=clang++-17` environment variables before running make.
+
+## Installing Clang on macOS
+
+On macOS clang is the default compiler and already included in the official Xcode toolchain. No additional setup required.
+
+## Installing Clang on Windows
+
+### CMake + Ninja
+
+Download and install the latest `win64` build from the official LLVM GitHub page:
+
+https://github.com/llvm/llvm-project/releases
+
+### Visual Studio
+
+In MSVC 2019 and 2022, there is built-in support for the Clang toolchain:
+
+https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild?view=msvc-170
+https://learn.microsoft.com/en-us/cpp/build/clang-support-cmake?view=msvc-170
+
+LLVM/Clang has very good compatibility with the MSVC ABI and is widely used for building large projects on Windows (including Chrome). Therefore, switching to LLVM/Clang should not cause any compatibility problems.
+
+## Transparent Clang use (experimental)
+
+Setting `KFR_WITH_CLANG` to `ON` instructs KFR to download Clang from the official GitHub, extract it to the build directory, and set all required CMake variables to enable its usage.
+Works on Windows and Linux.
+
+```bash
+cmake -B build -GNinja -DKFR_WITH_CLANG=ON -DCMAKE_BUILD_TYPE=Release
+```
diff --git a/docs/docs/conversion.md b/docs/docs/conversion.md
@@ -59,12 +59,12 @@ i24 s = convert_sample<i24, f32>(1.f);
## Supported formats
-Constant | Type | Description | Range
--------- | ---- | ----------- | -----
-audio_sample_type::i8 | i8 | 8-bit signed | -127..+127
-audio_sample_type::i16 | i16 | 16-bit signed | -32767..+32767
-audio_sample_type::i24 | i24 | 24-bit signed | -8388607..+8388607
-audio_sample_type::i32 | i32 | 32-bit signed | -2147483647..+2147483647
-audio_sample_type::i64 | i64 | 64-bit signed | -9223372036854775807..+9223372036854775807
-audio_sample_type::f32 | f32 | 32-bit IEEE | -1..+1
-audio_sample_type::f64 | f64 | 64-bit IEEE | -1..+1
+| Constant | Type | Description | Range |
+|------------------------|------|---------------|--------------------------------------------|
+| audio_sample_type::i8 | i8 | 8-bit signed | -127..+127 |
+| audio_sample_type::i16 | i16 | 16-bit signed | -32767..+32767 |
+| audio_sample_type::i24 | i24 | 24-bit signed | -8388607..+8388607 |
+| audio_sample_type::i32 | i32 | 32-bit signed | -2147483647..+2147483647 |
+| audio_sample_type::i64 | i64 | 64-bit signed | -9223372036854775807..+9223372036854775807 |
+| audio_sample_type::f32 | f32 | 32-bit IEEE | -1..+1 |
+| audio_sample_type::f64 | f64 | 64-bit IEEE | -1..+1 |
diff --git a/docs/docs/expressions.md b/docs/docs/expressions.md
@@ -51,7 +51,7 @@ univector<int, 5> z = x - y;
```
!!! note
- when an expression is assigned to a `univector` variable, expression is evaluated in `process` function and values are being written to the target storage.
+ When an expression is assigned to a `univector` variable, expression is evaluated in `process` function and values are being written to the target storage.
Same applies to calling KFR functions on univectors, this doesn't calculate values immediately. Instead, new expression will be created.
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -2,12 +2,12 @@
## Getting started
-* [What's new in KFR 5](whatsnew5.md)
+* [What's new in KFR 6](whatsnew6.md)
* [Installation](installation.md)
* [Basics](basics.md)
* [Expressions](expressions.md)
* [C API](capi.md)
-* [Upgrade to KFR 5](upgrade5.md)
+* [Upgrade to KFR 6](upgrade6.md)
## Guides
diff --git a/docs/docs/installation.md b/docs/docs/installation.md
@@ -8,15 +8,15 @@ KFR is tested and supported on the following systems and architectures:
**CPU** • x86 • x86_64 • ARM • ARM64 (AArch64)
-**x86 extensions** • SSE2 • SSE3 • SSSE3 • SSE4.1 • SSE4.2 • AVX • AVX2 • AVX512 • FMA
+**x86 extensions** • SSE2 • SSE3 • SSSE3 • SSE4.1 • SSE4.2 • AVX • AVX2 • FMA • AVX512
**ARM extensions** • NEON
-**Compiler** • GCC7+ • Clang 9+ • MSVC2019+ • Xcode 10.3+
+**Compiler** • GCC7+ • Clang 11+ • MSVC2019+ • Xcode 12+
## Prerequisites
-* CMake 3.10 or newer for building tests and examples
+* CMake 3.12 or newer for building tests and examples
* Python 3.6+ for running examples
* (recommended) Ninja (https://ninja-build.org/) for faster builds
@@ -29,25 +29,9 @@ pip install -r requirements.txt
### Clang
-Clang is highly recommended and proven to provide the best performance for KFR.
+Clang is highly recommended and proven to provide the best performance for KFR.
-#### Installing Clang on Linux
-
-Install clang using your package manager and add the following defines to the cmake command line:
-
-```bash
-cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ...
-```
-
-#### Installing Clang on macOS
-
-On macOS clang is the default compiler and already included in the official Xcode toolchain. No additional setup required.
-
-#### Installing Clang on Windows
-
-Download and install the latest `win64` build from the official LLVM GitHub page:
-
-https://github.com/llvm/llvm-project/releases
+See [how to install and setup Clang](clang.md)
## Getting KFR source code and binaries
@@ -61,23 +45,6 @@ git clone https://github.com/kfrlib/kfr.git
The repository default branch `main` is stable and passes all tests. Latest features reside in `dev`.
-#### Update
-
-```bash
-# in the kfr directory
-git pull
-```
-
-### Tarball/zip
-
-Download the latest release package from the GitHub releases:
-
-https://github.com/kfrlib/kfr/releases
-
-#### Update
-
-Re-download tarball and unpack it to the same location.
-
### vcpkg
#### vcpkg on Linux/macOS
@@ -105,244 +72,92 @@ Prebuilt binaries will be available soon.
## Usage
-### Including in CMake project (add_subdirectory)
-
-`CMakeLists.txt` contains these libraries:
-* `kfr` - header only interface library
-* `kfr_dft` - static library for DFT and related algorithms
-* `kfr_io` - static library for file IO and audio IO
-
-```cmake
-# Include KFR subdirectory
-add_subdirectory(kfr)
-
-# Add header-only KFR to your executable or library, this sets include directories etc
-target_link_libraries(your_executable_or_library kfr)
-
-# Add KFR DFT to your executable or library, (cpp file will be built for this)
-target_link_libraries(your_executable_or_library kfr_dft)
-
-# Add KFR IO to your executable or library, (cpp file will be built for this)
-target_link_libraries(your_executable_or_library kfr_io)
-```
-
-### Makefile, command line etc (Unix-like systems)
-
-```bash
-# Add this to command line
--Ipath_to_kfr/include
-
-# And this if needed
--lkfr_dft -lkfr_io
-
-# C++17 mode must be enabled
--std=c++17
-# or
--std=gnu++17
-
-# linker options (requires kfr to be installed)
--lkfr_dft -lkfr_io
-```
-
-### Linux
-
-#### Prerequisites
-
-* GCC 7 or newer
-* Clang 9.0 or newer (recommended)
-
-#### Command line
-
-```bash
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -DENABLE_TESTS=ON -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release ..
-make -- -j
-```
-Or using Ninja (better):
-```bash
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -GNinja -DENABLE_TESTS=ON -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release ..
-ninja
-```
-
-### macOS
-
-#### Prerequisites
-
-* Xcode 10.3 or later
+### VCPKG
-#### Command line
-Using Xcode project:
-```bash
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -GXcode -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Release ..
-cmake --build .
-```
-Using Unix Makefiles:
-```bash
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -G"Unix Makefiles" -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Release ..
-make -- -j
-```
-Or using Ninja (better):
-```bash
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -GNinja -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Release ..
-ninja
-```
-
-### Visual Studio
-
-#### Prerequisites
-* Visual Studio 2019 or later
-* Latest Clang (https://llvm.org/)
-* Ninja is highly recommended because Visual Studio does not support parallel build with Clang at this moment.
-
-#### Visual Studio IDE
-
-To work with KFR in Visual Studio you must add the path to the `include` directory inside KFR directory to the list of the project's include directories.<br>
-More details:
-https://learn.microsoft.com/en-us/cpp/build/reference/vcpp-directories-property-page?view=msvc-160
-
-Make sure that LLVM toolset is set for the project.
-
-Download and install the official LLVM toolchain extension:
-https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain
+Refer to the vcpkg documentation for instructions on using libraries installed through vcpkg.
-More details:
-https://docs.microsoft.com/en-us/cpp/ide/general-property-page-project?view=vs-2017
+### Build and install KFR (recommended)
-LLVM/Clang has very good compatibility with MSVC ABI and is widely used for building large projects on Windows (including Chrome), so switching to LLVM/Clang should not cause any compatibility problems.
+This way, KFR binaries are built in a separate step (Ninja is required).
-#### Command line
-Using Ninja:
-```
-cd <path_to_kfr>
-mkdir build && cd build
-call "C:\<path to your Visual Studio installation>\VC\Auxiliary\Build\vcvars64.bat"
-cmake -GNinja -DENABLE_TESTS=ON -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" -DCMAKE_BUILD_TYPE=Release ..
-ninja
-```
-Or generate Visual Studio solution (building will be slower):
-```
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -G"Visual Studio 16 2019 Win64" -DENABLE_TESTS=ON -Tllvm -DCMAKE_BUILD_TYPE=Release ..
+```shell
+cd path/to/kfr/repository
+cmake -B build-release -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=path/to/kfr/install/dir -DCMAKE_CXX_COMPILER=path/to/clang
+ninja -C build-release install
+cmake -B build-debug -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=path/to/kfr/install/dir -DCMAKE_CXX_COMPILER=path/to/clang
+ninja -C build-debug install
```
-### MinGW/MSYS
-
-#### Prerequisites
-* Latest MinGW or MSYS2
-* Clang 9.0 or newer
+The following directory tree will be produced after successfull install:
-Using Makefiles:
-```
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Release ..
-make -- -j
```
-Using Ninja:
+include
+ kfr
+ all.hpp
+ base.hpp
+ dsp.hpp
+ dft.hpp
+ io.hpp
+ ...
+lib
+ cmake
+ kfr
+ KFRConfig.cmake
+ KFRConfig-release.cmake
+ KFRConfig-debug.cmake
+ KFRConfigVersion.cmake
+ debug
+ kfr-debug-libraries...
+ kfr-libraries...
```
-cd <path_to_kfr>
-mkdir build && cd build
-cmake -GNinja -DENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Release ..
-ninja
-```
-
-## Compile for multiple architectures
-### Linux/macOS
+### CMake `find_package`
-There are two ways to use KFR. Use one architecture everywhere (but it must match in static library and your project) or use multiple architectures (selected at runtime).
+First, KFR binaries should be built as in [Build and install KFR](#build-and-install-kfr-recommended) section.
-#### 1. Single architecture (simpler setup)
-Use -DKFR_ARCH=avx2 (or avx or sse41 or even sse2) when you run CMake to install KFR.
-Example:
-```
-cmake -GNinja -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release -DKFR_ARCH=avx2 ..
-ninja
-sudo ninja install # This installs libkfr_dft.a
-```
-The same architecture should be used when building source files:
-Example:
-```
-g++ -mavx2 ... your_source.cpp -lkfr_dft
+```cmake
+# CMAKE_PREFIX_PATH must contain path-to-kfr-install-dir/lib/cmake
+find_package(KFR CONFIG REQUIRED)
+target_link_libraries(main PRIVATE kfr kfr_dsp)
```
-Then linking works well and KFR will use avx2 instructions for both DFT and other functions (built in your code).
+### Including in your project directly (add_subdirectory)
-Code from `examples/dft.cpp` will show:
-```
-KFR 5.1.0 avx2 64-bit (gcc-11.4.0/linux) +in
-fft_specialization<double, 7>(avx2): 0, 128, 3072, 0, 1, 0, 0, 0, 1, 0, 0
-```
+This way, KFR binaries will be built in your project's build directory as part of building your project.
-#### 2. Multiple architectures (best performance)
-
-Setting `KFR_ENABLE_MULTIARCH` to `ON` enables multiple architectures.
-In this case instead of a single `libkfr_dft.a` multiple arch-specific libraries will be installed.
-```
-cmake -GNinja -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release -DKFR_ENABLE_DFT_MULTIARCH=ON ..
-ninja
-sudo ninja install # This installs libkfr_dft_sse2.a libkfr_dft_sse41.a libkfr_dft_avx.a libkfr_dft_avx2.a libkfr_dft_avx512.a
-```
+After inclusion of KFR, the following CMake targets will be available:
+* `kfr` - header only interface library
+* `kfr_dft` - static library for DFT and related algorithms
+* `kfr_dsp` - static library for DSP algorithms
+* `kfr_io` - static library for file IO and audio IO
-Then you can compile your code using any architecture settings but should link all KFR DFT libraries:
-Example (gcc will select sse2 for `your_source.cpp`):
-```
-g++ your_source.cpp -Wl,--push-state,--whole-archive -lkfr_dft_sse2 -Wl,--pop-state -lkfr_dft_sse41 -lkfr_dft_avx -lkfr_dft_avx2 -lkfr_dft_avx512
-```
-`whole-archive` flag is needed to link inline and template functions with correct architecture.
+```cmake
+# Include KFR subdirectory
+add_subdirectory(kfr kfr-build-dir)
-KFR code will detect cpu at runtime and select appropriate code path for DFT.
+# Add header-only KFR to your executable or library, this sets include directories etc
+target_link_libraries(your_executable_or_library PUBLIC kfr)
-Code from `examples/dft.cpp` will show:
+# for <kfr/dsp.hpp>
+target_link_libraries(your_executable_or_library PUBLIC kfr_dsp)
+# for <kfr/dft.hpp>
+target_link_libraries(your_executable_or_library PUBLIC kfr_dft)
+# for <kfr/io.hpp>
+target_link_libraries(your_executable_or_library PUBLIC kfr_io)
```
-KFR 5.1.0 sse2 64-bit (gcc-11.4.0/linux) +in
-fft_specialization<double, 7>(avx2): 0, 128, 3072, 0, 1, 0, 0, 0, 1, 0, 0
-```
-
-Notice that first mentioned architecture is sse2 (architecture used for `your_source.cpp`) while the second is now avx2 (dft source selected at runtime)
-### Windows
+### Makefile, command line etc (Unix-like systems, not recommended)
-For Windows build instructions are similar but below are exact commands.
+First, KFR binaries should be built as in [Build and install KFR](#build-and-install-kfr-recommended) section.
-#### 1. Single architecture (simpler setup)
+Then see [using KFR without CMake](without_cmake.md)
-```
-:: Warning: VS Path and LLVM Path may be different on your machine
-call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
-cmake -GNinja -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" -DCMAKE_LINKER="C:/Program Files/LLVM/bin/lld-link.exe" -DCMAKE_BUILD_TYPE=Release -DKFR_ARCH=avx2 -DCMAKE_INSTALL_PREFIX=install ..
-ninja
-ninja install # This installs kfr_dft.lib to CMAKE_BINARY_DIR/install
-```
+### Visual Studio
-Then, the following compile options must be added (through VS Project Properties or CMake target_compile_options)
+First, KFR binaries should be built as in [Build and install KFR](#build-and-install-kfr-recommended) section.
-```
-/arch:AVX2 "PATH-TO-INSTALLED-KFR/lib/kfr_dft.lib"
-```
-As always `/arch` must match `KFR_ARCH` argument in CMake call.
+Then see [using KFR without CMake](without_cmake.md)
-#### 2. Multiple architectures (best performance)
+### MinGW/MSYS
-```
-:: Warning: VS Path and LLVM Path may be different on your machine
-call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
-cmake -GNinja -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" -DCMAKE_LINKER="C:/Program Files/LLVM/bin/lld-link.exe" -DCMAKE_BUILD_TYPE=Release -DKFR_ENABLE_DFT_MULTIARCH=ON -DCMAKE_INSTALL_PREFIX=install ..
-ninja
-ninja install # This installs kfr_dft_sse2.lib kfr_dft_sse41.lib kfr_dft_avx.lib kfr_dft_avx2.lib kfr_dft_avx512.lib to CMAKE_BINARY_DIR/install
-```
-`KFR_ENABLE_MULTIARCH=ON` is the key option here.
-```
-/WHOLEARCHIVE:"PATH-TO-INSTALLED-KFR/lib/kfr_dft_sse2.lib" "PATH-TO-INSTALLED-KFR/lib/kfr_dft_sse41.lib" "PATH-TO-INSTALLED-KFR/lib/kfr_dft_avx.lib" "PATH-TO-INSTALLED-KFR/lib/kfr_dft_avx2.lib" "PATH-TO-INSTALLED-KFR/lib/kfr_dft_avx512.lib"
-```
-`/WHOLEARCHIVE` for sse2 lib is required here for the same reason as linux code has `--whole-archive`: to force compiler to select correct inline/template functions from multiple similar libraries. Without this a runtime invalid instruction exception may occur.
+MinGW/MSYS environments are deprecated since KFR6 and no longer maintained. Use at your own risk.
diff --git a/docs/docs/upgrade6.md b/docs/docs/upgrade6.md
@@ -0,0 +1,114 @@
+# Migration to KFR6
+
+Here is migration guide to upgrade from KFR5.x to KFR6.
+
+For upgrade from KFR4.x to KFR5 see [Upgrade to KFR 5](upgrade5.md)
+
+## Multiarchitecture and C API
+
+### Multiarchitecture is enabled by default
+
+In KFR5 only DFT had support for multiarchitecture. This was controlled by the`KFR_ENABLE_DFT_MULTIARCH` CMake option (default `OFF`).
+
+Since KFR6, multiarchitecture is controlled by the `KFR_ENABLE_MULTIARCH` (default `ON`) and is supported by more algorithms.
+
+`KFR_ARCHS` CMake variable controls the list of the architectures for which the code will be generated.
+
+```
+cmake ... -DKFR_ARCHS=sse2;avx;avx2
+```
+
+This feature is now fully transparent to the users of the KFR library and doesn't require any changes to the source code.
+
+### C API is supported on non-x86 platforms
+
+On Linux and macOS, the following CMake option is required for building the C API:
+
+```shell
+-DCMAKE_POSITION_INDEPENDENT_CODE=ON
+```
+
+Note that this makes all static libraries built in KFR directory position-independent.
+
+The C API requires that `KFR_ENABLE_MULTIARCH` be enabled.
+
+### IIR, FIR filters and resampling now support multiarchitecture
+
+## Name changes
+
+| KFR5 | KFR6 |
+|---------------------------------|-----------------------------|
+| `biquad_params<T>` | → `biquad_section<T>` |
+| `biquad_filter<T>` | → `iir_filter<T>` |
+| `biquad(params, expression)` | → `iir(expression, params)` |
+| `expression_biquad` | → `expression_iir` |
+| `biquad_blocks<T, N>` | → `iir_params<T, N>` |
+| `std::vector<biquad_params<T>>` | → `iir_params<T>` |
+| `fir_taps<T>` | → `fir_params<T>` |
+
+The old names works in KFR6 but are marked deprecated.
+
+## CMake config files
+
+During install CMake config files are now generated.
+
+```cmake
+# CMAKE_PREFIX_PATH must contain path-to-kfr-install-dir/lib/cmake
+find_package(KFR CONFIG REQUIRED)
+target_link_libraries(main PRIVATE kfr kfr_dsp)
+```
+
+# Linking
+
+It is important to link KFR libraries correctly when using the multiarchitecture feature.
+
+The following methods automatically ensure that linking is correct:
+
+* `add_subdirectory`.
+* Installing KFR and using `find_package(KFR CONFIG)`
+
+If you use different method please follow [these instructions](without_cmake.md).
+
+## Other changes
+
+### `kfr::complex` type removed in favor of using `std::complex`
+
+The `KFR_STD_COMPLEX` CMake option and `KFR_STD_COMPLEX` macro are removed.
+
+### `KFR_DFT_NO_NPo2` macro is no more used. Non-power of 2 DFT is always enabled
+
+The `KFR_ENABLE_DFT_NP` CMake option is removed too.
+
+### `tensor<>::reshape_may_copy` and `tensor<>::flatten_may_copy` change parameters default values
+
+In KFR6 default behavior is to allow copying (as name suggests);
+```c++
+auto t = mytensor.reshape_may_copy(new_shape);
+```
+
+## Requirements
+
+### Clang minimum version is now 11
+
+Please update your build environment if you're using Clang 10 or older.
+
+### CMake minimum version is now 3.12
+
+Please update your build environment if you're using CMake 3.11 or older.
+
+## KFR Internals
+
+### DFT, DSP and IO sources have been moved to `src/` directory
+
+### `expression_make_function` must be used for expression function prototypes
+
+Before KFR6
+```c++
+template <typename E1, KFR_ACCEPT_EXPRESSIONS(E1)>
+KFR_FUNCTION expression_function<fn::sin, E1> sin(E1&& x);
+```
+KFR6
+```c++
+template <typename E1, KFR_ACCEPT_EXPRESSIONS(E1)>
+KFR_FUNCTION expression_make_function<fn::sin, E1> sin(E1&& x);
+```
diff --git a/docs/docs/whatsnew6.md b/docs/docs/whatsnew6.md
@@ -0,0 +1,55 @@
+# What's new in KFR 6
+
+* DFT performance has been improved up to 40% (backported to KFR 5.2.0 branch)
+* C API for non x86 architectures
+* DSP refactoring with easier initialization
+* Multiarchitecture for resampling, FIR and IIR filters
+* `matrix_transpose`: optimized matrix transpose (square/non-square, inplace/out-of-place, real/complex, scalar/vectors)
+* CMake config file generation (`find_package(KFR CONFIG)` support, see [installation](installation.md))
+* `.npy` format support (reading/writing, v1/v2, c/fortran order, real/complex, bigendian/littleendian)
+* Multidimensional DFT: real/complex
+* `inline_vector`
+
+### Other changes
+
+* CMake minimum version is 3.12
+* Multidimensional reference DFT
+* Easier cross compilation to ARM64 on x86_64 macOS
+* Automated tests using GitHub Actions (previously Azure Pipelines)
+* GCC 7 and 8: emulate missing avx-512 instrinsics
+* `read_group` and `write_group`
+* [❗breaking change] `reshape_may_copy` and `flatten_may_copy` in `tensor<>` allows copying by default
+* `shape<>::transpose` function
+* `tensor<>::transpose` function
+* `convert_endianess`
+* DFT, DSP and IO sources have been moved to `src/` directory
+* Multiarchitecture is enabled by default
+* `KFR_DFT_NO_NPo2` has been removed (assumed always enabled)
+* Tests refactoring
+* Some tests moved to `tests/internal/`
+* [❗breaking change] Scalars are now passed by value in expressions (this fixes dangling references in some cases)
+* Expression functions should return `expression_make_function` instead of `expression_function`
+* `KFR_WITH_CLANG`
+* `KFR_VERSION` CMake variable
+* Functions to get module versions (`library_version_dft`, `library_version_dsp` etc)
+* Exceptions are no longer enforced in MSVC
+* `kfr::complex` removed (use `std::complex` instead). `KFR_STD_COMPLEX` cmake variable removed too
+* `strides_for_shape` for fortran order
+* AARCH and ARM emulation refactoring (dynamic libraries are now supported)
+* `call_with_temp`
+* `maximum_dims` is now 16 (was 8)
+* `to_fmt`/`from_fmt` supports inplace
+* `shape` refactoring: `rotate_left`, `rotate_right`, `remove_back`, `remove_front`
+* temp argument can be `nullptr` for DFT (temporary buffer will be allocated on stack or heap)
+* `dft_plan` and similar classes have now default and move constructors
+* `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` is required for building C API
+* `ci/run.sh` can now build in a directory outside source tree
+* [❗breaking change]`graphics/color.hpp` and `graphics/geometry.hpp` have been removed
+* Simpler `CMT_CVAL` macro
+* `/Zc:lambda` is now required for building KFR in MSVC
+* `println` for `string_view`
+* MSVC internal compiler error fixed
+* Complex vector operators fixed
+
+
+For KFR5 changelog see [What's new in KFR 5](whatsnew5.md)
diff --git a/docs/docs/without_cmake.md b/docs/docs/without_cmake.md
@@ -0,0 +1,103 @@
+# Using KFR without CMake
+
+The following methods provide a much simpler way to build and use KFR but involves CMake:
+
+* `add_subdirectory`.
+* Installing KFR and using `find_package(KFR CONFIG)`
+
+Both methods are described in the [installation guide](installation.md).
+
+It is recommended to use these methods for a hassle-free experience.
+
+If you use different method please follow the instructions below.
+
+## Header path
+
+### Visual Studio
+
+The `include` subdirectory of the KFR directory must be added to the `Include directories` section in Project's properties.
+
+### Command line
+
+```shell
+-Ipath-to-kfr-repository/include
+```
+
+## Compiler flags
+
+### Visual Studio
+
+These compiler flags are required for KFR to work in Visual Studio.
+* `/Zc:lambda /bigobj`
+
+These flags must be added to C/C++ → Command line → Additional options.
+
+### Command line
+
+
+## Linking KFR in Multiarchitecture mode (`KFR_ENABLE_MULTIARCH=ON`, default)
+
+Multiarchitecture mode enables building algorithms multiple times, each for a different architecture.
+It adds runtime dispatch, allowing KFR to detect the CPU of the target machine and select the appropriate code path for algorithms.
+
+It is important to link KFR libraries correctly when using the multiarchitecture feature.
+
+In this example, we assume that `KFR_ARCHS` is set to `sse2;avx;avx2` with SSE2 being the base architecture.
+DFT and DSP modules are multiarchitecture-enabled while IO modules is not.
+
+KFR building produces the following static libraries:
+```
+# DFT module, <kfr/dft.hpp>
+kfr_dft_sse2
+kfr_dft_avx
+kfr_dft_avx2
+# DSP module, <kfr/dsp.hpp>
+kfr_dsp_sse2
+kfr_dsp_avx
+kfr_dsp_avx2
+# IO module, <kfr/io.hpp>
+kfr_io
+```
+
+!!! note
+ Exact name on Linux/macOS is `libkfr_dft_sse2.a` on Windows is `kfr_dft_sse2.lib` for `kfr_dft_sse2`
+
+The linking command line must contain the foolowing commands _before_ any KFR libraries:
+
+Linux:
+```shell
+--push-state --whole-archive kfr_dft_sse2 kfr_dsp_sse2 --pop-state
+```
+macOS:
+```shell
+-force_load path/to/libkfr_dft_sse2.a -force_load path/to/libkfr_dsp_sse2.a
+```
+Windows:
+```batch
+/WHOLEARCHIVE:path\to\kfr_dft_sse2.lib /WHOLEARCHIVE:path\to\kfr_dsp_sse2.lib
+```
+
+Without this, the linker may select incorrect functions which results in invalid instruction exception on older systems.
+
+Your project's target architecture should match the lowest architecture selected during KFR build. In the example above, it is SSE2.
+
+Add the `/arch` or `-m` flag to select the appropriate architecture for your code, or adjust `KFR_ARCHS` so that KFR matches your project settings.
+
+## Linking KFR in single architecture mode (`KFR_ENABLE_MULTIARCH=OFF`)
+
+KFR building produces the following static libraries:
+
+```
+# DFT module, <kfr/dft.hpp>
+kfr_dft
+# DSP module, <kfr/dsp.hpp>
+kfr_dsp
+# IO module, <kfr/io.hpp>
+kfr_io
+```
+
+Add these libraries to the command line or the link libraries list of your build system.
+
+Your project's target architecture should match the architecture selected during KFR build.
+
+Add the `/arch` or `-m` flag to select the appropriate architecture for your code, or adjust `KFR_ARCH` so that KFR matches your project settings.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -27,7 +27,7 @@ extra:
- icon: fontawesome/brands/twitter
link: 'https://twitter.com/kfrlib'
-copyright: 'Copyright © 2016 - 2023 KFR'
+copyright: 'Copyright © 2016 - 2024 KFR'
plugins:
- search
@@ -63,12 +63,12 @@ edit_uri: edit/master/docs/
nav:
- KFR:
- index.md
- - whatsnew5.md
+ - whatsnew6.md
- installation.md
- basics.md
- expressions.md
- capi.md
- - upgrade5.md
+ - upgrade6.md
- DSP:
- fir.md
- bq.md
