Adds iterable HP map parameters
[libcds.git] / build / cmake / readme.md
1 Building library with CMake
2 ===============
3
4 CDS suports both in-source and out-of-source cmake build types. Now project uses:
5
6 - CMake: general cross-platform building
7 - CTest: all unit tests can be run in a standard way by *ctest* command
8 - CPack: for making rpm/deb/nsys etc. packages
9
10 Compiling and testing
11 ----------
12 **Building out-of-source in "RELEASE" mode ("DEBUG" is default)**
13
14 - Wherever create empty directory for building, for instance `libcds-debug`
15 - Prepare: `cmake -DCMAKE_BUILD_TYPE=RELEASE <path to the project's root directory with CMakeLists.txt>`
16 - Compile: `make -j4`
17 - As a result you'll see shared and static cds libraries in the build directory
18
19 **Warning**: We strongly recommend not to use static cds library. Static library is not tested and not maintained. You can use it on own risk.
20
21 After using command cmake -L <path to the project's root directory with CMakeLists.txt> one can see some additional variables, that can activate additional features:
22
23 - `WITH_TESTS:BOOL=OFF`: if you want to build library with unit testing support use *-DWITH_TESTS=ON* on prepare step. Be careful with this flag, because compile time will dramatically increase
24 - `WITH_TESTS_COVERAGE:BOOL=OFF`: Analyze test coverage using gcov (only for gcc)
25 - `WITH_BOOST_ATOMIC:BOOL=OFF`: Use boost atomics (only for boost >= 1.54)
26 - `WITH_ASAN:BOOL=OFF`: compile libcds with AddressSanitizer instrumentation
27 - `WITH_TSAN:BOOL=OFF`: compile libcds with ThreadSanitizer instrumentation
28
29 Additional gtest hints (for unit and stress tests only):
30 - `GTEST_INCLUDE_DIRS=path`: gives full `path` to gtest include dir. 
31 - `GTEST_LIBRARY=path`: gives full `path` to `libgtest.a`.
32
33
34 Packaging
35 ----------
36
37 In order to package library *CPack* is used, command *cpack -G <Generator>* should create correspondent packages for particular operating system. Now the project supports building the following package types:
38
39 - *RPM*: redhat-based linux distribs        
40 - *DEB*: debian-based linux distribs
41 - *TGZ*: simple "*tgz*" archive with library and headers
42 - *NSYS*: windows installer package (NSYS should be installed)   
43   
44 "Live" building and packaging example
45 ----------
46 - `git clone https://github.com/khizmax/libcds.git`
47 - `mkdir libcds-release`
48 - `cd libcds-release`
49 - `cmake -DWITH\_TESTS=ON -DCMAKE\_BUILD_TYPE=RELEASE ../libcds`
50 ```
51     -- The C compiler identification is GNU 4.8.3
52     -- The CXX compiler identification is GNU 4.8.3
53     ...
54     -- Found Threads: TRUE
55     -- Boost version: 1.54.0
56     -- Found the following Boost libraries:
57     --   system
58     --   thread
59     Build type -- RELEASE
60     -- Configuring done
61     -- Generating done
62     -- Build files have been written to: <...>/libcds-release
63 ``` 
64 - `make -j4`
65 ```
66     Scanning dependencies of target cds
67     Scanning dependencies of target test-common
68     Scanning dependencies of target cds-s
69     Scanning dependencies of target test-hdr-offsetof
70     [  1%] Building CXX object CMakeFiles/cds-s.dir/src/hp_gc.cpp.o
71     ...
72     [100%] Built target test-hdr
73 ```
74
75 - `ctest`
76 ```
77     Test project /home/kel/projects_cds/libcds-debug
78         Start 1: test-hdr
79     1/7 Test #1: test-hdr .........................   Passed  1352.24 sec
80         Start 2: cdsu-misc
81     2/7 Test #2: cdsu-misc ........................   Passed    0.00 sec
82         Start 3: cdsu-map
83     ...
84 ```
85
86 - `cpack -G RPM`
87 ```
88     CPack: Create package using RPM
89     CPack: Install projects
90     CPack: - Run preinstall target for: cds
91     CPack: - Install project: cds
92     CPack: -   Install component: devel
93     CPack: -   Install component: lib
94     CPack: Create package
95     CPackRPM:Debug: Adding /usr/local to builtin omit list.
96     CPackRPM: Will use GENERATED spec file: /home/kel/projects_cds/libcds-debug/_CPack_Packages/Linux/RPM/SPECS/cds-devel.spec
97     CPackRPM: Will use GENERATED spec file: /home/kel/projects_cds/libcds-debug/_CPack_Packages/Linux/RPM/SPECS/cds-lib.spec
98     CPack: - package: /home/kel/projects_cds/libcds-debug/cds-2.1.0-1-devel.rpm generated.
99     CPack: - package: /home/kel/projects_cds/libcds-debug/cds-2.1.0-1-lib.rpm generated.
100 ```
101
102 Future development
103 ----------
104 - CDash: use CI system