Merge branch 'readme_refactor' into develop

CMakeLists.txt

@@ -89,6 +89,20 @@ if(GIT_FOUND)
         RESULT_VARIABLE DEPTHAI_DOWNLOADED_SOURCES
         OUTPUT_QUIET ERROR_QUIET
     )
+    execute_process(
+        COMMAND ${GIT_EXECUTABLE} rev-parse HEAD
+        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+        OUTPUT_VARIABLE BUILD_COMMIT
+        ERROR_QUIET
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    execute_process(
+        COMMAND ${GIT_EXECUTABLE} show -s --format=%ci ${BUILD_COMMIT}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+        OUTPUT_VARIABLE BUILD_COMMIT_DATETIME
+        ERROR_QUIET
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
 endif()
 
 ### Get and find dependencies
@@ -162,6 +176,8 @@ add_library(${TARGET_CORE_NAME}
     src/bspatch/bspatch.c
 )
 add_library("${PROJECT_NAME}::${TARGET_CORE_ALIAS}" ALIAS ${TARGET_CORE_NAME})
+# Specify that we are building core
+target_compile_definitions(${TARGET_CORE_NAME} PUBLIC DEPTHAI_TARGET_CORE)
 # Specifies name of generated IMPORTED target (set to alias)
 set_target_properties(${TARGET_CORE_NAME} PROPERTIES EXPORT_NAME ${TARGET_CORE_ALIAS})
 # Add to list of targets to export and install
@@ -288,10 +304,6 @@ else()
 
 endif()
 
-
-# Configure build information (version, ...)
-configure_file("${CMAKE_CURRENT_LIST_DIR}/cmake/version.hpp.in" "${CMAKE_CURRENT_LIST_DIR}/include/depthai/build/version.hpp")
-
 # Add include directories
 target_include_directories(${TARGET_CORE_NAME}
     PUBLIC
@@ -387,7 +399,10 @@ if(DEPTHAI_OPENCV_SUPPORT)
         target_link_libraries(${TARGET_OPENCV_NAME} PUBLIC ${REQUIRED_OPENCV_LIBRARIES})
 
         # Add public compile definition indicating that OpenCV support is available
-        target_compile_definitions(${TARGET_OPENCV_NAME} PUBLIC DEPTHAI_OPENCV_SUPPORT)
+        set(DEPTHAI_HAVE_OPENCV_SUPPORT ON)
+
+        # Specify that we are building target opencv
+        target_compile_definitions(${TARGET_OPENCV_NAME} PUBLIC DEPTHAI_TARGET_OPENCV)
 
         # Add public dependency to depthai::core library
         target_link_libraries(${TARGET_OPENCV_NAME} PUBLIC ${TARGET_CORE_NAME})
@@ -442,6 +457,17 @@ if (DEPTHAI_BUILD_DOCS)
     add_subdirectory(docs)
 endif()
 
+########################
+# Build configuration
+########################
+# Add year information
+string(TIMESTAMP BUILD_DATETIME "%Y-%m-%d %H:%M:%S +0000" UTC)
+message(STATUS "BUILD_DATETIME: ${BUILD_DATETIME}, BUILD_COMMIT: ${BUILD_COMMIT}, BUILD_COMMIT_DATETIME: ${BUILD_COMMIT_DATETIME}")
+
+# Configure build information (version, opencv support)
+configure_file("${CMAKE_CURRENT_LIST_DIR}/cmake/version.hpp.in" "${CMAKE_CURRENT_LIST_DIR}/include/depthai/build/version.hpp")
+configure_file("${CMAKE_CURRENT_LIST_DIR}/cmake/config.hpp.in" "${CMAKE_CURRENT_LIST_DIR}/include/depthai/build/config.hpp")
+
 ########################
 # Export and install
 ########################

README.md

@@ -21,66 +21,114 @@ MacOS: `brew install libusb`
 
 Linux: `sudo apt install libusb-1.0-0-dev`
 
-## Using as library
+## Integration
 
-To use this library in your own project you can use CMake `add_subdirectory` pointing to the root of this repository
-Optionally append `EXCLUDE_FROM_ALL` to hide depthai-core related targets, etc...
+### CMake
+
+Targets available to link to are:
+ - depthai::core - Core library, without using opencv internally
+ - depthai::opencv - Core + support for opencv related helper functions (requires OpenCV4)
+
+#### Using find_package
+
+Build static or dynamic version of library and install (See: [Building](##building) and [Installing](##installing))
+
+Add `find_package` and `target_link_libraries` to your project
+```
+find_package(depthai CONFIG REQUIRED)
+...
+target_link_libraries([my-app] PRIVATE depthai::opencv)
 ```
-add_subdirectory(depthai-core)
+
+And point CMake to either build directory or install directory:
+```
+-D depthai_DIR=depthai-core/build
 ```
 or
 ```
-add_subdirectory(depthai-core EXCLUDE_FROM_ALL)
+-D depthai_DIR=depthai-core/build/install/lib/cmake/depthai
 ```
-And at the end link to your target (PUBLIC or PRIVATE depending on your needs)
+
+If library was installed to default search path like `/usr/local` on Linux, specifying `depthai_DIR` isn't necessary as CMake will find it automatically.
+
+#### Using add_subdirectory
+
+This method is more intrusive but simpler as it doesn't require building the library separately.
+
+Add `add_subdirectory` which points to `depthai-core` folder **before** project command. Then link to any required targets.
 ```
-target_link_libraries(my-app PUBLIC depthai-core)
+add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/depthai-core EXCLUDE_FROM_ALL)
+...
+project(my-app)
+...
+target_link_libraries([my-app] PRIVATE depthai::opencv)
 ```
 
+### Non-CMake integration (Visual Studio, Xcode, CodeBlocks, ...)
+
+To integrate into a different build system than CMake, prefered way is compiling as dynamic library and pointing to correct include directories.
+1. First build as dynamic library: [Building Dynamic library](###dynamic-library)
+2. Then install: [Installing](##installing)
+3. Set needed library directories:
+    - `build/install/lib` (for linking to either depthai-core or depthai-opencv)
+    - `build/install/bin` (for .dll's)
+4. And include directories
+    - `build/install/include` (library headers)
+    - `build/install/include/depthai-shared/3rdparty` (shared 3rdparty headers)
+    - `build/install/lib/cmake/depthai/dependencies/include` (dependencies headers)
+
+> ℹ️ Threading library might need to be linked to explicitly.
+
 ## Building
 
-Make sure submodules are updated 
+Make sure submodules are updated
 ```
 git submodule update --init --recursive
 ```
-ℹ️ For the `--parallel` argument of the commands below, specify a value `[num CPU cores]` or less, to reduce memory consumption during build. E.g.: `--parallel 8`
 
-**Static library** 
+> ℹ️ To speed up build times, use `cmake --build build --parallel [num CPU cores]` (CMake >= 3.12).
+For older versions use: Linux/macOS: `cmake --build build -- -j[num CPU cores]`, MSVC: `cmake --build build -- /MP[num CPU cores]`
+
+### Static library
 ```
-mkdir build && cd build
-cmake ..
-cmake --build . --parallel
+cmake -H. -Bbuild
+cmake --build build
 ```
 
-**Dynamic library**
+### Dynamic library
 ```
-mkdir build && cd build
-cmake .. -D BUILD_SHARED_LIBS=ON
-cmake --build . --parallel
+cmake -H. -Bbuild -D BUILD_SHARED_LIBS=ON
+cmake --build build
 ```
 ## Installing
 
 To install specify optional prefix and build target install
 ```
-cmake .. -D CMAKE_INSTALL_PREFIX=[path/to/install/dir]
-cmake --build . --parallel
-cmake --build . --target install --parallel
+cmake -H. -Bbuild -D CMAKE_INSTALL_PREFIX=[path/to/install/dir]
+cmake --build build
+cmake --build build --target install
 ```
 
+If `CMAKE_INSTALL_PREFIX` isn't specified, the library is installed under build folder `install`.
+
 ## Running tests
 
 To run the tests build the library with the following options
 ```
-mkdir build_tests && cd build_tests
-cmake .. -D DEPTHAI_TEST_EXAMPLES=ON -D DEPTHAI_BUILD_TESTS=ON -D DEPTHAI_BUILD_EXAMPLES=ON
-cmake --build . --parallel
+cmake -H. -Bbuild -D DEPTHAI_TEST_EXAMPLES=ON -D DEPTHAI_BUILD_TESTS=ON -D DEPTHAI_BUILD_EXAMPLES=ON
+cmake --build build
+```
+
+Then navigate to `build` folder and run `ctest`
+```
+cd build
 ctest
 ```
 
 ## Style check
 
-The library uses clang format to enforce a certain style. 
-If a style check is failing, run the `clangformat` target, check the output and push changes
+The library uses clang format to enforce a certain coding style.
+If a style check is failing, run the `clangformat` target, check the output and push changes.
 
 To use this target clang format must be installed, preferably clang-format-10
 ```
@@ -89,7 +137,7 @@ sudo apt install clang-format-10
 
 And to apply formatting
 ```
-cmake --build [build/dir] --target clangformat
+cmake --build build --target clangformat
 ```
 
 ## Documentation generation
@@ -120,7 +168,7 @@ This retains the libraries source code, so that debugger can step through it (th
 ## Troubleshooting
 
 ### Hunter
-Hunter is a CMake-only dependency manager for C/C++ projects. 
+Hunter is a CMake-only dependency manager for C/C++ projects.
 
 If you are stuck with error message which mentions external libraries (subdirectory of `.hunter`) like the following:
 ```

cmake/config.hpp.in

@@ -0,0 +1,14 @@
+/*
+ * Generated by CMake build tool.
+ */
+#pragma once
+
+// This build supports OpenCV integration?
+#cmakedefine DEPTHAI_HAVE_OPENCV_SUPPORT
+
+// Build specific settings overwrite
+#ifdef DEPTHAI_TARGET_CORE
+#ifndef DEPTHAI_TARGET_OPENCV
+#undef DEPTHAI_HAVE_OPENCV_SUPPORT
+#endif
+#endif

cmake/version.hpp.in

@@ -1,16 +1,20 @@
-/* 
- * Generated by CMake build tool. 
- * To modify version, open CMakeLists.txt and bump the version in project() function 
+/*
+ * Generated by CMake build tool.
+ * To modify version, open CMakeLists.txt and bump the version in project() function
  */
-
 #pragma once
+
 namespace dai
 {
-    namespace build
-    {
-        constexpr static const char* VERSION = "${PROJECT_VERSION}";
-        constexpr static const int VERSION_MAJOR = ${PROJECT_VERSION_MAJOR};
-        constexpr static const int VERSION_MINOR = ${PROJECT_VERSION_MINOR};
-        constexpr static const int VERSION_PATCH = ${PROJECT_VERSION_PATCH};
-    } // namespace Build
+namespace build
+{
+    constexpr static const char* VERSION = "${PROJECT_VERSION}";
+    constexpr static const int VERSION_MAJOR = ${PROJECT_VERSION_MAJOR};
+    constexpr static const int VERSION_MINOR = ${PROJECT_VERSION_MINOR};
+    constexpr static const int VERSION_PATCH = ${PROJECT_VERSION_PATCH};
+
+    constexpr static const char* COMMIT = "${BUILD_COMMIT}";
+    constexpr static const char* COMMIT_DATETIME = "${BUILD_COMMIT_DATETIME}";
+    constexpr static const char* BUILD_DATETIME = "${BUILD_DATETIME}";
+} // namespace build
 } // namespace dai

docs/Doxyfile.in

@@ -2199,7 +2199,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DEPTHAI_OPENCV_SUPPORT
+PREDEFINED             = DEPTHAI_HAVE_OPENCV_SUPPORT
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

include/depthai/device/DataQueue.hpp

@@ -50,7 +50,7 @@ class DataOutputQueue {
     /**
      * Gets current queue behavior when full (maxSize)
      *
-     * @return true if blocking, false otherwise
+     * @returns True if blocking, false otherwise
      */
     bool getBlocking() const;
 
@@ -64,52 +64,52 @@ class DataOutputQueue {
     /**
      * Gets queue maximum size
      *
-     * @return Maximum queue size
+     * @returns Maximum queue size
      */
     unsigned int getMaxSize(unsigned int maxSize) const;
 
     /**
      * Gets queues name
      *
-     * @return Queue name
+     * @returns Queue name
      */
     std::string getName() const;
 
     /**
      * Adds a callback on message received
      *
      * @param callback Callback function with queue name and message pointer
-     * @return Callback id
+     * @returns Callback id
      */
     CallbackId addCallback(std::function<void(std::string, std::shared_ptr<ADatatype>)>);
 
     /**
      * Adds a callback on message received
      *
      * @param callback Callback function with message pointer
-     * @return Callback id
+     * @returns Callback id
      */
     CallbackId addCallback(std::function<void(std::shared_ptr<ADatatype>)>);
 
     /**
      * Adds a callback on message received
      *
      * @param callback Callback function without any parameters
-     * @return Callback id
+     * @returns Callback id
      */
     CallbackId addCallback(std::function<void()> callback);
 
     /**
      * Removes a callback
      *
      * @param callbackId Id of callback to be removed
-     * @return true if callback was removed, false otherwise
+     * @returns True if callback was removed, false otherwise
      */
     bool removeCallback(CallbackId callbackId);
 
     /**
      * Check whether front of the queue has message of type T
-     * @returns true if queue isn't empty and the first element is of type T, false otherwise
+     * @returns True if queue isn't empty and the first element is of type T, false otherwise
      */
     template <class T>
     bool has() {
@@ -123,7 +123,7 @@ class DataOutputQueue {
 
     /**
      * Check whether front of the queue has a message (isn't empty)
-     * @returns true if queue isn't empty, false otherwise
+     * @returns True if queue isn't empty, false otherwise
      */
     bool has() {
         if(!running) throw std::runtime_error(exceptionMessage.c_str());
@@ -349,7 +349,7 @@ class DataInputQueue {
     /**
      * Gets maximum queue size.
      *
-     * @return Maximum message size
+     * @returns Maximum message size
      */
     std::size_t getMaxDataSize();
 
@@ -363,7 +363,7 @@ class DataInputQueue {
     /**
      * Gets current queue behavior when full (maxSize)
      *
-     * @return true if blocking, false otherwise
+     * @returns True if blocking, false otherwise
      */
     bool getBlocking() const;
 
@@ -377,14 +377,14 @@ class DataInputQueue {
     /**
      * Gets queue maximum size
      *
-     * @return Maximum queue size
+     * @returns Maximum queue size
      */
     unsigned int getMaxSize(unsigned int maxSize) const;
 
     /**
      * Gets queues name
      *
-     * @return Queue name
+     * @returns Queue name
      */
     std::string getName() const;