Qt Base Documentation

HarfBuzz is a font platform and text shaping engine supporting OpenType and Apple Advanced Typography (AAT). It is organized into core, auxiliary, and experimental libraries:

Core Libraries

• libharfbuzz: Handles text shaping, drawing, and painting. Supports various integration backends like hb-ft (FreeType), hb-coretext (macOS), hb-uniscribe (Windows), hb-directwrite (Windows), hb-gdi (Windows), hb-glib, and hb-graphite2.
• libharfbuzz-subset: Provides font subsetting and variable-font instancing.

Auxiliary Libraries

• libharfbuzz-icu: Provides ICU Unicode integration.
• libharfbuzz-cairo: Provides Cairo rendering integration.
• libharfbuzz-gobject: Provides GObject/GI bindings.

Experimental Libraries

• libharfbuzz-raster: Glyph rasterization to bitmaps (includes color fonts) using hb-draw and hb-paint.
• libharfbuzz-vector: Glyph output to vector formats like SVG using hb-draw and hb-paint.
• libharfbuzz-gpu: Encodes glyph outlines for GPU rasterization (Slug algorithm) and provides shader sources in GLSL, WGSL, MSL, and HLSL.

PCRE2 (releases 10.00 and above) is distributed under the BSD-3-Clause WITH PCRE2-exception license.

Key Licensing Details:

• Basic Library Functions: Distributed under the standard BSD license.
• Just-In-Time (JIT) Compilation Support: This is an optional feature. When included, it is licensed under the 2-clause BSD license.
• Documentation: Distributed under the same terms as the software.
• Test Data: Located in the testdata directory; it is not copyrighted and is in the public domain.
• SLJIT: Code in the deps/sljit directory has its own separate LICENSE file.

Redistribution Requirements (BSD License):

1. Source Code: Must retain all copyright notices, the list of conditions, and the disclaimer.
2. Binary Form: Must reproduce the copyright notices, conditions, and disclaimer in the documentation and/or other materials provided with the distribution.
3. Endorsement: The names of the University of Cambridge or any contributors may not be used to endorse products derived from this software without specific prior written permission.

Exemption for Binary Library-Like Packages

The requirement to reproduce copyright notices in binary form does not apply transitively down a software chain. If Package A includes PCRE2, Package A must comply. If Package B includes Package A, Package B is not required to comply with the PCRE2 notice requirement unless Package B uses PCRE2 independently.

To avoid common pitfalls with variable evaluation and falsy values in CMake:

• Check for empty string: To check if a variable is exactly an empty string (and not just falsy), use STREQUAL "". If the variable might be undefined, wrap it in quotes: if("${var_name}" STREQUAL "").
• Check for definedness: Use if(DEFINED var_name).
• Check for non-falsy values: Use if(var_name). Falsy values include 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, "", or a string ending in -NOTFOUND.
• Avoid double evaluation: Never use if(${var_name}). This can lead to errors if the variable contains content that CMake tries to parse as a command.

# Correct: Check if a variable is an empty string (safe for undefined variables)
if("${var_name}" STREQUAL "")
    message("${var_name}")
endif()

# Correct: Check if a variable is defined
if(DEFINED var_name)
endif()

# Correct: Check for non-falsy values (0, OFF, FALSE, etc.)
if(var_name)
    message("${var_name}")
endif()

# WRONG: Leads to double evaluation problems
if(${var_name})
    message("${var_name}")
endif()

Follow this structure when documenting a Qt application example to ensure completeness:

• Overview: State the objective, the Qt technologies used, and the specific Qt features demonstrated.
• Workflow Diagram (Optional): For complex examples, include a workflow diagram.
• Running the Example:
  • Include the Launching Examples Template.
  • Describe the expected application output.
• Platform Information (Optional): List any platform-specific limitations or exceptions.
• UI Walkthrough (Optional): For complex UIs, describe how to navigate and access different parts of the application.
• Qt Classes and Modules (Optional): List the main Qt classes and modules used.
  • Class Diagram (Optional): Visually depict the hierarchy of the Qt classes used.
• Feature Descriptions: Create a section for each major feature (e.g., #### Describe Feature A) explaining its implementation in the code.
• Squish Testing (Optional): If the example was tested with Squish, include squish-tested-example.qdocinc.
• Best Practices (Optional): Add any relevant best practices.
• Links: Use the \sa command to link to 'All Qt Examples' and other relevant documentation. Note that the \example command automatically generates a link to the source code.