README.md 2.67 KB
Newer Older
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)
3 4

# compass 
5 6 7

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

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

14
2. you use the cmake build infrastructure to put compass in a desired folder
15

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
    ```
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. 
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;

}

```

Peter Steinbach's avatar
Peter Steinbach committed
60
if you want to learn more supported features, check this [test file](tests/test_machine.cpp).
61

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)
Peter Steinbach's avatar
Peter Steinbach committed
71
- [ ] extend support for OpenPower (gcc) if you have according hardware available
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.