k52 is a set of c++ libraries aimed to facilitate scientific experiments in the fields of signal processing and sound analysis with the strong incline into OOP, flexibility and readability. It also provides the implementation of some optimization, classification and other methods, as well as set of handy tools to support parallel computing. Distributed under the MIT License.
On both Linux and Windows you should install git and clone k52 repository.
For example you can create folder e:\example\
and run following commands from command prompt:
$ cd "e:\example"
$ git clone [email protected]:PavelKovalets/k52.git
Now you will have e:\example\k52
folder which contains k52 code. We will call it the k52 root folder.
Prerequisites:
- Visual Studio with c++ development tools
- CMake installed
In this example we will use e:\example
as a folder in which we will build k52. You can use any other folder path if you want.
Hint: However you should check that your full path doesn't contain spaces, otherwise some CMake code will fails (e.g. boost required headers will not be found)
Steps:
- Install boost dependency
- Download latest boost version ( at the moment of writing it was boost 1.61.0 )
- Extract it into
e:\example\
. After that you should have a foldere:\example\boost_1_61_0\
with, apart of others,bootstrap.bat
in it. - Add path into
k52.config
– corresponding line should be
set(BOOST_ROOT "e:\\example\\boost_1_61_0")
- Prepare the solution
- Create a folder to build in -
e:\example\k52\build\
- Run CMake from this folder from command line
(you might need to add
/d
option forcd
command if you are changing the drive e.g. fromc:\
toe:\
):
$ cd "e:\example\k52\build"
$ cmake ..
- Build k52
- Open the solution file which was created by CMake -
e:\example\k52\build\k52.sln
- Build the solution
This is the minimum set of steps to build k52. However some parts of k52 will not be build. To get fully-functional version you need to make some additional steps. After that you should re-run CMake to update the solution.
- Compile required boost libs
- Just run following commands from boost folder -
e:\example\boost_1_61_0\
$ bootstrap
$ .\b2 --with-test --with-thread --with-system --with-date_time
In case you have MPI installed on your system you can also add
--with-mpi --with-serialization
to compile k52 with MPI support,
but this is more advanced case and usually not required.
-
Install FFTW3 library
-
Download precompiled dlls
-
Extract into
c:\example\fftw-3.3.5-dll32
- we will call it FFTW3 folder. -
Only dynamic libs are precompiled. In order to link them from Visual C++, you need to create
.lib
"import libraries". To do this run following commands from FFTW3 folder.lib
command must be available, so one option is to use Developer Command Prompt for Visual Studio
$ lib /def:libfftw3-3.def
$ lib /def:libfftw3f-3.def
$ lib /def:libfftw3l-3.def
- Add path into
k52.config
– corresponding line should be
set(FFTW3_ROOT "C:\\example\\fftw-3.3.5-dll32")
- Now everything will compile, but in oreder to run FFTW3-dependent code
(e.g. unit tests project) you need to reference dlls.
You could either copy all dlls from FFTW3 folder to the folder with your
.exe
file or add it toPATH
environment variable (in Visual Studio go to project properties (Alt+F7), under Debugging, find an Environment field and set it toPATH=%PATH%;C:\example\fftw-3.3.5-dll32
).
All you have to do is:
- Run
$./tools/bootstrap.sh
script from k52 root folder to install k52 dependencies - Run
$./tools/build_k52_run_examples.sh
script from k52 root folder to build k52 and run its examples
In case of CMake - aware IDE's you just need to open CMake file from k52 root folder and build it.
Else, from k52 root folder execute following commands using cmd:
$ mkdir build
$ cd build
$ cmake ..
This will create project files for your default compiler/IDE in build
folder. You should check if there were no errors from ->-> K52 MESSAGE <-<-, if there are - try to fix them.
Now you have all the files that are necessary to build k52 in build
folder.
- Visual Studio - find .sln file in
build
folder and run it. - make - execute
$ make
frombuild
folder .
- Visual Studio - build
RUN_TESTS
project fromk52.sln
and see the output. - make - execute
$ make test
frombuild
folder and see the output.
k52 provides CMake config-file package during the install process. It can be then used by other CMake project to easily use k52.
To do so first you have to run install $ make install
(or build INSTALL project in VS).
After that you'll have install
folder in k52 root folder,
which contains all necessary files - config-file package, libs, headers.
After that you just need to link this config-file package in your project and use find_package(k52 CONFIG)
.
Example CMake project file that uses such config-file package is following:
cmake_minimum_required(VERSION 3.0)
set(PROJECT_NAME "test_project")
project(${PROJECT_NAME})
set(BOOST_ROOT "[your Boost root path here]")
find_package(Boost REQUIRED)
include_directories(${Boost_INCLUDE_DIRS})
find_package(k52 CONFIG REQUIRED HINTS "[your k52 install path here]")
include_directories(${k52_INCLUDE_DIRS})
link_directories(${k52_LIBRARY_DIRS})
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} ${k52_LIBRARIES})
Hint You can take a look at the tools/build_k52_run_examples.sh
script and try to run its commands
one by one to get the complete picture of how to use k52.
Or you can check to the examples
folder which contains working examples of k52 usage.
common
- helper classes, generic templates, patterns implementation, regularly-used functionalityoptimization
- implementation of various optimization methods for both discrete and continuous objective functionsdsp
- implementation of various signal processing and sound analysis algorithms and methodsparallel
- set of tools and helpers to support commonly-used parallel computing technologies (threads, MPI), with no or almost no set-up and infrastructural code required
k52 uses Gitflow Workflow. We have following dedicated branches:
master
- stores the official release history. All commits here must be tagged with a release version number.develop
- serves as an integration branch for features.coverity_scan
- serves as the source branch for the static analisys tool.develop
should be merged into this branch from time to time to detect new defects, e.g. before creating new commit inrelease
branch.- other feature branches - the implimentation and bugfixes should be done in these branches. They are branched from
develop
, have names corresponding to the taks being implemented, and then merged back todevelop
when task is finished.
The k52 root folder has following content:
cmake
- CMake external modules are loaded from this folderconfiguration
- contains CMake-specific configuration files, should not be edited unless requiredexamples
- contains example projects of how k52 might be usedinclude
- contains all k52 public headersinstall
- will be created on k52 install and contain all files necessary to use k52 in another projectsrc
- contains all k52 private headers and source filescommon
- lib source filesdsp
- lib source filesoptimization
- lib source filesparallel
- lib source filesunit_tests
- unit tests for k52 libstools
- set of useful scripts for k52 usage
-
k52.config
- main configuration file for CMake system, normally should be edited by the end user to contain all the settings corresponding to the machine k52 is build on (like FFTW3_ROOT) -
k52-config.cmake.in
- template file for CMake fing_package support -
tools/bootstrap.sh
- linux shell script to setup all necessary environment to build k52, used in Vagrant box, but also could be used on any other system -
tools/build_k52_run_examples.sh
- linux shell script to demonstrate the process of k52 build and usage; builds k52 to correspondingtools_build
folders, installs it intoinstall
folder, builds k52 examples to correspondingtools_build
folders and runs examples; can be used on Vagrant -
tools/encoding.sh
- linux shell script to check if all k52 source files have ASCII 7 bit encoding (only Latin symbols); outputs the name of files with different encoding, no output if encoding is ok -
CMakeLists.txt
- root CMake file -
LICENSE
- file with license -
README.md
- &(*this) -
CONTRIBUTING.md
- file which contains guidelines for those who wish to contribute to k52 via pull request -
Vagrantfile
- file with Vagrant settings (see below how to use) -
.gitattributes
- git settings, applied to the repository -
.gitignore
- used to exclude files from git tracking -
.travis.yml
- file with configuration for Travis CI
CMake, the cross-platform, open-source build system is used in k52, so you must install it to build k52. While theoretically any platform supported by CMake will be ok, the tested are Windows and Linux. make system is fully supported.
Following IDE might be helpful:
- CLion (really good one, limited evaluation)
- Visual Studio (not bad too, free)
- KDevelop (free)
- Eclipse CDT (free)
Vagrant is a handy tool that easily provides the environment on which k52 can be build:
- Install some virtualization provider (e.g. VirtualBox)
- Install Vagrant and read about it
- From project root (containing Vagrantfile) launch a console, create a vagrant VM, connect to the VM, and go to the project directory
$ vagrant up
$ vagrant ssh
$ cd /vagrant
- Now you can just make steps form Linux quick start example in your console. You do not need to install dependencies because Vagrant does it on start up.
- If any script from
tools
folder fails to run on Vagrant and you are using Windows host, try to temporary change script file's EOL format to Linux (Vagrant use files directly).
- For Visual Studio there might be problems with libs
(e.g.
cannot open file libboost_date_time-vc120-mt-gd-1_55.lib
). Not completelly clear, is it a bug or feature, but according to http://www.boost.org/doc/libs/1_54_0/doc/html/thread/build.html it is fixed by compiling ALL dependant libs explicitly
$ bjam --build-type=complete --with-thread --with-chrono --with-date_time)