Publish LumaOps source

2026-09-03 01:18:36 +02:00
commit 7f1c0e5f71
2363 changed files with 501543 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Build and install {#build}
+
+[TOC]
+
+# Basic installation {#basic-install}
+
+## Clone from github {#clone}
+To get the newest version of the hueplusplus library, clone it directly from [github](https://github.com/enwi/hueplusplus).
+The master branch contains the latest tested and stable version, while the development branch is more unstable.
+```{.sh}
+~ $ git clone https://github.com/enwi/hueplusplus.git
+```
+This creates a folder hueplusplus with the library sources.
+
+When you want to update the library for a new version, use pull with rebase.
+```{.sh}
+~/hueplusplus $ git pull --rebase
+```
+
+## Build with CMake {#build-cmake}
+To build the library, you need to use [CMake](https://cmake.org) version 3.10 or higher.
+It is easiest to create a separate build directory where the build files are stored.
+```{.sh}
+~/hueplusplus $ mkdir build
+~/hueplusplus $ cd build
+~/hueplusplus/build $ cmake ..
+~/hueplusplus/build $ make
+```
+
+To install or uninstall the library use the make targets.
+```{.sh}
+~/hueplusplus/build $ make install
+~/hueplusplus/build $ make uninstall
+```
+
+## Use in a CMake project {#import-cmake}
+If you have a project that already uses CMake you probably want to add the hueplusplus library directly in your cmake file.
+For that the best way is to use find_package().
+```{.cmake}
+find_package(hueplusplus REQUIRED)
+```
+But this will only work if the hueplusplus library is already installed.
+Instead, if you have the hueplusplus repository included in your project repository (as a submodule) or know where the folder lives you can do the following:
+```{.cmake}
+find_package(hueplusplus QUIET)
+if(NOT hueplusplus_FOUND)
+    message(STATUS "-- hueplusplus not found, building it")
+    add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/<path to directory>/hueplusplus" "${CMAKE_CURRENT_BINARY_DIR}/hueplusplus")
+endif()
+```
+This will check if the hueplusplus library was found by find_package() and if not it will use the specified path to the library source and compile it during the build process.
+
+The cmake project defines two library targets: `hueplusplusstatic` to link as a static library and `hueplusplusshared` to link as a shared library.
+```{.cmake}
+target_link_libraries(<executable> PUBLIC hueplusplusstatic)
+```
+
+## Use in another project {#import-other}
+When you are not using CMake, you have to install hueplusplus and change your build configuration to link to the compiled library.
+The header files in the include directory need to be added to the include path.
+How you do this depends on the build system.
+
+## Building tests {#build-tests}
+If you additionally want to run the tests use cmake with the option -Dhueplusplus_TESTS=ON. Testing is done with Google gtest and gmock. Note that you wont need to install gtest/gmock yourself, because cmake will automatically download them and include them during the build.
+The custom target `unittest` compiles and executes all tests.
+```bash
+mkdir build
+cd build
+cmake .. -Dhueplusplus_TESTS=ON
+make unittest
+```
+
+If you also want to execute coverage tests you will need to install gcov and lcov yourself. To run the coverage test use
+```bash
+make coveragetest
+```
+
+## Building examples {#build-examples}
+There are some small [example programs](@ref examples) using this library in the examples folder. To build them,
+set `hueplusplus_EXAMPLES=ON`. The target `hueplusplus_examples` builds all examples into build/examples.
+```{.sh}
+mkdir build
+cd build
+cmake .. -Dhueplusplus_EXAMPLES=ON
+make hueplusplus_examples
+```
+
+## External libraries
+Hueplusplus requires a few external libraries  (e.g. Mbed TLS and GTest), which are included automatically. If these are pre-installed on your system, those versions will be used by default. This can potentially cause issues if your installed versions are incompatible.
+In this case, set `hueplusplus_NO_EXTERNAL_LIBRARIES=ON` to force using the embedded versions instead of the installed libraries.