From c79173e163e6d4a08be5b615af0a91df6bf47669 Mon Sep 17 00:00:00 2001 From: ful1e5 <24286590+ful1e5@users.noreply.github.com> Date: Fri, 14 Oct 2022 16:36:27 +0530 Subject: [PATCH] README.md: Human readable docs fixed #16 --- CHANGELOG.md | 3 + README.md | 314 ++++++++++++++++++++++++++++++--------------------- pling.txt | 20 ++++ 3 files changed, 209 insertions(+), 128 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3c1c8b..b8a648b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,13 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Refactor: build with `clickgen v2` #21 - Add cursor top_left_arrow #10 #11 - Uninstall docs ful1e5/apple_cursor#79 ful1e5/apple_cursor#80 +- ci: support `clickgen v2` build with cross platform test ### Changed - fixed #17 - fixed #21 +- Human readable docs #16 ## [v1.0.3] - 13 Nov 2021 diff --git a/README.md b/README.md index e3d7d0b..1c6c2c9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,39 @@ # BreezeX Cursor -Extended KDE cursor, Highly inspired on **KDE Breeze** for `Windows` and `Linux` with _HiDPi Support_ 🎉. +Extended KDE cursor, Highly inspired on **KDE Breeze** for `Windows` and `Linux` with _HiDPi Support_ . [![build](https://github.com/ful1e5/BreezeX_Cursor/actions/workflows/build.yml/badge.svg)](https://github.com/ful1e5/BreezeX_Cursor/actions/workflows/build.yml) -#### Cursor Sizes +## BreezeX needs your Input + +Until 2021 my cursors projects were well funded by [pling.com](https://www.pling.com) but since the +[pling-factor](https://www.pling.com/terms/payout) on the website has decreased and monthly payments +are <500$, It is now dependent on community funding and sponsorships. If you want to help me to maintain +BreezeX and my other open source projects actively, consider sponsoring my work on [GitHub Sponsor](https://github.com/sponsors/ful1e5) +or DM me on [Twitter](https://twitter.com/ful1e5) if your company would like to support my projects, +I will gladly look into it and post your avatar in the project's README. + +I appreciate all the wonderful people who patronize and sponsoring my work. + +## Sponsors + + + +N/A + +--- + +![BreezeX Dark](https://imgur.com/zDGsq2h.png) +![BreezeX Light](https://imgur.com/tmKu1vC.png) +![BreezeX Black](https://imgur.com/kzLufkT.png) + +> **Note** +> All cursor's `.svg` files are found in [svg](./svg) directory or you can also find them on +> [Figma](https://www.figma.com/file/Uo4LeHvFUPDgoqLjnFc1LB/BreezeX?node-id=0%3A1). + +## Cursor Sizes + +### Xcursor Sizes: 22 24 @@ -19,211 +48,240 @@ Extended KDE cursor, Highly inspired on **KDE Breeze** for `Windows` and `Linux` 88 96 -#### Colors +### Windows Cursor Size: -![#4C4C4C](https://imgur.com/oHJxr47.png) -![#FFFFFF](https://imgur.com/0Wexs1k.png) -![#000000](https://imgur.com/06jisfL.png) +- 16x16 - Small +- 24x24 - Regular +- 32x32 - Large +- 48x48 - Extra Large -### Quick install +## Colors: -- BreezeX Dark: [https://www.pling.com/p/1538515](https://www.pling.com/p/1538515) -- BreezeX Light: [https://www.pling.com/p/1640746](https://www.pling.com/p/1640746) -- BreezeX Black: [https://www.pling.com/p/1640747](https://www.pling.com/p/1640747) +### BreezeX Dark -#### Preview: +- Base Color - `#4D4D4D` (Breeze Dark) +- Outline Color - `#FFFFFF` (White) -> Check Figma file [here](https://www.figma.com/file/Uo4LeHvFUPDgoqLjnFc1LB/BreezeX?node-id=0%3A1) +### BreezeX Light -

- -
- Dark BreezeX Cursors -

+- Base Color - `#FFFFFF` (White) +- Outline Color - `#000000` (Black) -

- -
- Light BreezeX Cursors -

+### BreezeX Dark -

- -
- Black BreezeX Cursors -

+- Base Color - `#000000` (Black) +- Outline Color - `#FFFFFF` (White) -### Manual Install +## How to get it + +### Easiest Way + +You can download latest `stable` & `development` releases from +[Release Page](https://github.com/ful1e5/BreezeX_Cursor/releases). + +## Installing BreezeX Cursor #### Linux/X11 +**Installation:** + ```bash -# extract `BreezeX.tar.gz` -tar -xvf BreezeX.tar.gz +tar -xvf BreezeX-Dark.tar.gz # extract `BreezeX-Dark.tar.gz` +mv BreezeX-* ~/.icons/ # Install to local users +sudo mv BreezeX-* /usr/share/icons/ # Install to all users +``` -# For local users -mv BreezeX-* ~/.icons/ +**Uninstallation:** -# For all users -sudo mv BreezeX-* /usr/share/icons/ +```bash +rm ~/.icons/BreezeX-* # Remove from local users +sudo rm /usr/share/icons/BreezeX-* # Remove from all users ``` #### Windows -1. unzip `.zip` file -2. Open unzipped directory in Explorer, and **right click** on `install.inf`. +**Installation:** + +1. Unzip `.zip` file +2. Open unziped directory in Explorer, and **right click** on `install.inf`. 3. Click 'Install' from the context menu, and authorize the modifications to your system. -4. Open _Control Panel > Personalization and Appearance > Change mouse pointers_, and select **BreezeX Cursors**. +4. Open Control Panel > Personalization and Appearance > Change mouse pointers, + and select **BreezeX Cursors**. 5. Click '**Apply**'. -### Uninstall +**Uninstallation:** -#### Linux/X11 +Run the `uninstall.bat` script packed with the `.zip` archive -```bash -# From local users -rm -rf ~/.icons/BreezeX-* - -# From all users -sudo rm -rf /usr/share/icons/BreezeX-* -``` - -#### Windows +**OR** follow these steps: 1. Go to **Registry Editor** by typing the same in the _start search box_. 2. Expand `HKEY_CURRENT_USER` folder and expand `Control Panel` folder. -3. Go to `Cursors` folder and click on `Schemes` folder - all the available custom cursors that are installed will be listed here. -4. **Right Click** on the name of cursor file you want to uninstall; for eg.: \_BreezeX Cursors\_ and click `Delete`. +3. Go to `Cursors` folder and click on `Schemes` folder - all the available custom cursors that are + installed will be listed here. +4. **Right Click** on the name of cursor file you want to uninstall; for eg.: _BreezeX Cursors_ and + click `Delete`. 5. Click '**yes**' when prompted. -# Dependencies +## Build From Source -## External Libraries +#### Notes -- libxcursor -- libx11 -- libpng (<=1.6) +- BreezeX build configuration and cursor hotspot settings are bundled in the `build.toml` file. +- Check out the scripts section in [package.json](./package.json) to see how we build the cursor theme, + excluding the render scripts. They are useful for converting `.svg` files to `.png` files. +- yarn is optional, For building XCursors and Windows cursors from `.png` files or resizing them + you don't need that. If you want to develop/modify BreezeX's colors, and bitmaps, or generate a png + file from a svg, Then you can use yarn because bitmapper is written in TypeScript. +- Since BreezeX variants are designed similarly, they share the same hotspot settings so a + single configuration file `build.toml` is responsible for building all variants. Due to this, you will have + to change the following options in `ctgen` to build the appropriate variant: + - **-d**: bitmaps directory + - **-n**: The name you want to give to the generated theme. + - **-c**: Theme comment. + - See `ctgen --help` for all available options. -#### Install External Libraries +### Build prerequisites -##### ~macOS~ **[WIP]** +- Python version 3.7 or higher +- [clickgen](https://github.com/ful1e5/clickgen)>=2.1.2 (`pip install clickgen`) +- [yarn](https://github.com/yarnpkg/yarn) + +### Quick start + +1. Install [build prerequisites](#build-prerequisites) on your system +2. `git clone https://github.com/ful1e5/BreezeX_Cursor` +3. `cd BreezeX_Cursor && yarn build` +4. See [Installing BreezeX Cursor](#installing-breezex-cursor). + +### Building + +> **Note** +> Bitmaps are already generated in the `bitmaps` directory and **managed by the maintainer** +> (do not edit them directly). + +First make sure you installed the [build prerequisites](#build-prerequisites). +Now that you have the dependencies, you can try build individual themes from bitmaps and +customize sizes, target platform, and etc. with the `ctgen` CLI (packed with `clickgen`). + +#### `yarn build` aberration + +Here are the default commands we used to build the BreezeX's variants and packed them into `yarn build`: ```bash -brew install --cask xquartz -brew install libpng +ctgen build.toml -d 'bitmaps/BreezeX-Dark' -n 'BreezeX-Dark' -c 'BreezeX Dark cursors.' +ctgen build.toml -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'BreezeX Light cursors.' +ctgen build.toml -d 'bitmaps/BreezeX-Black' -n 'BreezeX-Black' -c 'BreezeX Black cursors.' ``` -##### Debain/ubuntu +Afterwards, the themes can be found in the `themes` directory. + +#### Customize Sizes + +> **Note** +> You can change the cursor size up to 200 because pngs are rendered with 200x200. +> If the cursor is resized by more than rendered png size, the final cursor will be blurred. + +##### Customize Windows Cursor size + +To build Windows cursor with size `16`: + +> **Warning** +> Windows cursor supports only one size, if multiple sizes are given with `-s` the first size will +> be considered in build. ```bash -sudo apt install libx11-dev libxcursor-dev libpng-dev +ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cusors with size 16' ``` -##### ArchLinux/Manjaro +You can also customize output directory with `-o` option: ```bash -sudo pacman -S libx11 libxcursor libpng +ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Light' -o 'out' -n 'BreezeX-Light' -c 'White BreezeX cusors with size 16' ``` -##### Fedora/Fedora Silverblue/CentOS/RHEL +##### Customize XCursor size + +To build XCursor with size `16`: ```bash -sudo dnf install libX11-devel libXcursor-devel libpng-devel +ctgen build.toml -s 16 -p x11 -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cusors with size 16' ``` -## Build Dependencies - -- [gcc](https://gcc.gnu.org/install/) -- [make](https://www.gnu.org/software/make/) -- [nodejs](https://nodejs.org/en/) (<=12.x.x) -- [yarn](https://classic.yarnpkg.com/en/docs/install/) -- [python](https://www.python.org/downloads/) (<=3.8) -- [pip3](https://pip.pypa.io/en/stable/installing/) - -### Node Packages - -- [puppeteer](https://www.npmjs.com/package/puppeteer) -- [pngjs](https://www.npmjs.com/package/pngjs) -- [pixelmatch](https://www.npmjs.com/package/pixelmatch) - -### PyPi Packages - -- [clickgen](https://pypi.org/project/clickgen/s) - -## Build Dependencies - -- [gcc](https://gcc.gnu.org/install/) -- [make](https://www.gnu.org/software/make/) -- [nodejs](https://nodejs.org/en/) (<=12.x.x) -- [yarn](https://classic.yarnpkg.com/en/docs/install/) -- [python](https://www.python.org/downloads/) (<=3.8) -- [pip3](https://pip.pypa.io/en/stable/installing/) - -### Node Packages - -- [puppeteer](https://www.npmjs.com/package/puppeteer) -- [pngjs](https://www.npmjs.com/package/pngjs) -- [pixelmatch](https://www.npmjs.com/package/pixelmatch) - -### PyPi Packages - -- [clickgen](https://pypi.org/project/clickgen/s) - -## Build From Scratch - -### âš¡ Auto Build (using GitHub Actions) - -GitHub Actions is automatically runs on every `push`(on **main** and **dev** branches) and `pull request`(on **main** branch), You found theme resources in `artifact` section of **build**.GitHub **Actions** available inside [.github/workflows](https://github.com/ful1e5/BreezeX_Cursor/tree/main/.github/workflows) directory. - -### Manual Build +You can also assign multiple sizes to `ctgen` for XCursors build: ```bash -make +ctgen build.toml -s 16 24 32 -p x11 -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cusors with size 16' ``` -#### Build `XCursor` theme +#### Customize Colors + +To customize BreezeX's color you have to install node dependencies with `yarn install` command. +After installing dependencies you can customize the colors via `npx cbmp` Node CLI App which packed with +[cbmp](https://github.com/ful1e5/cbmp) node package. + +##### `yarn render` aberration + +Here are the default commands we used for generating the BreezeX's bitmaps and packed them into `yarn render`: ```bash -make unix +npx cbmp -d 'svg' -n 'BreezeX-Dark' -bc '#4D4D4D' -oc '#FFFFFF' +npx cbmp -d 'svg' -n 'BreezeX-Light' -bc '#FFFFFF' -oc '#000000' +npx cbmp -d 'svg' -n 'BreezeX-Black' -bc '#000000' -oc '#FFFFFF' ``` -#### Customize `XCursor` size +#### Examples + +Lets generate modern BreezeX with green base color and black outline: ```bash -make unix X_SIZES=22 # Only built '22px' pixel-size. -make unix X_SIZES=22 24 32 # Multiple sizes are provided with ' '(Space) +npx cbmp -d 'svg' -n 'BreezeX-Hacker' -bc '#00FE00' -oc '#000000' ``` -#### Install `XCursor` theme +After rendering custom color you have to build cursor through `ctgen`: ```bash -make install # install as user - # OR -sudo make install # install as root +ctgen build.toml -d 'bitmaps/BreezeX-Hacker' -n 'BreezeX-Hacker' -c 'Green and black BreezeX cursors.' ``` -#### Build `Windows` theme +Afterwards, Generated theme can be found in the `themes` directory. + +###### BreezeX Gruvbox ```bash -make windows +npx cbmp -d 'svg' -n 'BreezeX-Gruvbox' -bc '#282828' -oc '#EBDBB2' +ctgen build.toml -d 'bitmaps/BreezeX-Gruvbox' -n 'BreezeX-Gruvbox' -c 'Groovy BreezeX cursors.' ``` -#### Customize `Windows Cursor` size +###### BreezeX Solarized Dark ```bash -make windows WIN_SIZE=96 # Supports only one pixel-size +npx cbmp -d 'svg' -n 'BreezeX-Solarized-Dark' -bc '#002b36' -oc '#839496' +ctgen build.toml -d 'bitmaps/BreezeX-Solarized-Dark' -n 'BreezeX-Solarized-Dark' -c 'Solarized Dark BreezeX cursors.' ``` -> For installation follow [these](#windows) steps. +###### BreezeX Solarized Light -# Bugs +```bash +npx cbmp -d 'svg' -n 'BreezeX-Solarized-Light' -bc '#839496' -oc '#002b36' +ctgen build.toml -d 'bitmaps/BreezeX-Solarized-Light' -n 'BreezeX-Solarized-Light' -c 'Solarized Light BreezeX cursors.' +``` + +###### BreezeX Dracula + +```bash +npx cbmp -d 'svg' -n 'BreezeX-Dracula' -bc '#282a36' -oc '#f8f8f2' +ctgen build.toml -d 'bitmaps/BreezeX-Dracula' -n 'BreezeX-Dracula' -c 'Dracula BreezeX cursors.' +``` + +## Bugs Bugs should be reported [here](https://github.com/ful1e5/BreezeX_Cursor/issues) on the Github issues page. -# Getting Help +## Getting Help You can create a **issue**, I will help you. -# Contributing +## Contributing Check [CONTRIBUTING.md](CONTRIBUTING.md), any suggestions for features and contributions to the continuing code masterelopment can be made via the issue tracker or code contributions via a `Fork` & `Pull requests`. diff --git a/pling.txt b/pling.txt index e69de29..b3d86e8 100644 --- a/pling.txt +++ b/pling.txt @@ -0,0 +1,20 @@ +Extended KDE cursor, Highly inspired on KDE Breeze for Windows and Linux with HiDPi Support . + +Check [url=https://github.com/ful1e5/BreezeX_Cursor]README.md[/url] for installation, uninstallation, personalize cursor sizes or colors. + +[b]Notice:[/b] +Until 2021 my cursors projects were well funded by 'pling.com' but since the 'pling-factor' on the website has decreased and monthly payments are <500$, It is now dependent on community funding and sponsorships. If you want to help me to maintain BreezeX Cursors and my other open source projects actively, consider sponsoring my work on [url=https://github.com/sponsors/ful1e5]GitHub Sponsors[/url] or DM me on [url=https://twitter.com/ful1e5]Twitter[/url] if your company would like to support this project, I will gladly look into it and post your avatar in the README. + +I appreciate all the wonderful people who patronize and sponsoring my work. + +[b]XCursor Sizes:[/b] +22x22, 24x24, 28x28, 32x32, 40x40, 48x48, 56x56, 64x64, 72x72, 80x80, 88x88, 96x96 + +[b]Windows Cursor Size:[/b] +- 16x16 - Small +- 24x24 - Regular +- 32x32 - Large +- 48x48 - Extra Large + +[b]License & Terms:[/b] +'BreezeX_Cursor' is available under the terms of the 'GPL-3.0' license.