library-template

LibraryName is a <native/Qt> library allowing to <brief description>.

Tip

Latest development/pull requests will be committed into main branch.
Each stable release have their dedicated branch:

• 1.0.x: branch dev/1.0
• 1.1.x: branch dev/1.1
• etc...

Table of contents :

• 1. Library details
  • 1.1. Features
  • 1.2. Supported platforms
    • 1.2.1. Status
    • 1.2.2. Specific behaviours
• 2. Requirements
  • 2.1. C++ Standards
  • 2.2. Dependencies
• 3. How to build
  • 3.1. CMake Usage
  • 3.2. CMake options
• 4. How to use
  • 4.1. Usage
  • 4.2. Library version
    • 4.2.1. Compatibility
    • 4.2.2. Compilation time
    • 4.2.3. Runtime
• 5. Documentation
• 6. License

1. Library details

1.1. Features

• Provide library details here
• Provide informations about available and unavailable features (what can be do, what can't)

1.2. Supported platforms

1.2.1. Status

• Useful if cross-platform to track current implementation status or the supported/planned/rejected backend

1.2.2. Specific behaviours

• Because sometimes you can't escape some specific platforms/versions quirks

2. Requirements

2.1. C++ Standards

This library requires at least C++ 17 standard

2.2. Dependencies

A "dependencies" section example

Below, list of required dependencies:

Dependencies	VCPKG package	Comments
Qt	/	Compatible with Qt6.x Compatible with Qt5.15.x
Native APIs	/	Please refer to section supported platform for more details

Note

Dependency manager VCPKG is not mandatory, this is only a note to be able to list needed packages

3. How to build

3.1. CMake Usage

This library can be use as an embedded library in a subdirectory of your project (like a git submodule for example) :

1. In the root CMakeLists, add instructions :

add_subdirectory(mylibrary) # Or if library is put in a folder "dependencies" : add_subdirectory(dependencies/mylibrary)

2. In the application/library CMakeLists, add instructions :

# Link needed libraries
target_link_libraries(${PROJECT_NAME} PRIVATE mylibrary)

3.2. CMake options

This library provide some CMake build options:

• add here your custom CMake library options, for each, add: the name, the default value, when to use and what consequences

4. How to use

4.1. Usage

An "usage" section example

Please refer to myns::MyClass class documentation for more details.

4.2. Library version

4.2.1. Compatibility

This library use the PImpl Idiom in order to preserve ABI compatibility (Qt wiki also have a great tutorial on the PImpl idiom).
So only major release (this project use the semantic versioning) should break the ABI.

4.2.2. Compilation time

In order to easily check at compilation time library version (to manage compatibility between multiple versions for example), macro LIBRARYNAME_VERSION_ENCODE (defined inside library_global.h file) can be used:

#if LIBRARYNAME_VERSION >= LIBRARYNAME_VERSION_ENCODE(2,0,0)
    // Do stuff for version 2.0.0 or higher
#else
    // Do stuff for earlier versions
#endif

4.2.3. Runtime

Since library header used during final application build could differ from the actual library version, it is recommended to use the method:

#include "libraryname/someheader.h"

const QVersionNumber libSemver = qwm::getLibraryVersion();

5. Documentation

All classes/methods has been documented with Doxygen utility and automatically generated at online website documentation.

Note

This repository contains two kinds of documentation:

• Public API: Available via online website documentation or locally via Doxyfile docs/fragments/Doxyfile-public-api.in
• Internal: Available locally only via docs/fragments/Doxyfile-internal.in

To generate documentation locally, we can use:

doxygen ./docs/fragments/Doxyfile-name

Tip

You can also load the Doxyfile into Doxywizard (Doxygen GUI) and run generation.

6. License

This library is licensed under MIT license.