From 449ca86f164d7216562c75b893477e7cb97bca24 Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Fri, 11 Jul 2025 06:11:26 +0000 Subject: [PATCH] Update README.md --- README.md | 176 +++++++++++++++++++++++++----------------------------- 1 file changed, 83 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 00294b6..6afaf50 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,93 @@ # waylib -## Introduction +## 简介 +`waylib` 是一个基于 Qt 和 wlroots 的库，用于构建 Wayland 合成器。它提供了一套完整的组件和工具，简化了 Wayland 服务器的开发流程。 -waylib is a Wayland compositor development library, based on [qwlroots](https://github.com/vioken/qwlroots), provides a Qt-style development interface. It is designed to be deeply integrated with QtQuick, taking advantage of QtQuick's Scene Graphics model to simplify the complexity of window management. In waylib, it is possible to attach one or multiple Wayland Outputs to a QQuickWindow, and a corresponding Wayland Surface can be attached to a QQuickItem, allowing it to be mixed with QtQuick's graphics components and supporting QRHI for OpenGL and Vulkan compatibility in a single piece of code. +## 特性 +- 基于 Qt Quick 的渲染框架 +- 支持多种输出管理协议（如 `woutputmanagerv1`） +- 提供丰富的客户端交互支持（如光标、键盘、触摸等） +- 支持 XWayland 客户端集成 +- 提供多种表面类型（如 `WXdgToplevelSurface`, `WXWaylandSurface`） +- 支持图层壳（Layer Shell）协议 +- 提供输入法支持（Input Method） -Creating a Wayland compositor using waylib can be simple and efficient, which, on top of wlroots, provides: +## 构建 -* QtQuick-based rendering model -* Qt event model support -* Session management system (under development) -* Client/window group policies (under development) -* Window management abstraction (under development) - -Based on the above features, compositor developers need only focus on the business requirements of window management and can develop window compositors as if they were implementing a regular application. - -## Features - -* Support switch different display backend: DRM, Wayland, X11 -* Support custom input backend, by default it uses libinput -* Support for rendering cursors in both hardware and software -* Support for X Window cursor file format and theme -* Support for running in environments without dri devices -* Coexistence with Qt platform plug-in system -* Provides QML components - -## Building - -Step 1: Compiling and Installing wlroots and qwlroots - -waylib requires the development version (0.19) of wlroots, which needs to be [compiled and installed manually](https://gitlab.freedesktop.org/wlroots/wlroots#building). Arch Linux users can install [wlroots-0.19](https://archlinux.org/packages/extra/x86_64/wlroots0.19/). - -For qwlroots, it is currently recommended to use the version provided as a submodule. However, you can also [compile and install](https://github.com/vioken/qwlroots) it by yourself. - -If using the submodule version, please note the following two points: - -1. Initialize the submodules when you clone the source code: `git clone git@github.com:vioken/waylib.git --recursive` -2. Before the final compilation, add the cmake parameter "-DWITH_SUBMODULE_QWLROOTS=ON" to enable the building of the submodule. - -Step 2: Installing other dependencies - -Debian - -```` -# apt install pkg-config qt6-base-private-dev qt6-base-dev-tools qt6-declarative-private-dev wayland-protocols libpixman-1-dev -```` - -Archlinux - -```` -# pacman -Syu --noconfirm qt6-base qt6-declarative cmake pkgconfig pixman wayland-protocols ninja -```` - -NixOS: - -It is recommended to manage dependencies using [nix-direnv](https://github.com/nix-community/nix-direnv), or you can use the command `nix develop` to enter the build environment. - -You can also packaging by using the command "nix build -v -L". - -Step 3: Execute the following commands +### 依赖项 +确保安装以下依赖项： +#### Debian/Ubuntu ```bash -cmake -B build -DWITH_SUBMODULE_QWLROOTS=ON -cmake --build build +sudo apt install pkg-config qt6-base-private-dev qt6-base-dev-tools qt6-declarative-private-dev wayland-protocols libpixman-1-dev ``` -## How to Contribute - -This project assumes that you already have experience with `Qt` and `wlroots` libraries. In order to better integrate with Qt and wlroots, waylib adheres to Qt's guidelines in terms of interface style, wlroots' modular design philosophy with regards to the underlying design, and Qt's wrapping + layering design for the upper layers that are not directly related to wlroots. - -You are free to contribute as much code as you want to this project, provided that you follow the waylib design philosophy and the following types of requirements. - -### Code Style - -* When modifying existing code, the current code style should be respected. -* New code: the part that is closely related to wlroots should follow the code style of wlroots, underscore naming convention should be used for the corresponding slot function; other parts should follow the code style of Qt (https://wiki.qt.io/Qt_Coding_Style this link is for reference only. The actual Qt source code shall prevail) -* There is no absolute right or wrong code style, please consider the big picture, and do not rigidly stick to the small details - -### Code Architecture Guidelines - -* The code should be simple and easy to understand. -* Add comments to key nodes whether you change or add new code -* Security > Compatibility > Extensibility >= Performance - -### Contribution Guideline - -* Contribution steps. - 1. First login to your Github account and fork the project - 2. Pull the forked project locally using `git clone`. - 3. Push the new commit to your project using `git push`. - 4. commit your code to the upstream project on Github using the Pull Requese feature. -* commit message specification: align with Qt project, use English. Be sure to describe exactly what the commit "does" and "why it was made" -* A commit only does one thing, and the smaller the code changes, the easier it is to accept the commit. For larger code changes, try to split the commit into multiple commits (satisfying the git commit principle as a prerequisite) -* Please do your own testing and code review before committing the code, and submit the PR after confirming that the code is working correctly - -## Roadmap +#### Arch Linux +```bash +sudo pacman -Syu --noconfirm qt6-base qt6-declarative cmake pkgconfig pixman wayland-protocols ninja +``` -* Support of vulkan -* Support Hardware Plane -* Support for virtual devices (remote screen projection, mouse, keyboard multi-device sharing) -* Support multi-platform integration -* Support high refresh rate (120Hz) -* Support variable screen refresh rate +### 构建步骤 +1. 克隆仓库： + ```bash + git clone https://gitee.com/vioken/waylib.git + cd waylib + ``` + +2. 创建构建目录并进入： + ```bash + mkdir build && cd build + ``` + +3. 配置项目： + ```bash + cmake .. + ``` + +4. 编译项目： + ```bash + cmake --build . + ``` + +5. 安装（可选）： + ```bash + sudo cmake --install . + ``` + +## 贡献指南 + +我们欢迎社区贡献！请遵循以下指南： +- 提交代码前确保通过所有测试 +- 遵循项目编码风格 +- 提供清晰的提交信息 + +## 编码风格 +- 使用 Qt 推荐的命名规范 +- 类名使用 PascalCase +- 变量名使用 camelCase +- 保持代码简洁，避免冗余 + +## 代码质量 +- 所有代码必须通过静态检查 +- 提供单元测试覆盖关键逻辑 +- 避免内存泄漏和资源未释放问题 + +## 提交规范 +- 提交信息应清晰描述更改内容 +- 使用 `Fix #issue_number` 格式关联问题 +- 对重大更改使用 `Breaking Change:` 前缀 + +## 未来计划 +- 增强对多显示器的支持 +- 优化性能，减少合成延迟 +- 增加更多示例和文档 +- 支持更多 Wayland 协议扩展 + +## 示例 +项目包含多个示例程序，演示了如何使用 `waylib` 构建合成器： +- `examples/tinywl`: 最小化合成器示例 +- `examples/animationclient`: 动画客户端示例 +- `examples/blur`: 模糊效果示例 + +## 许可证 +本项目使用多种开源许可证，具体请查看 `LICENSES/` 目录下的文件。 \ No newline at end of file -- Gitee