README.md 2.63 KB
Newer Older
steinbac's avatar
steinbac committed
1
[![Build Status](https://travis-ci.org/psteinb/compass.svg?branch=master)](https://travis-ci.org/psteinb/compass)
steinbac's avatar
steinbac committed
2
[![Build status](https://ci.appveyor.com/api/projects/status/dvgk88ynuuvx1ldi/branch/master?svg=true)](https://ci.appveyor.com/project/psteinb/compass/branch/master)
steinbac's avatar
steinbac committed
3 4

# compass 
5 6 7

A drop-in header-only C++ library to detect hardware capabilities at runtime and at compiletime.

steinbac's avatar
steinbac committed
8
## How to use it?
9 10 11

You have 2 options:

12
1. you can just copy the contents of `single_include` (or `include` if you like to have multiple folders and source code files)  into your project and off you go
13

steinbac's avatar
steinbac committed
14
2. you use the cmake build infrastructure to put compass in a desired folder
15

steinbac's avatar
steinbac committed
16
    - on *NIX platforms and macOS/OSX
17 18 19 20 21 22 23
    ```
    $ cd repo
    $ mkdir build && cd build
    $ cmake -DCMAKE_INSTALL_PREFIX=/path/where/compass/needs/to/go ..
    $ make && ctest
    $ make install #depending on the contents of CMAKE_INSTALL_PREFIX, you may use sudo
    ```
steinbac's avatar
steinbac committed
24

25
    - on Windows platforms (assuming that `cmake` is in your `PATH`)
26 27 28 29
	```
	> cd repo
	> mkdir build
	> cd build
30
	> cmake.exe -G "Visual Studio 14 2015 Win64" ..
31 32 33
	> cmake.exe --build . --target ALL_BUILD --config Release
	> ctest.exe -C Release
	```
34

35
(3.) tests should only be run on the hardware where `cmake` was called. `CMakeLists.txt` is trying hard to detect the hardware features at `cmake` invocation. They are then included in the unit test suite. 
steinbac's avatar
steinbac committed
36

37 38 39 40 41 42 43 44
## Compass API

Here is a minimal code example that tries to detect SSE4 at runtime:

```
#include <iostream>
#include "compass.hpp"

45 46
using namespace compass;

47 48
int main(int argc, char** argv){

49
    if(runtime::has(feature::sse4()))
50 51
        std::cout << "SSE4 found!!\n";
    else
52
        std::cout << "This is an old machine. I hope I don't break anything.\n";
53 54 55 56 57 58 59
        
    return 0;

}

```

60 61
if you want to learn more supported features, check this [test file](tests/test_build_machine.cpp).

62 63 64 65
## Help needed 

This project is quite small, so here is your chance to boost open-source to the benefit of the entire C++ community.

66 67 68 69 70
- [ ] code review the model to extend compass for new compilers/platforms/OSes
- [ ] code review the model to extend compass for new features
- [ ] is thread-safety an issue of the current implementation ?
- [ ] contribute for adding Intel compiler on x86
- [ ] contribute for GPUs (nvcc)
steinbac's avatar
steinbac committed
71
- [ ] extend support for OpenPower (gcc)
steinbac's avatar
steinbac committed
72
- [ ] contribute for ARM (gcc/clang) if you have according hardware available
73

74
A good place to start and to see what is needed, is llvm [`Host.cpp`](http://llvm.org/docs/doxygen/html/Host_8cpp_source.html) file.
75

76 77
## License

steinbac's avatar
steinbac committed
78
This project is licensed under the BSD 3-clause open source license. See [LICENSE](LICENSE) for details.