### Build and Install tg_owt

Source: https://github.com/telegramdesktop/tdesktop/wiki/The-Packaged-Building-Mode

Use these CMake commands to build and install tg_owt as a static library. Ensure you have the necessary build environment set up.

```bash
cmake -B build .
cmake --build build
cmake --install build
```

--------------------------------

### Install Linux Desktop Application Files

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Installs the Telegram Desktop application files on Linux, including the executable, icons, D-Bus service files, and metainfo.

```cmake
if (LINUX AND DESKTOP_APP_USE_PACKAGED)
    include(GNUInstallDirs)
    configure_file("../lib/xdg/org.telegram.desktop.service" "${CMAKE_CURRENT_BINARY_DIR}/org.telegram.desktop.service" @ONLY)
    configure_file("../lib/xdg/org.telegram.desktop.metainfo.xml" "${CMAKE_CURRENT_BINARY_DIR}/org.telegram.desktop.metainfo.xml" @ONLY)
    generate_appstream_changelog(Telegram "${CMAKE_SOURCE_DIR}/changelog.txt" "${CMAKE_CURRENT_BINARY_DIR}/org.telegram.desktop.metainfo.xml")
    install(TARGETS Telegram RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" BUNDLE DESTINATION "${CMAKE_INSTALL_BINDIR}")
    install(FILES "Resources/art/icon16.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/16x16/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon16@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/16x16@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon32.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/32x32/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon32@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/32x32@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon48.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/48x48/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon48@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/48x48@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon64.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/64x64/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon64@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/64x64@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon128.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/128x128/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon128@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/128x128@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon256.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/256x256/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon256@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/256x256@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon512.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/512x512/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/art/icon512@2x.png" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/512x512@2/apps" RENAME "org.telegram.desktop.png")
    install(FILES "Resources/icons/tray_monochrome.svg" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/symbolic/apps" RENAME "org.telegram.desktop-symbolic.svg")
    install(FILES "Resources/icons/tray_monochrome_attention.svg" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/symbolic/apps" RENAME "org.telegram.desktop-attention-symbolic.svg")
    install(FILES "Resources/icons/tray_monochrome_mute.svg" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/icons/hicolor/symbolic/apps" RENAME "org.telegram.desktop-mute-symbolic.svg")
    install(FILES "../lib/xdg/org.telegram.desktop.desktop" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/applications")
    install(FILES "${CMAKE_CURRENT_BINARY_DIR}/org.telegram.desktop.service" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/dbus-1/services")
    install(FILES "${CMAKE_CURRENT_BINARY_DIR}/org.telegram.desktop.metainfo.xml" DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/metainfo")
endif()
```

--------------------------------

### Starting RPL Pipelines with on_next

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Subscribe to producer events using rpl::on_next. Explicitly std::move producers and pass a lifetime object.

```cpp
std::move(counter) | rpl::on_next([=](int value) {
    qDebug() << "Received: " << value;
}, lifetime);

// Without lifetime parameter - MUST store returned lifetime:
auto subscriptionLifetime = std::move(counter) | rpl::on_next([=](int value) {
    // process value
});
```

--------------------------------

### Install Homebrew and Dependencies on macOS

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-mac.md

Installs Homebrew package manager and essential build tools like git, automake, cmake, wget, pkg-config, gnu-tar, ninja, nasm, and meson. Ensure you have Xcode command-line tools installed.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git automake cmake wget pkg-config gnu-tar ninja nasm meson
```

--------------------------------

### Build Telegram Desktop on Linux (Docker)

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Build Telegram Desktop on Linux using a Docker container. This method requires Docker to be installed and uses a provided script for the build process.

```bash
# Linux (Docker build)
./Telegram/build/prepare/linux.sh
docker run --rm -it \
    -u $(id -u) \
    -v "$PWD:/usr/src/tdesktop" \
    tdesktop:centos_env \
    /usr/src/tdesktop/Telegram/build/docker/centos_env/build.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### Build Telegram Desktop on macOS

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Build Telegram Desktop on macOS. This involves installing dependencies via Homebrew, running a prepare script, and configuring the build with API credentials.

```bash
# macOS
brew install git automake cmake wget pkg-config gnu-tar ninja nasm meson
./Telegram/build/prepare/mac.sh
cd Telegram && ./configure.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH
# Open out/Telegram.xcodeproj in Xcode
```

--------------------------------

### Build Telegram Desktop

Source: https://github.com/telegramdesktop/tdesktop/wiki/The-Packaged-Building-Mode

Build Telegram Desktop using CMake, providing your API ID and hash. The installation command is optional; you can also specify the tg_owt directory via CMake flags.

```bash
cmake -B build . -DTDESKTOP_API_ID=your_id -DTDESKTOP_API_HASH=your_hash
cmake --build build
cmake --install build
```

--------------------------------

### Define RGB Color Constant

Source: https://github.com/telegramdesktop/tdesktop/wiki/Theme-Reference

Example of defining an RGB color constant for a UI component.

```text
activeButtonBgOver: #00a32b;
```

--------------------------------

### Define Localized Strings

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Example of defining localized strings in a .strings file format. Supports simple key-value pairs and pluralization using '#one' and '#other' suffixes.

```strings
"lng_settings_title" = "Settings";
"lng_confirm_delete_item" = "Are you sure you want to delete {item_name}?";
"lng_files_selected#one" = "{count} file selected";
"lng_files_selected#other" = "{count} files selected";
```

--------------------------------

### Set Xcode Command Line Tools on macOS

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-mac.md

Selects the active developer directory for Xcode. This command is necessary to ensure the build process uses the correct Xcode installation.

```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

--------------------------------

### Make Telegram API requests with callbacks

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

This pattern demonstrates making an API request using `api()`, handling successful responses with `.done()` and errors with `.fail()`. It includes examples of using `.match()` for multiple response constructors and `.data()` for single constructors.

```cpp
api().request(MTPnamespace_MethodName(
    MTP_flags(flags_value),
    MTP_inputPeer(peer),
    MTP_string(messageText),
    MTP_long(randomId),
    MTP_vector<MTPMessageEntity>()
)).done([=](const MTPResponseType &result) {
    // Handle successful response

    // Multiple constructors - use .match() or check type:
    result.match([&](const MTPDuser &data) {
        // use data.vfirst_name().v
    }, [&](const MTPDuserEmpty &data) {
        // handle empty user
    });

    // Single constructor - use .data() shortcut:
    const auto &data = result.data();
    // use data.vmessages().v

}).fail([=](const MTP::Error &error) {
    // Handle API error
    if (error.type() == u"FLOOD_WAIT_X"_q) {
        // Handle flood wait
    }
}).handleFloodErrors().send();

```

--------------------------------

### Operators at Start of Continuation Lines

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/REVIEW.md

When splitting expressions across lines, place operators like '&&', '||', ';', '+' at the beginning of continuation lines. This improves readability by clearly marking lines as continuations.

```cpp
// BAD - continuation looks like scope code:
if (const auto &lottie = animation->lottie;
	lottie && lottie->valid() && lottie->framesCount() > 1) {
	lottie->animate([=] {

// GOOD - semicolon at start signals continuation:
if (const auto &lottie = animation->lottie
	; lottie && lottie->valid() && lottie->framesCount() > 1) {
	lottie->animate([=] {

// BAD - trailing && makes next line look like independent code:
if (veryLongExpression() &&
	anotherLongExpression() &&
	anotherOne()) {
	doSomething();

// GOOD - leading && clearly marks continuation:
if (veryLongExpression()
	&& anotherLongExpression()
	&& anotherOne()) {
	doSomething();
```

--------------------------------

### Initialize Storage Facade

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

The Storage Facade provides access to shared media and user photos. It supports adding, removing, and querying media with reactive results.

```cpp
#include "storage/storage_facade.h"

// Storage facade for media queries
class Facade {
public:
    Facade();
    ~Facade();

    // Shared media operations (photos, videos, files, etc.)
    void add(SharedMediaAddNew &&query);
    void add(SharedMediaAddSlice &&query);
    void remove(SharedMediaRemoveOne &&query);
    void invalidate(SharedMediaInvalidateBottom &&query);

    // Query shared media with reactive results
    rpl::producer<SharedMediaResult> query(
        SharedMediaQuery &&query) const;

    // Check if media type is empty
    bool empty(const SharedMediaKey &key) const;

    // Subscribe to media updates
    rpl::producer<SharedMediaSliceUpdate> sharedMediaSliceUpdated() const;
    rpl::producer<SharedMediaRemoveOne> sharedMediaOneRemoved() const;

    // User photos operations
    void add(UserPhotosAddSlice &&query);
    void remove(UserPhotosRemoveOne &&query);

    rpl::producer<UserPhotosResult> query(
        UserPhotosQuery &&query) const;
};

// Example: Query shared photos
void loadSharedPhotos(not_null<Storage::Facade*> storage, PeerId peerId) {
    storage->query(Storage::SharedMediaQuery{
        .key = { peerId, Storage::SharedMediaType::Photo },
        .limitBefore = 0,
        .limitAfter = 50
    }) | rpl::start_with_next([=](Storage::SharedMediaResult result) {
        for (const auto &id : result.messageIds) {
            // Process photo message IDs
        }
    }, lifetime);
}
```

--------------------------------

### Initialize Window Controller

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Use the default constructor for the primary application window or provide IDs for secondary windows.

```cpp
#include "window/window_controller.h"

// Window controller for main application window
class Controller final : public base::has_weak_ptr {
public:
    Controller();  // Primary window
    Controller(SeparateId id, MsgId showAtMsgId);  // Secondary window

    // Window widget access
    [[nodiscard]] not_null<::MainWindow*> widget();

    // Account and session
    void showAccount(not_null<Main::Account*> account);
    [[nodiscard]] Main::Account &account() const;
    [[nodiscard]] SessionController *sessionController() const;

    // UI operations
    void showSettings();
    void showBox(
        object_ptr<Ui::BoxContent> content,
        Ui::LayerOptions options,
        anim::type animated);
    void hideLayer(anim::type animated = anim::type::normal);

    // Toast notifications
    void showToast(const QString &text, crl::time duration = 0);
    void showToast(TextWithEntities &&text, crl::time duration = 0);

    // Passcode lock
    void setupPasscodeLock();
    void clearPasscodeLock();
};

// Example: Show a dialog box
void showConfirmation(not_null<Window::Controller*> controller) {
    controller->showBox(
        Box<ConfirmBox>("Are you sure?", [=] {
            // Confirmed action
        }),
        Ui::LayerOption::KeepOther,
        anim::type::normal);
}
```

--------------------------------

### Define RGBA Color Constant

Source: https://github.com/telegramdesktop/tdesktop/wiki/Theme-Reference

Example of defining an RGBA color constant, including transparency.

```text
msgStickerOverlay: #2223237f;
```

--------------------------------

### Initialize Visual Studio Terminal for 64-bit

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-win.md

Initializes the Visual Studio environment for a 64-bit build, ensuring compatibility with Windows 7. Use this command before preparing libraries and building.

```batch
%comspec% /k "C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars64.bat" -vcvars_ver=14.44
```

--------------------------------

### Add StartupTask Executable Target for Windows

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Configures the 'StartupTask' executable for Windows builds. It initializes the target and sets the runtime output directory.

```cmake
elseif (build_winstore)
    add_executable(StartupTask WIN32)
    init_non_host_target(StartupTask)

    add_dependencies(Telegram StartupTask)

    nice_target_sources(StartupTask ${src_loc}
    PRIVATE
        _other/startup_task_win.cpp
    )

    set_target_properties(StartupTask PROPERTIES
        RUNTIME_OUTPUT_DIRECTORY ${output_folder}
    )
endif()
```

--------------------------------

### Core Application Class Structure

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

The Core::Application class serves as the main entry point, managing the client's lifecycle and providing access to various subsystems like platform integration, animations, audio, calls, and language management. Usage is typically initiated via Core::Launcher in main.cpp.

```cpp
#include "core/application.h"

// Application is a singleton managing the entire client lifecycle
class Application final : public QObject {
public:
    Application();
    ~Application();

    void run();  // Main entry point after construction

    // Access platform-specific integration
    [[nodiscard]] Platform::Integration &platformIntegration() const;

    // Animation system for UI transitions
    [[nodiscard]] Ui::Animations::Manager &animationManager() const;

    // Access the main user domain (multi-account support)
    [[nodiscard]] Main::Domain &domain() const;

    // Audio playback system
    [[nodiscard]] Media::Audio::Instance &audio() const;

    // Voice/video calls system
    [[nodiscard]] Calls::Instance &calls() const;

    // Language management
    [[nodiscard]] Lang::Instance &langpack() const;

    // Proxy configuration
    void setCurrentProxy(const MTP::ProxyData &proxy);
    [[nodiscard]] MTP::ProxyData currentProxy() const;
};

// Usage in main.cpp:
int main(int argc, char *argv[]) {
    Core::Launcher launcher(argc, argv);
    return launcher.exec();  // Creates and runs Application
}
```

--------------------------------

### Set Deployment Target and Prepare Breakpad

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-mas.md

Sets the macOS deployment target and navigates to the Libraries directory to clone the breakpad repository. This is a prerequisite for building the Mac App Store version.

```bash
MACOSX_DEPLOYMENT_TARGET=10.12

cd Libraries

git clone https://chromium.googlesource.com/breakpad/breakpad
cd breakpad
git checkout bc8fb886
git clone https://chromium.googlesource.com/linux-syscall-support src/third_party/lss
cd src/third_party/lss
git checkout a91633d1
cd ../../..
git apply ../patches/breakpad.diff
```

--------------------------------

### Clone Source Code and Prepare Libraries

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-win.md

Clones the Telegram Desktop repository recursively and runs the Windows preparation script. This should be executed in the initialized terminal within the build directory.

```batch
git clone --recursive https://github.com/telegramdesktop/tdesktop.git
tdesktop\Telegram\build\prepare\win.bat
```

--------------------------------

### Manage Voice and Video Calls

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

The Calls::Instance class manages voice and video calls, including one-on-one and group calls. Use startOutgoingCall to initiate a call to a user.

```cpp
#include "calls/calls_instance.h"

// Calls manager instance
class Instance final : public base::has_weak_ptr {
public:
    Instance();
    ~Instance();

    // Start outgoing call to a user
    void startOutgoingCall(
        not_null<UserData*> user,
        StartOutgoingCallArgs{
            .video = false,          // Audio or video call
            .isConfirmed = false     // Skip confirmation
        });

    // Join or create group call
    void startOrJoinGroupCall(
        std::shared_ptr<Ui::Show> show,
        not_null<PeerData*> peer,
        StartGroupCallArgs{
            .joinHash = inviteHash,
            .confirm = StartGroupCallArgs::JoinConfirm::IfNowInAnother,
            .scheduleNeeded = false
        });

    // Start conference call
    void startOrJoinConferenceCall(StartConferenceInfo args);

    // Access current calls
    [[nodiscard]] Call *currentCall() const;
    [[nodiscard]] GroupCall *currentGroupCall() const;
};

// Example: Initiating a call
void startCall(not_null<UserData*> user, bool video) {
    Core::App().calls().startOutgoingCall(user, {
        .video = video,
        .isConfirmed = true
    });
}

```

--------------------------------

### Initialize Visual Studio Terminal for 32-bit

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-win.md

Initializes the Visual Studio environment for a 32-bit build, ensuring compatibility with Windows 7. Use this command before preparing libraries and building.

```batch
%comspec% /k "C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars32.bat" -vcvars_ver=14.44
```

--------------------------------

### Define Multi-part Icons in .style

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Illustrates how to define complex icons with multiple layers using the icon syntax in .style files. Layers are drawn from bottom to top.

```style
myComplexIcon: icon{
  { "gui/icons/background", iconBgColor },
  { "gui/icons/foreground", iconFgColor }
};
```

--------------------------------

### Configure Build for 64-bit

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-win.md

Configures the build for a 64-bit target, requiring your Telegram API ID and API Hash. Run this command from the tdesktop\Telegram directory.

```batch
configure.bat x64 -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### Build Telegram Desktop on Windows (Visual Studio)

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Build Telegram Desktop on Windows using Visual Studio. Ensure you are using the correct version (2026, x64) and run the build commands from the VS Developer Command Prompt.

```bash
# Windows (Visual Studio 2026, x64)
# Run from VS Developer Command Prompt with -vcvars_ver=14.44
Telegram\build\prepare\win.bat
cd Telegram && configure.bat x64 \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH
# Open out/Telegram.slnx in Visual Studio
```

--------------------------------

### Build Telegram Desktop with Test API Key

Source: https://github.com/telegramdesktop/tdesktop/wiki/The-Packaged-Building-Mode

If you cannot obtain official API credentials, you can build Telegram Desktop using the test API key. This key has limited functionality.

```bash
cmake -B build . -DTDESKTOP_API_TEST=ON
cmake --build build
cmake --install build
```

--------------------------------

### Immediate String Localization

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Use tr::lng with tr::now for immediate QString results. Placeholders follow the lt_tag_name, value pattern.

```cpp
auto currentTitle = tr::lng_settings_title(tr::now);

auto currentConfirmation = tr::lng_confirm_delete_item(
    tr::now,
    lt_item_name, currentItemName);

auto filesText = tr::lng_files_selected(tr::now, lt_count, count);
```

--------------------------------

### Define Custom Color Constant

Source: https://github.com/telegramdesktop/tdesktop/wiki/Theme-Reference

Shows how to define a custom color constant for easy reuse.

```text
COLOR_GREEN_LIGHT: #15cd7d;
windowBoldFgOver: COLOR_GREEN_LIGHT;
menuIconFgOver: COLOR_GREEN_LIGHT;
```

--------------------------------

### Configure Build for 32-bit

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-win.md

Configures the build for a 32-bit target, requiring your Telegram API ID and API Hash. Run this command from the tdesktop\Telegram directory.

```batch
configure.bat -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### Configure Telegram Desktop Build with API Credentials

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-mac.md

Configures the Telegram Desktop build using a shell script. Replace YOUR_API_ID and YOUR_API_HASH with your actual Telegram API credentials obtained separately.

```bash
./configure.sh -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### Clone Telegram Desktop Source and Prepare Libraries

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-mac.md

Clones the recursive Git repository for Telegram Desktop and runs the macOS preparation script to download and set up necessary libraries for building.

```bash
git clone --recursive https://github.com/telegramdesktop/tdesktop.git
./tdesktop/Telegram/build/prepare/mac.sh
```

--------------------------------

### Use RAII for Resource Cleanup

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/REVIEW.md

Employ RAII wrappers like `gsl::finally` for resource cleanup (handles, file descriptors, COM objects) instead of manual calls. This ensures cleanup occurs even with early returns.

```cpp
// BAD - manual cleanup, fragile with early returns:
const auto snapshot = CreateToolhelp32Snapshot(...);
if (snapshot != INVALID_HANDLE_VALUE) {
	// ... logic that might grow early returns ...
	CloseHandle(snapshot);
}
```

```cpp
// GOOD - RAII guard, cleanup runs on any exit path:
const auto snapshot = CreateToolhelp32Snapshot(...);
if (snapshot == INVALID_HANDLE_VALUE) {
	return;
}
const auto guard = gsl::finally([&] {
	CloseHandle(snapshot);
});
// ... logic, early returns are safe ...
```

--------------------------------

### Define Borders in .style

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Shows how to define border properties for UI elements in .style files. Borders are typically defined by separate width and color properties.

```style
chatInput {
  border: 1px;
  borderFg: defaultInputFieldBorder;
}
```

--------------------------------

### Build Telegram Desktop with Docker (Release)

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-linux.md

Use this command to perform a release build of Telegram Desktop using Docker. Ensure you replace YOUR_API_ID and YOUR_API_HASH with your actual Telegram API credentials.

```bash
docker run --rm -it \
    -u $(id -u) \
    -v "$PWD:/usr/src/tdesktop" \
    tdesktop:centos_env \
    /usr/src/tdesktop/Telegram/build/docker/centos_env/build.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### Initialize and Use Data::Session Class

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Manages all data entities like users, chats, and messages with reactive updates. Use for accessing and manipulating conversation data.

```cpp
#include "data/data_session.h"

// Data session manages all entities
class Session final {
public:
    // Peer access (users, chats, channels)
    [[nodiscard]] not_null<PeerData*> peer(PeerId id);
    [[nodiscard]] UserData *user(UserId id);
    [[nodiscard]] ChatData *chat(ChatId id);
    [[nodiscard]] ChannelData *channel(ChannelId id);

    // History (conversation) access
    [[nodiscard]] not_null<History*> history(PeerId peerId);
    [[nodiscard]] History *historyLoaded(PeerId peerId);

    // Message operations
    [[nodiscard]] HistoryItem *message(FullMsgId itemId);
    void requestItemRepaint(not_null<const HistoryItem*> item);

    // Media and documents
    [[nodiscard]] not_null<PhotoData*> photo(PhotoId id);
    [[nodiscard]] not_null<DocumentData*> document(DocumentId id);

    // Folders and filters
    [[nodiscard]] Data::Folder *folder(FolderId id);
    [[nodiscard]] Data::ChatFilters &chatFilters();
};

// Example: Working with messages
void processConversation(not_null<Data::Session*> data, PeerId peerId) {
    auto history = data->history(peerId);

    // Iterate recent messages
    for (const auto &block : history->blocks) {
        for (const auto &item : block->messages) {
            if (auto media = item->media()) {
                if (auto photo = media->photo()) {
                    // Handle photo message
                }
            }
        }
    }
}
```

--------------------------------

### Initialize and Use Session Class

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Represents an authenticated user session. Provides access to user data, API, storage, and subsystems. Use when interacting with user-specific functionalities.

```cpp
#include "main/main_session.h"

// Session provides access to all user-related functionality
class Session final : public base::has_weak_ptr {
public:
    Session(
        not_null<Account*> account,
        const MTPUser &user,
        std::unique_ptr<SessionSettings> settings);

    // User identity
    [[nodiscard]] UserId userId() const;
    [[nodiscard]] not_null<UserData*> user() const;
    [[nodiscard]] bool premium() const;

    // Subsystem access
    [[nodiscard]] Data::Session &data() const;      // Data storage
    [[nodiscard]] ApiWrap &api() const;             // API wrapper
    [[nodiscard]] Storage::Facade &storage() const; // Local storage

    // Reactive data changes
    [[nodiscard]] Data::Changes &changes() const;
};

// Example: Access session from controller
void handleUserAction(not_null<Window::SessionController*> controller) {
    auto &session = controller->session();
    auto userId = session.userId();
    auto isPremium = session.premium();

    // Access data layer
    auto &data = session.data();
    auto peer = data.peer(peerId);

    // Use API wrapper
    session.api().requestFullPeer(peer);
}
```

--------------------------------

### Build Telegram Desktop with Docker (Debug)

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-linux.md

This command is used for creating a debug build of Telegram Desktop with Docker. Replace YOUR_API_ID and YOUR_API_HASH with your Telegram API credentials. The '-e CONFIG=Debug' flag specifies a debug configuration.

```bash
docker run --rm -it \
    -u $(id -u) \
    -v "$PWD:/usr/src/tdesktop" \
    -e CONFIG=Debug \
    tdesktop:centos_env \
    /usr/src/tdesktop/Telegram/build/docker/centos_env/build.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH
```

--------------------------------

### macOS App Store Build Configuration

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Sets specific bundle identifiers, entitlements, and output names for building the Telegram Lite app for the Mac App Store. Links against the Breakpad framework and performs cleanup of its resources.

```cmake
set(bundle_identifier "org.telegram.desktop")
set(bundle_entitlements "Telegram Lite.entitlements")
set(output_name "Telegram Lite")
target_link_options(Telegram
PRIVATE
    -F${libs_loc}/breakpad/src/client/mac/build/Release
)
target_link_frameworks(Telegram PRIVATE Breakpad)
add_custom_command(TARGET Telegram
PRE_LINK
    COMMAND rm -rf $<TARGET_FILE_DIR:Telegram>/../Frameworks
    COMMAND mkdir -p $<TARGET_FILE_DIR:Telegram>/../Frameworks
    COMMAND cp -a ${libs_loc}/breakpad/src/client/mac/build/Release/Breakpad.framework $<TARGET_FILE_DIR:Telegram>/../Frameworks/Breakpad.framework
    COMMAND rm -rf $<TARGET_FILE_DIR:Telegram>/../Frameworks/Breakpad.framework/Resources/crash_report_sender.app
    COMMAND rm -rf $<TARGET_FILE_DIR:Telegram>/../Frameworks/Breakpad.framework/Resources/Inspector
)
```

--------------------------------

### Build Telegram Executable

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Use this command from the repository root to build the Telegram executable in Debug configuration. The output executable will be located at out/Debug/Telegram.exe.

```bash
cmake --build out --config Debug --target Telegram
```

--------------------------------

### Access Style Members in C++

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Shows how to include style headers and access style properties like height, icon, and padding from C++ code using the 'st' namespace.

```cpp
#include "styles/style_widgets.h"

// Access style members
int height = st::primaryButton.height;
const style::icon &icon = st::primaryButton.icon;
style::margins padding = st::primaryButton.textPadding;

// Use in painting
void MyWidget::paintEvent(QPaintEvent *e) {
    Painter p(this);
    p.fillRect(rect(), st::chatInput.backgroundColor);
}
```

--------------------------------

### Reuse Color Constant

Source: https://github.com/telegramdesktop/tdesktop/wiki/Theme-Reference

Demonstrates how one color constant can reuse the definition of another.

```text
windowActiveTextFg: #15cd7d;
msgInServiceFg: windowActiveTextFg;
```

--------------------------------

### Rich Text Localization with Projectors

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/AGENTS.md

Use tr::... projectors as the last argument for TextWithEntities or as placeholder wrappers for rich formatting.

```cpp
// As last argument (projector):
auto title = tr::lng_export_progress_title(tr::now, tr::bold);
auto text = tr::lng_proxy_incorrect_secret(tr::now, tr::rich);
// As placeholder value wrapper + projector:
auto desc = tr::lng_some_key(
    tr::now,
    lt_name,
    tr::bold(userName),
    lt_group,
    tr::bold(groupName),
    tr::rich);
// Nested tr::lng as placeholder:
auto linked = tr::lng_settings_birthday_contacts(
    lt_link,
    tr::lng_settings_birthday_contacts_link(tr::url(link)),
    tr::marked);
```

--------------------------------

### macOS Icon and Resource Handling

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Configures macOS specific icon files and localizable strings for the Telegram application bundle. Ensures icons are placed in the Resources directory and language strings are correctly localized.

```cmake
set_source_files_properties(Icon.icns PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
target_add_resource(Telegram Icon.icns)
```

```cmake
set(lang_packs
    en
    de
    es
    it
    nl
    ko
    pt-BR
)
foreach (lang ${lang_packs})
    set(strings_path ${res_loc}/langs/${lang}.lproj/Localizable.strings)
    set_source_files_properties(${strings_path} PROPERTIES
    MACOSX_PACKAGE_LOCATION
        Resources/${lang}.lproj
    )
    target_sources(Telegram PRIVATE ${strings_path})
    source_group(TREE ${res_loc} PREFIX Resources FILES ${strings_path})
endforeach()
```

--------------------------------

### Include Subdirectories for Libraries

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Includes various library subdirectories into the build system, organizing project modules.

```cmake
add_subdirectory(lib_rpl)
add_subdirectory(lib_crl)
add_subdirectory(lib_base)
add_subdirectory(lib_ui)
add_subdirectory(lib_tl)
add_subdirectory(lib_spellcheck)
add_subdirectory(lib_storage)
add_subdirectory(lib_lottie)
add_subdirectory(lib_qr)
add_subdirectory(lib_translate)
add_subdirectory(lib_webrtc)
add_subdirectory(lib_webview)
add_subdirectory(codegen)
```

--------------------------------

### Send Existing Document via API

Source: https://context7.com/telegramdesktop/tdesktop/llms.txt

Sends a pre-existing document (file, video, audio) using the Api::SendExistingDocument function. Requires a MessageToSend object and a DocumentData pointer.

```cpp
#include "api/api_sending.h"

// Send an existing document (file, video, audio, etc.)
Api::SendExistingDocument(
    Api::MessageToSend{
        .action = Api::SendAction(history),
        .textWithTags = { "Caption text", {} }
    },
    document,                    // not_null<DocumentData*>
    std::nullopt                 // Optional local message ID
);
```

--------------------------------

### Include Custom CMake Modules

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Includes custom CMake modules for project configuration, options, and specific functionalities like FFmpeg, Stripe, and WebRTC integration.

```cmake
include(cmake/telegram_options.cmake)
include(cmake/lib_ffmpeg.cmake)
include(cmake/lib_stripe.cmake)
include(cmake/lib_tgcalls.cmake)
include(cmake/lib_prisma.cmake)
include(cmake/td_export.cmake)
include(cmake/td_iv.cmake)
include(cmake/td_lang.cmake)
include(cmake/td_mtproto.cmake)
include(cmake/td_scheme.cmake)
include(cmake/td_tde2e.cmake)
include(cmake/td_ui.cmake)
include(cmake/telegram_apple_swift_runtime.cmake)
include(cmake/generate_appstream_changelog.cmake)
```

--------------------------------

### VS Code Settings for Docker Integration

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/docs/building-linux.md

Add this JSON configuration to your `.vscode/settings.json` file to enable Visual Studio Code's Dev Containers integration for building Telegram Desktop. This requires your API ID and API Hash.

```json
{
    "cmake.configureSettings": {
        "TDESKTOP_API_ID": "YOUR_API_ID",
        "TDESKTOP_API_HASH": "YOUR_API_HASH"
    }
}
```

--------------------------------

### Custom Build Commands for macOS Resources

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/CMakeLists.txt

Adds custom commands to copy essential resource files like UI and spellcheck dictionaries to the application's Resources directory before linking.

```cmake
add_custom_command(TARGET Telegram
PRE_LINK
    COMMAND mkdir -p $<TARGET_FILE_DIR:Telegram>/../Resources
    COMMAND cp ${CMAKE_BINARY_DIR}/lib_ui.rcc $<TARGET_FILE_DIR:Telegram>/../Resources
    COMMAND cp ${CMAKE_BINARY_DIR}/lib_spellcheck.rcc $<TARGET_FILE_DIR:Telegram>/../Resources
)
```

--------------------------------

### Use tr:: projections for TextWithEntities

Source: https://github.com/telegramdesktop/tdesktop/blob/dev/REVIEW.md

Prefer `tr::` projection helpers over `Ui::Text::` equivalents for conciseness and uniform behavior. Use `tr::marked()` for creating `TextWithEntities`.

```cpp
// BAD - verbose Ui::Text:: functions:
tr::lng_some_key(
    tr::now,
    lt_name,
    Ui::Text::Bold(name),
    lt_group,
    Ui::Text::Bold(group),
    Ui::Text::RichLangValue)

// GOOD - concise tr:: helpers:
tr::lng_some_key(
    tr::now,
    lt_name,
    tr::bold(name),
    lt_group,
    tr::bold(group),
    tr::rich)
```

```cpp
// BAD - verbose constructor:
auto text = TextWithEntities();
auto text = TextWithEntities{ u"hello"_q };
auto text = TextWithEntities().append(u"hello"_q);

// GOOD - concise:
auto text = tr::marked();
auto text = tr::marked(u"hello"_q);
```